1 /////////////////////////////////////////////////////////////////////////////
2 // Name: treelistctrl.h
3 // Purpose: wxTreeListCtrl class
4 // Author: Robert Roebling
5 // Maintainer: Otto Wyss
7 // RCS-ID: $Id: treelistctrl.h,v 1.3 2008/10/01 14:23:59 guigues Exp $
8 // Copyright: (c) 2004 Robert Roebling, Julian Smart, Alberto Griggio,
9 // Vadim Zeitlin, Otto Wyss
11 /////////////////////////////////////////////////////////////////////////////
14 #ifndef TREELISTCTRL_H
15 #define TREELISTCTRL_H
22 #if defined(__GNUG__) && !defined(__APPLE__)
23 #pragma interface "treelistctrl.h"
26 #include <creaImageIOSystem.h>
29 #include <wx/treectrl.h>
30 #include <wx/control.h>
32 #include <wx/listctrl.h> // for wxListEvent
35 class CREAIMAGEIO_EXPORT wxTreeListItem;
36 class CREAIMAGEIO_EXPORT wxTreeListHeaderWindow;
37 class CREAIMAGEIO_EXPORT wxTreeListMainWindow;
39 #define wxTR_VIRTUAL 0x1000 // The application provides items text on demand.
41 // Using this typedef removes an ambiguity when calling Remove()
43 #if !wxCHECK_VERSION(2, 5, 0)
44 typedef long wxTreeItemIdValue;
46 typedef void *wxTreeItemIdValue;
50 //-----------------------------------------------------------------------------
51 // wxTreeListColumnAttrs
52 //-----------------------------------------------------------------------------
55 DEFAULT_COL_WIDTH = 100
58 class CREAIMAGEIO_EXPORT wxTreeListColumnInfo: public wxObject {
61 wxTreeListColumnInfo (const wxString &text = wxEmptyString,
62 int width = DEFAULT_COL_WIDTH,
63 int flag = wxALIGN_LEFT,
71 m_selected_image = -1;
76 wxTreeListColumnInfo (const wxTreeListColumnInfo& other) {
77 m_text = other.m_text;
78 m_width = other.m_width;
79 m_flag = other.m_flag;
80 m_image = other.m_image;
81 m_selected_image = other.m_selected_image;
82 m_shown = other.m_shown;
83 m_edit = other.m_edit;
86 ~wxTreeListColumnInfo() {}
89 wxString GetText() const { return m_text; }
90 wxTreeListColumnInfo& SetText (const wxString& text) { m_text = text; return *this; }
92 int GetWidth() const { return m_width; }
93 wxTreeListColumnInfo& SetWidth (int width) { m_width = width; return *this; }
95 int GetAlignment() const { return m_flag; }
96 wxTreeListColumnInfo& SetAlignment (int flag) { m_flag = flag; return *this; }
98 int GetImage() const { return m_image; }
99 wxTreeListColumnInfo& SetImage (int image) { m_image = image; return *this; }
101 int GetSelectedImage() const { return m_selected_image; }
102 wxTreeListColumnInfo& SetSelectedImage (int image) { m_selected_image = image; return *this; }
104 bool IsEditable() const { return m_edit; }
105 wxTreeListColumnInfo& SetEditable (bool edit)
106 { m_edit = edit; return *this; }
108 bool IsShown() const { return m_shown; }
109 wxTreeListColumnInfo& SetShown(bool shown) { m_shown = shown; return *this; }
116 int m_selected_image;
121 //----------------------------------------------------------------------------
122 // wxTreeListCtrl - the multicolumn tree control
123 //----------------------------------------------------------------------------
125 // modes for navigation
126 const int wxTL_MODE_NAV_FULLTREE = 0x0000; // default
127 const int wxTL_MODE_NAV_EXPANDED = 0x0001;
128 const int wxTL_MODE_NAV_VISIBLE = 0x0002;
129 const int wxTL_MODE_NAV_LEVEL = 0x0004;
131 // modes for FindItem
132 const int wxTL_MODE_FIND_EXACT = 0x0000; // default
133 const int wxTL_MODE_FIND_PARTIAL = 0x0010;
134 const int wxTL_MODE_FIND_NOCASE = 0x0020;
136 // additional flag for HitTest
137 const int wxTREE_HITTEST_ONITEMCOLUMN = 0x2000;
138 extern CREAIMAGEIO_EXPORT const wxChar* wxTreeListCtrlNameStr;
141 class CREAIMAGEIO_EXPORT wxTreeListCtrl : public wxControl
147 : m_header_win(0), m_main_win(0), m_headerHeight(0)
150 wxTreeListCtrl(wxWindow *parent, wxWindowID id = -1,
151 const wxPoint& pos = wxDefaultPosition,
152 const wxSize& size = wxDefaultSize,
153 long style = wxTR_DEFAULT_STYLE,
154 const wxValidator &validator = wxDefaultValidator,
155 const wxString& name = wxTreeListCtrlNameStr )
156 : m_header_win(0), m_main_win(0), m_headerHeight(0)
158 Create(parent, id, pos, size, style, validator, name);
161 virtual ~wxTreeListCtrl() {}
163 bool Create(wxWindow *parent, wxWindowID id = -1,
164 const wxPoint& pos = wxDefaultPosition,
165 const wxSize& size = wxDefaultSize,
166 long style = wxTR_DEFAULT_STYLE,
167 const wxValidator &validator = wxDefaultValidator,
168 const wxString& name = wxTreeListCtrlNameStr );
170 void Refresh(bool erase=TRUE, const wxRect* rect=NULL);
175 // get the total number of items in the control
176 size_t GetCount() const;
178 // indent is the number of pixels the children are indented relative to
179 // the parents position. SetIndent() also redraws the control
181 unsigned int GetIndent() const;
182 void SetIndent(unsigned int indent);
184 // line spacing is the space above and below the text on each line
185 unsigned int GetLineSpacing() const;
186 void SetLineSpacing(unsigned int spacing);
188 // image list: these functions allow to associate an image list with
189 // the control and retrieve it. Note that when assigned with
190 // SetImageList, the control does _not_ delete
191 // the associated image list when it's deleted in order to allow image
192 // lists to be shared between different controls. If you use
193 // AssignImageList, the control _does_ delete the image list.
195 // The normal image list is for the icons which correspond to the
196 // normal tree item state (whether it is selected or not).
197 // Additionally, the application might choose to show a state icon
198 // which corresponds to an app-defined item state (for example,
199 // checked/unchecked) which are taken from the state image list.
200 wxImageList *GetImageList() const;
201 wxImageList *GetStateImageList() const;
202 wxImageList *GetButtonsImageList() const;
204 void SetImageList(wxImageList *imageList);
205 void SetStateImageList(wxImageList *imageList);
206 void SetButtonsImageList(wxImageList *imageList);
207 void AssignImageList(wxImageList *imageList);
208 void AssignStateImageList(wxImageList *imageList);
209 void AssignButtonsImageList(wxImageList *imageList);
212 // Functions to work with columns
215 void AddColumn (const wxString& text,
216 int width = DEFAULT_COL_WIDTH,
217 int flag = wxALIGN_LEFT,
221 AddColumn (wxTreeListColumnInfo (text, width, flag, image, shown, edit));
223 void AddColumn (const wxTreeListColumnInfo& colInfo);
225 // inserts a column before the given one
226 void InsertColumn (int before,
227 const wxString& text,
228 int width = DEFAULT_COL_WIDTH,
229 int flag = wxALIGN_LEFT,
233 InsertColumn (before,
234 wxTreeListColumnInfo (text, width, flag, image, shown, edit));
236 void InsertColumn (int before, const wxTreeListColumnInfo& colInfo);
238 // deletes the given column - does not delete the corresponding column
239 void RemoveColumn (int column);
241 // returns the number of columns in the ctrl
242 int GetColumnCount() const;
244 // tells which column is the "main" one, i.e. the "threaded" one
245 void SetMainColumn (int column);
246 int GetMainColumn() const;
248 void SetColumn (int column, const wxTreeListColumnInfo& colInfo);
249 wxTreeListColumnInfo& GetColumn (int column);
250 const wxTreeListColumnInfo& GetColumn (int column) const;
252 void SetColumnText (int column, const wxString& text);
253 wxString GetColumnText (int column) const;
255 void SetColumnWidth (int column, int width);
256 int GetColumnWidth (int column) const;
258 void SetColumnAlignment (int column, int flag);
259 int GetColumnAlignment (int column) const;
261 void SetColumnImage (int column, int image);
262 int GetColumnImage (int column) const;
264 void SetColumnShown (int column, bool shown = true);
265 bool IsColumnShown (int column) const;
267 void SetColumnEditable (int column, bool edit = true);
268 bool IsColumnEditable (int column) const;
270 // Functions to work with items.
275 // retrieve item's label (of the main column)
276 wxString GetItemText (const wxTreeItemId& item) const
277 { return GetItemText (item, GetMainColumn()); }
278 // retrieves item's label of the given column
279 wxString GetItemText (const wxTreeItemId& item, int column) const;
281 // get one of the images associated with the item (normal by default)
282 int GetItemImage (const wxTreeItemId& item,
283 wxTreeItemIcon which = wxTreeItemIcon_Normal) const
284 { return GetItemImage (item, GetMainColumn(), which); }
285 int GetItemImage (const wxTreeItemId& item, int column,
286 wxTreeItemIcon which = wxTreeItemIcon_Normal) const;
288 // get the data associated with the item
289 wxTreeItemData *GetItemData (const wxTreeItemId& item) const;
291 bool GetItemBold (const wxTreeItemId& item) const;
292 wxColour GetItemTextColour (const wxTreeItemId& item) const;
293 wxColour GetItemBackgroundColour (const wxTreeItemId& item) const;
294 wxFont GetItemFont (const wxTreeItemId& item) const;
299 void SetItemText (const wxTreeItemId& item, const wxString& text)
300 { SetItemText (item, GetMainColumn(), text); }
301 void SetItemText (const wxTreeItemId& item, int column, const wxString& text);
303 // get one of the images associated with the item (normal by default)
304 void SetItemImage (const wxTreeItemId& item, int image,
305 wxTreeItemIcon which = wxTreeItemIcon_Normal)
306 { SetItemImage (item, GetMainColumn(), image, which); }
307 // the which parameter is ignored for all columns but the main one
308 void SetItemImage (const wxTreeItemId& item, int column, int image,
309 wxTreeItemIcon which = wxTreeItemIcon_Normal);
311 // associate some data with the item
312 void SetItemData (const wxTreeItemId& item, wxTreeItemData *data);
314 // force appearance of [+] button near the item. This is useful to
315 // allow the user to expand the items which don't have any children now
316 // - but instead add them only when needed, thus minimizing memory
317 // usage and loading time.
318 void SetItemHasChildren(const wxTreeItemId& item, bool has = true);
320 // the item will be shown in bold
321 void SetItemBold (const wxTreeItemId& item, bool bold = true);
323 // set the item's text colour
324 void SetItemTextColour (const wxTreeItemId& item, const wxColour& colour);
326 // set the item's background colour
327 void SetItemBackgroundColour (const wxTreeItemId& item, const wxColour& colour);
329 // set the item's font (should be of the same height for all items)
330 void SetItemFont (const wxTreeItemId& item, const wxFont& font);
332 // set the window font
333 virtual bool SetFont ( const wxFont &font );
336 void SetWindowStyle (const long styles);
337 long GetWindowStyle() const;
338 long GetWindowStyleFlag () const { return GetWindowStyle(); }
340 // item status inquiries
341 // ---------------------
343 // is the item visible (it might be outside the view or not expanded)?
344 bool IsVisible (const wxTreeItemId& item, bool fullRow = false) const;
345 // does the item has any children?
346 bool HasChildren (const wxTreeItemId& item) const;
347 // is the item expanded (only makes sense if HasChildren())?
348 bool IsExpanded (const wxTreeItemId& item) const;
349 // is this item currently selected (the same as has focus)?
350 bool IsSelected (const wxTreeItemId& item) const;
351 // is item text in bold font?
352 bool IsBold (const wxTreeItemId& item) const;
353 // does the layout include space for a button?
355 // number of children
356 // ------------------
358 // if 'recursively' is FALSE, only immediate children count, otherwise
359 // the returned number is the number of all items in this branch
360 size_t GetChildrenCount (const wxTreeItemId& item, bool recursively = true);
365 // wxTreeItemId.IsOk() will return FALSE if there is no such item
367 // get the root tree item
368 wxTreeItemId GetRootItem() const;
370 // get the item currently selected (may return NULL if no selection)
371 // wxTreeItemId GetSelection() const;
372 wxTreeItemId GetCurrent() const;
374 // returns the number of currently selected items
375 size_t GetSelectionSize() const;
377 // get the items currently selected, return the number of such item
378 size_t GetSelections (wxArrayTreeItemIds&) const;
380 // get the parent of this item (may return NULL if root)
381 wxTreeItemId GetItemParent (const wxTreeItemId& item) const;
383 // for this enumeration function you must pass in a "cookie" parameter
384 // which is opaque for the application but is necessary for the library
385 // to make these functions reentrant (i.e. allow more than one
386 // enumeration on one and the same object simultaneously). Of course,
387 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
390 // get child of this item
391 #if !wxCHECK_VERSION(2, 5, 0)
392 wxTreeItemId GetFirstChild(const wxTreeItemId& item, long& cookie) const;
393 wxTreeItemId GetNextChild(const wxTreeItemId& item, long& cookie) const;
394 wxTreeItemId GetPrevChild(const wxTreeItemId& item, long& cookie) const;
395 wxTreeItemId GetLastChild(const wxTreeItemId& item, long& cookie) const;
397 wxTreeItemId GetFirstChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
398 wxTreeItemId GetNextChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
399 wxTreeItemId GetPrevChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
400 wxTreeItemId GetLastChild(const wxTreeItemId& item, wxTreeItemIdValue& cookie) const;
403 // get sibling of this item
404 wxTreeItemId GetNextSibling(const wxTreeItemId& item) const;
405 wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const;
407 // get item in the full tree (currently only for internal use)
408 wxTreeItemId GetNext(const wxTreeItemId& item) const;
409 wxTreeItemId GetPrev(const wxTreeItemId& item) const;
411 // get expanded item, see IsExpanded()
412 wxTreeItemId GetFirstExpandedItem() const;
413 wxTreeItemId GetNextExpanded(const wxTreeItemId& item) const;
414 wxTreeItemId GetPrevExpanded(const wxTreeItemId& item) const;
416 // get visible item, see IsVisible()
417 wxTreeItemId GetFirstVisibleItem(bool fullRow = false) const;
418 wxTreeItemId GetNextVisible(const wxTreeItemId& item, bool fullRow = false) const;
419 wxTreeItemId GetPrevVisible(const wxTreeItemId& item, bool fullRow = false) const;
424 // add the root node to the tree
425 wxTreeItemId AddRoot (const wxString& text,
426 int image = -1, int selectedImage = -1,
427 wxTreeItemData *data = NULL);
429 // insert a new item in as the first child of the parent
430 wxTreeItemId PrependItem (const wxTreeItemId& parent,
431 const wxString& text,
432 int image = -1, int selectedImage = -1,
433 wxTreeItemData *data = NULL);
435 // insert a new item after a given one
436 wxTreeItemId InsertItem (const wxTreeItemId& parent,
437 const wxTreeItemId& idPrevious,
438 const wxString& text,
439 int image = -1, int selectedImage = -1,
440 wxTreeItemData *data = NULL);
442 // insert a new item before the one with the given index
443 wxTreeItemId InsertItem (const wxTreeItemId& parent,
445 const wxString& text,
446 int image = -1, int selectedImage = -1,
447 wxTreeItemData *data = NULL);
449 // insert a new item in as the last child of the parent
450 wxTreeItemId AppendItem (const wxTreeItemId& parent,
451 const wxString& text,
452 int image = -1, int selectedImage = -1,
453 wxTreeItemData *data = NULL);
455 // delete this item (except root) and associated data if any
456 void Delete (const wxTreeItemId& item);
457 // delete all children (but don't delete the item itself)
458 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
459 void DeleteChildren (const wxTreeItemId& item);
460 // delete the root and all its children from the tree
461 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events
465 void Expand (const wxTreeItemId& item);
466 // expand this item and all subitems recursively
467 void ExpandAll (const wxTreeItemId& item);
468 // collapse the item without removing its children
469 void Collapse (const wxTreeItemId& item);
470 // collapse the item and remove all children
471 void CollapseAndReset(const wxTreeItemId& item); //? TODO ???
472 // toggles the current state
473 void Toggle (const wxTreeItemId& item);
475 // remove the selection from currently selected item (if any)
476 // LG 19/09/08 : Added
477 void Unselect(wxTreeItemId& item);
481 void SelectItem (const wxTreeItemId& item,
482 const wxTreeItemId& last = (wxTreeItemId*)NULL,
483 bool unselect_others = true);
484 // select all items in the expanded tree
486 // make sure this item is visible (expanding the parent item and/or
487 // scrolling to this item if necessary)
488 void EnsureVisible (const wxTreeItemId& item);
489 // scroll to this item (but don't expand its parent)
490 void ScrollTo (const wxTreeItemId& item);
492 // The first function is more portable (because easier to implement
493 // on other platforms), but the second one returns some extra info.
494 wxTreeItemId HitTest (const wxPoint& point)
495 { int flags; int column; return HitTest (point, flags, column); }
496 wxTreeItemId HitTest (const wxPoint& point, int& flags)
497 { int column; return HitTest (point, flags, column); }
498 wxTreeItemId HitTest (const wxPoint& point, int& flags, int& column);
500 // get the bounding rectangle of the item (or of its label only)
501 bool GetBoundingRect (const wxTreeItemId& item, wxRect& rect,
502 bool textOnly = false) const;
504 // Start editing the item label: this (temporarily) replaces the item
505 // with a one line edit control. The item will be selected if it hadn't
507 void EditLabel (const wxTreeItemId& item)
508 { EditLabel (item, GetMainColumn()); }
509 // edit item's label of the given column
510 void EditLabel (const wxTreeItemId& item, int column);
513 virtual wxString OnGetItemText( wxTreeItemData* item, long column ) const;
516 // this function is called to compare 2 items and should return -1, 0
517 // or +1 if the first item is less than, equal to or greater than the
518 // second one. The base class version performs alphabetic comparaison
519 // of item labels (GetText)
520 virtual int OnCompareItems (const wxTreeItemId& item1, const wxTreeItemId& item2);
521 // sort the children of this item using OnCompareItems
522 // NB: this function is not reentrant and not MT-safe (FIXME)!
523 void SortChildren(const wxTreeItemId& item);
526 wxTreeItemId FindItem (const wxTreeItemId& item, const wxString& str, int mode = 0);
528 // overridden base class virtuals
529 virtual bool SetBackgroundColour (const wxColour& colour);
530 virtual bool SetForegroundColour (const wxColour& colour);
533 void SetDragItem (const wxTreeItemId& item = (wxTreeItemId*)NULL);
536 wxTreeListHeaderWindow* GetHeaderWindow() const
537 { return m_header_win; }
539 wxTreeListMainWindow* GetMainWindow() const
540 { return m_main_win; }
542 virtual wxSize DoGetBestSize() const;
545 // header window, responsible for column visualization and manipulation
546 wxTreeListHeaderWindow* m_header_win;
548 // main window, the "true" tree ctrl
549 wxTreeListMainWindow* m_main_win;
551 void CalculateAndSetHeaderHeight();
552 void DoHeaderLayout();
553 void OnSize(wxSizeEvent& event);
558 DECLARE_EVENT_TABLE()
559 // DECLARE_DYNAMIC_CLASS(wxTreeListCtrl)
562 #endif // TREELISTCTRL_H