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