]> git.saurik.com Git - wxWidgets.git/blame_incremental - include/wx/treelist.h
Partial fix for #15196: wxRichTextCell caret issues (dghart)
[wxWidgets.git] / include / wx / treelist.h
... / ...
CommitLineData
1///////////////////////////////////////////////////////////////////////////////
2// Name: wx/treelist.h
3// Purpose: wxTreeListCtrl class declaration.
4// Author: Vadim Zeitlin
5// Created: 2011-08-17
6// Copyright: (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
7// Licence: wxWindows licence
8///////////////////////////////////////////////////////////////////////////////
9
10#ifndef _WX_TREELIST_H_
11#define _WX_TREELIST_H_
12
13#include "wx/defs.h"
14
15#if wxUSE_TREELISTCTRL
16
17#include "wx/compositewin.h"
18#include "wx/containr.h"
19#include "wx/headercol.h"
20#include "wx/itemid.h"
21#include "wx/vector.h"
22#include "wx/window.h"
23#include "wx/withimages.h"
24
25class WXDLLIMPEXP_FWD_ADV wxDataViewCtrl;
26class WXDLLIMPEXP_FWD_ADV wxDataViewEvent;
27
28extern WXDLLIMPEXP_DATA_ADV(const char) wxTreeListCtrlNameStr[];
29
30class wxTreeListCtrl;
31class wxTreeListModel;
32class 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.
42enum
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 wxTL_NO_HEADER = 0x0010, // Column titles not visible.
50
51 wxTL_DEFAULT_STYLE = wxTL_SINGLE,
52 wxTL_STYLE_MASK = wxTL_SINGLE |
53 wxTL_MULTIPLE |
54 wxTL_CHECKBOX |
55 wxTL_3STATE |
56 wxTL_USER_3STATE
57};
58
59// ----------------------------------------------------------------------------
60// wxTreeListItem: unique identifier of an item in wxTreeListCtrl.
61// ----------------------------------------------------------------------------
62
63// Make wxTreeListItem a forward-declarable class even though it's simple
64// enough to possibly be declared as a simple typedef.
65class wxTreeListItem : public wxItemId<wxTreeListModelNode*>
66{
67public:
68 wxTreeListItem(wxTreeListModelNode* item = NULL)
69 : wxItemId<wxTreeListModelNode*>(item)
70 {
71 }
72};
73
74// Container of multiple items.
75typedef wxVector<wxTreeListItem> wxTreeListItems;
76
77// Some special "items" that can be used with InsertItem():
78extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_FIRST;
79extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_LAST;
80
81// ----------------------------------------------------------------------------
82// wxTreeListItemComparator: defines order of wxTreeListCtrl items.
83// ----------------------------------------------------------------------------
84
85class wxTreeListItemComparator
86{
87public:
88 wxTreeListItemComparator() { }
89
90 // The comparison function should return negative, null or positive value
91 // depending on whether the first item is less than, equal to or greater
92 // than the second one. The items should be compared using their values for
93 // the given column.
94 virtual int
95 Compare(wxTreeListCtrl* treelist,
96 unsigned column,
97 wxTreeListItem first,
98 wxTreeListItem second) = 0;
99
100 // Although this class is not used polymorphically by wxWidgets itself,
101 // provide virtual dtor in case it's used like this in the user code.
102 virtual ~wxTreeListItemComparator() { }
103
104private:
105 wxDECLARE_NO_COPY_CLASS(wxTreeListItemComparator);
106};
107
108// ----------------------------------------------------------------------------
109// wxTreeListCtrl: a control combining wxTree- and wxListCtrl features.
110// ----------------------------------------------------------------------------
111
112// This control also provides easy to use high level interface. Although the
113// implementation uses wxDataViewCtrl internally, this class is intentionally
114// simpler than wxDataViewCtrl and doesn't provide all of its functionality.
115//
116// If you need extra features you can always use GetDataView() accessor to work
117// with wxDataViewCtrl directly but doing this makes your unportable to possible
118// future non-wxDataViewCtrl-based implementations of this class.
119
120class WXDLLIMPEXP_ADV wxTreeListCtrl
121 : public wxCompositeWindow< wxNavigationEnabled<wxWindow> >,
122 public wxWithImages
123{
124public:
125 // Constructors and such
126 // ---------------------
127
128 wxTreeListCtrl() { Init(); }
129 wxTreeListCtrl(wxWindow* parent,
130 wxWindowID id,
131 const wxPoint& pos = wxDefaultPosition,
132 const wxSize& size = wxDefaultSize,
133 long style = wxTL_DEFAULT_STYLE,
134 const wxString& name = wxTreeListCtrlNameStr)
135 {
136 Init();
137
138 Create(parent, id, pos, size, style, name);
139 }
140
141 bool Create(wxWindow* parent,
142 wxWindowID id,
143 const wxPoint& pos = wxDefaultPosition,
144 const wxSize& size = wxDefaultSize,
145 long style = wxTL_DEFAULT_STYLE,
146 const wxString& name = wxTreeListCtrlNameStr);
147
148
149 virtual ~wxTreeListCtrl();
150
151 // Columns methods
152 // ---------------
153
154 // Add a column with the given title and attributes, returns the index of
155 // the new column or -1 on failure.
156 int AppendColumn(const wxString& title,
157 int width = wxCOL_WIDTH_AUTOSIZE,
158 wxAlignment align = wxALIGN_LEFT,
159 int flags = wxCOL_RESIZABLE)
160 {
161 return DoInsertColumn(title, -1, width, align, flags);
162 }
163
164 // Return the total number of columns.
165 unsigned GetColumnCount() const;
166
167 // Delete the column with the given index, returns false if index is
168 // invalid or deleting the column failed for some other reason.
169 bool DeleteColumn(unsigned col);
170
171 // Delete all columns.
172 void ClearColumns();
173
174 // Set column width to either the given value in pixels or to the value
175 // large enough to fit all of the items if width == wxCOL_WIDTH_AUTOSIZE.
176 void SetColumnWidth(unsigned col, int width);
177
178 // Get the current width of the given column in pixels.
179 int GetColumnWidth(unsigned col) const;
180
181 // Get the width appropriate for showing the given text. This is typically
182 // used as second argument for AppendColumn() or with SetColumnWidth().
183 int WidthFor(const wxString& text) const;
184
185
186 // Item methods
187 // ------------
188
189 // Adding items. The parent and text of the first column of the new item
190 // must always be specified, the rest is optional.
191 //
192 // Each item can have two images: one used for closed state and another for
193 // opened one. Only the first one is ever used for the items that don't
194 // have children. And both are not set by default.
195 //
196 // It is also possible to associate arbitrary client data pointer with the
197 // new item. It will be deleted by the control when the item is deleted
198 // (either by an explicit DeleteItem() call or because the entire control
199 // is destroyed).
200
201 wxTreeListItem AppendItem(wxTreeListItem parent,
202 const wxString& text,
203 int imageClosed = NO_IMAGE,
204 int imageOpened = NO_IMAGE,
205 wxClientData* data = NULL)
206 {
207 return DoInsertItem(parent, wxTLI_LAST, text,
208 imageClosed, imageOpened, data);
209 }
210
211 wxTreeListItem InsertItem(wxTreeListItem parent,
212 wxTreeListItem previous,
213 const wxString& text,
214 int imageClosed = NO_IMAGE,
215 int imageOpened = NO_IMAGE,
216 wxClientData* data = NULL)
217 {
218 return DoInsertItem(parent, previous, text,
219 imageClosed, imageOpened, data);
220 }
221
222 wxTreeListItem PrependItem(wxTreeListItem parent,
223 const wxString& text,
224 int imageClosed = NO_IMAGE,
225 int imageOpened = NO_IMAGE,
226 wxClientData* data = NULL)
227 {
228 return DoInsertItem(parent, wxTLI_FIRST, text,
229 imageClosed, imageOpened, data);
230 }
231
232 // Deleting items.
233 void DeleteItem(wxTreeListItem item);
234 void DeleteAllItems();
235
236
237 // Tree navigation
238 // ---------------
239
240 // Return the (never shown) root item.
241 wxTreeListItem GetRootItem() const;
242
243 // The parent item may be invalid for the root-level items.
244 wxTreeListItem GetItemParent(wxTreeListItem item) const;
245
246 // Iterate over the given item children: start by calling GetFirstChild()
247 // and then call GetNextSibling() for as long as it returns valid item.
248 wxTreeListItem GetFirstChild(wxTreeListItem item) const;
249 wxTreeListItem GetNextSibling(wxTreeListItem item) const;
250
251 // Return the first child of the root item, which is also the first item of
252 // the tree in depth-first traversal order.
253 wxTreeListItem GetFirstItem() const { return GetFirstChild(GetRootItem()); }
254
255 // Get item after the given one in the depth-first tree-traversal order.
256 // Calling this function starting with the result of GetFirstItem() allows
257 // iterating over all items in the tree.
258 wxTreeListItem GetNextItem(wxTreeListItem item) const;
259
260
261 // Items attributes
262 // ----------------
263
264 const wxString& GetItemText(wxTreeListItem item, unsigned col = 0) const;
265
266 // The convenience overload below sets the text for the first column.
267 void SetItemText(wxTreeListItem item, unsigned col, const wxString& text);
268 void SetItemText(wxTreeListItem item, const wxString& text)
269 {
270 SetItemText(item, 0, text);
271 }
272
273 // By default the opened image is the same as the normal, closed one (if
274 // it's used at all).
275 void SetItemImage(wxTreeListItem item, int closed, int opened = NO_IMAGE);
276
277 // Retrieve or set the data associated with the item.
278 wxClientData* GetItemData(wxTreeListItem item) const;
279 void SetItemData(wxTreeListItem item, wxClientData* data);
280
281
282 // Expanding and collapsing
283 // ------------------------
284
285 void Expand(wxTreeListItem item);
286 void Collapse(wxTreeListItem item);
287 bool IsExpanded(wxTreeListItem item) const;
288
289
290 // Selection handling
291 // ------------------
292
293 // This function can be used with single selection controls, use
294 // GetSelections() with the multi-selection ones.
295 wxTreeListItem GetSelection() const;
296
297 // This one can be used with either single or multi-selection controls.
298 unsigned GetSelections(wxTreeListItems& selections) const;
299
300 // In single selection mode Select() deselects any other selected items, in
301 // multi-selection case it adds to the selection.
302 void Select(wxTreeListItem item);
303
304 // Can be used in multiple selection mode only, single selected item in the
305 // single selection mode can't be unselected.
306 void Unselect(wxTreeListItem item);
307
308 // Return true if the item is selected, can be used in both single and
309 // multiple selection modes.
310 bool IsSelected(wxTreeListItem item) const;
311
312 // Select or unselect all items, only valid in multiple selection mode.
313 void SelectAll();
314 void UnselectAll();
315
316
317 // Checkbox handling
318 // -----------------
319
320 // Methods in this section can only be used with the controls created with
321 // wxTL_CHECKBOX style.
322
323 // Simple set, unset or query the checked state.
324 void CheckItem(wxTreeListItem item, wxCheckBoxState state = wxCHK_CHECKED);
325 void UncheckItem(wxTreeListItem item) { CheckItem(item, wxCHK_UNCHECKED); }
326
327 // The same but do it recursively for this item itself and its children.
328 void CheckItemRecursively(wxTreeListItem item,
329 wxCheckBoxState state = wxCHK_CHECKED);
330
331 // Update the parent of this item recursively: if this item and all its
332 // siblings are checked, the parent will become checked as well. If this
333 // item and all its siblings are unchecked, the parent will be unchecked.
334 // And if the siblings of this item are not all in the same state, the
335 // parent will be switched to indeterminate state. And then the same logic
336 // will be applied to the parents parent and so on recursively.
337 //
338 // This is typically called when the state of the given item has changed
339 // from EVT_TREELIST_ITEM_CHECKED() handler in the controls which have
340 // wxTL_3STATE flag. Notice that without this flag this function can't work
341 // as it would be unable to set the state of a parent with both checked and
342 // unchecked items so it's only allowed to call it when this flag is set.
343 void UpdateItemParentStateRecursively(wxTreeListItem item);
344
345 // Return the current state.
346 wxCheckBoxState GetCheckedState(wxTreeListItem item) const;
347
348 // Return true if all item children (if any) are in the given state.
349 bool AreAllChildrenInState(wxTreeListItem item,
350 wxCheckBoxState state) const;
351
352
353
354 // Sorting.
355 // --------
356
357 // Sort by the given column, either in ascending (default) or descending
358 // sort order.
359 //
360 // By default, simple alphabetical sorting is done by this column contents
361 // but SetItemComparator() may be called to perform comparison in some
362 // other way.
363 void SetSortColumn(unsigned col, bool ascendingOrder = true);
364
365 // If the control contents is sorted, return true and fill the output
366 // parameters with the column which is currently used for sorting and
367 // whether we sort using ascending or descending order. Otherwise, i.e. if
368 // the control contents is unsorted, simply return false.
369 bool GetSortColumn(unsigned* col, bool* ascendingOrder = NULL);
370
371 // Set the object to use for comparing the items. It will be called when
372 // the control is being sorted because the user clicked on a sortable
373 // column.
374 //
375 // The provided pointer is stored by the control so the object it points to
376 // must have a life-time equal or greater to that of the control itself. In
377 // addition, the pointer can be NULL to stop using custom comparator and
378 // revert to the default alphabetical comparison.
379 void SetItemComparator(wxTreeListItemComparator* comparator);
380
381
382 // View window functions.
383 // ----------------------
384
385 // This control itself is entirely covered by the "view window" which is
386 // currently a wxDataViewCtrl but if you want to avoid relying on this to
387 // allow your code to work with later versions which might not be
388 // wxDataViewCtrl-based, use the first function only and only use the
389 // second one if you really need to call wxDataViewCtrl methods on it.
390 wxWindow* GetView() const;
391 wxDataViewCtrl* GetDataView() const { return m_view; }
392
393private:
394 // Common part of all ctors.
395 void Init();
396
397 // Pure virtual method inherited from wxCompositeWindow.
398 virtual wxWindowList GetCompositeWindowParts() const;
399
400 // Implementation of AppendColumn().
401 int DoInsertColumn(const wxString& title,
402 int pos, // May be -1 meaning "append".
403 int width,
404 wxAlignment align,
405 int flags);
406
407 // Common part of {Append,Insert,Prepend}Item().
408 wxTreeListItem DoInsertItem(wxTreeListItem parent,
409 wxTreeListItem previous,
410 const wxString& text,
411 int imageClosed,
412 int imageOpened,
413 wxClientData* data);
414
415 // Send wxTreeListEvent corresponding to the given wxDataViewEvent for an
416 // item (as opposed for column-oriented events).
417 //
418 // Also updates the original event "skipped" and "vetoed" flags.
419 void SendItemEvent(wxEventType evt, wxDataViewEvent& event);
420
421 // Send wxTreeListEvent corresponding to the given column wxDataViewEvent.
422 void SendColumnEvent(wxEventType evt, wxDataViewEvent& event);
423
424
425 // Called by wxTreeListModel when an item is toggled by the user.
426 void OnItemToggled(wxTreeListItem item, wxCheckBoxState stateOld);
427
428 // Event handlers.
429 void OnSelectionChanged(wxDataViewEvent& event);
430 void OnItemExpanding(wxDataViewEvent& event);
431 void OnItemExpanded(wxDataViewEvent& event);
432 void OnItemActivated(wxDataViewEvent& event);
433 void OnItemContextMenu(wxDataViewEvent& event);
434 void OnColumnSorted(wxDataViewEvent& event);
435 void OnSize(wxSizeEvent& event);
436
437 wxDECLARE_EVENT_TABLE();
438
439
440 wxDataViewCtrl* m_view;
441 wxTreeListModel* m_model;
442
443 wxTreeListItemComparator* m_comparator;
444
445
446 // It calls our inherited protected wxWithImages::GetImage() method.
447 friend class wxTreeListModel;
448
449 wxDECLARE_NO_COPY_CLASS(wxTreeListCtrl);
450};
451
452// ----------------------------------------------------------------------------
453// wxTreeListEvent: event generated by wxTreeListCtrl.
454// ----------------------------------------------------------------------------
455
456class WXDLLIMPEXP_ADV wxTreeListEvent : public wxNotifyEvent
457{
458public:
459 // Default ctor is provided for wxRTTI needs only but should never be used.
460 wxTreeListEvent() { Init(); }
461
462 // The item affected by the event. Valid for all events except
463 // column-specific ones such as COLUMN_SORTED.
464 wxTreeListItem GetItem() const { return m_item; }
465
466 // The previous state of the item checkbox for ITEM_CHECKED events only.
467 wxCheckBoxState GetOldCheckedState() const { return m_oldCheckedState; }
468
469 // The index of the column affected by the event. Currently only used by
470 // COLUMN_SORTED event.
471 unsigned GetColumn() const { return m_column; }
472
473 virtual wxEvent* Clone() const { return new wxTreeListEvent(*this); }
474
475private:
476 // Common part of all ctors.
477 void Init()
478 {
479 m_column = static_cast<unsigned>(-1);
480
481 m_oldCheckedState = wxCHK_UNDETERMINED;
482 }
483
484 // Ctor is private, only wxTreeListCtrl can create events of this type.
485 wxTreeListEvent(wxEventType evtType,
486 wxTreeListCtrl* treelist,
487 wxTreeListItem item)
488 : wxNotifyEvent(evtType, treelist->GetId()),
489 m_item(item)
490 {
491 SetEventObject(treelist);
492
493 Init();
494 }
495
496 // Set the checkbox state before this event for ITEM_CHECKED events.
497 void SetOldCheckedState(wxCheckBoxState state)
498 {
499 m_oldCheckedState = state;
500 }
501
502 // Set the column affected by this event for COLUMN_SORTED events.
503 void SetColumn(unsigned column)
504 {
505 m_column = column;
506 }
507
508
509 const wxTreeListItem m_item;
510
511 wxCheckBoxState m_oldCheckedState;
512
513 unsigned m_column;
514
515 friend class wxTreeListCtrl;
516
517 wxDECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxTreeListEvent);
518};
519
520// Event types and event table macros.
521
522typedef void (wxEvtHandler::*wxTreeListEventFunction)(wxTreeListEvent&);
523
524#define wxTreeListEventHandler(func) \
525 wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func)
526
527#define wxEVT_TREELIST_GENERIC(name, id, fn) \
528 wx__DECLARE_EVT1(wxEVT_TREELIST_##name, id, wxTreeListEventHandler(fn))
529
530#define wxDECLARE_TREELIST_EVENT(name) \
531 wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_ADV, \
532 wxEVT_TREELIST_##name, \
533 wxTreeListEvent)
534
535wxDECLARE_TREELIST_EVENT(SELECTION_CHANGED);
536#define EVT_TREELIST_SELECTION_CHANGED(id, fn) \
537 wxEVT_TREELIST_GENERIC(SELECTION_CHANGED, id, fn)
538
539wxDECLARE_TREELIST_EVENT(ITEM_EXPANDING);
540#define EVT_TREELIST_ITEM_EXPANDING(id, fn) \
541 wxEVT_TREELIST_GENERIC(ITEM_EXPANDING, id, fn)
542
543wxDECLARE_TREELIST_EVENT(ITEM_EXPANDED);
544#define EVT_TREELIST_ITEM_EXPANDED(id, fn) \
545 wxEVT_TREELIST_GENERIC(ITEM_EXPANDED, id, fn)
546
547wxDECLARE_TREELIST_EVENT(ITEM_CHECKED);
548#define EVT_TREELIST_ITEM_CHECKED(id, fn) \
549 wxEVT_TREELIST_GENERIC(ITEM_CHECKED, id, fn)
550
551wxDECLARE_TREELIST_EVENT(ITEM_ACTIVATED);
552#define EVT_TREELIST_ITEM_ACTIVATED(id, fn) \
553 wxEVT_TREELIST_GENERIC(ITEM_ACTIVATED, id, fn)
554
555wxDECLARE_TREELIST_EVENT(ITEM_CONTEXT_MENU);
556#define EVT_TREELIST_ITEM_CONTEXT_MENU(id, fn) \
557 wxEVT_TREELIST_GENERIC(ITEM_CONTEXT_MENU, id, fn)
558
559wxDECLARE_TREELIST_EVENT(COLUMN_SORTED);
560#define EVT_TREELIST_COLUMN_SORTED(id, fn) \
561 wxEVT_TREELIST_GENERIC(COLUMN_SORTED, id, fn)
562
563#undef wxDECLARE_TREELIST_EVENT
564
565// old wxEVT_COMMAND_* constants
566#define wxEVT_COMMAND_TREELIST_SELECTION_CHANGED wxEVT_TREELIST_SELECTION_CHANGED
567#define wxEVT_COMMAND_TREELIST_ITEM_EXPANDING wxEVT_TREELIST_ITEM_EXPANDING
568#define wxEVT_COMMAND_TREELIST_ITEM_EXPANDED wxEVT_TREELIST_ITEM_EXPANDED
569#define wxEVT_COMMAND_TREELIST_ITEM_CHECKED wxEVT_TREELIST_ITEM_CHECKED
570#define wxEVT_COMMAND_TREELIST_ITEM_ACTIVATED wxEVT_TREELIST_ITEM_ACTIVATED
571#define wxEVT_COMMAND_TREELIST_ITEM_CONTEXT_MENU wxEVT_TREELIST_ITEM_CONTEXT_MENU
572#define wxEVT_COMMAND_TREELIST_COLUMN_SORTED wxEVT_TREELIST_COLUMN_SORTED
573
574#endif // wxUSE_TREELISTCTRL
575
576#endif // _WX_TREELIST_H_