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