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 // wxTreeCtrl - the tree control
 101 // -----------------------------------------------------------------------------
 102
 103 class WXDLLEXPORT wxTreeCtrl : public wxScrolledWindow
 104 {
 105 public:
 106     // creation
 107     // --------
 108     wxTreeCtrl() { Init(); }
 109
 110     wxTreeCtrl(wxWindow *parent, wxWindowID id = -1,
 111                const wxPoint& pos = wxDefaultPosition,
 112                const wxSize& size = wxDefaultSize,
 113                long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
 114                const wxValidator &validator = wxDefaultValidator,
 115                const wxString& name = wxTreeCtrlNameStr)
 116     {
 117         Create(parent, id, pos, size, style, validator, name);
 118     }
 119
 120     virtual ~wxTreeCtrl();
 121
 122     bool Create(wxWindow *parent, wxWindowID id = -1,
 123                 const wxPoint& pos = wxDefaultPosition,
 124                 const wxSize& size = wxDefaultSize,
 125                 long style = wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT,
 126                 const wxValidator &validator = wxDefaultValidator,
 127                 const wxString& name = wxTreeCtrlNameStr);
 128
 129     // accessors
 130     // ---------
 131
 132         // get the total number of items in the control
 133     size_t GetCount() const;
 134
 135         // indent is the number of pixels the children are indented relative to
 136         // the parents position. SetIndent() also redraws the control
 137         // immediately.
 138     unsigned int GetIndent() const { return m_indent; }
 139     void SetIndent(unsigned int indent);
 140
 141         // spacing is the number of pixels between the start and the Text
 142     unsigned int GetSpacing() const { return m_spacing; }
 143     void SetSpacing(unsigned int spacing);
 144
 145         // image list: these functions allow to associate an image list with
 146         // the control and retrieve it. Note that the control does _not_ delete
 147         // the associated image list when it's deleted in order to allow image
 148         // lists to be shared between different controls.
 149         //
 150         // The normal image list is for the icons which correspond to the
 151         // normal tree item state (whether it is selected or not).
 152         // Additionally, the application might choose to show a state icon
 153         // which corresponds to an app-defined item state (for example,
 154         // checked/unchecked) which are taken from the state image list.
 155     wxImageList *GetImageList() const;
 156     wxImageList *GetStateImageList() const;
 157
 158     void SetImageList(wxImageList *imageList);
 159     void SetStateImageList(wxImageList *imageList);
 160
 161     // Functions to work with tree ctrl items.
 162
 163     // accessors
 164     // ---------
 165
 166         // retrieve items label
 167     wxString GetItemText(const wxTreeItemId& item) const;
 168         // get one of the images associated with the item (normal by default)
 169     int GetItemImage(const wxTreeItemId& item,
 170                      wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
 171         // get the data associated with the item
 172     wxTreeItemData *GetItemData(const wxTreeItemId& item) const;
 173
 174     // modifiers
 175     // ---------
 176
 177         // set items label
 178     void SetItemText(const wxTreeItemId& item, const wxString& text);
 179         // get one of the images associated with the item (normal by default)
 180     void SetItemImage(const wxTreeItemId& item, int image,
 181                       wxTreeItemIcon which = wxTreeItemIcon_Normal);
 182         // associate some data with the item
 183     void SetItemData(const wxTreeItemId& item, wxTreeItemData *data);
 184
 185         // force appearance of [+] button near the item. This is useful to
 186         // allow the user to expand the items which don't have any children now
 187         // - but instead add them only when needed, thus minimizing memory
 188         // usage and loading time.
 189     void SetItemHasChildren(const wxTreeItemId& item, bool has = TRUE);
 190
 191         // the item will be shown in bold
 192     void SetItemBold(const wxTreeItemId& item, bool bold = TRUE);
 193
 194         // set the items text colour
 195     void SetItemTextColour(const wxTreeItemId& item, const wxColour& col);
 196
 197         // set the items background colour
 198     void SetItemBackgroundColour(const wxTreeItemId& item, const wxColour& col);
 199
 200         // set the items font (should be of the same height for all items)
 201     void SetItemFont(const wxTreeItemId& item, const wxFont& font);
 202
 203     // item status inquiries
 204     // ---------------------
 205
 206         // is the item visible (it might be outside the view or not expanded)?
 207     bool IsVisible(const wxTreeItemId& item) const;
 208         // does the item has any children?
 209     bool HasChildren(const wxTreeItemId& item) const
 210       { return ItemHasChildren(item); }
 211     bool ItemHasChildren(const wxTreeItemId& item) const;
 212         // is the item expanded (only makes sense if HasChildren())?
 213     bool IsExpanded(const wxTreeItemId& item) const;
 214         // is this item currently selected (the same as has focus)?
 215     bool IsSelected(const wxTreeItemId& item) const;
 216         // is item text in bold font?
 217     bool IsBold(const wxTreeItemId& item) const;
 218
 219     // number of children
 220     // ------------------
 221
 222         // if 'recursively' is FALSE, only immediate children count, otherwise
 223         // the returned number is the number of all items in this branch
 224     size_t GetChildrenCount(const wxTreeItemId& item, bool recursively = TRUE);
 225
 226     // navigation
 227     // ----------
 228
 229     // wxTreeItemId.IsOk() will return FALSE if there is no such item
 230
 231         // get the root tree item
 232     wxTreeItemId GetRootItem() const { return m_anchor; }
 233
 234         // get the item currently selected (may return NULL if no selection)
 235     wxTreeItemId GetSelection() const { return m_current; }
 236
 237         // get the items currently selected, return the number of such item
 238     size_t GetSelections(wxArrayTreeItemIds&) const;
 239
 240         // get the parent of this item (may return NULL if root)
 241     wxTreeItemId GetParent(const wxTreeItemId& item) const;
 242
 243         // for this enumeration function you must pass in a "cookie" parameter
 244         // which is opaque for the application but is necessary for the library
 245         // to make these functions reentrant (i.e. allow more than one
 246         // enumeration on one and the same object simultaneously). Of course,
 247         // the "cookie" passed to GetFirstChild() and GetNextChild() should be
 248         // the same!
 249
 250         // get the first child of this item
 251     wxTreeItemId GetFirstChild(const wxTreeItemId& item, long& cookie) const;
 252         // get the next child
 253     wxTreeItemId GetNextChild(const wxTreeItemId& item, long& cookie) const;
 254         // get the last child of this item - this method doesn't use cookies
 255     wxTreeItemId GetLastChild(const wxTreeItemId& item) const;
 256
 257         // get the next sibling of this item
 258     wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 259         // get the previous sibling
 260     wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 261
 262         // get first visible item
 263     wxTreeItemId GetFirstVisibleItem() const;
 264         // get the next visible item: item must be visible itself!
 265         // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
 266     wxTreeItemId GetNextVisible(const wxTreeItemId& item) const;
 267         // get the previous visible item: item must be visible itself!
 268     wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const;
 269
 270     // operations
 271     // ----------
 272
 273         // add the root node to the tree
 274     wxTreeItemId AddRoot(const wxString& text,
 275                          int image = -1, int selectedImage = -1,
 276                          wxTreeItemData *data = NULL);
 277
 278         // insert a new item in as the first child of the parent
 279     wxTreeItemId PrependItem(const wxTreeItemId& parent,
 280                              const wxString& text,
 281                              int image = -1, int selectedImage = -1,
 282                              wxTreeItemData *data = NULL);
 283
 284         // insert a new item after a given one
 285     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 286                             const wxTreeItemId& idPrevious,
 287                             const wxString& text,
 288                             int image = -1, int selectedImage = -1,
 289                             wxTreeItemData *data = NULL);
 290
 291         // insert a new item before the one with the given index
 292     wxTreeItemId InsertItem(const wxTreeItemId& parent,
 293                             size_t index,
 294                             const wxString& text,
 295                             int image = -1, int selectedImage = -1,
 296                             wxTreeItemData *data = NULL);
 297
 298         // insert a new item in as the last child of the parent
 299     wxTreeItemId AppendItem(const wxTreeItemId& parent,
 300                             const wxString& text,
 301                             int image = -1, int selectedImage = -1,
 302                             wxTreeItemData *data = NULL);
 303
 304         // delete this item and associated data if any
 305     void Delete(const wxTreeItemId& item);
 306         // delete all children (but don't delete the item itself)
 307         // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 308     void DeleteChildren(const wxTreeItemId& item);
 309         // delete all items from the tree
 310         // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 311     void DeleteAllItems();
 312
 313         // expand this item
 314     void Expand(const wxTreeItemId& item);
 315         // expand this item and all subitems recursively
 316     void ExpandAll(const wxTreeItemId& item);
 317         // collapse the item without removing its children
 318     void Collapse(const wxTreeItemId& item);
 319         // collapse the item and remove all children
 320     void CollapseAndReset(const wxTreeItemId& item);
 321         // toggles the current state
 322     void Toggle(const wxTreeItemId& item);
 323
 324         // remove the selection from currently selected item (if any)
 325     void Unselect();
 326     void UnselectAll();
 327         // select this item
 328     void SelectItem(const wxTreeItemId& item, bool unselect_others=TRUE, bool extended_select=FALSE);
 329         // make sure this item is visible (expanding the parent item and/or
 330         // scrolling to this item if necessary)
 331     void EnsureVisible(const wxTreeItemId& item);
 332         // scroll to this item (but don't expand its parent)
 333     void ScrollTo(const wxTreeItemId& item);
 334
 335         // The first function is more portable (because easier to implement
 336         // on other platforms), but the second one returns some extra info.
 337     wxTreeItemId HitTest(const wxPoint& point)
 338         { int dummy; return HitTest(point, dummy); }
 339     wxTreeItemId HitTest(const wxPoint& point, int& flags);
 340
 341         // Start editing the item label: this (temporarily) replaces the item
 342         // with a one line edit control. The item will be selected if it hadn't
 343         // been before.
 344     void EditLabel( const wxTreeItemId& item ) { Edit( item ); }
 345     void Edit( const wxTreeItemId& item );
 346
 347     // sorting
 348         // this function is called to compare 2 items and should return -1, 0
 349         // or +1 if the first item is less than, equal to or greater than the
 350         // second one. The base class version performs alphabetic comparaison
 351         // of item labels (GetText)
 352     virtual int OnCompareItems(const wxTreeItemId& item1,
 353                                const wxTreeItemId& item2);
 354         // sort the children of this item using OnCompareItems
 355         //
 356         // NB: this function is not reentrant and not MT-safe (FIXME)!
 357     void SortChildren(const wxTreeItemId& item);
 358
 359     // deprecated functions: use Set/GetItemImage directly
 360         // get the selected item image
 361     int GetItemSelectedImage(const wxTreeItemId& item) const
 362         { return GetItemImage(item, wxTreeItemIcon_Selected); }
 363         // set the selected item image
 364     void SetItemSelectedImage(const wxTreeItemId& item, int image)
 365         { SetItemImage(item, image, wxTreeItemIcon_Selected); }
 366
 367     // implementation only from now on
 368
 369     // callbacks
 370     void OnPaint( wxPaintEvent &event );
 371     void OnSetFocus( wxFocusEvent &event );
 372     void OnKillFocus( wxFocusEvent &event );
 373     void OnChar( wxKeyEvent &event );
 374     void OnMouse( wxMouseEvent &event );
 375     void OnIdle( wxIdleEvent &event );
 376
 377     // implementation helpers
 378     void SendDeleteEvent(wxGenericTreeItem *itemBeingDeleted);
 379
 380     void DrawBorder(const wxTreeItemId& item);
 381     void DrawLine(const wxTreeItemId& item, bool below);
 382
 383 protected:
 384     friend class wxGenericTreeItem;
 385     friend class wxTreeRenameTimer;
 386     friend class wxTreeTextCtrl;
 387
 388     wxFont               m_normalFont;
 389     wxFont               m_boldFont;
 390
 391     wxGenericTreeItem   *m_anchor;
 392     wxGenericTreeItem   *m_current, *m_key_current, *m_currentEdit;
 393     bool                 m_hasFocus;
 394     bool                 m_dirty;
 395     int                  m_xScroll,m_yScroll;
 396     unsigned int         m_indent;
 397     unsigned int         m_spacing;
 398     int                  m_lineHeight;
 399     wxPen                m_dottedPen;
 400     wxBrush             *m_hilightBrush;
 401     wxImageList         *m_imageListNormal,
 402                         *m_imageListState;
 403
 404     int                  m_dragCount;
 405     wxPoint              m_dragStart;
 406     bool                 m_isDragging; // true between BEGIN/END drag events
 407     wxGenericTreeItem   *m_dropTarget;
 408     wxCursor             m_oldCursor;  // cursor is changed while dragging
 409     wxGenericTreeItem   *m_oldSelection;
 410
 411     wxTimer             *m_renameTimer;
 412     bool                 m_renameAccept;
 413     bool                 m_lastOnSame;  // last click on the same item as prev
 414     wxString             m_renameRes;
 415
 416     // the common part of all ctors
 417     void Init();
 418
 419     // misc helpers
 420     wxTreeItemId DoInsertItem(const wxTreeItemId& parent,
 421                               size_t previous,
 422                               const wxString& text,
 423                               int image, int selectedImage,
 424                               wxTreeItemData *data);
 425
 426     void AdjustMyScrollbars();
 427     int  GetLineHeight(wxGenericTreeItem *item) const;
 428     void PaintLevel( wxGenericTreeItem *item, wxDC& dc, int level, int &y );
 429     void PaintItem( wxGenericTreeItem *item, wxDC& dc);
 430
 431     void CalculateLevel( wxGenericTreeItem *item, wxDC &dc, int level, int &y );
 432     void CalculatePositions();
 433     void CalculateSize( wxGenericTreeItem *item, wxDC &dc );
 434
 435     void RefreshSubtree( wxGenericTreeItem *item );
 436     void RefreshLine( wxGenericTreeItem *item );
 437
 438     void OnRenameTimer();
 439     void OnRenameAccept();
 440
 441     void FillArray(wxGenericTreeItem*, wxArrayTreeItemIds&) const;
 442     void SelectItemRange( wxGenericTreeItem *item1, wxGenericTreeItem *item2 );
 443     bool TagAllChildrenUntilLast(wxGenericTreeItem *crt_item, wxGenericTreeItem *last_item, bool select);
 444     bool TagNextChildren(wxGenericTreeItem *crt_item, wxGenericTreeItem *last_item, bool select);
 445     void UnselectAllChildren( wxGenericTreeItem *item );
 446
 447     void DrawDropEffect(wxGenericTreeItem *item);
 448
 449 private:
 450     DECLARE_EVENT_TABLE()
 451     DECLARE_DYNAMIC_CLASS(wxTreeCtrl)
 452 };
 453
 454 #endif // _GENERIC_TREECTRL_H_
 455