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

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