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