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.2 2008/09/30 08:41:54 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     // get the items currently selected, return the number of such item
 375     size_t GetSelections (wxArrayTreeItemIds&) const;
 376
 377     // get the parent of this item (may return NULL if root)
 378     wxTreeItemId GetItemParent (const wxTreeItemId& item) const;
 379
 380     // for this enumeration function you must pass in a "cookie" parameter
 381     // which is opaque for the application but is necessary for the library
 382     // to make these functions reentrant (i.e. allow more than one
 383     // enumeration on one and the same object simultaneously). Of course,
 384     // the "cookie" passed to GetFirstChild() and GetNextChild() should be
 385     // the same!
 386
 387     // get child of this item
 388 #if !wxCHECK_VERSION(2, 5, 0)
 389     wxTreeItemId GetFirstChild(const wxTreeItemId& item, long& cookie) const;
 390     wxTreeItemId GetNextChild(const wxTreeItemId& item, long& cookie) const;
 391     wxTreeItemId GetPrevChild(const wxTreeItemId& item, long& cookie) const;
 392     wxTreeItemId GetLastChild(const wxTreeItemId& item, long& cookie) const;
 393 #else
 394     wxTreeItemId GetFirstChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
 395     wxTreeItemId GetNextChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
 396     wxTreeItemId GetPrevChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
 397     wxTreeItemId GetLastChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
 398 #endif
 399
 400     // get sibling of this item
 401     wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
 402     wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
 403
 404     // get item in the full tree (currently only for internal use)
 405     wxTreeItemId GetNext(const wxTreeItemId& item) const;
 406     wxTreeItemId GetPrev(const wxTreeItemId& item) const;
 407
 408     // get expanded item, see IsExpanded()
 409     wxTreeItemId GetFirstExpandedItem() const;
 410     wxTreeItemId GetNextExpanded(const wxTreeItemId& item) const;
 411     wxTreeItemId GetPrevExpanded(const wxTreeItemId& item) const;
 412
 413     // get visible item, see IsVisible()
 414     wxTreeItemId GetFirstVisibleItem(bool fullRow = false) const;
 415     wxTreeItemId GetNextVisible(const wxTreeItemId& item, bool fullRow = false) const;
 416     wxTreeItemId GetPrevVisible(const wxTreeItemId& item, bool fullRow = false) const;
 417
 418     // operations
 419     // ----------
 420
 421     // add the root node to the tree
 422     wxTreeItemId AddRoot (const wxString& text,
 423                           int image = -1, int selectedImage = -1,
 424                           wxTreeItemData *data = NULL);
 425
 426     // insert a new item in as the first child of the parent
 427     wxTreeItemId PrependItem (const wxTreeItemId& parent,
 428                               const wxString& text,
 429                               int image = -1, int selectedImage = -1,
 430                               wxTreeItemData *data = NULL);
 431
 432     // insert a new item after a given one
 433     wxTreeItemId InsertItem (const wxTreeItemId& parent,
 434                              const wxTreeItemId& idPrevious,
 435                              const wxString& text,
 436                              int image = -1, int selectedImage = -1,
 437                              wxTreeItemData *data = NULL);
 438
 439     // insert a new item before the one with the given index
 440     wxTreeItemId InsertItem (const wxTreeItemId& parent,
 441                              size_t index,
 442                              const wxString& text,
 443                              int image = -1, int selectedImage = -1,
 444                              wxTreeItemData *data = NULL);
 445
 446     // insert a new item in as the last child of the parent
 447     wxTreeItemId AppendItem (const wxTreeItemId& parent,
 448                              const wxString& text,
 449                              int image = -1, int selectedImage = -1,
 450                              wxTreeItemData *data = NULL);
 451
 452     // delete this item (except root) and associated data if any
 453     void Delete (const wxTreeItemId& item);
 454     // delete all children (but don't delete the item itself)
 455     // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 456     void DeleteChildren (const wxTreeItemId& item);
 457     // delete the root and all its children from the tree
 458     // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
 459     void DeleteRoot();
 460
 461     // expand this item
 462     void Expand (const wxTreeItemId& item);
 463     // expand this item and all subitems recursively
 464     void ExpandAll (const wxTreeItemId& item);
 465     // collapse the item without removing its children
 466     void Collapse (const wxTreeItemId& item);
 467     // collapse the item and remove all children
 468     void CollapseAndReset(const wxTreeItemId& item); //? TODO ???
 469     // toggles the current state
 470     void Toggle (const wxTreeItemId& item);
 471
 472   // remove the selection from currently selected item (if any)
 473   // LG 19/09/08 : Added
 474   void Unselect(wxTreeItemId& item);
 475     void Unselect();
 476     void UnselectAll();
 477     // select this item
 478     void SelectItem (const wxTreeItemId& item,
 479                      const wxTreeItemId& last = (wxTreeItemId*)NULL,
 480                      bool unselect_others = true);
 481     // select all items in the expanded tree
 482     void SelectAll();
 483     // make sure this item is visible (expanding the parent item and/or
 484     // scrolling to this item if necessary)
 485     void EnsureVisible (const wxTreeItemId& item);
 486     // scroll to this item (but don't expand its parent)
 487     void ScrollTo (const wxTreeItemId& item);
 488
 489     // The first function is more portable (because easier to implement
 490     // on other platforms), but the second one returns some extra info.
 491     wxTreeItemId HitTest (const wxPoint& point)
 492         { int flags; int column; return HitTest (point, flags, column); }
 493     wxTreeItemId HitTest (const wxPoint& point, int& flags)
 494         { int column; return HitTest (point, flags, column); }
 495     wxTreeItemId HitTest (const wxPoint& point, int& flags, int& column);
 496
 497     // get the bounding rectangle of the item (or of its label only)
 498     bool GetBoundingRect (const wxTreeItemId& item, wxRect& rect,
 499                           bool textOnly = false) const;
 500
 501     // Start editing the item label: this (temporarily) replaces the item
 502     // with a one line edit control. The item will be selected if it hadn't
 503     // been before.
 504     void EditLabel (const wxTreeItemId& item)
 505         { EditLabel (item, GetMainColumn()); }
 506     // edit item's label of the given column
 507     void EditLabel (const wxTreeItemId& item, int column);
 508
 509     // virtual mode
 510     virtual wxString OnGetItemText( wxTreeItemData* item, long column ) const;
 511
 512     // sorting
 513     // this function is called to compare 2 items and should return -1, 0
 514     // or +1 if the first item is less than, equal to or greater than the
 515     // second one. The base class version performs alphabetic comparaison
 516     // of item labels (GetText)
 517     virtual int OnCompareItems (const wxTreeItemId& item1, const wxTreeItemId& item2);
 518     // sort the children of this item using OnCompareItems
 519     // NB: this function is not reentrant and not MT-safe (FIXME)!
 520     void SortChildren(const wxTreeItemId& item);
 521
 522     // searching
 523     wxTreeItemId FindItem (const wxTreeItemId& item, const wxString& str, int mode = 0);
 524
 525     // overridden base class virtuals
 526     virtual bool SetBackgroundColour (const wxColour& colour);
 527     virtual bool SetForegroundColour (const wxColour& colour);
 528
 529     // drop over item
 530     void SetDragItem (const wxTreeItemId& item = (wxTreeItemId*)NULL);
 531
 532
 533     wxTreeListHeaderWindow* GetHeaderWindow() const
 534         { return m_header_win; }
 535
 536     wxTreeListMainWindow* GetMainWindow() const
 537         { return m_main_win; }
 538
 539     virtual wxSize DoGetBestSize() const;
 540
 541 protected:
 542     // header window, responsible for column visualization and manipulation
 543     wxTreeListHeaderWindow* m_header_win;
 544
 545     // main window, the "true" tree ctrl
 546     wxTreeListMainWindow* m_main_win;
 547
 548     void CalculateAndSetHeaderHeight();
 549     void DoHeaderLayout();
 550     void OnSize(wxSizeEvent& event);
 551
 552 private:
 553     int m_headerHeight;
 554
 555     DECLARE_EVENT_TABLE()
 556    // DECLARE_DYNAMIC_CLASS(wxTreeListCtrl)
 557 };
 558
 559 #endif // TREELISTCTRL_H
 560