1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDataView* classes
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
11 @class wxDataViewModel
13 wxDataViewModel is the base class for all data model to be displayed by a
16 All other models derive from it and must implement its pure virtual functions
17 in order to define a complete data model. In detail, you need to override
18 wxDataViewModel::IsContainer, wxDataViewModel::GetParent, wxDataViewModel::GetChildren,
19 wxDataViewModel::GetColumnCount, wxDataViewModel::GetColumnType and
20 wxDataViewModel::GetValue in order to define the data model which acts as an
21 interface between your actual data and the wxDataViewCtrl.
23 Note that wxDataViewModel does not define the position or index of any item
24 in the control because different controls might display the same data differently.
25 wxDataViewModel does provide a wxDataViewModel::Compare method which the
26 wxDataViewCtrl may use to sort the data either in conjunction with a column
27 header or without (see wxDataViewModel::HasDefaultCompare).
29 wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant
30 to store data and its type in a generic way. wxVariant can be extended to contain
31 almost any data without changes to the original class. To a certain extent,
32 you can use (the somewhat more elegant) wxAny instead of wxVariant as there
33 is code to convert between the two, but it is unclear what impact this will
36 Since you will usually allow the wxDataViewCtrl to change your data
37 through its graphical interface, you will also have to override
38 wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change
39 to some data has been committed.
41 If the data represented by the model is changed by something else than its
42 associated wxDataViewCtrl, the control has to be notified about the change.
43 Depending on what happened you need to call one of the following methods:
44 - wxDataViewModel::ValueChanged,
45 - wxDataViewModel::ItemAdded,
46 - wxDataViewModel::ItemDeleted,
47 - wxDataViewModel::ItemChanged,
48 - wxDataViewModel::Cleared.
50 There are plural forms for notification of addition, change or removal of
51 several item at once. See:
52 - wxDataViewModel::ItemsAdded,
53 - wxDataViewModel::ItemsDeleted,
54 - wxDataViewModel::ItemsChanged.
56 This class maintains a list of wxDataViewModelNotifier which link this class
57 to the specific implementations on the supported platforms so that e.g. calling
58 wxDataViewModel::ValueChanged on this model will just call
59 wxDataViewModelNotifier::ValueChanged for each notifier that has been added.
60 You can also add your own notifier in order to get informed about any changes
61 to the data in the list model.
63 Currently wxWidgets provides the following models apart from the base model:
64 wxDataViewIndexListModel, wxDataViewVirtualListModel, wxDataViewTreeStore,
67 Note that wxDataViewModel is reference counted, derives from wxRefCounter
68 and cannot be deleted directly as it can be shared by several wxDataViewCtrls.
69 This implies that you need to decrease the reference count after
70 associating the model with a control like this:
73 wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
74 wxDataViewModel *musicModel = new MyMusicModel;
75 m_musicCtrl->AssociateModel( musicModel );
76 musicModel->DecRef(); // avoid memory leak !!
81 A potentially better way to avoid memory leaks is to use wxObjectDataPtr
84 wxObjectDataPtr<MyMusicModel> musicModel;
86 wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
87 musicModel = new MyMusicModel;
88 m_musicCtrl->AssociateModel( musicModel.get() );
97 class wxDataViewModel
: public wxRefCounter
106 Adds a wxDataViewModelNotifier to the model.
108 void AddNotifier(wxDataViewModelNotifier
* notifier
);
111 Change the value of the given item and update the control to reflect
114 This function simply calls SetValue() and, if it succeeded,
122 The item (row) to update.
124 The column to update.
126 @true if both SetValue() and ValueChanged() returned @true.
128 bool ChangeValue(const wxVariant
& variant
,
129 const wxDataViewItem
& item
,
133 Called to inform the model that all data has been cleared.
134 The control will reread the data from the model again.
136 virtual bool Cleared();
139 The compare function to be used by control. The default compare function
140 sorts by container and other items separately and in ascending order.
141 Override this for a different sorting behaviour.
143 @see HasDefaultCompare().
145 virtual int Compare(const wxDataViewItem
& item1
,
146 const wxDataViewItem
& item2
,
148 bool ascending
) const;
151 Override this to indicate that the item has special font attributes.
152 This only affects the wxDataViewTextRendererText renderer.
154 The base class version always simply returns @false.
156 @see wxDataViewItemAttr.
159 The item for which the attribute is requested.
161 The column of the item for which the attribute is requested.
163 The attribute to be filled in if the function returns @true.
165 @true if this item has an attribute or @false otherwise.
167 virtual bool GetAttr(const wxDataViewItem
& item
, unsigned int col
,
168 wxDataViewItemAttr
& attr
) const;
171 Override this to indicate that the item should be disabled.
173 Disabled items are displayed differently (e.g. grayed out) and cannot
176 The base class version always returns @true, thus making all items
180 The item whose enabled status is requested.
182 The column of the item whose enabled status is requested.
184 @true if this item should be enabled, @false otherwise.
186 @note Currently disabling items is not supported by the wxOSX/Carbon
191 virtual bool IsEnabled(const wxDataViewItem
&item
,
192 unsigned int col
) const;
195 Override this so the control can query the child items of an item.
196 Returns the number of items.
198 virtual unsigned int GetChildren(const wxDataViewItem
& item
,
199 wxDataViewItemArray
& children
) const = 0;
202 Override this to indicate the number of columns in the model.
204 virtual unsigned int GetColumnCount() const = 0;
207 Override this to indicate what type of data is stored in the
208 column specified by @a col.
210 This should return a string indicating the type of data as reported by wxVariant.
212 virtual wxString
GetColumnType(unsigned int col
) const = 0;
215 Override this to indicate which wxDataViewItem representing the parent
216 of @a item or an invalid wxDataViewItem if the root item is
219 virtual wxDataViewItem
GetParent(const wxDataViewItem
& item
) const = 0;
222 Override this to indicate the value of @a item.
223 A wxVariant is used to store the data.
225 virtual void GetValue(wxVariant
& variant
, const wxDataViewItem
& item
,
226 unsigned int col
) const = 0;
229 Override this method to indicate if a container item merely acts as a
230 headline (or for categorisation) or if it also acts a normal item with
231 entries for further columns. By default returns @false.
233 virtual bool HasContainerColumns(const wxDataViewItem
& item
) const;
236 Override this to indicate that the model provides a default compare
237 function that the control should use if no wxDataViewColumn has been
238 chosen for sorting. Usually, the user clicks on a column header for
239 sorting, the data will be sorted alphanumerically.
241 If any other order (e.g. by index or order of appearance) is required,
242 then this should be used.
243 See wxDataViewIndexListModel for a model which makes use of this.
245 virtual bool HasDefaultCompare() const;
248 Return true if there is a value in the given column of this item.
250 All normal items have values in all columns but the container items
251 only show their label in the first column (@a col == 0) by default (but
252 see HasContainerColumns()). So this function always returns true for
253 the first column while for the other ones it returns true only if the
254 item is not a container or HasContainerColumns() was overridden to
259 bool HasValue(const wxDataViewItem
& item
, unsigned col
) const;
262 Override this to indicate of @a item is a container, i.e. if
263 it can have child items.
265 virtual bool IsContainer(const wxDataViewItem
& item
) const = 0;
268 Call this to inform the model that an item has been added to the data.
270 bool ItemAdded(const wxDataViewItem
& parent
,
271 const wxDataViewItem
& item
);
274 Call this to inform the model that an item has changed.
276 This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
277 event (in which the column fields will not be set) to the user.
279 bool ItemChanged(const wxDataViewItem
& item
);
282 Call this to inform the model that an item has been deleted from the data.
284 bool ItemDeleted(const wxDataViewItem
& parent
,
285 const wxDataViewItem
& item
);
288 Call this to inform the model that several items have been added to the data.
290 bool ItemsAdded(const wxDataViewItem
& parent
,
291 const wxDataViewItemArray
& items
);
294 Call this to inform the model that several items have changed.
296 This will eventually emit @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
297 events (in which the column fields will not be set) to the user.
299 bool ItemsChanged(const wxDataViewItemArray
& items
);
302 Call this to inform the model that several items have been deleted.
304 bool ItemsDeleted(const wxDataViewItem
& parent
,
305 const wxDataViewItemArray
& items
);
308 Remove the @a notifier from the list of notifiers.
310 void RemoveNotifier(wxDataViewModelNotifier
* notifier
);
313 Call this to initiate a resort after the sort function has been changed.
315 virtual void Resort();
318 This gets called in order to set a value in the data model.
320 The most common scenario is that the wxDataViewCtrl calls this method
321 after the user changed some data in the view.
323 This is the function you need to override in your derived class but if
324 you want to call it, ChangeValue() is usually more convenient as
325 otherwise you need to manually call ValueChanged() to update the
328 virtual bool SetValue(const wxVariant
& variant
,
329 const wxDataViewItem
& item
,
330 unsigned int col
) = 0;
333 Call this to inform this model that a value in the model has been changed.
334 This is also called from wxDataViewCtrl's internal editing code, e.g. when
335 editing a text field in the control.
337 This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
340 virtual bool ValueChanged(const wxDataViewItem
& item
,
346 Destructor. This should not be called directly. Use DecRef() instead.
348 virtual ~wxDataViewModel();
354 @class wxDataViewListModel
356 Base class with abstract API for wxDataViewIndexListModel and
357 wxDataViewVirtualListModel.
362 class wxDataViewListModel
: public wxDataViewModel
369 virtual ~wxDataViewIndexListModel();
372 Compare method that sorts the items by their index.
374 int Compare(const wxDataViewItem
& item1
,
375 const wxDataViewItem
& item2
,
376 unsigned int column
, bool ascending
) const;
379 Override this to indicate that the row has special font attributes.
380 This only affects the wxDataViewTextRendererText() renderer.
382 The base class version always simply returns @false.
384 @see wxDataViewItemAttr.
387 The row for which the attribute is requested.
389 The column for which the attribute is requested.
391 The attribute to be filled in if the function returns @true.
393 @true if this item has an attribute or @false otherwise.
395 virtual bool GetAttrByRow(unsigned int row
, unsigned int col
,
396 wxDataViewItemAttr
& attr
) const;
399 Override this if you want to disable specific items.
401 The base class version always returns @true, thus making all items
405 The row of the item whose enabled status is requested.
407 The column of the item whose enabled status is requested.
409 @true if the item at this row and column should be enabled,
412 @note See wxDataViewModel::IsEnabled() for the current status of
413 support for disabling the items under different platforms.
417 virtual bool IsEnabledByRow(unsigned int row
,
418 unsigned int col
) const;
421 Returns the number of items (or rows) in the list.
423 unsigned int GetCount() const;
426 Returns the wxDataViewItem at the given @e row.
428 wxDataViewItem
GetItem(unsigned int row
) const;
431 Returns the position of given @e item.
433 unsigned int GetRow(const wxDataViewItem
& item
) const;
436 Override this to allow getting values from the model.
438 virtual void GetValueByRow(wxVariant
& variant
, unsigned int row
,
439 unsigned int col
) const = 0;
442 Call this after if the data has to be read again from the model.
443 This is useful after major changes when calling the methods below
444 (possibly thousands of times) doesn't make sense.
446 void Reset(unsigned int new_size
);
449 Call this after a row has been appended to the model.
454 Call this after a row has been changed.
456 void RowChanged(unsigned int row
);
459 Call this after a row has been deleted.
461 void RowDeleted(unsigned int row
);
464 Call this after a row has been inserted at the given position.
466 void RowInserted(unsigned int before
);
469 Call this after a row has been prepended to the model.
474 Call this after a value has been changed.
476 void RowValueChanged(unsigned int row
, unsigned int col
);
479 Call this after rows have been deleted.
480 The array will internally get copied and sorted in descending order so
481 that the rows with the highest position will be deleted first.
483 void RowsDeleted(const wxArrayInt
& rows
);
486 Called in order to set a value in the model.
488 virtual bool SetValueByRow(const wxVariant
& variant
, unsigned int row
,
489 unsigned int col
) = 0;
494 @class wxDataViewIndexListModel
496 wxDataViewIndexListModel is a specialized data model which lets you address
497 an item by its position (row) rather than its wxDataViewItem (which you can
498 obtain from this class).
499 This model also provides its own wxDataViewIndexListModel::Compare
500 method which sorts the model's data by the index.
502 This model is not a virtual model since the control stores each wxDataViewItem.
503 Use wxDataViewVirtualListModel if you need to display millions of items or
504 have other reason to use a virtual control.
506 @see wxDataViewListModel for the API.
512 class wxDataViewIndexListModel
: public wxDataViewListModel
518 wxDataViewIndexListModel(unsigned int initial_size
= 0);
523 @class wxDataViewVirtualListModel
525 wxDataViewVirtualListModel is a specialized data model which lets you address
526 an item by its position (row) rather than its wxDataViewItem and as such offers
527 the exact same interface as wxDataViewIndexListModel.
528 The important difference is that under platforms other than OS X, using this
529 model will result in a truly virtual control able to handle millions of items
530 as the control doesn't store any item (a feature not supported by OS X).
532 @see wxDataViewListModel for the API.
538 class wxDataViewVirtualListModel
: public wxDataViewListModel
544 wxDataViewVirtualListModel(unsigned int initial_size
= 0);
551 @class wxDataViewItemAttr
553 This class is used to indicate to a wxDataViewCtrl that a certain item
554 (see wxDataViewItem) has extra font attributes for its renderer.
555 For this, it is required to override wxDataViewModel::GetAttr.
557 Attributes are currently only supported by wxDataViewTextRendererText.
562 class wxDataViewItemAttr
568 wxDataViewItemAttr();
571 Call this to indicate that the item shall be displayed in bold text.
573 void SetBold(bool set
);
576 Call this to indicate that the item shall be displayed with that colour.
578 void SetColour(const wxColour
& colour
);
581 Call this to set the background colour to use.
583 Currently this attribute is only supported in the generic version of
584 wxDataViewCtrl and ignored by the native GTK+ and OS X implementations.
588 void SetBackgroundColour(const wxColour
& colour
);
591 Call this to indicate that the item shall be displayed in italic text.
593 void SetItalic(bool set
);
599 @class wxDataViewItem
601 wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl
602 in a persistent way, i.e. independent of the position of the item in the control
603 or changes to its contents.
605 It must hold a unique ID of type @e void* in its only field and can be converted
608 If the ID is @NULL the wxDataViewItem is invalid and wxDataViewItem::IsOk will
609 return @false which used in many places in the API of wxDataViewCtrl to
610 indicate that e.g. no item was found. An ID of @NULL is also used to indicate
611 the invisible root. Examples for this are wxDataViewModel::GetParent and
612 wxDataViewModel::GetChildren.
625 wxDataViewItem(const wxDataViewItem
& item
);
626 explicit wxDataViewItem(void* id
);
635 Returns @true if the ID is not @NULL.
641 // ----------------------------------------------------------------------------
642 // wxDataViewCtrl flags
643 // ----------------------------------------------------------------------------
645 // size of a wxDataViewRenderer without contents:
646 #define wxDVC_DEFAULT_RENDERER_SIZE 20
648 // the default width of new (text) columns:
649 #define wxDVC_DEFAULT_WIDTH 80
651 // the default width of new toggle columns:
652 #define wxDVC_TOGGLE_DEFAULT_WIDTH 30
654 // the default minimal width of the columns:
655 #define wxDVC_DEFAULT_MINWIDTH 30
657 // The default alignment of wxDataViewRenderers is to take
658 // the alignment from the column it owns.
659 #define wxDVR_DEFAULT_ALIGNMENT -1
661 #define wxDV_SINGLE 0x0000 // for convenience
662 #define wxDV_MULTIPLE 0x0001 // can select multiple items
664 #define wxDV_NO_HEADER 0x0002 // column titles not visible
665 #define wxDV_HORIZ_RULES 0x0004 // light horizontal rules between rows
666 #define wxDV_VERT_RULES 0x0008 // light vertical rules between columns
668 #define wxDV_ROW_LINES 0x0010 // alternating colour in rows
669 #define wxDV_VARIABLE_LINE_HEIGHT 0x0020 // variable line height
673 wxEventType wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED
;
675 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED
;
676 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING
;
677 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED
;
678 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING
;
679 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED
;
680 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING
;
681 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED
;
682 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE
;
683 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED
;
685 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU
;
687 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK
;
688 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK
;
689 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED
;
690 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED
;
691 wxEventType wxEVT_COMMAND_DATAVIEW_CACHE_HINT
;
693 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG
;
694 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE
;
695 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP
;
698 @class wxDataViewCtrl
700 wxDataViewCtrl is a control to display data either in a tree like fashion or
701 in a tabular form or both.
703 If you only need to display a simple tree structure with an API more like the
704 older wxTreeCtrl class, then the specialized wxDataViewTreeCtrl can be used.
705 Likewise, if you only want to display simple table structure you can use
706 the specialized wxDataViewListCtrl class. Both wxDataViewTreeCtrl and
707 wxDataViewListCtrl can be used without defining your own wxDataViewModel.
709 A wxDataViewItem is used to represent a (visible) item in the control.
711 Unlike wxListCtrl, wxDataViewCtrl doesn't get its data from the user through
712 virtual functions or by setting it directly. Instead you need to write your own
713 wxDataViewModel and associate it with this control.
714 Then you need to add a number of wxDataViewColumn to this control to define
715 what each column shall display. Each wxDataViewColumn in turn owns 1 instance
716 of a wxDataViewRenderer to render its cells.
718 A number of standard renderers for rendering text, dates, images, toggle,
719 a progress bar etc. are provided. Additionally, the user can write custom
720 renderers deriving from wxDataViewCustomRenderer for displaying anything.
722 All data transfer from the control to the model and the user code is done
723 through wxVariant which can be extended to support more data formats as necessary.
724 Accordingly, all type information uses the strings returned from wxVariant::GetType.
728 Single selection mode. This is the default.
729 @style{wxDV_MULTIPLE}
730 Multiple selection mode.
731 @style{wxDV_ROW_LINES}
732 Use alternating colours for rows if supported by platform and theme.
733 Currently only supported by the native GTK and OS X implementations
734 but not by the generic one.
735 @style{wxDV_HORIZ_RULES}
736 Display fine rules between row if supported.
737 @style{wxDV_VERT_RULES}
738 Display fine rules between columns is supported.
739 @style{wxDV_VARIABLE_LINE_HEIGHT}
740 Allow variable line heights.
741 This can be inefficient when displaying large number of items.
742 @style{wxDV_NO_HEADER}
743 Do not show column headers (which are shown by default).
746 @beginEventEmissionTable{wxDataViewEvent}
747 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
748 Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
749 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
750 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. This event
751 is triggered by double clicking an item or pressing some special key
752 (usually "Enter") when it is focused.
753 @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}
754 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING event. This
755 event can be vetoed in order to prevent editing on an item by item
757 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
758 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
759 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
760 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
761 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
762 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
763 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
764 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
765 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
766 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
767 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
768 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
769 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
770 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
771 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
772 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event
773 generated when the user right clicks inside the control. Notice that
774 this menu is generated even if the click didn't occur on any valid
775 item, in this case wxDataViewEvent::GetItem() simply returns an
777 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
778 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK event.
779 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
780 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
781 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
782 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
783 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
784 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
785 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
786 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
787 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
788 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
789 @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
790 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
793 Notice that this control doesn't allow to process generic mouse events such
794 as @c wxEVT_LEFT_DOWN in all ports (notably it doesn't work in wxGTK). If
795 you need to handle any mouse events not covered by the ones above, consider
796 using a custom renderer for the cells that must handle them.
800 @appearance{dataviewctrl.png}
802 class wxDataViewCtrl
: public wxControl
811 Constructor. Calls Create().
813 wxDataViewCtrl(wxWindow
* parent
, wxWindowID id
,
814 const wxPoint
& pos
= wxDefaultPosition
,
815 const wxSize
& size
= wxDefaultSize
,
817 const wxValidator
& validator
= wxDefaultValidator
,
818 const wxString
& name
= wxDataViewCtrlNameStr
);
823 virtual ~wxDataViewCtrl();
826 Appends a wxDataViewColumn to the control. Returns @true on success.
828 Note that there is a number of short cut methods which implicitly create
829 a wxDataViewColumn and a wxDataViewRenderer for it (see below).
831 virtual bool AppendColumn(wxDataViewColumn
* col
);
834 Prepends a wxDataViewColumn to the control. Returns @true on success.
836 Note that there is a number of short cut methods which implicitly create
837 a wxDataViewColumn and a wxDataViewRenderer for it.
839 virtual bool PrependColumn(wxDataViewColumn
* col
);
842 Inserts a wxDataViewColumn to the control. Returns @true on success.
844 virtual bool InsertColumn(unsigned int pos
, wxDataViewColumn
* col
);
848 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
849 created in the function or @NULL on failure.
851 wxDataViewColumn
* AppendBitmapColumn(const wxString
& label
,
852 unsigned int model_column
,
853 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
855 wxAlignment align
= wxALIGN_CENTER
,
856 int flags
= wxDATAVIEW_COL_RESIZABLE
);
857 wxDataViewColumn
* AppendBitmapColumn(const wxBitmap
& label
,
858 unsigned int model_column
,
859 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
861 wxAlignment align
= wxALIGN_CENTER
,
862 int flags
= wxDATAVIEW_COL_RESIZABLE
);
867 Appends a column for rendering a date. Returns the wxDataViewColumn
868 created in the function or @NULL on failure.
870 @note The @a align parameter is applied to both the column header and
873 wxDataViewColumn
* AppendDateColumn(const wxString
& label
,
874 unsigned int model_column
,
875 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
877 wxAlignment align
= wxALIGN_NOT
,
878 int flags
= wxDATAVIEW_COL_RESIZABLE
);
879 wxDataViewColumn
* AppendDateColumn(const wxBitmap
& label
,
880 unsigned int model_column
,
881 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
883 wxAlignment align
= wxALIGN_NOT
,
884 int flags
= wxDATAVIEW_COL_RESIZABLE
);
889 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
890 created in the function or @NULL on failure.
891 This method uses the wxDataViewIconTextRenderer class.
893 @note The @a align parameter is applied to both the column header and
896 wxDataViewColumn
* AppendIconTextColumn(const wxString
& label
,
897 unsigned int model_column
,
898 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
900 wxAlignment align
= wxALIGN_NOT
,
901 int flags
= wxDATAVIEW_COL_RESIZABLE
);
902 wxDataViewColumn
* AppendIconTextColumn(const wxBitmap
& label
,
903 unsigned int model_column
,
904 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
906 wxAlignment align
= wxALIGN_NOT
,
907 int flags
= wxDATAVIEW_COL_RESIZABLE
);
912 Appends a column for rendering a progress indicator. Returns the
913 wxDataViewColumn created in the function or @NULL on failure.
915 @note The @a align parameter is applied to both the column header and
918 wxDataViewColumn
* AppendProgressColumn(const wxString
& label
,
919 unsigned int model_column
,
920 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
922 wxAlignment align
= wxALIGN_CENTER
,
923 int flags
= wxDATAVIEW_COL_RESIZABLE
);
924 wxDataViewColumn
* AppendProgressColumn(const wxBitmap
& label
,
925 unsigned int model_column
,
926 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
928 wxAlignment align
= wxALIGN_CENTER
,
929 int flags
= wxDATAVIEW_COL_RESIZABLE
);
934 Appends a column for rendering text. Returns the wxDataViewColumn
935 created in the function or @NULL on failure.
937 @note The @a align parameter is applied to both the column header and
940 wxDataViewColumn
* AppendTextColumn(const wxString
& label
,
941 unsigned int model_column
,
942 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
944 wxAlignment align
= wxALIGN_NOT
,
945 int flags
= wxDATAVIEW_COL_RESIZABLE
);
946 wxDataViewColumn
* AppendTextColumn(const wxBitmap
& label
,
947 unsigned int model_column
,
948 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
950 wxAlignment align
= wxALIGN_NOT
,
951 int flags
= wxDATAVIEW_COL_RESIZABLE
);
956 Appends a column for rendering a toggle. Returns the wxDataViewColumn
957 created in the function or @NULL on failure.
959 @note The @a align parameter is applied to both the column header and
962 wxDataViewColumn
* AppendToggleColumn(const wxString
& label
,
963 unsigned int model_column
,
964 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
966 wxAlignment align
= wxALIGN_CENTER
,
967 int flags
= wxDATAVIEW_COL_RESIZABLE
);
968 wxDataViewColumn
* AppendToggleColumn(const wxBitmap
& label
,
969 unsigned int model_column
,
970 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
972 wxAlignment align
= wxALIGN_CENTER
,
973 int flags
= wxDATAVIEW_COL_RESIZABLE
);
977 Associates a wxDataViewModel with the control.
978 This increases the reference count of the model by 1.
980 virtual bool AssociateModel(wxDataViewModel
* model
);
985 virtual bool ClearColumns();
990 virtual void Collapse(const wxDataViewItem
& item
);
993 Create the control. Useful for two step creation.
995 bool Create(wxWindow
* parent
, wxWindowID id
,
996 const wxPoint
& pos
= wxDefaultPosition
,
997 const wxSize
& size
= wxDefaultSize
,
999 const wxValidator
& validator
= wxDefaultValidator
,
1000 const wxString
& name
= wxDataViewCtrlNameStr
);
1003 Deletes given column.
1005 virtual bool DeleteColumn(wxDataViewColumn
* column
);
1008 Programmatically starts editing given cell of @a item.
1010 Doesn't do anything if the item or this column is not editable.
1012 @note Currently not implemented in wxOSX/Carbon.
1016 virtual void EditItem(const wxDataViewItem
& item
, const wxDataViewColumn
*column
);
1019 Enable drag operations using the given @a format.
1021 virtual bool EnableDragSource( const wxDataFormat
&format
);
1024 Enable drop operations using the given @a format.
1026 virtual bool EnableDropTarget( const wxDataFormat
&format
);
1029 Call this to ensure that the given item is visible.
1031 virtual void EnsureVisible(const wxDataViewItem
& item
,
1032 const wxDataViewColumn
* column
= NULL
);
1037 virtual void Expand(const wxDataViewItem
& item
);
1040 Expands all ancestors of the @a item. This method also
1041 ensures that the item itself as well as all ancestor
1042 items have been read from the model by the control.
1044 virtual void ExpandAncestors( const wxDataViewItem
& item
);
1047 Returns pointer to the column. @a pos refers to the position in the
1048 control which may change after reordering columns by the user.
1050 virtual wxDataViewColumn
* GetColumn(unsigned int pos
) const;
1053 Returns the number of columns.
1055 virtual unsigned int GetColumnCount() const;
1058 Returns the position of the column or -1 if not found in the control.
1060 virtual int GetColumnPosition(const wxDataViewColumn
* column
) const;
1063 Returns column containing the expanders.
1065 wxDataViewColumn
* GetExpanderColumn() const;
1068 Returns the currently focused item.
1070 This is the item that the keyboard commands apply to. It may be invalid
1071 if there is no focus currently.
1073 This method is mostly useful for the controls with @c wxDV_MULTIPLE
1074 style as in the case of single selection it returns the same thing as
1077 Notice that under all platforms except Mac OS X the currently focused
1078 item may be selected or not but under OS X the current item is always
1081 @see SetCurrentItem(), GetCurrentColumn()
1085 wxDataViewItem
GetCurrentItem() const;
1088 Returns the column that currently has focus.
1090 If the focus is set to individual cell within the currently focused
1091 item (as opposed to being on the item as a whole), then this is the
1092 column that the focus is on.
1094 Returns NULL if no column currently has focus.
1096 @see GetCurrentItem()
1100 wxDataViewColumn
*GetCurrentColumn() const;
1103 Returns indentation.
1105 int GetIndent() const;
1108 Returns item rectangle.
1110 This method is currently not implemented at all in wxGTK and only
1111 implemented for non-@NULL @a col argument in wxOSX. It is fully
1112 implemented in the generic version of the control.
1117 If non-@NULL, the rectangle returned corresponds to the
1118 intersection of the item with the specified column. If @NULL, the
1119 rectangle spans all the columns.
1121 virtual wxRect
GetItemRect(const wxDataViewItem
& item
,
1122 const wxDataViewColumn
* col
= NULL
) const;
1125 Returns pointer to the data model associated with the control (if any).
1127 wxDataViewModel
* GetModel();
1130 Returns the number of currently selected items.
1132 This method may be called for both the controls with single and
1133 multiple selections and returns the number of selected item, possibly
1138 virtual int GetSelectedItemsCount() const;
1141 Returns first selected item or an invalid item if none is selected.
1143 This method may be called for both the controls with single and
1144 multiple selections but returns an invalid item if more than one item
1145 is selected in the latter case, use HasSelection() to determine if
1146 there are any selected items when using multiple selection.
1148 virtual wxDataViewItem
GetSelection() const;
1151 Fills @a sel with currently selected items and returns their number.
1153 This method may be called for both the controls with single and
1154 multiple selections. In the single selection case it returns the array
1155 with at most one element in it.
1157 @see GetSelectedItemsCount()
1159 virtual int GetSelections(wxDataViewItemArray
& sel
) const;
1162 Returns the wxDataViewColumn currently responsible for sorting
1163 or @NULL if none has been selected.
1165 virtual wxDataViewColumn
* GetSortingColumn() const;
1168 Returns true if any items are currently selected.
1170 This method may be called for both the controls with single and
1171 multiple selections.
1173 Calling this method is equivalent to calling GetSelectedItemsCount()
1174 and comparing its result with 0 but is more clear and might also be
1175 implemented more efficiently in the future.
1179 bool HasSelection() const;
1184 virtual void HitTest(const wxPoint
& point
, wxDataViewItem
& item
,
1185 wxDataViewColumn
*& col
) const;
1188 Return @true if the item is expanded.
1190 virtual bool IsExpanded(const wxDataViewItem
& item
) const;
1193 Return @true if the item is selected.
1195 virtual bool IsSelected(const wxDataViewItem
& item
) const;
1198 Select the given item.
1200 In single selection mode this changes the (unique) currently selected
1201 item. In multi selection mode, the @a item is selected and the
1202 previously selected items remain selected.
1204 virtual void Select(const wxDataViewItem
& item
);
1209 virtual void SelectAll();
1212 Set which column shall contain the tree-like expanders.
1214 void SetExpanderColumn(wxDataViewColumn
* col
);
1217 Changes the currently focused item.
1219 The @a item parameter must be valid, there is no way to remove the
1220 current item from the control.
1222 In single selection mode, calling this method is the same as calling
1223 Select() and is thus not very useful. In multiple selection mode this
1224 method only moves the current item however without changing the
1225 selection except under OS X where the current item is always selected,
1226 so calling SetCurrentItem() selects @a item if it hadn't been selected
1229 @see GetCurrentItem()
1233 void SetCurrentItem(const wxDataViewItem
& item
);
1236 Sets the indentation.
1238 void SetIndent(int indent
);
1241 Sets the selection to the array of wxDataViewItems.
1243 virtual void SetSelections(const wxDataViewItemArray
& sel
);
1246 Unselect the given item.
1248 virtual void Unselect(const wxDataViewItem
& item
);
1252 This method only has effect if multiple selections are allowed.
1254 virtual void UnselectAll();
1257 Sets the row height.
1259 This function can only be used when all rows have the same height, i.e.
1260 when wxDV_VARIABLE_LINE_HEIGHT flag is not used.
1262 Currently this is implemented in the generic and native GTK versions
1263 only and nothing is done (and @false returned) when using OS X port.
1265 Also notice that this method can only be used to increase the row
1266 height compared with the default one (as determined by the return value
1267 of wxDataViewRenderer::GetSize()), if it is set to a too small value
1268 then the minimum required by the renderers will be used.
1270 @return @true if the line height was changed or @false otherwise.
1274 virtual bool SetRowHeight(int rowHeight
);
1280 @class wxDataViewModelNotifier
1282 A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
1283 its notification interface.
1284 See the documentation of that class for further information.
1289 class wxDataViewModelNotifier
1295 wxDataViewModelNotifier();
1300 virtual ~wxDataViewModelNotifier();
1303 Called by owning model.
1305 virtual bool Cleared() = 0;
1308 Get owning wxDataViewModel.
1310 wxDataViewModel
* GetOwner() const;
1313 Called by owning model.
1315 @return Always return @true from this function in derived classes.
1317 virtual bool ItemAdded(const wxDataViewItem
& parent
,
1318 const wxDataViewItem
& item
) = 0;
1321 Called by owning model.
1323 @return Always return @true from this function in derived classes.
1325 virtual bool ItemChanged(const wxDataViewItem
& item
) = 0;
1328 Called by owning model.
1330 @return Always return @true from this function in derived classes.
1332 virtual bool ItemDeleted(const wxDataViewItem
& parent
,
1333 const wxDataViewItem
& item
) = 0;
1336 Called by owning model.
1338 @return Always return @true from this function in derived classes.
1340 virtual bool ItemsAdded(const wxDataViewItem
& parent
,
1341 const wxDataViewItemArray
& items
);
1344 Called by owning model.
1346 @return Always return @true from this function in derived classes.
1348 virtual bool ItemsChanged(const wxDataViewItemArray
& items
);
1351 Called by owning model.
1353 @return Always return @true from this function in derived classes.
1355 virtual bool ItemsDeleted(const wxDataViewItem
& parent
,
1356 const wxDataViewItemArray
& items
);
1359 Called by owning model.
1361 virtual void Resort() = 0;
1364 Set owner of this notifier. Used internally.
1366 void SetOwner(wxDataViewModel
* owner
);
1369 Called by owning model.
1371 @return Always return @true from this function in derived classes.
1373 virtual bool ValueChanged(const wxDataViewItem
& item
, unsigned int col
) = 0;
1378 The mode of a data-view cell; see wxDataViewRenderer for more info.
1380 enum wxDataViewCellMode
1383 The cell only displays information and cannot be manipulated or
1384 otherwise interacted with in any way.
1386 Note that this doesn't mean that the row being drawn can't be selected,
1387 just that a particular element of it cannot be individually modified.
1389 wxDATAVIEW_CELL_INERT
,
1392 Indicates that the cell can be @em activated by clicking it or using
1395 Activating a cell is an alternative to showing inline editor when the
1396 value can be edited in a simple way that doesn't warrant full editor
1397 control. The most typical use of cell activation is toggling the
1398 checkbox in wxDataViewToggleRenderer; others would be e.g. an embedded
1399 volume slider or a five-star rating column.
1401 The exact means of activating a cell are platform-dependent, but they
1402 are usually similar to those used for inline editing of values.
1403 Typically, a cell would be activated by Space or Enter keys or by left
1406 @note Do not confuse this with item activation in wxDataViewCtrl
1407 and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is
1408 used for activating the item (or, to put it differently, the
1409 entire row) similarly to analogous messages in wxTreeCtrl and
1410 wxListCtrl, and the effect differs (play a song, open a file
1411 etc.). Cell activation, on the other hand, is all about
1412 interacting with the individual cell.
1414 @see wxDataViewCustomRenderer::ActivateCell()
1416 wxDATAVIEW_CELL_ACTIVATABLE
,
1419 Indicates that the user can edit the data in-place in an inline editor
1420 control that will show up when the user wants to edit the cell.
1422 A typical example of this behaviour is changing the filename in a file
1425 Editing is typically triggered by slowly double-clicking the cell or by
1426 a platform-dependent keyboard shortcut (F2 is typical on Windows, Space
1427 and/or Enter is common elsewhere and supported on Windows too).
1429 @see wxDataViewCustomRenderer::CreateEditorCtrl()
1431 wxDATAVIEW_CELL_EDITABLE
1435 The values of this enum controls how a wxDataViewRenderer should display
1436 its contents in a cell.
1438 enum wxDataViewCellRenderState
1440 wxDATAVIEW_CELL_SELECTED
= 1,
1441 wxDATAVIEW_CELL_PRELIT
= 2,
1442 wxDATAVIEW_CELL_INSENSITIVE
= 4,
1443 wxDATAVIEW_CELL_FOCUSED
= 8
1447 @class wxDataViewRenderer
1449 This class is used by wxDataViewCtrl to render the individual cells.
1450 One instance of a renderer class is owned by a wxDataViewColumn.
1451 There is a number of ready-to-use renderers provided:
1452 - wxDataViewTextRenderer,
1453 - wxDataViewIconTextRenderer,
1454 - wxDataViewToggleRenderer,
1455 - wxDataViewProgressRenderer,
1456 - wxDataViewBitmapRenderer,
1457 - wxDataViewDateRenderer,
1458 - wxDataViewSpinRenderer.
1459 - wxDataViewChoiceRenderer.
1461 Additionally, the user can write own renderers by deriving from
1462 wxDataViewCustomRenderer.
1464 The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1465 by the constructors respectively controls what actions the cell data allows
1466 and how the renderer should display its contents in a cell.
1471 class wxDataViewRenderer
: public wxObject
1477 wxDataViewRenderer(const wxString
& varianttype
,
1478 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1479 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1482 Enable or disable replacing parts of the item text with ellipsis to
1483 make it fit the column width.
1485 This method only makes sense for the renderers working with text, such
1486 as wxDataViewTextRenderer or wxDataViewIconTextRenderer.
1488 By default wxELLIPSIZE_MIDDLE is used.
1491 Ellipsization mode, use wxELLIPSIZE_NONE to disable.
1495 void EnableEllipsize(wxEllipsizeMode mode
= wxELLIPSIZE_MIDDLE
);
1498 Disable replacing parts of the item text with ellipsis.
1500 If ellipsizing is disabled, the string will be truncated if it doesn't
1503 This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode.
1507 void DisableEllipsize();
1510 Returns the alignment. See SetAlignment()
1512 virtual int GetAlignment() const;
1515 Returns the ellipsize mode used by the renderer.
1517 If the return value is wxELLIPSIZE_NONE, the text is simply truncated
1520 @see EnableEllipsize()
1522 wxEllipsizeMode
GetEllipsizeMode() const;
1525 Returns the cell mode.
1527 virtual wxDataViewCellMode
GetMode() const;
1530 Returns pointer to the owning wxDataViewColumn.
1532 wxDataViewColumn
* GetOwner() const;
1535 This methods retrieves the value from the renderer in order to
1536 transfer the value back to the data model.
1538 Returns @false on failure.
1540 virtual bool GetValue(wxVariant
& value
) const = 0;
1543 Returns a string with the type of the wxVariant supported by this renderer.
1545 wxString
GetVariantType() const;
1548 Sets the alignment of the renderer's content.
1549 The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1550 should have the same alignment as the column header.
1552 The method is not implemented under OS X and the renderer always aligns
1553 its contents as the column header on that platform. The other platforms
1554 support both vertical and horizontal alignment.
1556 virtual void SetAlignment( int align
);
1558 Sets the owning wxDataViewColumn.
1559 This is usually called from within wxDataViewColumn.
1561 void SetOwner(wxDataViewColumn
* owner
);
1564 Set the value of the renderer (and thus its cell) to @a value.
1565 The internal code will then render this cell with this data.
1567 virtual bool SetValue(const wxVariant
& value
) = 0;
1570 Before data is committed to the data model, it is passed to this
1571 method where it can be checked for validity. This can also be
1572 used for checking a valid range or limiting the user input in
1573 a certain aspect (e.g. max number of characters or only alphanumeric
1574 input, ASCII only etc.). Return @false if the value is not valid.
1576 Please note that due to implementation limitations, this validation
1577 is done after the editing control already is destroyed and the
1578 editing process finished.
1580 virtual bool Validate(wxVariant
& value
);
1586 @class wxDataViewTextRenderer
1588 wxDataViewTextRenderer is used for rendering text.
1589 It supports in-place editing if desired.
1594 class wxDataViewTextRenderer
: public wxDataViewRenderer
1600 wxDataViewTextRenderer(const wxString
& varianttype
= "string",
1601 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1602 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1608 @class wxDataViewIconTextRenderer
1610 The wxDataViewIconTextRenderer class is used to display text with
1611 a small icon next to it as it is typically done in a file manager.
1613 This classes uses the wxDataViewIconText helper class to store its data.
1614 wxDataViewIconText can be converted to and from a wxVariant using the left
1620 class wxDataViewIconTextRenderer
: public wxDataViewRenderer
1626 wxDataViewIconTextRenderer(const wxString
& varianttype
= "wxDataViewIconText",
1627 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1628 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1634 @class wxDataViewProgressRenderer
1636 This class is used by wxDataViewCtrl to render progress bars.
1641 class wxDataViewProgressRenderer
: public wxDataViewRenderer
1647 wxDataViewProgressRenderer(const wxString
& label
= wxEmptyString
,
1648 const wxString
& varianttype
= "long",
1649 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1650 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1656 @class wxDataViewSpinRenderer
1658 This is a specialized renderer for rendering integer values.
1659 It supports modifying the values in-place by using a wxSpinCtrl.
1660 The renderer only support variants of type @e long.
1665 class wxDataViewSpinRenderer
: public wxDataViewCustomRenderer
1670 @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1672 wxDataViewSpinRenderer(int min
, int max
,
1673 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1674 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1680 @class wxDataViewToggleRenderer
1682 This class is used by wxDataViewCtrl to render toggle controls.
1687 class wxDataViewToggleRenderer
: public wxDataViewRenderer
1693 wxDataViewToggleRenderer(const wxString
& varianttype
= "bool",
1694 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1695 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1700 A wxDataViewCtrl renderer using wxChoice control and values of strings in
1703 This class is used by wxDataViewCtrl to render choice controls.
1704 It stores a string so that SetValue() and GetValue() operate
1705 on a variant holding a string.
1707 @see wxDataViewChoiceByIndexRenderer
1713 class wxDataViewChoiceRenderer
: public wxDataViewRenderer
1719 wxDataViewChoiceRenderer( const wxArrayString
&choices
,
1720 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1721 int alignment
= wxDVR_DEFAULT_ALIGNMENT
);
1724 Returns the choice referred to by index.
1726 wxString
GetChoice(size_t index
) const;
1729 Returns all choices.
1731 const wxArrayString
& GetChoices() const;
1736 A wxDataViewCtrl renderer using wxChoice control and indexes into it.
1738 Unlike its base wxDataViewChoiceRenderer class, this one stores the choice
1739 index, i.e. an @c int, in the variant used by its SetValue() and
1745 class wxDataViewChoiceByIndexRenderer
: public wxDataViewChoiceRenderer
1751 wxDataViewChoiceByIndexRenderer( const wxArrayString
&choices
,
1752 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1753 int alignment
= wxDVR_DEFAULT_ALIGNMENT
);
1758 @class wxDataViewDateRenderer
1760 This class is used by wxDataViewCtrl to render calendar controls.
1765 class wxDataViewDateRenderer
: public wxDataViewRenderer
1771 wxDataViewDateRenderer(const wxString
& varianttype
= "datetime",
1772 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1773 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1779 @class wxDataViewCustomRenderer
1781 You need to derive a new class from wxDataViewCustomRenderer in
1782 order to write a new renderer.
1784 You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1785 wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1787 If you want your renderer to support in-place editing then you also need to override
1788 wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1789 and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1791 Note that a special event handler will be pushed onto that editor control
1792 which handles @e \<ENTER\> and focus out events in order to end the editing.
1797 class wxDataViewCustomRenderer
: public wxDataViewRenderer
1803 wxDataViewCustomRenderer(const wxString
& varianttype
= "string",
1804 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1805 int align
= -1, bool no_init
= false);
1810 virtual ~wxDataViewCustomRenderer();
1813 Override this to react to cell @em activation. Activating a cell is an
1814 alternative to showing inline editor when the value can be edited in a
1815 simple way that doesn't warrant full editor control. The most typical
1816 use of cell activation is toggling the checkbox in
1817 wxDataViewToggleRenderer; others would be e.g. an embedded volume
1818 slider or a five-star rating column.
1820 The exact means of activating a cell are platform-dependent, but they
1821 are usually similar to those used for inline editing of values.
1822 Typically, a cell would be activated by Space or Enter keys or by left
1825 This method will only be called if the cell has the
1826 wxDATAVIEW_CELL_ACTIVATABLE mode.
1829 Coordinates of the activated cell's area.
1831 The model to manipulate in response.
1835 Activated column of @a item.
1837 If the activation was triggered by mouse click, contains the
1838 corresponding event. Is @NULL otherwise (for keyboard activation).
1839 Mouse coordinates are adjusted to be relative to the cell.
1843 @note Do not confuse this method with item activation in wxDataViewCtrl
1844 and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is
1845 used for activating the item (or, to put it differently, the
1846 entire row) similarly to analogous messages in wxTreeCtrl and
1847 wxListCtrl, and the effect differs (play a song, open a file
1848 etc.). Cell activation, on the other hand, is all about
1849 interacting with the individual cell.
1851 @see CreateEditorCtrl()
1853 virtual bool ActivateCell(const wxRect
& cell
,
1854 wxDataViewModel
* model
,
1855 const wxDataViewItem
& item
,
1857 const wxMouseEvent
*mouseEvent
);
1860 Override this to create the actual editor control once editing
1863 This method will only be called if the cell has the
1864 wxDATAVIEW_CELL_EDITABLE mode. Editing is typically triggered by slowly
1865 double-clicking the cell or by a platform-dependent keyboard shortcut
1866 (F2 is typical on Windows, Space and/or Enter is common elsewhere and
1867 supported on Windows too).
1870 The parent of the editor control.
1872 Indicates the position and size of the editor control. The control
1873 should be created in place of the cell and @a labelRect should be
1874 respected as much as possible.
1876 Initial value of the editor.
1882 return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1883 labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1889 virtual wxWindow
* CreateEditorCtrl(wxWindow
* parent
,
1891 const wxVariant
& value
);
1894 Return the attribute to be used for rendering.
1896 This function may be called from Render() implementation to use the
1897 attributes defined for the item if the renderer supports them.
1899 Notice that when Render() is called, the wxDC object passed to it is
1900 already set up to use the correct attributes (e.g. its font is set to
1901 bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic()
1902 returns true) so it may not be necessary to call it explicitly if you
1903 only want to render text using the items attributes.
1907 const wxDataViewItemAttr
& GetAttr() const;
1910 Return size required to show content.
1912 virtual wxSize
GetSize() const = 0;
1915 Override this so that the renderer can get the value from the editor
1916 control (pointed to by @a editor):
1919 wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1920 long l = sc->GetValue();
1926 virtual bool GetValueFromEditorCtrl(wxWindow
* editor
,
1930 Override this and make it return @true in order to
1931 indicate that this renderer supports in-place editing.
1933 virtual bool HasEditorCtrl() const;
1936 Override this to react to a left click.
1937 This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1939 virtual bool LeftClick( const wxPoint
& cursor
,
1941 wxDataViewModel
* model
,
1942 const wxDataViewItem
& item
,
1946 Override this to render the cell.
1947 Before this is called, wxDataViewRenderer::SetValue was called
1948 so that this instance knows what to render.
1950 virtual bool Render(wxRect cell
, wxDC
* dc
, int state
) = 0;
1953 This method should be called from within Render() whenever you need to
1955 This will ensure that the correct colour, font and vertical alignment will
1956 be chosen so the text will look the same as text drawn by native renderers.
1958 void RenderText(const wxString
& text
, int xoffset
, wxRect cell
,
1959 wxDC
* dc
, int state
);
1962 Override this to start a drag operation. Not yet supported.
1964 virtual bool StartDrag(const wxPoint
& cursor
,
1966 wxDataViewModel
* model
,
1967 const wxDataViewItem
& item
,
1974 @class wxDataViewBitmapRenderer
1976 This class is used by wxDataViewCtrl to render bitmap controls.
1981 class wxDataViewBitmapRenderer
: public wxDataViewRenderer
1987 wxDataViewBitmapRenderer(const wxString
& varianttype
= "wxBitmap",
1988 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1989 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1994 The flags used by wxDataViewColumn.
1995 Can be combined together.
1997 enum wxDataViewColumnFlags
1999 wxDATAVIEW_COL_RESIZABLE
= 1,
2000 wxDATAVIEW_COL_SORTABLE
= 2,
2001 wxDATAVIEW_COL_REORDERABLE
= 4,
2002 wxDATAVIEW_COL_HIDDEN
= 8
2006 @class wxDataViewColumn
2008 This class represents a column in a wxDataViewCtrl.
2009 One wxDataViewColumn is bound to one column in the data model to which the
2010 wxDataViewCtrl has been associated.
2012 An instance of wxDataViewRenderer is used by this class to render its data.
2017 class wxDataViewColumn
: public wxSettableHeaderColumn
2021 Constructs a text column.
2024 The title of the column.
2026 The class which will render the contents of this column.
2028 The index of the model's column which is associated with this object.
2030 The width of the column.
2031 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
2033 The alignment of the column title.
2035 One or more flags of the ::wxDataViewColumnFlags enumeration.
2037 wxDataViewColumn(const wxString
& title
,
2038 wxDataViewRenderer
* renderer
,
2039 unsigned int model_column
,
2040 int width
= wxDVC_DEFAULT_WIDTH
,
2041 wxAlignment align
= wxALIGN_CENTER
,
2042 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2045 Constructs a bitmap column.
2048 The bitmap of the column.
2050 The class which will render the contents of this column.
2052 The index of the model's column which is associated with this object.
2054 The width of the column.
2055 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
2057 The alignment of the column title.
2059 One or more flags of the ::wxDataViewColumnFlags enumeration.
2061 wxDataViewColumn(const wxBitmap
& bitmap
,
2062 wxDataViewRenderer
* renderer
,
2063 unsigned int model_column
,
2064 int width
= wxDVC_DEFAULT_WIDTH
,
2065 wxAlignment align
= wxALIGN_CENTER
,
2066 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2069 Returns the index of the column of the model, which this
2070 wxDataViewColumn is displaying.
2072 unsigned int GetModelColumn() const;
2075 Returns the owning wxDataViewCtrl.
2077 wxDataViewCtrl
* GetOwner() const;
2080 Returns the renderer of this wxDataViewColumn.
2082 @see wxDataViewRenderer.
2084 wxDataViewRenderer
* GetRenderer() const;
2090 @class wxDataViewListCtrl
2092 This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
2093 and forwards most of its API to that class.
2095 The purpose of this class is to offer a simple way to display and
2096 edit a small table of data without having to write your own wxDataViewModel.
2099 wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
2101 listctrl->AppendToggleColumn( "Toggle" );
2102 listctrl->AppendTextColumn( "Text" );
2104 wxVector<wxVariant> data;
2105 data.push_back( wxVariant(true) );
2106 data.push_back( wxVariant("row 1") );
2107 listctrl->AppendItem( data );
2110 data.push_back( wxVariant(false) );
2111 data.push_back( wxVariant("row 3") );
2112 listctrl->AppendItem( data );
2116 See wxDataViewCtrl for the list of supported styles.
2119 @beginEventEmissionTable
2120 See wxDataViewCtrl for the list of events emitted by this class.
2126 class wxDataViewListCtrl
: public wxDataViewCtrl
2132 wxDataViewListCtrl();
2135 Constructor. Calls Create().
2137 wxDataViewListCtrl( wxWindow
*parent
, wxWindowID id
,
2138 const wxPoint
& pos
= wxDefaultPosition
,
2139 const wxSize
& size
= wxDefaultSize
, long style
= wxDV_ROW_LINES
,
2140 const wxValidator
& validator
= wxDefaultValidator
);
2143 Destructor. Deletes the image list if any.
2145 ~wxDataViewListCtrl();
2148 Creates the control and a wxDataViewListStore as its internal model.
2150 bool Create( wxWindow
*parent
, wxWindowID id
,
2151 const wxPoint
& pos
= wxDefaultPosition
,
2152 const wxSize
& size
= wxDefaultSize
, long style
= wxDV_ROW_LINES
,
2153 const wxValidator
& validator
= wxDefaultValidator
);
2159 wxDataViewListStore
*GetStore();
2160 const wxDataViewListStore
*GetStore() const;
2164 Returns the position of given @e item or wxNOT_FOUND if it's
2169 int ItemToRow(const wxDataViewItem
&item
) const;
2172 Returns the wxDataViewItem at the given @e row.
2176 wxDataViewItem
RowToItem(int row
) const;
2180 @name Selection handling functions
2184 Returns index of the selected row or wxNOT_FOUND.
2186 @see wxDataViewCtrl::GetSelection()
2190 int GetSelectedRow() const;
2195 @see wxDataViewCtrl::Select()
2199 void SelectRow(unsigned row
);
2202 Unselects given row.
2204 @see wxDataViewCtrl::Unselect()
2208 void UnselectRow(unsigned row
);
2211 Returns true if @a row is selected.
2213 @see wxDataViewCtrl::IsSelected()
2217 bool IsRowSelected(unsigned row
) const;
2222 @name Column management functions
2227 Appends a column to the control and additionally appends a
2228 column to the store with the type string.
2230 virtual bool AppendColumn( wxDataViewColumn
*column
);
2233 Appends a column to the control and additionally appends a
2234 column to the list store with the type @a varianttype.
2236 void AppendColumn( wxDataViewColumn
*column
, const wxString
&varianttype
);
2239 Appends a text column to the control and the store.
2241 See wxDataViewColumn::wxDataViewColumn for more info about
2244 wxDataViewColumn
*AppendTextColumn( const wxString
&label
,
2245 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
2246 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
2247 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2250 Appends a toggle column to the control and the store.
2252 See wxDataViewColumn::wxDataViewColumn for more info about
2255 wxDataViewColumn
*AppendToggleColumn( const wxString
&label
,
2256 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
2257 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
2258 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2261 Appends a progress column to the control and the store.
2263 See wxDataViewColumn::wxDataViewColumn for more info about
2266 wxDataViewColumn
*AppendProgressColumn( const wxString
&label
,
2267 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
2268 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
2269 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2272 Appends an icon-and-text column to the control and the store.
2274 See wxDataViewColumn::wxDataViewColumn for more info about
2277 wxDataViewColumn
*AppendIconTextColumn( const wxString
&label
,
2278 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
2279 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
2280 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2283 Inserts a column to the control and additionally inserts a
2284 column to the store with the type string.
2286 virtual bool InsertColumn( unsigned int pos
, wxDataViewColumn
*column
);
2289 Inserts a column to the control and additionally inserts a
2290 column to the list store with the type @a varianttype.
2292 void InsertColumn( unsigned int pos
, wxDataViewColumn
*column
,
2293 const wxString
&varianttype
);
2296 Prepends a column to the control and additionally prepends a
2297 column to the store with the type string.
2299 virtual bool PrependColumn( wxDataViewColumn
*column
);
2302 Prepends a column to the control and additionally prepends a
2303 column to the list store with the type @a varianttype.
2305 void PrependColumn( wxDataViewColumn
*column
, const wxString
&varianttype
);
2311 @name Item management functions
2316 Appends an item (=row) to the control and store.
2318 void AppendItem( const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2321 Prepends an item (=row) to the control and store.
2323 void PrependItem( const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2326 Inserts an item (=row) to the control and store.
2328 void InsertItem( unsigned int row
, const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2331 Delete the row at position @a row.
2333 void DeleteItem( unsigned row
);
2336 Delete all items (= all rows).
2338 void DeleteAllItems();
2341 Returns the number of items (=rows) in the control
2345 unsigned int GetItemCount() const;
2348 Returns the client data associated with the item.
2354 wxUIntPtr
GetItemData(const wxDataViewItem
& item
) const;
2357 Sets the value in the store and update the control.
2359 void SetValue( const wxVariant
&value
, unsigned int row
, unsigned int col
);
2362 Returns the value from the store.
2364 void GetValue( wxVariant
&value
, unsigned int row
, unsigned int col
);
2367 Sets the value in the store and update the control.
2369 This method assumes that the string is stored in respective
2372 void SetTextValue( const wxString
&value
, unsigned int row
, unsigned int col
);
2375 Returns the value from the store.
2377 This method assumes that the string is stored in respective
2380 wxString
GetTextValue( unsigned int row
, unsigned int col
) const;
2383 Sets the value in the store and update the control.
2385 This method assumes that the boolean value is stored in
2388 void SetToggleValue( bool value
, unsigned int row
, unsigned int col
);
2391 Returns the value from the store.
2393 This method assumes that the boolean value is stored in
2396 bool GetToggleValue( unsigned int row
, unsigned int col
) const;
2399 Associates a client data pointer with the given item.
2401 Notice that the control does @e not take ownership of the pointer for
2402 compatibility with wxListCtrl. I.e. it will @e not delete the pointer
2403 (if it is a pointer and not a number) itself, it is up to you to do it.
2409 void SetItemData(const wxDataViewItem
& item
, wxUIntPtr data
);
2416 @class wxDataViewTreeCtrl
2418 This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
2419 and forwards most of its API to that class.
2420 Additionally, it uses a wxImageList to store a list of icons.
2422 The main purpose of this class is to provide a simple upgrade path for code
2426 See wxDataViewCtrl for the list of supported styles.
2429 @beginEventEmissionTable
2430 See wxDataViewCtrl for the list of events emitted by this class.
2435 @appearance{dataviewtreectrl.png}
2437 class wxDataViewTreeCtrl
: public wxDataViewCtrl
2443 wxDataViewTreeCtrl();
2450 wxDataViewTreeCtrl(wxWindow
* parent
, wxWindowID id
,
2451 const wxPoint
& pos
= wxDefaultPosition
,
2452 const wxSize
& size
= wxDefaultSize
,
2453 long style
= wxDV_NO_HEADER
| wxDV_ROW_LINES
,
2454 const wxValidator
& validator
= wxDefaultValidator
);
2457 Destructor. Deletes the image list if any.
2459 virtual ~wxDataViewTreeCtrl();
2462 Appends a container to the given @a parent.
2464 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
2465 const wxString
& text
,
2468 wxClientData
* data
= NULL
);
2471 Appends an item to the given @a parent.
2473 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
2474 const wxString
& text
,
2476 wxClientData
* data
= NULL
);
2479 Creates the control and a wxDataViewTreeStore as its internal model.
2481 The default tree column created by this method is an editable column
2482 using wxDataViewIconTextRenderer as its renderer.
2484 bool Create(wxWindow
* parent
, wxWindowID id
,
2485 const wxPoint
& pos
= wxDefaultPosition
,
2486 const wxSize
& size
= wxDefaultSize
,
2487 long style
= wxDV_NO_HEADER
| wxDV_ROW_LINES
,
2488 const wxValidator
& validator
= wxDefaultValidator
);
2491 Calls the identical method from wxDataViewTreeStore.
2493 void DeleteAllItems();
2496 Calls the identical method from wxDataViewTreeStore.
2498 void DeleteChildren(const wxDataViewItem
& item
);
2501 Calls the identical method from wxDataViewTreeStore.
2503 void DeleteItem(const wxDataViewItem
& item
);
2506 Calls the identical method from wxDataViewTreeStore.
2508 int GetChildCount(const wxDataViewItem
& parent
) const;
2511 Returns the image list.
2513 wxImageList
* GetImageList();
2516 Calls the identical method from wxDataViewTreeStore.
2518 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
2521 Calls the identical method from wxDataViewTreeStore.
2523 const wxIcon
& GetItemExpandedIcon(const wxDataViewItem
& item
) const;
2526 Calls the identical method from wxDataViewTreeStore.
2528 const wxIcon
& GetItemIcon(const wxDataViewItem
& item
) const;
2531 Calls the identical method from wxDataViewTreeStore.
2533 wxString
GetItemText(const wxDataViewItem
& item
) const;
2536 Calls the identical method from wxDataViewTreeStore.
2538 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
2539 unsigned int pos
) const;
2545 wxDataViewTreeStore
* GetStore();
2546 const wxDataViewTreeStore
* GetStore() const;
2550 Calls the same method from wxDataViewTreeStore but uses
2551 an index position in the image list instead of a wxIcon.
2553 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
2554 const wxDataViewItem
& previous
,
2555 const wxString
& text
,
2558 wxClientData
* data
= NULL
);
2561 Calls the same method from wxDataViewTreeStore but uses
2562 an index position in the image list instead of a wxIcon.
2564 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
2565 const wxDataViewItem
& previous
,
2566 const wxString
& text
,
2568 wxClientData
* data
= NULL
);
2571 Returns true if item is a container.
2573 bool IsContainer( const wxDataViewItem
& item
);
2576 Calls the same method from wxDataViewTreeStore but uses
2577 an index position in the image list instead of a wxIcon.
2579 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
2580 const wxString
& text
,
2583 wxClientData
* data
= NULL
);
2586 Calls the same method from wxDataViewTreeStore but uses
2587 an index position in the image list instead of a wxIcon.
2589 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
2590 const wxString
& text
,
2592 wxClientData
* data
= NULL
);
2595 Sets the image list.
2597 void SetImageList(wxImageList
* imagelist
);
2600 Calls the identical method from wxDataViewTreeStore.
2602 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
2605 Calls the identical method from wxDataViewTreeStore.
2607 void SetItemExpandedIcon(const wxDataViewItem
& item
,
2608 const wxIcon
& icon
);
2611 Calls the identical method from wxDataViewTreeStore.
2613 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
2616 Calls the identical method from wxDataViewTreeStore.
2618 void SetItemText(const wxDataViewItem
& item
,
2619 const wxString
& text
);
2624 @class wxDataViewListStore
2626 wxDataViewListStore is a specialised wxDataViewModel for storing
2627 a simple table of data. Since it derives from wxDataViewIndexListModel
2628 its data is be accessed by row (i.e. by index) instead of only
2631 This class actually stores the values (therefore its name)
2632 and implements all virtual methods from the base classes so it can be
2633 used directly without having to derive any class from it, but it is
2634 mostly used from within wxDataViewListCtrl.
2640 class wxDataViewListStore
: public wxDataViewIndexListModel
2646 wxDataViewListStore();
2651 ~wxDataViewListStore();
2654 Prepends a data column.
2656 @a variantype indicates the type of values store in the column.
2658 This does not automatically fill in any (default) values in
2659 rows which exist in the store already.
2661 void PrependColumn( const wxString
&varianttype
);
2664 Inserts a data column before @a pos.
2666 @a variantype indicates the type of values store in the column.
2668 This does not automatically fill in any (default) values in
2669 rows which exist in the store already.
2671 void InsertColumn( unsigned int pos
, const wxString
&varianttype
);
2674 Appends a data column.
2676 @a variantype indicates the type of values store in the column.
2678 This does not automatically fill in any (default) values in
2679 rows which exist in the store already.
2681 void AppendColumn( const wxString
&varianttype
);
2684 Appends an item (=row) and fills it with @a values.
2686 The values must match the values specifies in the column
2687 in number and type. No (default) values are filled in
2690 void AppendItem( const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2693 Prepends an item (=row) and fills it with @a values.
2695 The values must match the values specifies in the column
2696 in number and type. No (default) values are filled in
2699 void PrependItem( const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2702 Inserts an item (=row) and fills it with @a values.
2704 The values must match the values specifies in the column
2705 in number and type. No (default) values are filled in
2708 void InsertItem( unsigned int row
, const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2711 Delete the item (=row) at position @a pos.
2713 void DeleteItem( unsigned pos
);
2716 Delete all item (=all rows) in the store.
2718 void DeleteAllItems();
2721 Returns the number of items (=rows) in the control
2725 unsigned int GetItemCount() const;
2728 Returns the client data associated with the item.
2734 wxUIntPtr
GetItemData(const wxDataViewItem
& item
) const;
2737 Overridden from wxDataViewModel
2739 virtual unsigned int GetColumnCount() const;
2742 Overridden from wxDataViewModel
2744 virtual wxString
GetColumnType( unsigned int col
) const;
2747 Sets the client data associated with the item.
2749 Notice that this class does @e not take ownership of the passed in
2750 pointer and will not delete it.
2756 void SetItemData(const wxDataViewItem
& item
, wxUIntPtr data
);
2759 Overridden from wxDataViewIndexListModel
2761 virtual void GetValueByRow( wxVariant
&value
,
2762 unsigned int row
, unsigned int col
) const;
2765 Overridden from wxDataViewIndexListModel
2767 virtual bool SetValueByRow( const wxVariant
&value
,
2768 unsigned int row
, unsigned int col
);
2773 @class wxDataViewTreeStore
2775 wxDataViewTreeStore is a specialised wxDataViewModel for storing simple
2776 trees very much like wxTreeCtrl does and it offers a similar API.
2778 This class actually stores the entire tree and the values (therefore its name)
2779 and implements all virtual methods from the base class so it can be used directly
2780 without having to derive any class from it, but it is mostly used from within
2786 class wxDataViewTreeStore
: public wxDataViewModel
2790 Constructor. Creates the invisible root node internally.
2792 wxDataViewTreeStore();
2797 virtual ~wxDataViewTreeStore();
2802 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
2803 const wxString
& text
,
2804 const wxIcon
& icon
= wxNullIcon
,
2805 const wxIcon
& expanded
= wxNullIcon
,
2806 wxClientData
* data
= NULL
);
2811 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
2812 const wxString
& text
,
2813 const wxIcon
& icon
= wxNullIcon
,
2814 wxClientData
* data
= NULL
);
2817 Delete all item in the model.
2819 void DeleteAllItems();
2822 Delete all children of the item, but not the item itself.
2824 void DeleteChildren(const wxDataViewItem
& item
);
2829 void DeleteItem(const wxDataViewItem
& item
);
2832 Return the number of children of item.
2834 int GetChildCount(const wxDataViewItem
& parent
) const;
2837 Returns the client data associated with the item.
2839 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
2842 Returns the icon to display in expanded containers.
2844 const wxIcon
& GetItemExpandedIcon(const wxDataViewItem
& item
) const;
2847 Returns the icon of the item.
2849 const wxIcon
& GetItemIcon(const wxDataViewItem
& item
) const;
2852 Returns the text of the item.
2854 wxString
GetItemText(const wxDataViewItem
& item
) const;
2857 Returns the nth child item of item.
2859 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
2860 unsigned int pos
) const;
2863 Inserts a container after @a previous.
2865 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
2866 const wxDataViewItem
& previous
,
2867 const wxString
& text
,
2868 const wxIcon
& icon
= wxNullIcon
,
2869 const wxIcon
& expanded
= wxNullIcon
,
2870 wxClientData
* data
= NULL
);
2873 Inserts an item after @a previous.
2875 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
2876 const wxDataViewItem
& previous
,
2877 const wxString
& text
,
2878 const wxIcon
& icon
= wxNullIcon
,
2879 wxClientData
* data
= NULL
);
2882 Inserts a container before the first child item or @a parent.
2884 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
2885 const wxString
& text
,
2886 const wxIcon
& icon
= wxNullIcon
,
2887 const wxIcon
& expanded
= wxNullIcon
,
2888 wxClientData
* data
= NULL
);
2891 Inserts an item before the first child item or @a parent.
2893 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
2894 const wxString
& text
,
2895 const wxIcon
& icon
= wxNullIcon
,
2896 wxClientData
* data
= NULL
);
2899 Sets the client data associated with the item.
2901 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
2904 Sets the expanded icon for the item.
2906 void SetItemExpandedIcon(const wxDataViewItem
& item
,
2907 const wxIcon
& icon
);
2910 Sets the icon for the item.
2912 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
2917 @class wxDataViewIconText
2919 wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2920 This class can be converted to and from a wxVariant.
2925 class wxDataViewIconText
: public wxObject
2932 wxDataViewIconText(const wxString
& text
= wxEmptyString
,
2933 const wxIcon
& icon
= wxNullIcon
);
2934 wxDataViewIconText(const wxDataViewIconText
& other
);
2940 const wxIcon
& GetIcon() const;
2945 wxString
GetText() const;
2950 void SetIcon(const wxIcon
& icon
);
2955 void SetText(const wxString
& text
);
2961 @class wxDataViewEvent
2963 This is the event class for the wxDataViewCtrl notifications.
2965 @beginEventTable{wxDataViewEvent}
2966 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2967 Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2968 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2969 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2970 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2971 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2972 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2973 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2974 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2975 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2976 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2977 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2978 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2979 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2980 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2981 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2982 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2983 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2984 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2985 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2986 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2987 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK event.
2988 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2989 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2990 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2991 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2992 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2993 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2994 Currently this even is only generated when using the native OSX
2996 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2997 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2998 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2999 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
3000 @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
3001 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
3002 @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
3003 Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
3007 @category{events,dvc}
3009 class wxDataViewEvent
: public wxNotifyEvent
3013 Constructor. Typically used by wxWidgets internals only.
3015 wxDataViewEvent(wxEventType commandType
= wxEVT_NULL
,
3019 Returns the position of the column in the control or -1
3020 if no column field was set by the event emitter.
3022 int GetColumn() const;
3025 Returns a pointer to the wxDataViewColumn from which
3026 the event was emitted or @NULL.
3028 wxDataViewColumn
* GetDataViewColumn() const;
3031 Returns the wxDataViewModel associated with the event.
3033 wxDataViewModel
* GetModel() const;
3036 Returns the position of a context menu event in screen coordinates.
3038 wxPoint
GetPosition() const;
3041 Returns a reference to a value.
3043 const wxVariant
& GetValue() const;
3046 Can be used to determine whether the new value is going to be accepted
3047 in wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE handler.
3049 Returns @true if editing the item was cancelled or if the user tried to
3050 enter an invalid value (refused by wxDataViewRenderer::Validate()). If
3051 this method returns @false, it means that the value in the model is
3052 about to be changed to the new one.
3054 Notice that wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event handler can
3055 call wxNotifyEvent::Veto() to prevent this from happening.
3057 Currently support for setting this field and for vetoing the change is
3058 only available in the generic version of wxDataViewCtrl, i.e. under MSW
3059 but not GTK nor OS X.
3063 bool IsEditCancelled() const;
3066 Sets the column index associated with this event.
3068 void SetColumn(int col
);
3071 For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK only.
3073 void SetDataViewColumn(wxDataViewColumn
* col
);
3076 Sets the dataview model associated with this event.
3078 void SetModel(wxDataViewModel
* model
);
3081 Sets the value associated with this event.
3083 void SetValue(const wxVariant
& value
);
3086 Set wxDataObject for data transfer within a drag operation.
3088 void SetDataObject( wxDataObject
*obj
);
3091 Gets the wxDataFormat during a drop operation.
3093 wxDataFormat
GetDataFormat() const;
3096 Gets the data size for a drop data transfer.
3098 size_t GetDataSize() const;
3101 Gets the data buffer for a drop data transfer.
3103 void *GetDataBuffer() const;
3106 Specify the kind of the drag operation to perform.
3108 This method can be used inside a wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG
3109 handler in order to configure the drag operation. Valid values are
3110 ::wxDrag_CopyOnly (default), ::wxDrag_AllowMove (allow the data to be
3111 moved) and ::wxDrag_DefaultMove.
3113 Currently it is only honoured by the generic version of wxDataViewCtrl
3114 (used e.g. under MSW) and not supported by the native GTK and OS X
3117 @see GetDropEffect()
3121 void SetDragFlags(int flags
);
3124 Returns the effect the user requested to happen to the dropped data.
3126 This function can be used inside
3127 wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE and
3128 wxEVT_COMMAND_DATAVIEW_ITEM_DROP handlers and returns whether the user
3129 is trying to copy (the return value is ::wxDragCopy) or move (if the
3130 return value is ::wxDragMove) the data.
3132 Currently this is only available when using the generic version of
3133 wxDataViewCtrl (used e.g. under MSW) and always returns ::wxDragNone in
3134 the GTK and OS X native versions.
3138 wxDragResult
GetDropEffect() const;
3141 Return the first row that will be displayed.
3143 int GetCacheFrom() const;
3146 Return the last row that will be displayed.
3148 int GetCacheTo() const;