wxPython/contrib/gizmos/wxCode/include/wx/treelistctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        treelistctrl.h
   3 // Purpose:     wxTreeListCtrl class
   4 // Author:      Robert Roebling
   5 // Maintainer:  Otto Wyss
   6 // Created:     01/02/97
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2004 Robert Roebling, Julian Smart, Alberto Griggio,
   9 //              Vadim Zeitlin, Otto Wyss
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13
  14 #ifndef TREELISTCTRL_H
  15 #define TREELISTCTRL_H
  16
  17 #include <wx/treectrl.h>
  18 #include <wx/control.h>
  19 #include <wx/pen.h>
  20 #include <wx/listctrl.h> // for wxListEvent
  21
  22 #ifdef GIZMOISDLL
  23 #define GIZMODLLEXPORT WXDLLEXPORT
  24 #else
  25 #define GIZMODLLEXPORT
  26 #endif
  27
  28
  29 class GIZMODLLEXPORT wxTreeListItem;
  30 class GIZMODLLEXPORT wxTreeListHeaderWindow;
  31 class GIZMODLLEXPORT wxTreeListMainWindow;
  32
  33 #define wxTR_COLUMN_LINES 0x1000 // put border around items
  34 #define wxTR_VIRTUAL      0x4000 // The application provides items text on demand.
  35
  36 // Using this typedef removes an ambiguity when calling Remove()
  37 #ifdef __WXMSW__
  38 #if !wxCHECK_VERSION(2, 5, 0)
  39 typedef long wxTreeItemIdValue;
  40 #else
  41 typedef void *wxTreeItemIdValue;
  42 #endif
  43 #endif
  44
  45 //-----------------------------------------------------------------------------
  46 // wxTreeListColumnAttrs
  47 //-----------------------------------------------------------------------------
  48
  49 enum {
  50     DEFAULT_COL_WIDTH = 100
  51 };
  52
  53 class GIZMODLLEXPORT wxTreeListColumnInfo: public wxObject {
  54
  55 public:
  56     wxTreeListColumnInfo (const wxString &text = wxEmptyString,
  57                           int width = DEFAULT_COL_WIDTH,
  58                           int flag = wxALIGN_LEFT,
  59                           int image = -1,
  60                           bool shown = true,
  61                           bool edit = false) {
  62         m_text = text;
  63         m_width = width;
  64         m_flag = flag;
  65         m_image = image;
  66         m_selected_image = -1;
  67         m_shown = shown;
  68         m_edit = edit;
  69     }
  70
  71     wxTreeListColumnInfo (const wxTreeListColumnInfo& other) {
  72         m_text = other.m_text;
  73         m_width = other.m_width;
  74         m_flag = other.m_flag;
  75         m_image = other.m_image;
  76         m_selected_image = other.m_selected_image;
  77         m_shown = other.m_shown;
  78         m_edit = other.m_edit;
  79     }
  80
  81     ~wxTreeListColumnInfo() {}
  82
  83     // get/set
  84     wxString GetText() const { return m_text; }
  85     wxTreeListColumnInfo& SetText (const wxString& text) { m_text = text; return *this; }
  86
  87     int GetWidth() const { return m_width; }
  88     wxTreeListColumnInfo& SetWidth (int width) { m_width = width; return *this; }
  89
  90     int GetAlignment() const { return m_flag; }
  91     wxTreeListColumnInfo& SetAlignment (int flag) { m_flag = flag; return *this; }
  92
  93     int GetImage() const { return m_image; }
  94     wxTreeListColumnInfo& SetImage (int image) { m_image = image; return *this; }
  95
  96     int GetSelectedImage() const { return m_selected_image; }
  97     wxTreeListColumnInfo& SetSelectedImage (int image) { m_selected_image = image; return *this; }
  98
  99     bool IsEditable() const { return m_edit; }
 100     wxTreeListColumnInfo& SetEditable (bool edit)
 101         { m_edit = edit; return *this; }
 102
 103     bool IsShown() const { return m_shown; }
 104     wxTreeListColumnInfo& SetShown(bool shown) { m_shown = shown; return *this; }
 105
 106 private:
 107     wxString m_text;
 108     int m_width;
 109     int m_flag;
 110     int m_image;
 111     int m_selected_image;
 112     bool m_shown;
 113     bool m_edit;
 114 };
 115
 116 //----------------------------------------------------------------------------
 117 // wxTreeListCtrl - the multicolumn tree control
 118 //----------------------------------------------------------------------------
 119
 120 // modes for navigation
 121 const int wxTL_MODE_NAV_FULLTREE = 0x0000; // default
 122 const int wxTL_MODE_NAV_EXPANDED = 0x0001;
 123 const int wxTL_MODE_NAV_VISIBLE  = 0x0002;
 124 const int wxTL_MODE_NAV_LEVEL    = 0x0004;
 125
 126 // modes for FindItem
 127 const int wxTL_MODE_FIND_EXACT   = 0x0000; // default
 128 const int wxTL_MODE_FIND_PARTIAL = 0x0010;
 129 const int wxTL_MODE_FIND_NOCASE  = 0x0020;
 130
 131 // additional flag for HitTest
 132 const int wxTREE_HITTEST_ONITEMCOLUMN = 0x2000;
 133 extern GIZMODLLEXPORT const wxChar* wxTreeListCtrlNameStr;
 134
 135
 136 class GIZMODLLEXPORT wxTreeListCtrl : public wxControl
 137 {
 138 public:
 139     // creation
 140     // --------
 141     wxTreeListCtrl()
 142         : m_header_win(0), m_main_win(0), m_headerHeight(0)
 143     {}
 144
 145     wxTreeListCtrl(wxWindow *parent, wxWindowID id = -1,
 146                const wxPoint& pos = wxDefaultPosition,
 147                const wxSize& size = wxDefaultSize,
 148                long style = wxTR_DEFAULT_STYLE,
 149                const wxValidator &validator = wxDefaultValidator,
 150                const wxString& name = wxTreeListCtrlNameStr )
 151         : m_header_win(0), m_main_win(0), m_headerHeight(0)
 152     {
 153         Create(parent, id, pos, size, style, validator, name);
 154     }
 155
 156     virtual ~wxTreeListCtrl() {}
 157
 158     bool Create(wxWindow *parent, wxWindowID id = -1,
 159                 const wxPoint& pos = wxDefaultPosition,
 160                 const wxSize& size = wxDefaultSize,
 161                 long style = wxTR_DEFAULT_STYLE,
 162                 const wxValidator &validator = wxDefaultValidator,
 163                 const wxString& name = wxTreeListCtrlNameStr );
 164
 165     void Refresh(bool erase=TRUE, const wxRect* rect=NULL);
 166     void SetFocus();
 167     // accessors
 168     // ---------
 169
 170     // get the total number of items in the control
 171     size_t GetCount() const;
 172
 173     // indent is the number of pixels the children are indented relative to
 174     // the parents position. SetIndent() also redraws the control
 175     // immediately.
 176     unsigned int GetIndent() const;
 177     void SetIndent(unsigned int indent);
 178
 179     // line spacing is the space above and below the text on each line
 180     unsigned int GetLineSpacing() const;
 181     void SetLineSpacing(unsigned int spacing);
 182
 183     // image list: these functions allow to associate an image list with
 184     // the control and retrieve it. Note that when assigned with
 185     // SetImageList, the control does _not_ delete
 186     // the associated image list when it's deleted in order to allow image
 187     // lists to be shared between different controls. If you use
 188     // AssignImageList, the control _does_ delete the image list.
 189     //
 190     // The normal image list is for the icons which correspond to the
 191     // normal tree item state (whether it is selected or not).
 192     // Additionally, the application might choose to show a state icon
 193     // which corresponds to an app-defined item state (for example,
 194     // checked/unchecked) which are taken from the state image list.
 195     wxImageList *GetImageList() const;
 196     wxImageList *GetStateImageList() const;
 197     wxImageList *GetButtonsImageList() const;
 198
 199     void SetImageList(wxImageList *imageList);
 200     void SetStateImageList(wxImageList *imageList);
 201     void SetButtonsImageList(wxImageList *imageList);
 202     void AssignImageList(wxImageList *imageList);
 203     void AssignStateImageList(wxImageList *imageList);
 204     void AssignButtonsImageList(wxImageList *imageList);
 205
 206
 207     // Functions to work with columns
 208
 209     // adds a column
 210     void AddColumn (const wxString& text,
 211                     int width = DEFAULT_COL_WIDTH,
 212                     int flag = wxALIGN_LEFT,
 213                     int image = -1,
 214                     bool shown = true,
 215                     bool edit = false) {
 216         AddColumn (wxTreeListColumnInfo (text, width, flag, image, shown, edit));
 217     }
 218     void AddColumn (const wxTreeListColumnInfo& colInfo);
 219
 220     // inserts a column before the given one
 221     void InsertColumn (int before,
 222                        const wxString& text,
 223                        int width = DEFAULT_COL_WIDTH,
 224                        int flag = wxALIGN_LEFT,
 225                        int image = -1,
 226                        bool shown = true,
 227                        bool edit = false) {
 228         InsertColumn (before,
 229                       wxTreeListColumnInfo (text, width, flag, image, shown, edit));
 230     }
 231     void InsertColumn (int before, const wxTreeListColumnInfo& colInfo);
 232
 233     // deletes the given column - does not delete the corresponding column
 234     void RemoveColumn (int column);
 235
 236     // returns the number of columns in the ctrl
 237     int GetColumnCount() const;
 238
 239     // tells which column is the "main" one, i.e. the "threaded" one
 240     void SetMainColumn (int column);
 241     int GetMainColumn() const;
 242
 243     void SetColumn (int column, const wxTreeListColumnInfo& colInfo);
 244     wxTreeListColumnInfo& GetColumn (int column);
 245     const wxTreeListColumnInfo& GetColumn (int column) const;
 246
 247     void SetColumnText (int column, const wxString& text);
 248     wxString GetColumnText (int column) const;
 249
 250     void SetColumnWidth (int column, int width);
 251     int GetColumnWidth (int column) const;
 252
 253     void SetColumnAlignment (int column, int flag);
 254     int GetColumnAlignment (int column) const;
 255
 256     void SetColumnImage (int column, int image);
 257     int GetColumnImage (int column) const;
 258
 259     void SetColumnShown (int column, bool shown = true);
 260     bool IsColumnShown (int column) const;
 261
 262     void SetColumnEditable (int column, bool edit = true);
 263     bool IsColumnEditable (int column) const;
 264
 265     // Functions to work with items.
 266
 267     // accessors
 268     // ---------
 269
 270     // retrieve item's label (of the main column)
 271     wxString GetItemText (const wxTreeItemId& item) const
 272         { return GetItemText (item, GetMainColumn()); }
 273     // retrieves item's label of the given column
 274     wxString GetItemText (const wxTreeItemId& item, int column) const;
 275
 276     // get one of the images associated with the item (normal by default)
 277     int GetItemImage (const wxTreeItemId& item,
 278                       wxTreeItemIcon which = wxTreeItemIcon_Normal) const
 279     { return GetItemImage (item, GetMainColumn(), which); }
 280     int GetItemImage (const wxTreeItemId& item, int column,
 281                       wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
 282
 283     // get the data associated with the item
 284     wxTreeItemData *GetItemData (const wxTreeItemId& item) const;
 285
 286     bool GetItemBold (const wxTreeItemId& item) const;
 287     wxColour GetItemTextColour (const wxTreeItemId& item) const;
 288     wxColour GetItemBackgroundColour (const wxTreeItemId& item) const;
 289     wxFont GetItemFont (const wxTreeItemId& item) const;
 290
 291     // modifiers
 292
 293     // set item's label
 294     void SetItemText (const wxTreeItemId& item, const wxString& text)
 295         { SetItemText (item, GetMainColumn(), text); }
 296     void SetItemText (const wxTreeItemId& item, int column, const wxString& text);
 297
 298     // get one of the images associated with the item (normal by default)
 299     void SetItemImage (const wxTreeItemId& item, int image,
 300                        wxTreeItemIcon which = wxTreeItemIcon_Normal)
 301         { SetItemImage (item, GetMainColumn(), image, which); }
 302     // the which parameter is ignored for all columns but the main one
 303     void SetItemImage (const wxTreeItemId& item, int column, int image,
 304                        wxTreeItemIcon which = wxTreeItemIcon_Normal);
 305
 306     // associate some data with the item
 307     void SetItemData (const wxTreeItemId& item, wxTreeItemData *data);
 308
 309     // force appearance of [+] button near the item. This is useful to
 310     // allow the user to expand the items which don't have any children now
 311     // - but instead add them only when needed, thus minimizing memory
 312     // usage and loading time.
 313     void SetItemHasChildren(const wxTreeItemId& item, bool has = true);
 314
 315     // the item will be shown in bold
 316     void SetItemBold (const wxTreeItemId& item, bool bold = true);
 317
 318     // set the item's text colour
 319     void SetItemTextColour (const wxTreeItemId& item, const wxColour& colour);
 320
 321     // set the item's background colour
 322     void SetItemBackgroundColour (const wxTreeItemId& item, const wxColour& colour);
 323
 324     // set the item's font (should be of the same height for all items)
 325     void SetItemFont (const wxTreeItemId& item, const wxFont& font);
 326
 327     // set the window font
 328     virtual bool SetFont ( const wxFont &font );
 329
 330     // set the styles.
 331     void SetWindowStyle (const long styles);
 332     long GetWindowStyle() const;
 333     long GetWindowStyleFlag () const { return GetWindowStyle(); }
 334
 335     // item status inquiries
 336     // ---------------------
 337
 338     // is the item visible (it might be outside the view or not expanded)?
 339     bool IsVisible (const wxTreeItemId& item, bool fullRow = false) const;
 340     // does the item has any children?
 341     bool HasChildren (const wxTreeItemId& item) const;
 342     // is the item expanded (only makes sense if HasChildren())?
 343     bool IsExpanded (const wxTreeItemId& item) const;
 344     // is this item currently selected (the same as has focus)?
 345     bool IsSelected (const wxTreeItemId& item) const;
 346     // is item text in bold font?
 347     bool IsBold (const wxTreeItemId& item) const;
 348     // does the layout include space for a button?
 349
 350     // number of children
 351     // ------------------
 352
 353     // if 'recursively' is FALSE, only immediate children count, otherwise
 354     // the returned number is the number of all items in this branch
 355     size_t GetChildrenCount (const wxTreeItemId& item, bool recursively = true);
 356
 357     // navigation
 358     // ----------
 359
 360     // wxTreeItemId.IsOk() will return FALSE if there is no such item
 361
 362     // get the root tree item
 363     wxTreeItemId GetRootItem() const;
 364
 365     // get the item currently selected (may return NULL if no selection)
 366     wxTreeItemId GetSelection() const;
 367
 368     // get the items currently selected, return the number of such item
 369     size_t GetSelections (wxArrayTreeItemIds&) const;
 370
 371     // get the parent of this item (may return NULL if root)
 372     wxTreeItemId GetItemParent (const wxTreeItemId& item) const;
 373
 374     // for this enumeration function you must pass in a "cookie" parameter
 375     // which is opaque for the application but is necessary for the library
 376     // to make these functions reentrant (i.e. allow more than one
 377     // enumeration on one and the same object simultaneously). Of course,
 378     // the "cookie" passed to GetFirstChild() and GetNextChild() should be
 379     // the same!
 380
 381     // get child of this item
 382 #if !wxCHECK_VERSION(2, 5, 0)
 383     wxTreeItemId GetFirstChild(const wxTreeItemId& item, long& cookie) const;
 384     wxTreeItemId GetNextChild(const wxTreeItemId& item, long& cookie) const;
 385     wxTreeItemId GetPrevChild(const wxTreeItemId& item, long& cookie) const;
 386     wxTreeItemId GetLastChild(const wxTreeItemId& item, long& cookie) const;
 387 #else
 388     wxTreeItemId GetFirstChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
 389     wxTreeItemId GetNextChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
 390     wxTreeItemId GetPrevChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
 391     wxTreeItemId GetLastChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
 392 #endif
 393
 394     // get sibling of this item
 395     wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 396     wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 397
 398     // get item in the full tree (currently only for internal use)
 399     wxTreeItemId GetNext(const wxTreeItemId& item) const;
 400     wxTreeItemId GetPrev(const wxTreeItemId& item) const;
 401
 402     // get expanded item, see IsExpanded()
 403     wxTreeItemId GetFirstExpandedItem() const;
 404     wxTreeItemId GetNextExpanded(const wxTreeItemId& item) const;
 405     wxTreeItemId GetPrevExpanded(const wxTreeItemId& item) const;
 406
 407     // get visible item, see IsVisible()
 408     wxTreeItemId GetFirstVisibleItem(bool fullRow = false) const;
 409     wxTreeItemId GetNextVisible(const wxTreeItemId& item, bool fullRow = false) const;
 410     wxTreeItemId GetPrevVisible(const wxTreeItemId& item, bool fullRow = false) const;
 411
 412     // operations
 413     // ----------
 414
 415     // add the root node to the tree
 416     wxTreeItemId AddRoot (const wxString& text,
 417                           int image = -1, int selectedImage = -1,
 418                           wxTreeItemData *data = NULL);
 419
 420     // insert a new item in as the first child of the parent
 421     wxTreeItemId PrependItem (const wxTreeItemId& parent,
 422                               const wxString& text,
 423                               int image = -1, int selectedImage = -1,
 424                               wxTreeItemData *data = NULL);
 425
 426     // insert a new item after a given one
 427     wxTreeItemId InsertItem (const wxTreeItemId& parent,
 428                              const wxTreeItemId& idPrevious,
 429                              const wxString& text,
 430                              int image = -1, int selectedImage = -1,
 431                              wxTreeItemData *data = NULL);
 432
 433     // insert a new item before the one with the given index
 434     wxTreeItemId InsertItem (const wxTreeItemId& parent,
 435                              size_t index,
 436                              const wxString& text,
 437                              int image = -1, int selectedImage = -1,
 438                              wxTreeItemData *data = NULL);
 439
 440     // insert a new item in as the last child of the parent
 441     wxTreeItemId AppendItem (const wxTreeItemId& parent,
 442                              const wxString& text,
 443                              int image = -1, int selectedImage = -1,
 444                              wxTreeItemData *data = NULL);
 445
 446     // delete this item (except root) and associated data if any
 447     void Delete (const wxTreeItemId& item);
 448     // delete all children (but don't delete the item itself)
 449     // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 450     void DeleteChildren (const wxTreeItemId& item);
 451     // delete the root and all its children from the tree
 452     // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 453     void DeleteRoot();
 454
 455     // expand this item
 456     void Expand (const wxTreeItemId& item);
 457     // expand this item and all subitems recursively
 458     void ExpandAll (const wxTreeItemId& item);
 459     // collapse the item without removing its children
 460     void Collapse (const wxTreeItemId& item);
 461     // collapse the item and remove all children
 462     void CollapseAndReset(const wxTreeItemId& item); //? TODO ???
 463     // toggles the current state
 464     void Toggle (const wxTreeItemId& item);
 465
 466     // remove the selection from currently selected item (if any)
 467     void Unselect();
 468     void UnselectAll();
 469     // select this item
 470     void SelectItem (const wxTreeItemId& item,
 471                      const wxTreeItemId& last = (wxTreeItemId*)NULL,
 472                      bool unselect_others = true);
 473     // select all items in the expanded tree
 474     void SelectAll();
 475     // make sure this item is visible (expanding the parent item and/or
 476     // scrolling to this item if necessary)
 477     void EnsureVisible (const wxTreeItemId& item);
 478     // scroll to this item (but don't expand its parent)
 479     void ScrollTo (const wxTreeItemId& item);
 480
 481     // The first function is more portable (because easier to implement
 482     // on other platforms), but the second one returns some extra info.
 483     wxTreeItemId HitTest (const wxPoint& point)
 484         { int flags; int column; return HitTest (point, flags, column); }
 485     wxTreeItemId HitTest (const wxPoint& point, int& flags)
 486         { int column; return HitTest (point, flags, column); }
 487     wxTreeItemId HitTest (const wxPoint& point, int& flags, int& column);
 488
 489     // get the bounding rectangle of the item (or of its label only)
 490     bool GetBoundingRect (const wxTreeItemId& item, wxRect& rect,
 491                           bool textOnly = false) const;
 492
 493     // Start editing the item label: this (temporarily) replaces the item
 494     // with a one line edit control. The item will be selected if it hadn't
 495     // been before.
 496     void EditLabel (const wxTreeItemId& item)
 497         { EditLabel (item, GetMainColumn()); }
 498     // edit item's label of the given column
 499     void EditLabel (const wxTreeItemId& item, int column);
 500
 501     // virtual mode
 502     virtual wxString OnGetItemText( wxTreeItemData* item, long column ) const;
 503
 504     // sorting
 505     // this function is called to compare 2 items and should return -1, 0
 506     // or +1 if the first item is less than, equal to or greater than the
 507     // second one. The base class version performs alphabetic comparaison
 508     // of item labels (GetText)
 509     virtual int OnCompareItems (const wxTreeItemId& item1, const wxTreeItemId& item2);
 510     // sort the children of this item using OnCompareItems
 511     // NB: this function is not reentrant and not MT-safe (FIXME)!
 512     void SortChildren(const wxTreeItemId& item);
 513
 514     // searching
 515     wxTreeItemId FindItem (const wxTreeItemId& item, const wxString& str, int mode = 0);
 516
 517     // overridden base class virtuals
 518     virtual bool SetBackgroundColour (const wxColour& colour);
 519     virtual bool SetForegroundColour (const wxColour& colour);
 520
 521     // drop over item
 522     void SetDragItem (const wxTreeItemId& item = (wxTreeItemId*)NULL);
 523
 524
 525     wxTreeListHeaderWindow* GetHeaderWindow() const
 526         { return m_header_win; }
 527
 528     wxTreeListMainWindow* GetMainWindow() const
 529         { return m_main_win; }
 530
 531     virtual wxSize DoGetBestSize() const;
 532
 533 protected:
 534     // header window, responsible for column visualization and manipulation
 535     wxTreeListHeaderWindow* m_header_win;
 536
 537     // main window, the "true" tree ctrl
 538     wxTreeListMainWindow* m_main_win;
 539
 540     void CalculateAndSetHeaderHeight();
 541     void DoHeaderLayout();
 542     void OnSize(wxSizeEvent& event);
 543
 544 private:
 545     int m_headerHeight;
 546
 547     DECLARE_EVENT_TABLE()
 548     DECLARE_DYNAMIC_CLASS(wxTreeListCtrl)
 549 };
 550
 551 #endif // TREELISTCTRL_H
 552