include/wx/generic/treectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        treectrl.h
   3 // Purpose:     wxTreeCtrl class
   4 // Author:      Robert Roebling
   5 // Modified by:
   6 // Created:     01/02/97
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1997,1998 Robert Roebling
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _GENERIC_TREECTRL_H_
  13 #define _GENERIC_TREECTRL_H_
  14
  15 #ifdef __GNUG__
  16     #pragma interface "treectrl.h"
  17 #endif
  18
  19 #include "wx/defs.h"
  20 #include "wx/string.h"
  21 #include "wx/object.h"
  22 #include "wx/event.h"
  23 #include "wx/scrolwin.h"
  24 #include "wx/textctrl.h"
  25 #include "wx/pen.h"
  26 #include "wx/dynarray.h"
  27 #include "wx/timer.h"
  28
  29 // -----------------------------------------------------------------------------
  30 // forward declaration
  31 // -----------------------------------------------------------------------------
  32
  33 class WXDLLEXPORT wxImageList;
  34 class WXDLLEXPORT wxGenericTreeItem;
  35
  36 class WXDLLEXPORT wxTreeItemData;
  37
  38 class WXDLLEXPORT wxTreeRenameTimer;
  39 class WXDLLEXPORT wxTreeTextCtrl;
  40
  41 // -----------------------------------------------------------------------------
  42 // wxTreeItemId - unique identifier of a tree element
  43 // -----------------------------------------------------------------------------
  44
  45 class WXDLLEXPORT wxTreeItemId
  46 {
  47 friend class wxTreeCtrl;
  48 friend class wxTreeEvent;
  49 public:
  50     // ctors
  51         // 0 is invalid value for HTREEITEM
  52     wxTreeItemId() { m_pItem = 0; }
  53
  54         // default copy ctor/assignment operator are ok for us
  55
  56     // accessors
  57         // is this a valid tree item?
  58     bool IsOk() const { return m_pItem != 0; }
  59
  60     // deprecated: only for compatibility
  61     wxTreeItemId(long itemId) { m_pItem = (wxGenericTreeItem *)itemId; }
  62     operator long() const { return (long)m_pItem; }
  63
  64 //protected: // not for gcc
  65     // for wxTreeCtrl usage only
  66     wxTreeItemId(wxGenericTreeItem *pItem) { m_pItem = pItem; }
  67
  68     wxGenericTreeItem *m_pItem;
  69 };
  70
  71 WX_DECLARE_OBJARRAY(wxTreeItemId, wxArrayTreeItemIds);
  72
  73 // ----------------------------------------------------------------------------
  74 // wxTreeItemData is some (arbitrary) user class associated with some item.
  75 //
  76 // Because the objects of this class are deleted by the tree, they should
  77 // always be allocated on the heap!
  78 // ----------------------------------------------------------------------------
  79
  80 class WXDLLEXPORT wxTreeItemData: public wxClientData
  81 {
  82 friend class wxTreeCtrl;
  83 public:
  84     // creation/destruction
  85     // --------------------
  86         // default ctor
  87     wxTreeItemData() { }
  88
  89         // default copy ctor/assignment operator are ok
  90
  91     // accessor: get the item associated with us
  92     const wxTreeItemId& GetId() const { return m_pItem; }
  93     void SetId(const wxTreeItemId& id) { m_pItem = id; }
  94
  95 protected:
  96     wxTreeItemId m_pItem;
  97 };
  98
  99 //-----------------------------------------------------------------------------
 100 // wxTreeRenameTimer (internal)
 101 //-----------------------------------------------------------------------------
 102
 103 class WXDLLEXPORT wxTreeRenameTimer: public wxTimer
 104 {
 105  private:
 106    wxTreeCtrl   *m_owner;
 107
 108  public:
 109    wxTreeRenameTimer( wxTreeCtrl *owner );
 110    void Notify();
 111 };
 112
 113 //-----------------------------------------------------------------------------
 114 //  wxTreeTextCtrl (internal)
 115 //-----------------------------------------------------------------------------
 116
 117 class WXDLLEXPORT wxTreeTextCtrl: public wxTextCtrl
 118 {
 119   DECLARE_DYNAMIC_CLASS(wxTreeTextCtrl);
 120
 121   private:
 122     bool               *m_accept;
 123     wxString           *m_res;
 124     wxTreeCtrl         *m_owner;
 125     wxString            m_startValue;
 126
 127   public:
 128     wxTreeTextCtrl(void) {};
 129     wxTreeTextCtrl( wxWindow *parent, const wxWindowID id,
 130                     bool *accept, wxString *res, wxTreeCtrl *owner,
 131                     const wxString &value = wxEmptyString,
 132                     const wxPoint &pos = wxDefaultPosition, const wxSize &size = wxDefaultSize,
 133                     int style = 0,
 134                     const wxValidator& validator = wxDefaultValidator,
 135                     const wxString &name = wxTextCtrlNameStr );
 136     void OnChar( wxKeyEvent &event );
 137     void OnKillFocus( wxFocusEvent &event );
 138
 139   DECLARE_EVENT_TABLE()
 140 };
 141
 142 // -----------------------------------------------------------------------------
 143 // wxTreeCtrl - the tree control
 144 // -----------------------------------------------------------------------------
 145
 146 class WXDLLEXPORT wxTreeCtrl : public wxScrolledWindow
 147 {
 148 public:
 149     // creation
 150     // --------
 151     wxTreeCtrl() { Init(); }
 152
 153     wxTreeCtrl(wxWindow *parent, wxWindowID id = -1,
 154                const wxPoint& pos = wxDefaultPosition,
 155                const wxSize& size = wxDefaultSize,
 156                long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
 157                const wxValidator &validator = wxDefaultValidator,
 158                const wxString& name = wxTreeCtrlNameStr)
 159     {
 160         Create(parent, id, pos, size, style, validator, name);
 161     }
 162
 163     virtual ~wxTreeCtrl();
 164
 165     bool Create(wxWindow *parent, wxWindowID id = -1,
 166                 const wxPoint& pos = wxDefaultPosition,
 167                 const wxSize& size = wxDefaultSize,
 168                 long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
 169                 const wxValidator &validator = wxDefaultValidator,
 170                 const wxString& name = wxTreeCtrlNameStr);
 171
 172     // accessors
 173     // ---------
 174
 175         // get the total number of items in the control
 176     size_t GetCount() const;
 177
 178         // indent is the number of pixels the children are indented relative to
 179         // the parents position. SetIndent() also redraws the control
 180         // immediately.
 181     unsigned int GetIndent() const { return m_indent; }
 182     void SetIndent(unsigned int indent);
 183
 184         // spacing is the number of pixels between the start and the Text
 185     unsigned int GetSpacing() const { return m_spacing; }
 186     void SetSpacing(unsigned int spacing);
 187
 188         // image list: these functions allow to associate an image list with
 189         // the control and retrieve it. Note that the control does _not_ delete
 190         // the associated image list when it's deleted in order to allow image
 191         // lists to be shared between different controls.
 192         //
 193         // The normal image list is for the icons which correspond to the
 194         // normal tree item state (whether it is selected or not).
 195         // Additionally, the application might choose to show a state icon
 196         // which corresponds to an app-defined item state (for example,
 197         // checked/unchecked) which are taken from the state image list.
 198     wxImageList *GetImageList() const;
 199     wxImageList *GetStateImageList() const;
 200
 201     void SetImageList(wxImageList *imageList);
 202     void SetStateImageList(wxImageList *imageList);
 203
 204     // Functions to work with tree ctrl items.
 205
 206     // accessors
 207     // ---------
 208
 209         // retrieve items label
 210     wxString GetItemText(const wxTreeItemId& item) const;
 211         // get one of the images associated with the item (normal by default)
 212     int GetItemImage(const wxTreeItemId& item,
 213                      wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
 214         // get the data associated with the item
 215     wxTreeItemData *GetItemData(const wxTreeItemId& item) const;
 216
 217     // modifiers
 218     // ---------
 219
 220         // set items label
 221     void SetItemText(const wxTreeItemId& item, const wxString& text);
 222         // get one of the images associated with the item (normal by default)
 223     void SetItemImage(const wxTreeItemId& item, int image,
 224                       wxTreeItemIcon which = wxTreeItemIcon_Normal);
 225         // associate some data with the item
 226     void SetItemData(const wxTreeItemId& item, wxTreeItemData *data);
 227
 228         // force appearance of [+] button near the item. This is useful to
 229         // allow the user to expand the items which don't have any children now
 230         // - but instead add them only when needed, thus minimizing memory
 231         // usage and loading time.
 232     void SetItemHasChildren(const wxTreeItemId& item, bool has = TRUE);
 233
 234         // the item will be shown in bold
 235     void SetItemBold(const wxTreeItemId& item, bool bold = TRUE);
 236
 237         // set the items text colour
 238     void SetItemTextColour(const wxTreeItemId& item, const wxColour& col);
 239
 240         // set the items background colour
 241     void SetItemBackgroundColour(const wxTreeItemId& item, const wxColour& col);
 242
 243         // set the items font (should be of the same height for all items)
 244     void SetItemFont(const wxTreeItemId& item, const wxFont& font);
 245
 246     // item status inquiries
 247     // ---------------------
 248
 249         // is the item visible (it might be outside the view or not expanded)?
 250     bool IsVisible(const wxTreeItemId& item) const;
 251         // does the item has any children?
 252     bool HasChildren(const wxTreeItemId& item) const
 253       { return ItemHasChildren(item); }
 254     bool ItemHasChildren(const wxTreeItemId& item) const;
 255         // is the item expanded (only makes sense if HasChildren())?
 256     bool IsExpanded(const wxTreeItemId& item) const;
 257         // is this item currently selected (the same as has focus)?
 258     bool IsSelected(const wxTreeItemId& item) const;
 259         // is item text in bold font?
 260     bool IsBold(const wxTreeItemId& item) const;
 261
 262     // number of children
 263     // ------------------
 264
 265         // if 'recursively' is FALSE, only immediate children count, otherwise
 266         // the returned number is the number of all items in this branch
 267     size_t GetChildrenCount(const wxTreeItemId& item, bool recursively = TRUE);
 268
 269     // navigation
 270     // ----------
 271
 272     // wxTreeItemId.IsOk() will return FALSE if there is no such item
 273
 274         // get the root tree item
 275     wxTreeItemId GetRootItem() const { return m_anchor; }
 276
 277         // get the item currently selected (may return NULL if no selection)
 278     wxTreeItemId GetSelection() const { return m_current; }
 279
 280         // get the items currently selected, return the number of such item
 281     size_t GetSelections(wxArrayTreeItemIds&) const;
 282
 283         // get the parent of this item (may return NULL if root)
 284     wxTreeItemId GetParent(const wxTreeItemId& item) const;
 285
 286         // for this enumeration function you must pass in a "cookie" parameter
 287         // which is opaque for the application but is necessary for the library
 288         // to make these functions reentrant (i.e. allow more than one
 289         // enumeration on one and the same object simultaneously). Of course,
 290         // the "cookie" passed to GetFirstChild() and GetNextChild() should be
 291         // the same!
 292
 293         // get the first child of this item
 294     wxTreeItemId GetFirstChild(const wxTreeItemId& item, long& cookie) const;
 295         // get the next child
 296     wxTreeItemId GetNextChild(const wxTreeItemId& item, long& cookie) const;
 297         // get the last child of this item - this method doesn't use cookies
 298     wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
 299
 300         // get the next sibling of this item
 301     wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 302         // get the previous sibling
 303     wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 304
 305         // get first visible item
 306     wxTreeItemId GetFirstVisibleItem() const;
 307         // get the next visible item: item must be visible itself!
 308         // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
 309     wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
 310         // get the previous visible item: item must be visible itself!
 311     wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
 312
 313     // operations
 314     // ----------
 315
 316         // add the root node to the tree
 317     wxTreeItemId AddRoot(const wxString& text,
 318                          int image = -1, int selectedImage = -1,
 319                          wxTreeItemData *data = NULL);
 320
 321         // insert a new item in as the first child of the parent
 322     wxTreeItemId PrependItem(const wxTreeItemId& parent,
 323                              const wxString& text,
 324                              int image = -1, int selectedImage = -1,
 325                              wxTreeItemData *data = NULL);
 326
 327         // insert a new item after a given one
 328     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 329                             const wxTreeItemId& idPrevious,
 330                             const wxString& text,
 331                             int image = -1, int selectedImage = -1,
 332                             wxTreeItemData *data = NULL);
 333
 334         // insert a new item before the one with the given index
 335     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 336                             size_t index,
 337                             const wxString& text,
 338                             int image = -1, int selectedImage = -1,
 339                             wxTreeItemData *data = NULL);
 340
 341         // insert a new item in as the last child of the parent
 342     wxTreeItemId AppendItem(const wxTreeItemId& parent,
 343                             const wxString& text,
 344                             int image = -1, int selectedImage = -1,
 345                             wxTreeItemData *data = NULL);
 346
 347         // delete this item and associated data if any
 348     void Delete(const wxTreeItemId& item);
 349         // delete all children (but don't delete the item itself)
 350         // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 351     void DeleteChildren(const wxTreeItemId& item);
 352         // delete all items from the tree
 353         // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 354     void DeleteAllItems();
 355
 356         // expand this item
 357     void Expand(const wxTreeItemId& item);
 358         // collapse the item without removing its children
 359     void Collapse(const wxTreeItemId& item);
 360         // collapse the item and remove all children
 361     void CollapseAndReset(const wxTreeItemId& item);
 362         // toggles the current state
 363     void Toggle(const wxTreeItemId& item);
 364
 365         // remove the selection from currently selected item (if any)
 366     void Unselect();
 367     void UnselectAll();
 368         // select this item
 369     void SelectItem(const wxTreeItemId& item, bool unselect_others=TRUE, bool extended_select=FALSE);
 370         // make sure this item is visible (expanding the parent item and/or
 371         // scrolling to this item if necessary)
 372     void EnsureVisible(const wxTreeItemId& item);
 373         // scroll to this item (but don't expand its parent)
 374     void ScrollTo(const wxTreeItemId& item);
 375
 376         // The first function is more portable (because easier to implement
 377         // on other platforms), but the second one returns some extra info.
 378     wxTreeItemId HitTest(const wxPoint& point)
 379         { int dummy; return HitTest(point, dummy); }
 380     wxTreeItemId HitTest(const wxPoint& point, int& flags);
 381
 382         // Start editing the item label: this (temporarily) replaces the item
 383         // with a one line edit control. The item will be selected if it hadn't
 384         // been before.
 385     void EditLabel( const wxTreeItemId& item ) { Edit( item ); }
 386     void Edit( const wxTreeItemId& item );
 387
 388     // sorting
 389         // this function is called to compare 2 items and should return -1, 0
 390         // or +1 if the first item is less than, equal to or greater than the
 391         // second one. The base class version performs alphabetic comparaison
 392         // of item labels (GetText)
 393     virtual int OnCompareItems(const wxTreeItemId& item1,
 394                                const wxTreeItemId& item2);
 395         // sort the children of this item using OnCompareItems
 396         //
 397         // NB: this function is not reentrant and not MT-safe (FIXME)!
 398     void SortChildren(const wxTreeItemId& item);
 399
 400     // deprecated functions: use Set/GetItemImage directly
 401         // get the selected item image
 402     int GetItemSelectedImage(const wxTreeItemId& item) const
 403         { return GetItemImage(item, wxTreeItemIcon_Selected); }
 404         // set the selected item image
 405     void SetItemSelectedImage(const wxTreeItemId& item, int image)
 406         { SetItemImage(item, image, wxTreeItemIcon_Selected); }
 407
 408     // implementation
 409
 410     // callbacks
 411     void OnPaint( wxPaintEvent &event );
 412     void OnSetFocus( wxFocusEvent &event );
 413     void OnKillFocus( wxFocusEvent &event );
 414     void OnChar( wxKeyEvent &event );
 415     void OnMouse( wxMouseEvent &event );
 416     void OnIdle( wxIdleEvent &event );
 417
 418     // implementation
 419     void SendDeleteEvent(wxGenericTreeItem *itemBeingDeleted);
 420
 421     // Draw Special Information
 422     void DrawBorder(wxTreeItemId& item);
 423     void DrawLine(wxTreeItemId& item, bool below);
 424
 425 protected:
 426     friend class wxGenericTreeItem;
 427     friend class wxTreeRenameTimer;
 428     friend class wxTreeTextCtrl;
 429
 430     wxFont               m_normalFont;
 431     wxFont               m_boldFont;
 432
 433     wxGenericTreeItem   *m_anchor;
 434     wxGenericTreeItem   *m_current, *m_key_current, *m_currentEdit;
 435     bool                 m_hasFocus;
 436     bool                 m_dirty;
 437     int                  m_xScroll,m_yScroll;
 438     unsigned int         m_indent;
 439     unsigned int         m_spacing;
 440     int                  m_lineHeight;
 441     wxPen                m_dottedPen;
 442     wxBrush             *m_hilightBrush;
 443     wxImageList         *m_imageListNormal,
 444                         *m_imageListState;
 445     int                  m_dragCount;
 446     wxPoint              m_dragStart;
 447     wxTimer             *m_renameTimer;
 448     bool                 m_renameAccept;
 449     wxString             m_renameRes;
 450
 451     // the common part of all ctors
 452     void Init();
 453
 454     // misc helpers
 455     wxTreeItemId DoInsertItem(const wxTreeItemId& parent,
 456                               size_t previous,
 457                               const wxString& text,
 458                               int image, int selectedImage,
 459                               wxTreeItemData *data);
 460
 461     void AdjustMyScrollbars();
 462     int  GetLineHeight(wxGenericTreeItem *item) const;
 463     void PaintLevel( wxGenericTreeItem *item, wxDC& dc, int level, int &y );
 464     void PaintItem( wxGenericTreeItem *item, wxDC& dc);
 465
 466     void CalculateLevel( wxGenericTreeItem *item, wxDC &dc, int level, int &y );
 467     void CalculatePositions();
 468     void CalculateSize( wxGenericTreeItem *item, wxDC &dc );
 469
 470     void RefreshSubtree( wxGenericTreeItem *item );
 471     void RefreshLine( wxGenericTreeItem *item );
 472
 473     void OnRenameTimer();
 474     void OnRenameAccept();
 475
 476     void FillArray(wxGenericTreeItem*, wxArrayTreeItemIds&) const;
 477     void SelectItemRange( wxGenericTreeItem *item1, wxGenericTreeItem *item2 );
 478     bool TagAllChildrenUntilLast(wxGenericTreeItem *crt_item, wxGenericTreeItem *last_item, bool select);
 479     bool TagNextChildren(wxGenericTreeItem *crt_item, wxGenericTreeItem *last_item, bool select);
 480     void UnselectAllChildren( wxGenericTreeItem *item );
 481
 482 private:
 483     DECLARE_EVENT_TABLE()
 484     DECLARE_DYNAMIC_CLASS(wxTreeCtrl)
 485 };
 486
 487 #endif // _GENERIC_TREECTRL_H_
 488