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