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