]> git.saurik.com Git - wxWidgets.git/blob - include/wx/treelist.h
Reset previous sort column in generic wxDataViewColumn::SetSortOrder().
[wxWidgets.git] / include / wx / treelist.h
1 ///////////////////////////////////////////////////////////////////////////////
2 // Name: wx/treelist.h
3 // Purpose: wxTreeListCtrl class declaration.
4 // Author: Vadim Zeitlin
5 // Created: 2011-08-17
6 // RCS-ID: $Id: wxhead.h,v 1.12 2010-04-22 12:44:51 zeitlin Exp $
7 // Copyright: (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
8 // Licence: wxWindows licence
9 ///////////////////////////////////////////////////////////////////////////////
10
11 #ifndef _WX_TREELIST_H_
12 #define _WX_TREELIST_H_
13
14 #include "wx/defs.h"
15
16 #if wxUSE_TREELISTCTRL
17
18 #include "wx/compositewin.h"
19 #include "wx/containr.h"
20 #include "wx/headercol.h"
21 #include "wx/itemid.h"
22 #include "wx/vector.h"
23 #include "wx/window.h"
24 #include "wx/withimages.h"
25
26 class WXDLLIMPEXP_FWD_ADV wxDataViewCtrl;
27 class WXDLLIMPEXP_FWD_ADV wxDataViewEvent;
28
29 extern WXDLLIMPEXP_DATA_CORE(const char) wxTreeListCtrlNameStr[];
30
31 class wxTreeListModel;
32 class wxTreeListModelNode;
33
34 // ----------------------------------------------------------------------------
35 // Constants.
36 // ----------------------------------------------------------------------------
37
38 // wxTreeListCtrl styles.
39 //
40 // Notice that using wxTL_USER_3STATE implies wxTL_3STATE and wxTL_3STATE in
41 // turn implies wxTL_CHECKBOX.
42 enum
43 {
44 wxTL_SINGLE = 0x0000, // This is the default anyhow.
45 wxTL_MULTIPLE = 0x0001, // Allow multiple selection.
46 wxTL_CHECKBOX = 0x0002, // Show checkboxes in the first column.
47 wxTL_3STATE = 0x0004, // Allow 3rd state in checkboxes.
48 wxTL_USER_3STATE = 0x0008, // Allow user to set 3rd state.
49
50 wxTL_DEFAULT_STYLE = wxTL_SINGLE,
51 wxTL_STYLE_MASK = wxTL_SINGLE |
52 wxTL_MULTIPLE |
53 wxTL_CHECKBOX |
54 wxTL_3STATE |
55 wxTL_USER_3STATE
56 };
57
58 // ----------------------------------------------------------------------------
59 // wxTreeListItem: unique identifier of an item in wxTreeListCtrl.
60 // ----------------------------------------------------------------------------
61
62 // Make wxTreeListItem a forward-declarable class even though it's simple
63 // enough to possibly be declared as a simple typedef.
64 class wxTreeListItem : public wxItemId<wxTreeListModelNode*>
65 {
66 public:
67 wxTreeListItem(wxTreeListModelNode* item = NULL)
68 : wxItemId<wxTreeListModelNode*>(item)
69 {
70 }
71 };
72
73 // Container of multiple items.
74 typedef wxVector<wxTreeListItem> wxTreeListItems;
75
76 // Some special "items" that can be used with InsertItem():
77 extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_FIRST;
78 extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_LAST;
79
80 // ----------------------------------------------------------------------------
81 // wxTreeListCtrl: a control combining wxTree- and wxListCtrl features.
82 // ----------------------------------------------------------------------------
83
84 // This control also provides easy to use high level interface. Although the
85 // implementation uses wxDataViewCtrl internally, this class is intentionally
86 // simpler than wxDataViewCtrl and doesn't provide all of its functionality.
87 //
88 // If you need extra features you can always use GetDataView() accessor to work
89 // with wxDataViewCtrl directly but doing this makes your unportable to possible
90 // future non-wxDataViewCtrl-based implementations of this class.
91
92 class WXDLLIMPEXP_ADV wxTreeListCtrl
93 : public wxCompositeWindow< wxNavigationEnabled<wxWindow> >,
94 public wxWithImages
95 {
96 public:
97 // Constructors and such
98 // ---------------------
99
100 wxTreeListCtrl() { Init(); }
101 wxTreeListCtrl(wxWindow* parent,
102 wxWindowID id,
103 const wxPoint& pos = wxDefaultPosition,
104 const wxSize& size = wxDefaultSize,
105 long style = wxTL_DEFAULT_STYLE,
106 const wxString& name = wxTreeListCtrlNameStr)
107 {
108 Init();
109
110 Create(parent, id, pos, size, style, name);
111 }
112
113 bool Create(wxWindow* parent,
114 wxWindowID id,
115 const wxPoint& pos = wxDefaultPosition,
116 const wxSize& size = wxDefaultSize,
117 long style = wxTL_DEFAULT_STYLE,
118 const wxString& name = wxTreeListCtrlNameStr);
119
120
121 virtual ~wxTreeListCtrl();
122
123 // Columns methods
124 // ---------------
125
126 // Add a column with the given title and attributes, returns the index of
127 // the new column or -1 on failure.
128 int AppendColumn(const wxString& title,
129 int width = wxCOL_WIDTH_AUTOSIZE,
130 wxAlignment align = wxALIGN_LEFT,
131 int flags = wxCOL_RESIZABLE)
132 {
133 return DoInsertColumn(title, -1, width, align, flags);
134 }
135
136 // Return the total number of columns.
137 unsigned GetColumnCount() const;
138
139 // Delete the column with the given index, returns false if index is
140 // invalid or deleting the column failed for some other reason.
141 bool DeleteColumn(unsigned col);
142
143 // Delete all columns.
144 void ClearColumns();
145
146 // Set column width to either the given value in pixels or to the value
147 // large enough to fit all of the items if width == wxCOL_WIDTH_AUTOSIZE.
148 void SetColumnWidth(unsigned col, int width);
149
150 // Get the current width of the given column in pixels.
151 int GetColumnWidth(unsigned col) const;
152
153 // Get the width appropriate for showing the given text. This is typically
154 // used as second argument for AppendColumn() or with SetColumnWidth().
155 int WidthFor(const wxString& text) const;
156
157
158 // Item methods
159 // ------------
160
161 // Adding items. The parent and text of the first column of the new item
162 // must always be specified, the rest is optional.
163 //
164 // Each item can have two images: one used for closed state and another for
165 // opened one. Only the first one is ever used for the items that don't
166 // have children. And both are not set by default.
167 //
168 // It is also possible to associate arbitrary client data pointer with the
169 // new item. It will be deleted by the control when the item is deleted
170 // (either by an explicit DeleteItem() call or because the entire control
171 // is destroyed).
172
173 wxTreeListItem AppendItem(wxTreeListItem parent,
174 const wxString& text,
175 int imageClosed = NO_IMAGE,
176 int imageOpened = NO_IMAGE,
177 wxClientData* data = NULL)
178 {
179 return DoInsertItem(parent, wxTLI_LAST, text,
180 imageClosed, imageOpened, data);
181 }
182
183 wxTreeListItem InsertItem(wxTreeListItem parent,
184 wxTreeListItem previous,
185 const wxString& text,
186 int imageClosed = NO_IMAGE,
187 int imageOpened = NO_IMAGE,
188 wxClientData* data = NULL)
189 {
190 return DoInsertItem(parent, previous, text,
191 imageClosed, imageOpened, data);
192 }
193
194 wxTreeListItem PrependItem(wxTreeListItem parent,
195 const wxString& text,
196 int imageClosed = NO_IMAGE,
197 int imageOpened = NO_IMAGE,
198 wxClientData* data = NULL)
199 {
200 return DoInsertItem(parent, wxTLI_FIRST, text,
201 imageClosed, imageOpened, data);
202 }
203
204 // Deleting items.
205 void DeleteItem(wxTreeListItem item);
206 void DeleteAllItems();
207
208
209 // Tree navigation
210 // ---------------
211
212 // Return the (never shown) root item.
213 wxTreeListItem GetRootItem() const;
214
215 // The parent item may be invalid for the root-level items.
216 wxTreeListItem GetItemParent(wxTreeListItem item) const;
217
218 // Iterate over the given item children: start by calling GetFirstChild()
219 // and then call GetNextSibling() for as long as it returns valid item.
220 wxTreeListItem GetFirstChild(wxTreeListItem item) const;
221 wxTreeListItem GetNextSibling(wxTreeListItem item) const;
222
223 // Return the first child of the root item, which is also the first item of
224 // the tree in depth-first traversal order.
225 wxTreeListItem GetFirstItem() const { return GetFirstChild(GetRootItem()); }
226
227 // Get item after the given one in the depth-first tree-traversal order.
228 // Calling this function starting with the result of GetFirstItem() allows
229 // iterating over all items in the tree.
230 wxTreeListItem GetNextItem(wxTreeListItem item) const;
231
232
233 // Items attributes
234 // ----------------
235
236 const wxString& GetItemText(wxTreeListItem item, unsigned col = 0) const;
237
238 // The convenience overload below sets the text for the first column.
239 void SetItemText(wxTreeListItem item, unsigned col, const wxString& text);
240 void SetItemText(wxTreeListItem item, const wxString& text)
241 {
242 SetItemText(item, 0, text);
243 }
244
245 // By default the opened image is the same as the normal, closed one (if
246 // it's used at all).
247 void SetItemImage(wxTreeListItem item, int closed, int opened = NO_IMAGE);
248
249 // Retrieve or set the data associated with the item.
250 wxClientData* GetItemData(wxTreeListItem item) const;
251 void SetItemData(wxTreeListItem item, wxClientData* data);
252
253
254 // Expanding and collapsing
255 // ------------------------
256
257 void Expand(wxTreeListItem item);
258 void Collapse(wxTreeListItem item);
259 bool IsExpanded(wxTreeListItem item) const;
260
261
262 // Selection handling
263 // ------------------
264
265 // This function can be used with single selection controls, use
266 // GetSelections() with the multi-selection ones.
267 wxTreeListItem GetSelection() const;
268
269 // This one can be used with either single or multi-selection controls.
270 unsigned GetSelections(wxTreeListItems& selections) const;
271
272 // In single selection mode Select() deselects any other selected items, in
273 // multi-selection case it adds to the selection.
274 void Select(wxTreeListItem item);
275
276 // Can be used in multiple selection mode only, single selected item in the
277 // single selection mode can't be unselected.
278 void Unselect(wxTreeListItem item);
279
280 // Return true if the item is selected, can be used in both single and
281 // multiple selection modes.
282 bool IsSelected(wxTreeListItem item) const;
283
284 // Select or unselect all items, only valid in multiple selection mode.
285 void SelectAll();
286 void UnselectAll();
287
288
289 // Checkbox handling
290 // -----------------
291
292 // Methods in this section can only be used with the controls created with
293 // wxTL_CHECKBOX style.
294
295 // Simple set, unset or query the checked state.
296 void CheckItem(wxTreeListItem item, wxCheckBoxState state = wxCHK_CHECKED);
297 void UncheckItem(wxTreeListItem item) { CheckItem(item, wxCHK_UNCHECKED); }
298
299 // The same but do it recursively for this item itself and its children.
300 void CheckItemRecursively(wxTreeListItem item,
301 wxCheckBoxState state = wxCHK_CHECKED);
302
303 // Update the parent of this item recursively: if this item and all its
304 // siblings are checked, the parent will become checked as well. If this
305 // item and all its siblings are unchecked, the parent will be unchecked.
306 // And if the siblings of this item are not all in the same state, the
307 // parent will be switched to indeterminate state. And then the same logic
308 // will be applied to the parents parent and so on recursively.
309 //
310 // This is typically called when the state of the given item has changed
311 // from EVT_TREELIST_ITEM_CHECKED() handler in the controls which have
312 // wxTL_3STATE flag. Notice that without this flag this function can't work
313 // as it would be unable to set the state of a parent with both checked and
314 // unchecked items so it's only allowed to call it when this flag is set.
315 void UpdateItemParentStateRecursively(wxTreeListItem item);
316
317 // Return the current state.
318 wxCheckBoxState GetCheckedState(wxTreeListItem item) const;
319
320 // Return true if all item children (if any) are in the given state.
321 bool AreAllChildrenInState(wxTreeListItem item,
322 wxCheckBoxState state) const;
323
324
325
326 // View window functions.
327 // ----------------------
328
329 // This control itself is entirely covered by the "view window" which is
330 // currently a wxDataViewCtrl but if you want to avoid relying on this to
331 // allow your code to work with later versions which might not be
332 // wxDataViewCtrl-based, use the first function only and only use the
333 // second one if you really need to call wxDataViewCtrl methods on it.
334 wxWindow* GetView() const;
335 wxDataViewCtrl* GetDataView() const { return m_view; }
336
337 private:
338 // Common part of all ctors.
339 void Init();
340
341 // Pure virtual method inherited from wxCompositeWindow.
342 virtual wxWindowList GetCompositeWindowParts() const;
343
344 // Implementation of AppendColumn().
345 int DoInsertColumn(const wxString& title,
346 int pos, // May be -1 meaning "append".
347 int width,
348 wxAlignment align,
349 int flags);
350
351 // Common part of {Append,Insert,Prepend}Item().
352 wxTreeListItem DoInsertItem(wxTreeListItem parent,
353 wxTreeListItem previous,
354 const wxString& text,
355 int imageClosed,
356 int imageOpened,
357 wxClientData* data);
358
359 // Send wxTreeListEvent corresponding to the given wxDataViewEvent.
360 //
361 // Also updates the original event "skipped" and "vetoed" flags.
362 void SendEvent(wxEventType evt, wxDataViewEvent& event);
363
364
365 // Called by wxTreeListModel when an item is toggled by the user.
366 void OnItemToggled(wxTreeListItem item, wxCheckBoxState stateOld);
367
368 // Event handlers.
369 void OnSelectionChanged(wxDataViewEvent& event);
370 void OnItemExpanding(wxDataViewEvent& event);
371 void OnItemExpanded(wxDataViewEvent& event);
372 void OnItemActivated(wxDataViewEvent& event);
373 void OnItemContextMenu(wxDataViewEvent& event);
374 void OnSize(wxSizeEvent& event);
375
376 wxDECLARE_EVENT_TABLE();
377
378
379 wxDataViewCtrl* m_view;
380 wxTreeListModel* m_model;
381
382
383 // It calls our inherited protected wxWithImages::GetImage() method.
384 friend class wxTreeListModel;
385
386 wxDECLARE_NO_COPY_CLASS(wxTreeListCtrl);
387 };
388
389 // ----------------------------------------------------------------------------
390 // wxTreeListEvent: event generated by wxTreeListCtrl.
391 // ----------------------------------------------------------------------------
392
393 class wxTreeListEvent : public wxNotifyEvent
394 {
395 public:
396 // The item affected by the event.
397 wxTreeListItem GetItem() const { return m_item; }
398
399 // The previous state of the item checkbox for ITEM_CHECKED events only.
400 wxCheckBoxState GetOldCheckedState() const { return m_oldCheckedState; }
401
402
403 virtual wxEvent* Clone() const { return new wxTreeListEvent(*this); }
404
405 private:
406 // Ctor is private, only wxTreeListCtrl can create events of this type.
407 wxTreeListEvent(wxEventType evtType,
408 wxTreeListCtrl* treelist,
409 wxTreeListItem item)
410 : wxNotifyEvent(evtType, treelist->GetId()),
411 m_item(item)
412 {
413 SetEventObject(treelist);
414 }
415
416 // Set the checkbox state before this event for ITEM_CHECKED events.
417 void SetOldCheckedState(wxCheckBoxState state)
418 {
419 m_oldCheckedState = state;
420 }
421
422
423 const wxTreeListItem m_item;
424
425 wxCheckBoxState m_oldCheckedState;
426
427 friend class wxTreeListCtrl;
428
429 wxDECLARE_ABSTRACT_CLASS(wxTreeListEvent);
430 };
431
432 // Event types and event table macros.
433
434 typedef void (wxEvtHandler::*wxTreeListEventFunction)(wxTreeListEvent&);
435
436 #define wxTreeListEventHandler(func) \
437 wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func)
438
439 #define wxEVT_TREELIST_GENERIC(name, id, fn) \
440 wx__DECLARE_EVT1(wxEVT_COMMAND_TREELIST_##name, id, wxTreeListEventHandler(fn))
441
442 #define wxDECLARE_TREELIST_EVENT(name) \
443 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_ADV, \
444 wxEVT_COMMAND_TREELIST_##name, \
445 wxTreeListEvent)
446
447 wxDECLARE_TREELIST_EVENT(SELECTION_CHANGED);
448 #define EVT_TREELIST_SELECTION_CHANGED(id, fn) \
449 wxEVT_TREELIST_GENERIC(SELECTION_CHANGED, id, fn)
450
451 wxDECLARE_TREELIST_EVENT(ITEM_EXPANDING);
452 #define EVT_TREELIST_ITEM_EXPANDING(id, fn) \
453 wxEVT_TREELIST_GENERIC(ITEM_EXPANDING, id, fn)
454
455 wxDECLARE_TREELIST_EVENT(ITEM_EXPANDED);
456 #define EVT_TREELIST_ITEM_EXPANDED(id, fn) \
457 wxEVT_TREELIST_GENERIC(ITEM_EXPANDED, id, fn)
458
459 wxDECLARE_TREELIST_EVENT(ITEM_CHECKED);
460 #define EVT_TREELIST_ITEM_CHECKED(id, fn) \
461 wxEVT_TREELIST_GENERIC(ITEM_CHECKED, id, fn)
462
463 wxDECLARE_TREELIST_EVENT(ITEM_ACTIVATED);
464 #define EVT_TREELIST_ITEM_ACTIVATED(id, fn) \
465 wxEVT_TREELIST_GENERIC(ITEM_ACTIVATED, id, fn)
466
467 wxDECLARE_TREELIST_EVENT(ITEM_CONTEXT_MENU);
468 #define EVT_TREELIST_ITEM_CONTEXT_MENU(id, fn) \
469 wxEVT_TREELIST_GENERIC(ITEM_CONTEXT_MENU, id, fn)
470
471 #undef wxDECLARE_TREELIST_EVENT
472
473 #endif // wxUSE_TREELISTCTRL
474
475 #endif // _WX_TREELIST_H_