1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/os2/treectrl.h
3 // Purpose: wxTreeCtrl class
4 // Author: David Webster
8 // Copyright: (c) David Webster
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_TREECTRL_H_
13 #define _WX_TREECTRL_H_
15 // ----------------------------------------------------------------------------
17 // ----------------------------------------------------------------------------
21 #include "wx/textctrl.h"
22 #include "wx/dynarray.h"
23 #include "wx/treebase.h"
24 #include "wx/hashmap.h"
26 // the type for "untyped" data
27 typedef long wxDataType
;
30 class WXDLLEXPORT wxImageList
;
31 class WXDLLEXPORT wxDragImage
;
32 struct WXDLLEXPORT wxTreeViewItem
;
34 // a callback function used for sorting tree items, it should return -1 if the
35 // first item precedes the second, +1 if the second precedes the first or 0 if
39 // flags for deprecated InsertItem() variant
40 #define wxTREE_INSERT_FIRST 0xFFFF0001
41 #define wxTREE_INSERT_LAST 0xFFFF0002
43 // hash storing attributes for our items
44 WX_DECLARE_EXPORTED_VOIDPTR_HASH_MAP(wxTreeItemAttr
*, wxMapTreeAttr
);
46 // ----------------------------------------------------------------------------
48 // ----------------------------------------------------------------------------
49 class WXDLLEXPORT wxTreeCtrl
: public wxControl
54 wxTreeCtrl() { Init(); }
56 wxTreeCtrl( wxWindow
* pParent
57 ,wxWindowID vId
= wxID_ANY
58 ,const wxPoint
& rPos
= wxDefaultPosition
59 ,const wxSize
& rSize
= wxDefaultSize
60 ,long lStyle
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
61 ,const wxValidator
& rValidator
= wxDefaultValidator
62 ,const wxString
& rsName
= wxTreeCtrlNameStr
74 virtual ~wxTreeCtrl();
76 bool Create( wxWindow
* pParent
77 ,wxWindowID vId
= wxID_ANY
78 ,const wxPoint
& rPos
= wxDefaultPosition
79 ,const wxSize
& rSize
= wxDefaultSize
80 ,long lStyle
= wxTR_HAS_BUTTONS
| wxTR_LINES_AT_ROOT
81 ,const wxValidator
& rValidator
= wxDefaultValidator
82 ,const wxString
& rsName
= wxTreeCtrlNameStr
91 // Get the total number of items in the control
93 virtual unsigned int GetCount(void) const;
96 // Indent is the number of pixels the children are indented relative to
97 // the parents position. SetIndent() also redraws the control
100 unsigned int GetIndent(void) const;
101 void SetIndent(unsigned int uIndent
);
104 // Spacing is the number of pixels between the start and the Text
106 unsigned int GetSpacing(void) const { return 18; } // return wxGTK default
107 void SetSpacing(unsigned int uSpacing
) { }
110 // Image list: these functions allow to associate an image list with
111 // the control and retrieve it. Note that the control does _not_ delete
112 // the associated image list when it's deleted in order to allow image
113 // lists to be shared between different controls.
115 // OS/2 doesn't really use imagelists as MSW does, but since the MSW
116 // control is the basis for this one, until I decide how to get rid of
117 // the need for them they are here for now.
119 wxImageList
* GetImageList(void) const;
120 wxImageList
* GetStateImageList(void) const;
122 void AssignImageList(wxImageList
* pImageList
);
123 void AssignStateImageList(wxImageList
* pImageList
);
124 void SetImageList(wxImageList
* pImageList
);
125 void SetStateImageList(wxImageList
* pImageList
);
128 // Functions to work with tree ctrl items. Unfortunately, they can _not_ be
129 // member functions of wxTreeItem because they must know the tree the item
130 // belongs to for Windows implementation and storing the pointer to
131 // wxTreeCtrl in each wxTreeItem is just too much waste.
136 wxString
GetItemText(const wxTreeItemId
& rItem
) const;
137 void SetItemText( const wxTreeItemId
& rItem
138 ,const wxString
& rsText
142 // One of the images associated with the item (normal by default)
144 int GetItemImage( const wxTreeItemId
& rItem
145 ,wxTreeItemIcon vWhich
= wxTreeItemIcon_Normal
147 void SetItemImage( const wxTreeItemId
& rItem
149 ,wxTreeItemIcon vWhich
= wxTreeItemIcon_Normal
153 // Data associated with the item
155 wxTreeItemData
* GetItemData(const wxTreeItemId
& rItem
) const;
156 void SetItemData( const wxTreeItemId
& rItem
157 ,wxTreeItemData
* pData
161 // Item's text colour
163 wxColour
GetItemTextColour(const wxTreeItemId
& rItem
) const;
164 void SetItemTextColour( const wxTreeItemId
& rItem
165 ,const wxColour
& rColor
169 // Item's background colour
171 wxColour
GetItemBackgroundColour(const wxTreeItemId
& rItem
) const;
172 void SetItemBackgroundColour( const wxTreeItemId
& rItem
173 ,const wxColour
& rColour
179 wxFont
GetItemFont(const wxTreeItemId
& rItem
) const;
180 void SetItemFont( const wxTreeItemId
& rItem
185 // Force appearance of [+] button near the item. This is useful to
186 // allow the user to expand the items which don't have any children now
187 // - but instead add them only when needed, thus minimizing memory
188 // usage and loading time.
190 void SetItemHasChildren( const wxTreeItemId
& rItem
195 // The item will be shown in bold
197 void SetItemBold( const wxTreeItemId
& rItem
202 // The item will be shown with a drop highlight
204 void SetItemDropHighlight( const wxTreeItemId
& rItem
205 ,bool bHighlight
= true
209 // Item status inquiries
210 // ---------------------
214 // Is the item visible (it might be outside the view or not expanded)?
216 bool IsVisible(const wxTreeItemId
& rItem
) const;
219 // Does the item has any children?
221 bool ItemHasChildren(const wxTreeItemId
& rItem
) const;
224 // Is the item expanded (only makes sense if HasChildren())?
226 bool IsExpanded(const wxTreeItemId
& rItem
) const;
229 // Is this item currently selected (the same as has focus)?
231 bool IsSelected(const wxTreeItemId
& rItem
) const;
234 // Is item text in bold font?
236 bool IsBold(const wxTreeItemId
& rItem
) const;
239 // Number of children
240 // ------------------
244 // If 'bRecursively' is false, only immediate children count, otherwise
245 // the returned number is the number of all items in this branch
247 size_t GetChildrenCount( const wxTreeItemId
& rItem
248 ,bool bRecursively
= true
257 // Get the root tree item
259 wxTreeItemId
GetRootItem(void) const;
262 // Get the item currently selected (may return NULL if no selection)
264 wxTreeItemId
GetSelection(void) const;
267 // Get the items currently selected, return the number of such item
269 size_t GetSelections(wxArrayTreeItemIds
& rSelections
) const;
272 // Get the parent of this item (may return NULL if root)
274 wxTreeItemId
GetItemParent(const wxTreeItemId
& rItem
) const;
276 // for this enumeration function you must pass in a "cookie" parameter
277 // which is opaque for the application but is necessary for the library
278 // to make these functions reentrant (i.e. allow more than one
279 // enumeration on one and the same object simultaneously). Of course,
280 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
283 // get the first child of this item
284 wxTreeItemId
GetFirstChild(const wxTreeItemId
& item
,
285 wxTreeItemIdValue
& cookie
) const;
286 // get the next child
287 wxTreeItemId
GetNextChild(const wxTreeItemId
& item
,
288 wxTreeItemIdValue
& cookie
) const;
291 // Get the last child of this item - this method doesn't use cookies
293 wxTreeItemId
GetLastChild(const wxTreeItemId
& rItem
) const;
296 // Get the next sibling of this item
298 wxTreeItemId
GetNextSibling(const wxTreeItemId
& rItem
) const;
301 // Get the previous sibling
303 wxTreeItemId
GetPrevSibling(const wxTreeItemId
& rItem
) const;
306 // Get first visible item
308 wxTreeItemId
GetFirstVisibleItem(void) const;
311 // Get the next visible item: item must be visible itself!
312 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem()
314 wxTreeItemId
GetNextVisible(const wxTreeItemId
& rItem
) const;
317 // Get the previous visible item: item must be visible itself!
319 wxTreeItemId
GetPrevVisible(const wxTreeItemId
& rItem
) const;
327 // Add the root node to the tree
329 wxTreeItemId
AddRoot( const wxString
& rsText
331 ,int nSelectedImage
= -1
332 ,wxTreeItemData
* pData
= NULL
336 // Insert a new item in as the first child of the parent
338 wxTreeItemId
PrependItem( const wxTreeItemId
& rParent
339 ,const wxString
& rsText
341 ,int nSelectedImage
= -1
342 ,wxTreeItemData
* pData
= NULL
346 // Insert a new item after a given one
348 wxTreeItemId
InsertItem( const wxTreeItemId
& rParent
349 ,const wxTreeItemId
& rIdPrevious
350 ,const wxString
& rsText
352 ,int nSelectedImage
= -1
353 ,wxTreeItemData
* pData
= NULL
357 // Insert a new item before the one with the given index
359 wxTreeItemId
InsertItem( const wxTreeItemId
& pParent
361 ,const wxString
& rsText
363 ,int nSelectedImage
= -1
364 ,wxTreeItemData
* pData
= NULL
368 // Insert a new item in as the last child of the parent
370 wxTreeItemId
AppendItem( const wxTreeItemId
& rParent
371 ,const wxString
& rsText
373 ,int nSelectedImage
= -1
374 ,wxTreeItemData
* pData
= NULL
378 // Delete this item and associated data if any
380 void Delete(const wxTreeItemId
& rItem
);
383 // Delete all children (but don't delete the item itself)
385 void DeleteChildren(const wxTreeItemId
& rItem
);
388 // Delete all items from the tree
390 void DeleteAllItems(void);
395 void Expand(const wxTreeItemId
& rItem
);
398 // Collapse the item without removing its children
400 void Collapse(const wxTreeItemId
& rItem
);
403 // Collapse the item and remove all children
405 void CollapseAndReset(const wxTreeItemId
& rItem
);
408 // Toggles the current state
410 void Toggle(const wxTreeItemId
& rItem
);
413 // Remove the selection from currently selected item (if any)
418 // Unselect all items (only makes sense for multiple selection control)
420 void UnselectAll(void);
425 void SelectItem(const wxTreeItemId
& rItem
);
428 // Make sure this item is visible (expanding the parent item and/or
429 // scrolling to this item if necessary)
431 void EnsureVisible(const wxTreeItemId
& rItem
);
434 // Scroll to this item (but don't expand its parent)
436 void ScrollTo(const wxTreeItemId
& rItem
);
439 // OS/2 does not use a separate edit field for editting text. Here for
440 // interface compatibility, only.
442 wxTextCtrl
* EditLabel( const wxTreeItemId
& rItem
443 ,wxClassInfo
* pTextCtrlClass
= CLASSINFO(wxTextCtrl
)
447 // returns NULL for OS/2 in ALL cases
449 wxTextCtrl
* GetEditControl(void) const {return (wxTextCtrl
*)NULL
;}
452 // End editing and accept or discard the changes to item label
454 void EndEditLabel( const wxTreeItemId
& rItem
455 ,bool bDiscardChanges
= false
464 // This function is called to compare 2 items and should return -1, 0
465 // or +1 if the first item is less than, equal to or greater than the
466 // second one. The base class version performs alphabetic comparaison
467 // of item labels (GetText)
469 virtual int OnCompareItems( const wxTreeItemId
& rItem1
470 ,const wxTreeItemId
& rItem2
474 // Sort the children of this item using OnCompareItems
476 void SortChildren(const wxTreeItemId
& rItem
);
484 // Determine to which item (if any) belongs the given point (the
485 // coordinates specified are relative to the client area of tree ctrl)
486 // and fill the flags parameter with a bitmask of wxTREE_HITTEST_xxx
490 // The first function is more portable (because easier to implement
491 // on other platforms), but the second one returns some extra info.
493 wxTreeItemId
HitTest(const wxPoint
& rPoint
)
494 { int nDummy
= 0; return HitTest(rPoint
, nDummy
); }
495 wxTreeItemId
HitTest( const wxPoint
& rPoint
500 // Get the bounding rectangle of the item (or of its label only)
502 bool GetBoundingRect( const wxTreeItemId
& rItem
504 ,bool bTextOnly
= false
511 #if WXWIN_COMPATIBILITY_2_4
512 // These methods are deprecated and will be removed in future versions of
513 // wxWidgets, they're here for compatibility only, don't use them in new
514 // code (the comments indicate why these methods are now useless and how to
519 // Use Expand, Collapse, CollapseAndReset or Toggle
521 wxDEPRECATED( void ExpandItem( const wxTreeItemId
& rItem
526 // Use AddRoot, PrependItem or AppendItem
528 wxDEPRECATED( wxTreeItemId
InsertItem( const wxTreeItemId
& pParent
529 ,const wxString
& rsText
532 ,long lInsertAfter
= wxTREE_INSERT_LAST
536 // Use Set/GetImageList and Set/GetStateImageList
538 wxDEPRECATED( wxImageList
* GetImageList(int nVal
) const );
539 wxDEPRECATED( void SetImageList(wxImageList
* pImageList
, int nVal
) );
542 // Use Set/GetItemImage directly
544 wxDEPRECATED( int GetItemSelectedImage(const wxTreeItemId
& rItem
) const );
545 wxDEPRECATED( void SetItemSelectedImage(const wxTreeItemId
& rItem
, int nImage
) );
548 // For this enumeration function you must pass in a "cookie" parameter
549 // which is opaque for the application but is necessary for the library
550 // to make these functions reentrant (i.e. allow more than one
551 // enumeration on one and the same object simultaneously). Of course,
552 // the "cookie" passed to GetFirstChild() and GetNextChild() should be
557 // Get the first child of this item
559 wxDEPRECATED( wxTreeItemId
GetFirstChild( const wxTreeItemId
& rItem
564 // Get the next child
566 wxDEPRECATED( wxTreeItemId
GetNextChild( const wxTreeItemId
& rItem
569 #endif // WXWIN_COMPATIBILITY_2_4
576 virtual MRESULT
OS2WindowProc( WXUINT uMsg
580 virtual bool OS2Command( WXUINT uParam
583 // virtual bool OMSWOnNotify(int idCtrl, WXLPARAM lParam, WXLPARAM *result);
586 // Override some base class virtuals
588 virtual bool SetBackgroundColour(const wxColour
& rColour
);
589 virtual bool SetForegroundColour(const wxColour
& rColour
);
592 // Get/set the check state for the item (only for wxTR_MULTIPLE)
594 bool IsItemChecked(const wxTreeItemId
& rItem
) const;
595 void SetItemCheck( const wxTreeItemId
& rItem
601 // SetImageList helper
603 void SetAnyImageList( wxImageList
* pImageList
608 // Refresh a single item
610 void RefreshItem(const wxTreeItemId
& rItem
);
612 wxImageList
* m_pImageListNormal
; // images for tree elements
613 wxImageList
* m_pImageListState
; // special images for app defined states
614 bool m_bOwnsImageListNormal
;
615 bool m_bOwnsImageListState
;
620 // The common part of all ctors
627 inline bool DoGetItem(wxTreeViewItem
* pTvItem
) const;
628 inline void DoSetItem(wxTreeViewItem
* pTvItem
);
630 inline void DoExpand( const wxTreeItemId
& rItem
633 wxTreeItemId
DoInsertItem( const wxTreeItemId
& pParent
634 ,wxTreeItemId hInsertAfter
635 ,const wxString
& rsText
638 ,wxTreeItemData
* pData
640 int DoGetItemImageFromData( const wxTreeItemId
& rItem
641 ,wxTreeItemIcon vWhich
643 void DoSetItemImageFromData( const wxTreeItemId
& rItem
645 ,wxTreeItemIcon vWhich
647 void DoSetItemImages( const wxTreeItemId
& rItem
651 void DeleteTextCtrl() { };
654 // support for additional item images which we implement using
655 // wxTreeItemIndirectData technique - see the comments in msw/treectrl.cpp
657 void SetIndirectItemData( const wxTreeItemId
& rItem
658 ,class wxTreeItemIndirectData
* pData
660 bool HasIndirectData(const wxTreeItemId
& rItem
) const;
661 bool IsDataIndirect(wxTreeItemData
* pData
) const
662 { return pData
&& pData
->GetId().m_pItem
== 0; }
665 // The hash storing the items attributes (indexed by items ids)
667 wxMapTreeAttr m_vAttrs
;
670 // true if the hash above is not empty
677 wxDragImage
* m_pDragImage
;
679 // Virtual root item, if wxTR_HIDE_ROOT is set.
680 // void* m_pVirtualRoot;
682 // the starting item for selection with Shift
683 // WXHTREEITEM m_htSelStart;
685 friend class wxTreeItemIndirectData
;
686 friend class wxTreeSortHelper
;
688 DECLARE_DYNAMIC_CLASS(wxTreeCtrl
)
689 DECLARE_NO_COPY_CLASS(wxTreeCtrl
)
690 }; // end of CLASS wxTreeCtrl
692 #endif // wxUSE_TREECTRL