contrib/include/wx/gizmos/treelistctrl.h

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