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
,
344 virtual bool IsListModel() const;
345 virtual bool IsVirtualListModel() const;
350 Destructor. This should not be called directly. Use DecRef() instead.
352 virtual ~wxDataViewModel();
358 @class wxDataViewListModel
360 Base class with abstract API for wxDataViewIndexListModel and
361 wxDataViewVirtualListModel.
366 class wxDataViewListModel
: public wxDataViewModel
373 virtual ~wxDataViewListModel();
376 Compare method that sorts the items by their index.
378 int Compare(const wxDataViewItem
& item1
,
379 const wxDataViewItem
& item2
,
380 unsigned int column
, bool ascending
) const;
383 Override this to indicate that the row has special font attributes.
384 This only affects the wxDataViewTextRendererText() renderer.
386 The base class version always simply returns @false.
388 @see wxDataViewItemAttr.
391 The row for which the attribute is requested.
393 The column for which the attribute is requested.
395 The attribute to be filled in if the function returns @true.
397 @true if this item has an attribute or @false otherwise.
399 virtual bool GetAttrByRow(unsigned int row
, unsigned int col
,
400 wxDataViewItemAttr
& attr
) const;
403 Override this if you want to disable specific items.
405 The base class version always returns @true, thus making all items
409 The row of the item whose enabled status is requested.
411 The column of the item whose enabled status is requested.
413 @true if the item at this row and column should be enabled,
416 @note See wxDataViewModel::IsEnabled() for the current status of
417 support for disabling the items under different platforms.
421 virtual bool IsEnabledByRow(unsigned int row
,
422 unsigned int col
) const;
425 Returns the number of items (or rows) in the list.
427 unsigned int GetCount() const = 0;
430 Returns the position of given @e item.
432 unsigned int GetRow(const wxDataViewItem
& item
) const = 0;
435 Override this to allow getting values from the model.
437 virtual void GetValueByRow(wxVariant
& variant
, unsigned int row
,
438 unsigned int col
) const = 0;
441 Called in order to set a value in the model.
443 virtual bool SetValueByRow(const wxVariant
& variant
, unsigned int row
,
444 unsigned int col
) = 0;
449 @class wxDataViewIndexListModel
451 wxDataViewIndexListModel is a specialized data model which lets you address
452 an item by its position (row) rather than its wxDataViewItem (which you can
453 obtain from this class).
454 This model also provides its own wxDataViewIndexListModel::Compare
455 method which sorts the model's data by the index.
457 This model is not a virtual model since the control stores each wxDataViewItem.
458 Use wxDataViewVirtualListModel if you need to display millions of items or
459 have other reason to use a virtual control.
461 @see wxDataViewListModel for the API.
467 class wxDataViewIndexListModel
: public wxDataViewListModel
473 wxDataViewIndexListModel(unsigned int initial_size
= 0);
476 Returns the wxDataViewItem at the given @e row.
478 wxDataViewItem
GetItem(unsigned int row
) const;
481 Call this after if the data has to be read again from the model.
482 This is useful after major changes when calling the methods below
483 (possibly thousands of times) doesn't make sense.
485 void Reset(unsigned int new_size
);
488 Call this after a row has been appended to the model.
493 Call this after a row has been changed.
495 void RowChanged(unsigned int row
);
498 Call this after a row has been deleted.
500 void RowDeleted(unsigned int row
);
503 Call this after a row has been inserted at the given position.
505 void RowInserted(unsigned int before
);
508 Call this after a row has been prepended to the model.
513 Call this after a value has been changed.
515 void RowValueChanged(unsigned int row
, unsigned int col
);
518 Call this after rows have been deleted.
519 The array will internally get copied and sorted in descending order so
520 that the rows with the highest position will be deleted first.
522 void RowsDeleted(const wxArrayInt
& rows
);
527 @class wxDataViewVirtualListModel
529 wxDataViewVirtualListModel is a specialized data model which lets you address
530 an item by its position (row) rather than its wxDataViewItem and as such offers
531 the exact same interface as wxDataViewIndexListModel.
532 The important difference is that under platforms other than OS X, using this
533 model will result in a truly virtual control able to handle millions of items
534 as the control doesn't store any item (a feature not supported by OS X).
536 @see wxDataViewListModel for the API.
542 class wxDataViewVirtualListModel
: public wxDataViewListModel
548 wxDataViewVirtualListModel(unsigned int initial_size
= 0);
551 Returns the wxDataViewItem at the given @e row.
553 wxDataViewItem
GetItem(unsigned int row
) const;
556 Call this after if the data has to be read again from the model.
557 This is useful after major changes when calling the methods below
558 (possibly thousands of times) doesn't make sense.
560 void Reset(unsigned int new_size
);
563 Call this after a row has been appended to the model.
568 Call this after a row has been changed.
570 void RowChanged(unsigned int row
);
573 Call this after a row has been deleted.
575 void RowDeleted(unsigned int row
);
578 Call this after a row has been inserted at the given position.
580 void RowInserted(unsigned int before
);
583 Call this after a row has been prepended to the model.
588 Call this after a value has been changed.
590 void RowValueChanged(unsigned int row
, unsigned int col
);
593 Call this after rows have been deleted.
594 The array will internally get copied and sorted in descending order so
595 that the rows with the highest position will be deleted first.
597 void RowsDeleted(const wxArrayInt
& rows
);
604 @class wxDataViewItemAttr
606 This class is used to indicate to a wxDataViewCtrl that a certain item
607 (see wxDataViewItem) has extra font attributes for its renderer.
608 For this, it is required to override wxDataViewModel::GetAttr.
610 Attributes are currently only supported by wxDataViewTextRendererText.
615 class wxDataViewItemAttr
621 wxDataViewItemAttr();
624 Call this to indicate that the item shall be displayed in bold text.
626 void SetBold(bool set
);
629 Call this to indicate that the item shall be displayed with that colour.
631 void SetColour(const wxColour
& colour
);
634 Call this to set the background colour to use.
636 Currently this attribute is only supported in the generic version of
637 wxDataViewCtrl and ignored by the native GTK+ and OS X implementations.
641 void SetBackgroundColour(const wxColour
& colour
);
644 Call this to indicate that the item shall be displayed in italic text.
646 void SetItalic(bool set
);
650 Returns true if the colour property has been set.
652 bool HasColour() const;
655 Returns this attribute's colour.
657 const wxColour
& GetColour() const;
660 Returns true if any property affecting the font has been set.
662 bool HasFont() const;
665 Returns value of the bold property.
667 bool GetBold() const;
670 Returns value of the italics property.
672 bool GetItalic() const;
675 Returns true if the background colour property has been set.
677 bool HasBackgroundColour() const;
680 Returns the colour to be used for the background.
682 const wxColour
& GetBackgroundColour() const;
685 Returns true if none of the properties have been set.
687 bool IsDefault() const;
690 Return the font based on the given one with this attribute applied to it.
692 wxFont
GetEffectiveFont(const wxFont
& font
) const;
698 @class wxDataViewItem
700 wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl
701 in a persistent way, i.e. independent of the position of the item in the control
702 or changes to its contents.
704 It must hold a unique ID of type @e void* in its only field and can be converted
707 If the ID is @NULL the wxDataViewItem is invalid and wxDataViewItem::IsOk will
708 return @false which used in many places in the API of wxDataViewCtrl to
709 indicate that e.g. no item was found. An ID of @NULL is also used to indicate
710 the invisible root. Examples for this are wxDataViewModel::GetParent and
711 wxDataViewModel::GetChildren.
724 wxDataViewItem(const wxDataViewItem
& item
);
725 explicit wxDataViewItem(void* id
);
734 Returns @true if the ID is not @NULL.
740 // ----------------------------------------------------------------------------
741 // wxDataViewCtrl flags
742 // ----------------------------------------------------------------------------
744 // size of a wxDataViewRenderer without contents:
745 #define wxDVC_DEFAULT_RENDERER_SIZE 20
747 // the default width of new (text) columns:
748 #define wxDVC_DEFAULT_WIDTH 80
750 // the default width of new toggle columns:
751 #define wxDVC_TOGGLE_DEFAULT_WIDTH 30
753 // the default minimal width of the columns:
754 #define wxDVC_DEFAULT_MINWIDTH 30
756 // The default alignment of wxDataViewRenderers is to take
757 // the alignment from the column it owns.
758 #define wxDVR_DEFAULT_ALIGNMENT -1
760 #define wxDV_SINGLE 0x0000 // for convenience
761 #define wxDV_MULTIPLE 0x0001 // can select multiple items
763 #define wxDV_NO_HEADER 0x0002 // column titles not visible
764 #define wxDV_HORIZ_RULES 0x0004 // light horizontal rules between rows
765 #define wxDV_VERT_RULES 0x0008 // light vertical rules between columns
767 #define wxDV_ROW_LINES 0x0010 // alternating colour in rows
768 #define wxDV_VARIABLE_LINE_HEIGHT 0x0020 // variable line height
772 wxEventType wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED
;
774 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED
;
775 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING
;
776 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED
;
777 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING
;
778 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED
;
779 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING
;
780 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED
;
781 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE
;
782 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED
;
784 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU
;
786 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK
;
787 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK
;
788 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED
;
789 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED
;
790 wxEventType wxEVT_COMMAND_DATAVIEW_CACHE_HINT
;
792 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG
;
793 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE
;
794 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP
;
797 @class wxDataViewCtrl
799 wxDataViewCtrl is a control to display data either in a tree like fashion or
800 in a tabular form or both.
802 If you only need to display a simple tree structure with an API more like the
803 older wxTreeCtrl class, then the specialized wxDataViewTreeCtrl can be used.
804 Likewise, if you only want to display simple table structure you can use
805 the specialized wxDataViewListCtrl class. Both wxDataViewTreeCtrl and
806 wxDataViewListCtrl can be used without defining your own wxDataViewModel.
808 A wxDataViewItem is used to represent a (visible) item in the control.
810 Unlike wxListCtrl, wxDataViewCtrl doesn't get its data from the user through
811 virtual functions or by setting it directly. Instead you need to write your own
812 wxDataViewModel and associate it with this control.
813 Then you need to add a number of wxDataViewColumn to this control to define
814 what each column shall display. Each wxDataViewColumn in turn owns 1 instance
815 of a wxDataViewRenderer to render its cells.
817 A number of standard renderers for rendering text, dates, images, toggle,
818 a progress bar etc. are provided. Additionally, the user can write custom
819 renderers deriving from wxDataViewCustomRenderer for displaying anything.
821 All data transfer from the control to the model and the user code is done
822 through wxVariant which can be extended to support more data formats as necessary.
823 Accordingly, all type information uses the strings returned from wxVariant::GetType.
827 Single selection mode. This is the default.
828 @style{wxDV_MULTIPLE}
829 Multiple selection mode.
830 @style{wxDV_ROW_LINES}
831 Use alternating colours for rows if supported by platform and theme.
832 Currently only supported by the native GTK and OS X implementations
833 but not by the generic one.
834 @style{wxDV_HORIZ_RULES}
835 Display the separator lines between rows.
836 @style{wxDV_VERT_RULES}
837 Display the separator lines between columns.
838 @style{wxDV_VARIABLE_LINE_HEIGHT}
839 Allow variable line heights.
840 This can be inefficient when displaying large number of items.
841 @style{wxDV_NO_HEADER}
842 Do not show column headers (which are shown by default).
845 @beginEventEmissionTable{wxDataViewEvent}
846 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
847 Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
848 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
849 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. This event
850 is triggered by double clicking an item or pressing some special key
851 (usually "Enter") when it is focused.
852 @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}
853 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING event. This
854 event can be vetoed in order to prevent editing on an item by item
856 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
857 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
858 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
859 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
860 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
861 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
862 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
863 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
864 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
865 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
866 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
867 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
868 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
869 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
870 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
871 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event
872 generated when the user right clicks inside the control. Notice that
873 this menu is generated even if the click didn't occur on any valid
874 item, in this case wxDataViewEvent::GetItem() simply returns an
876 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
877 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK event.
878 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
879 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
880 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
881 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
882 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
883 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
884 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
885 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
886 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
887 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
888 @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
889 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
892 Notice that this control doesn't allow to process generic mouse events such
893 as @c wxEVT_LEFT_DOWN in all ports (notably it doesn't work in wxGTK). If
894 you need to handle any mouse events not covered by the ones above, consider
895 using a custom renderer for the cells that must handle them.
899 @appearance{dataviewctrl}
901 class wxDataViewCtrl
: public wxControl
910 Constructor. Calls Create().
912 wxDataViewCtrl(wxWindow
* parent
, wxWindowID id
,
913 const wxPoint
& pos
= wxDefaultPosition
,
914 const wxSize
& size
= wxDefaultSize
,
916 const wxValidator
& validator
= wxDefaultValidator
,
917 const wxString
& name
= wxDataViewCtrlNameStr
);
922 virtual ~wxDataViewCtrl();
925 Create the control. Useful for two step creation.
927 bool Create(wxWindow
* parent
, wxWindowID id
,
928 const wxPoint
& pos
= wxDefaultPosition
,
929 const wxSize
& size
= wxDefaultSize
,
931 const wxValidator
& validator
= wxDefaultValidator
,
932 const wxString
& name
= wxDataViewCtrlNameStr
);
935 Appends a wxDataViewColumn to the control. Returns @true on success.
937 Note that there is a number of short cut methods which implicitly create
938 a wxDataViewColumn and a wxDataViewRenderer for it (see below).
940 virtual bool AppendColumn(wxDataViewColumn
* col
);
943 Prepends a wxDataViewColumn to the control. Returns @true on success.
945 Note that there is a number of short cut methods which implicitly create
946 a wxDataViewColumn and a wxDataViewRenderer for it.
948 virtual bool PrependColumn(wxDataViewColumn
* col
);
951 Inserts a wxDataViewColumn to the control. Returns @true on success.
953 virtual bool InsertColumn(unsigned int pos
, wxDataViewColumn
* col
);
957 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
958 created in the function or @NULL on failure.
960 wxDataViewColumn
* AppendBitmapColumn(const wxString
& label
,
961 unsigned int model_column
,
962 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
964 wxAlignment align
= wxALIGN_CENTER
,
965 int flags
= wxDATAVIEW_COL_RESIZABLE
);
966 wxDataViewColumn
* AppendBitmapColumn(const wxBitmap
& label
,
967 unsigned int model_column
,
968 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
970 wxAlignment align
= wxALIGN_CENTER
,
971 int flags
= wxDATAVIEW_COL_RESIZABLE
);
976 Prepends a column for rendering a bitmap. Returns the wxDataViewColumn
977 created in the function or @NULL on failure.
979 wxDataViewColumn
* PrependBitmapColumn(const wxString
& label
,
980 unsigned int model_column
,
981 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
983 wxAlignment align
= wxALIGN_CENTER
,
984 int flags
= wxDATAVIEW_COL_RESIZABLE
);
985 wxDataViewColumn
* PrependBitmapColumn(const wxBitmap
& label
,
986 unsigned int model_column
,
987 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
989 wxAlignment align
= wxALIGN_CENTER
,
990 int flags
= wxDATAVIEW_COL_RESIZABLE
);
995 Appends a column for rendering a date. Returns the wxDataViewColumn
996 created in the function or @NULL on failure.
998 @note The @a align parameter is applied to both the column header and
1001 wxDataViewColumn
* AppendDateColumn(const wxString
& label
,
1002 unsigned int model_column
,
1003 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1005 wxAlignment align
= wxALIGN_NOT
,
1006 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1007 wxDataViewColumn
* AppendDateColumn(const wxBitmap
& label
,
1008 unsigned int model_column
,
1009 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1011 wxAlignment align
= wxALIGN_NOT
,
1012 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1017 Prepends a column for rendering a date. Returns the wxDataViewColumn
1018 created in the function or @NULL on failure.
1020 @note The @a align parameter is applied to both the column header and
1021 the column renderer.
1023 wxDataViewColumn
* PrependDateColumn(const wxString
& label
,
1024 unsigned int model_column
,
1025 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1027 wxAlignment align
= wxALIGN_NOT
,
1028 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1029 wxDataViewColumn
* PrependDateColumn(const wxBitmap
& label
,
1030 unsigned int model_column
,
1031 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1033 wxAlignment align
= wxALIGN_NOT
,
1034 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1039 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
1040 created in the function or @NULL on failure.
1041 This method uses the wxDataViewIconTextRenderer class.
1043 @note The @a align parameter is applied to both the column header and
1044 the column renderer.
1046 wxDataViewColumn
* AppendIconTextColumn(const wxString
& label
,
1047 unsigned int model_column
,
1048 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1050 wxAlignment align
= wxALIGN_NOT
,
1051 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1052 wxDataViewColumn
* AppendIconTextColumn(const wxBitmap
& label
,
1053 unsigned int model_column
,
1054 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1056 wxAlignment align
= wxALIGN_NOT
,
1057 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1062 Prepends a column for rendering text with an icon. Returns the wxDataViewColumn
1063 created in the function or @NULL on failure.
1064 This method uses the wxDataViewIconTextRenderer class.
1066 @note The @a align parameter is applied to both the column header and
1067 the column renderer.
1069 wxDataViewColumn
* PrependIconTextColumn(const wxString
& label
,
1070 unsigned int model_column
,
1071 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1073 wxAlignment align
= wxALIGN_NOT
,
1074 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1075 wxDataViewColumn
* PrependIconTextColumn(const wxBitmap
& label
,
1076 unsigned int model_column
,
1077 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1079 wxAlignment align
= wxALIGN_NOT
,
1080 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1085 Appends a column for rendering a progress indicator. Returns the
1086 wxDataViewColumn created in the function or @NULL on failure.
1088 @note The @a align parameter is applied to both the column header and
1089 the column renderer.
1091 wxDataViewColumn
* AppendProgressColumn(const wxString
& label
,
1092 unsigned int model_column
,
1093 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1095 wxAlignment align
= wxALIGN_CENTER
,
1096 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1097 wxDataViewColumn
* AppendProgressColumn(const wxBitmap
& label
,
1098 unsigned int model_column
,
1099 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1101 wxAlignment align
= wxALIGN_CENTER
,
1102 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1107 Prepends a column for rendering a progress indicator. Returns the
1108 wxDataViewColumn created in the function or @NULL on failure.
1110 @note The @a align parameter is applied to both the column header and
1111 the column renderer.
1113 wxDataViewColumn
* PrependProgressColumn(const wxString
& label
,
1114 unsigned int model_column
,
1115 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1117 wxAlignment align
= wxALIGN_CENTER
,
1118 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1119 wxDataViewColumn
* PrependProgressColumn(const wxBitmap
& label
,
1120 unsigned int model_column
,
1121 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1123 wxAlignment align
= wxALIGN_CENTER
,
1124 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1129 Appends a column for rendering text. Returns the wxDataViewColumn
1130 created in the function or @NULL on failure.
1132 @note The @a align parameter is applied to both the column header and
1133 the column renderer.
1135 wxDataViewColumn
* AppendTextColumn(const wxString
& label
,
1136 unsigned int model_column
,
1137 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1139 wxAlignment align
= wxALIGN_NOT
,
1140 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1141 wxDataViewColumn
* AppendTextColumn(const wxBitmap
& label
,
1142 unsigned int model_column
,
1143 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1145 wxAlignment align
= wxALIGN_NOT
,
1146 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1151 Prepends a column for rendering text. Returns the wxDataViewColumn
1152 created in the function or @NULL on failure.
1154 @note The @a align parameter is applied to both the column header and
1155 the column renderer.
1157 wxDataViewColumn
* PrependTextColumn(const wxString
& label
,
1158 unsigned int model_column
,
1159 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1161 wxAlignment align
= wxALIGN_NOT
,
1162 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1163 wxDataViewColumn
* PrependTextColumn(const wxBitmap
& label
,
1164 unsigned int model_column
,
1165 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1167 wxAlignment align
= wxALIGN_NOT
,
1168 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1173 Appends a column for rendering a toggle. Returns the wxDataViewColumn
1174 created in the function or @NULL on failure.
1176 @note The @a align parameter is applied to both the column header and
1177 the column renderer.
1179 wxDataViewColumn
* AppendToggleColumn(const wxString
& label
,
1180 unsigned int model_column
,
1181 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1183 wxAlignment align
= wxALIGN_CENTER
,
1184 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1185 wxDataViewColumn
* AppendToggleColumn(const wxBitmap
& label
,
1186 unsigned int model_column
,
1187 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1189 wxAlignment align
= wxALIGN_CENTER
,
1190 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1195 Prepends a column for rendering a toggle. Returns the wxDataViewColumn
1196 created in the function or @NULL on failure.
1198 @note The @a align parameter is applied to both the column header and
1199 the column renderer.
1201 wxDataViewColumn
* PrependToggleColumn(const wxString
& label
,
1202 unsigned int model_column
,
1203 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1205 wxAlignment align
= wxALIGN_CENTER
,
1206 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1207 wxDataViewColumn
* PrependToggleColumn(const wxBitmap
& label
,
1208 unsigned int model_column
,
1209 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1211 wxAlignment align
= wxALIGN_CENTER
,
1212 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1216 Associates a wxDataViewModel with the control.
1217 This increases the reference count of the model by 1.
1219 virtual bool AssociateModel(wxDataViewModel
* model
);
1222 Removes all columns.
1224 virtual bool ClearColumns();
1229 virtual void Collapse(const wxDataViewItem
& item
);
1232 Deletes given column.
1234 virtual bool DeleteColumn(wxDataViewColumn
* column
);
1237 Programmatically starts editing given cell of @a item.
1239 Doesn't do anything if the item or this column is not editable.
1241 @note Currently not implemented in wxOSX/Carbon.
1245 virtual void EditItem(const wxDataViewItem
& item
, const wxDataViewColumn
*column
);
1248 Enable drag operations using the given @a format.
1250 virtual bool EnableDragSource( const wxDataFormat
&format
);
1253 Enable drop operations using the given @a format.
1255 virtual bool EnableDropTarget( const wxDataFormat
&format
);
1258 Call this to ensure that the given item is visible.
1260 virtual void EnsureVisible(const wxDataViewItem
& item
,
1261 const wxDataViewColumn
* column
= NULL
);
1266 virtual void Expand(const wxDataViewItem
& item
);
1269 Expands all ancestors of the @a item. This method also
1270 ensures that the item itself as well as all ancestor
1271 items have been read from the model by the control.
1273 virtual void ExpandAncestors( const wxDataViewItem
& item
);
1276 Returns pointer to the column. @a pos refers to the position in the
1277 control which may change after reordering columns by the user.
1279 virtual wxDataViewColumn
* GetColumn(unsigned int pos
) const;
1282 Returns the number of columns.
1284 virtual unsigned int GetColumnCount() const;
1287 Returns the position of the column or -1 if not found in the control.
1289 virtual int GetColumnPosition(const wxDataViewColumn
* column
) const;
1292 Returns column containing the expanders.
1294 wxDataViewColumn
* GetExpanderColumn() const;
1297 Returns the currently focused item.
1299 This is the item that the keyboard commands apply to. It may be invalid
1300 if there is no focus currently.
1302 This method is mostly useful for the controls with @c wxDV_MULTIPLE
1303 style as in the case of single selection it returns the same thing as
1306 Notice that under all platforms except Mac OS X the currently focused
1307 item may be selected or not but under OS X the current item is always
1310 @see SetCurrentItem(), GetCurrentColumn()
1314 wxDataViewItem
GetCurrentItem() const;
1317 Returns the column that currently has focus.
1319 If the focus is set to individual cell within the currently focused
1320 item (as opposed to being on the item as a whole), then this is the
1321 column that the focus is on.
1323 Returns NULL if no column currently has focus.
1325 @see GetCurrentItem()
1329 wxDataViewColumn
*GetCurrentColumn() const;
1332 Returns indentation.
1334 int GetIndent() const;
1337 Returns item rectangle.
1339 This method is currently not implemented at all in wxGTK and only
1340 implemented for non-@NULL @a col argument in wxOSX. It is fully
1341 implemented in the generic version of the control.
1346 If non-@NULL, the rectangle returned corresponds to the
1347 intersection of the item with the specified column. If @NULL, the
1348 rectangle spans all the columns.
1350 virtual wxRect
GetItemRect(const wxDataViewItem
& item
,
1351 const wxDataViewColumn
* col
= NULL
) const;
1354 Returns pointer to the data model associated with the control (if any).
1356 wxDataViewModel
* GetModel();
1359 Returns the number of currently selected items.
1361 This method may be called for both the controls with single and
1362 multiple selections and returns the number of selected item, possibly
1367 virtual int GetSelectedItemsCount() const;
1370 Returns first selected item or an invalid item if none is selected.
1372 This method may be called for both the controls with single and
1373 multiple selections but returns an invalid item if more than one item
1374 is selected in the latter case, use HasSelection() to determine if
1375 there are any selected items when using multiple selection.
1377 virtual wxDataViewItem
GetSelection() const;
1380 Fills @a sel with currently selected items and returns their number.
1382 This method may be called for both the controls with single and
1383 multiple selections. In the single selection case it returns the array
1384 with at most one element in it.
1386 @see GetSelectedItemsCount()
1388 virtual int GetSelections(wxDataViewItemArray
& sel
) const;
1391 Returns the wxDataViewColumn currently responsible for sorting
1392 or @NULL if none has been selected.
1394 virtual wxDataViewColumn
* GetSortingColumn() const;
1397 Returns true if any items are currently selected.
1399 This method may be called for both the controls with single and
1400 multiple selections.
1402 Calling this method is equivalent to calling GetSelectedItemsCount()
1403 and comparing its result with 0 but is more clear and might also be
1404 implemented more efficiently in the future.
1408 bool HasSelection() const;
1413 virtual void HitTest(const wxPoint
& point
, wxDataViewItem
& item
,
1414 wxDataViewColumn
*& col
) const;
1417 Return @true if the item is expanded.
1419 virtual bool IsExpanded(const wxDataViewItem
& item
) const;
1422 Return @true if the item is selected.
1424 virtual bool IsSelected(const wxDataViewItem
& item
) const;
1427 Select the given item.
1429 In single selection mode this changes the (unique) currently selected
1430 item. In multi selection mode, the @a item is selected and the
1431 previously selected items remain selected.
1433 virtual void Select(const wxDataViewItem
& item
);
1438 virtual void SelectAll();
1441 Set which column shall contain the tree-like expanders.
1443 void SetExpanderColumn(wxDataViewColumn
* col
);
1446 Changes the currently focused item.
1448 The @a item parameter must be valid, there is no way to remove the
1449 current item from the control.
1451 In single selection mode, calling this method is the same as calling
1452 Select() and is thus not very useful. In multiple selection mode this
1453 method only moves the current item however without changing the
1454 selection except under OS X where the current item is always selected,
1455 so calling SetCurrentItem() selects @a item if it hadn't been selected
1458 @see GetCurrentItem()
1462 void SetCurrentItem(const wxDataViewItem
& item
);
1465 Sets the indentation.
1467 void SetIndent(int indent
);
1470 Sets the selection to the array of wxDataViewItems.
1472 virtual void SetSelections(const wxDataViewItemArray
& sel
);
1475 Unselect the given item.
1477 virtual void Unselect(const wxDataViewItem
& item
);
1481 This method only has effect if multiple selections are allowed.
1483 virtual void UnselectAll();
1486 Sets the row height.
1488 This function can only be used when all rows have the same height, i.e.
1489 when wxDV_VARIABLE_LINE_HEIGHT flag is not used.
1491 Currently this is implemented in the generic and native GTK versions
1492 only and nothing is done (and @false returned) when using OS X port.
1494 Also notice that this method can only be used to increase the row
1495 height compared with the default one (as determined by the return value
1496 of wxDataViewRenderer::GetSize()), if it is set to a too small value
1497 then the minimum required by the renderers will be used.
1499 @return @true if the line height was changed or @false otherwise.
1503 virtual bool SetRowHeight(int rowHeight
);
1509 @class wxDataViewModelNotifier
1511 A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
1512 its notification interface.
1513 See the documentation of that class for further information.
1518 class wxDataViewModelNotifier
1524 wxDataViewModelNotifier();
1529 virtual ~wxDataViewModelNotifier();
1532 Called by owning model.
1534 virtual bool Cleared() = 0;
1537 Get owning wxDataViewModel.
1539 wxDataViewModel
* GetOwner() const;
1542 Called by owning model.
1544 @return Always return @true from this function in derived classes.
1546 virtual bool ItemAdded(const wxDataViewItem
& parent
,
1547 const wxDataViewItem
& item
) = 0;
1550 Called by owning model.
1552 @return Always return @true from this function in derived classes.
1554 virtual bool ItemChanged(const wxDataViewItem
& item
) = 0;
1557 Called by owning model.
1559 @return Always return @true from this function in derived classes.
1561 virtual bool ItemDeleted(const wxDataViewItem
& parent
,
1562 const wxDataViewItem
& item
) = 0;
1565 Called by owning model.
1567 @return Always return @true from this function in derived classes.
1569 virtual bool ItemsAdded(const wxDataViewItem
& parent
,
1570 const wxDataViewItemArray
& items
);
1573 Called by owning model.
1575 @return Always return @true from this function in derived classes.
1577 virtual bool ItemsChanged(const wxDataViewItemArray
& items
);
1580 Called by owning model.
1582 @return Always return @true from this function in derived classes.
1584 virtual bool ItemsDeleted(const wxDataViewItem
& parent
,
1585 const wxDataViewItemArray
& items
);
1588 Called by owning model.
1590 virtual void Resort() = 0;
1593 Set owner of this notifier. Used internally.
1595 void SetOwner(wxDataViewModel
* owner
);
1598 Called by owning model.
1600 @return Always return @true from this function in derived classes.
1602 virtual bool ValueChanged(const wxDataViewItem
& item
, unsigned int col
) = 0;
1607 The mode of a data-view cell; see wxDataViewRenderer for more info.
1609 enum wxDataViewCellMode
1612 The cell only displays information and cannot be manipulated or
1613 otherwise interacted with in any way.
1615 Note that this doesn't mean that the row being drawn can't be selected,
1616 just that a particular element of it cannot be individually modified.
1618 wxDATAVIEW_CELL_INERT
,
1621 Indicates that the cell can be @em activated by clicking it or using
1624 Activating a cell is an alternative to showing inline editor when the
1625 value can be edited in a simple way that doesn't warrant full editor
1626 control. The most typical use of cell activation is toggling the
1627 checkbox in wxDataViewToggleRenderer; others would be e.g. an embedded
1628 volume slider or a five-star rating column.
1630 The exact means of activating a cell are platform-dependent, but they
1631 are usually similar to those used for inline editing of values.
1632 Typically, a cell would be activated by Space or Enter keys or by left
1635 @note Do not confuse this with item activation in wxDataViewCtrl
1636 and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is
1637 used for activating the item (or, to put it differently, the
1638 entire row) similarly to analogous messages in wxTreeCtrl and
1639 wxListCtrl, and the effect differs (play a song, open a file
1640 etc.). Cell activation, on the other hand, is all about
1641 interacting with the individual cell.
1643 @see wxDataViewCustomRenderer::ActivateCell()
1645 wxDATAVIEW_CELL_ACTIVATABLE
,
1648 Indicates that the user can edit the data in-place in an inline editor
1649 control that will show up when the user wants to edit the cell.
1651 A typical example of this behaviour is changing the filename in a file
1654 Editing is typically triggered by slowly double-clicking the cell or by
1655 a platform-dependent keyboard shortcut (F2 is typical on Windows, Space
1656 and/or Enter is common elsewhere and supported on Windows too).
1658 @see wxDataViewCustomRenderer::CreateEditorCtrl()
1660 wxDATAVIEW_CELL_EDITABLE
1664 The values of this enum controls how a wxDataViewRenderer should display
1665 its contents in a cell.
1667 enum wxDataViewCellRenderState
1669 wxDATAVIEW_CELL_SELECTED
= 1,
1670 wxDATAVIEW_CELL_PRELIT
= 2,
1671 wxDATAVIEW_CELL_INSENSITIVE
= 4,
1672 wxDATAVIEW_CELL_FOCUSED
= 8
1676 @class wxDataViewRenderer
1678 This class is used by wxDataViewCtrl to render the individual cells.
1679 One instance of a renderer class is owned by a wxDataViewColumn.
1680 There is a number of ready-to-use renderers provided:
1681 - wxDataViewTextRenderer,
1682 - wxDataViewIconTextRenderer,
1683 - wxDataViewToggleRenderer,
1684 - wxDataViewProgressRenderer,
1685 - wxDataViewBitmapRenderer,
1686 - wxDataViewDateRenderer,
1687 - wxDataViewSpinRenderer.
1688 - wxDataViewChoiceRenderer.
1690 Additionally, the user can write their own renderers by deriving from
1691 wxDataViewCustomRenderer.
1693 The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1694 by the constructors respectively controls what actions the cell data allows
1695 and how the renderer should display its contents in a cell.
1700 class wxDataViewRenderer
: public wxObject
1706 wxDataViewRenderer(const wxString
& varianttype
,
1707 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1708 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1711 Enable or disable replacing parts of the item text with ellipsis to
1712 make it fit the column width.
1714 This method only makes sense for the renderers working with text, such
1715 as wxDataViewTextRenderer or wxDataViewIconTextRenderer.
1717 By default wxELLIPSIZE_MIDDLE is used.
1720 Ellipsization mode, use wxELLIPSIZE_NONE to disable.
1724 void EnableEllipsize(wxEllipsizeMode mode
= wxELLIPSIZE_MIDDLE
);
1727 Disable replacing parts of the item text with ellipsis.
1729 If ellipsizing is disabled, the string will be truncated if it doesn't
1732 This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode.
1736 void DisableEllipsize();
1739 Returns the alignment. See SetAlignment()
1741 virtual int GetAlignment() const;
1744 Returns the ellipsize mode used by the renderer.
1746 If the return value is wxELLIPSIZE_NONE, the text is simply truncated
1749 @see EnableEllipsize()
1751 wxEllipsizeMode
GetEllipsizeMode() const;
1754 Returns the cell mode.
1756 virtual wxDataViewCellMode
GetMode() const;
1759 Returns pointer to the owning wxDataViewColumn.
1761 wxDataViewColumn
* GetOwner() const;
1764 This methods retrieves the value from the renderer in order to
1765 transfer the value back to the data model.
1767 Returns @false on failure.
1769 virtual bool GetValue(wxVariant
& value
) const = 0;
1772 Returns a string with the type of the wxVariant supported by this renderer.
1774 wxString
GetVariantType() const;
1777 Sets the alignment of the renderer's content.
1778 The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1779 should have the same alignment as the column header.
1781 The method is not implemented under OS X and the renderer always aligns
1782 its contents as the column header on that platform. The other platforms
1783 support both vertical and horizontal alignment.
1785 virtual void SetAlignment( int align
);
1787 Sets the owning wxDataViewColumn.
1788 This is usually called from within wxDataViewColumn.
1790 void SetOwner(wxDataViewColumn
* owner
);
1793 Set the value of the renderer (and thus its cell) to @a value.
1794 The internal code will then render this cell with this data.
1796 virtual bool SetValue(const wxVariant
& value
) = 0;
1799 Before data is committed to the data model, it is passed to this
1800 method where it can be checked for validity. This can also be
1801 used for checking a valid range or limiting the user input in
1802 a certain aspect (e.g. max number of characters or only alphanumeric
1803 input, ASCII only etc.). Return @false if the value is not valid.
1805 Please note that due to implementation limitations, this validation
1806 is done after the editing control already is destroyed and the
1807 editing process finished.
1809 virtual bool Validate(wxVariant
& value
);
1812 virtual bool HasEditorCtrl() const;
1813 virtual wxWindow
* CreateEditorCtrl(wxWindow
* parent
,
1815 const wxVariant
& value
);
1816 virtual bool GetValueFromEditorCtrl(wxWindow
* editor
,
1818 virtual bool StartEditing( const wxDataViewItem
&item
, wxRect labelRect
);
1819 virtual void CancelEditing();
1820 virtual bool FinishEditing();
1821 wxWindow
*GetEditorCtrl();
1824 wxDataViewCtrl
* GetView() const;
1830 @class wxDataViewTextRenderer
1832 wxDataViewTextRenderer is used for rendering text.
1833 It supports in-place editing if desired.
1838 class wxDataViewTextRenderer
: public wxDataViewRenderer
1844 wxDataViewTextRenderer(const wxString
& varianttype
= "string",
1845 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1846 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1852 @class wxDataViewIconTextRenderer
1854 The wxDataViewIconTextRenderer class is used to display text with
1855 a small icon next to it as it is typically done in a file manager.
1857 This classes uses the wxDataViewIconText helper class to store its data.
1858 wxDataViewIconText can be converted to and from a wxVariant using the left
1864 class wxDataViewIconTextRenderer
: public wxDataViewRenderer
1870 wxDataViewIconTextRenderer(const wxString
& varianttype
= "wxDataViewIconText",
1871 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1872 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1878 @class wxDataViewProgressRenderer
1880 This class is used by wxDataViewCtrl to render progress bars.
1885 class wxDataViewProgressRenderer
: public wxDataViewRenderer
1891 wxDataViewProgressRenderer(const wxString
& label
= wxEmptyString
,
1892 const wxString
& varianttype
= "long",
1893 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1894 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1900 @class wxDataViewSpinRenderer
1902 This is a specialized renderer for rendering integer values.
1903 It supports modifying the values in-place by using a wxSpinCtrl.
1904 The renderer only support variants of type @e long.
1909 class wxDataViewSpinRenderer
: public wxDataViewCustomRenderer
1914 @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1916 wxDataViewSpinRenderer(int min
, int max
,
1917 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1918 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1924 @class wxDataViewToggleRenderer
1926 This class is used by wxDataViewCtrl to render toggle controls.
1931 class wxDataViewToggleRenderer
: public wxDataViewRenderer
1937 wxDataViewToggleRenderer(const wxString
& varianttype
= "bool",
1938 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1939 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1944 A wxDataViewCtrl renderer using wxChoice control and values of strings in
1947 This class is used by wxDataViewCtrl to render choice controls.
1948 It stores a string so that SetValue() and GetValue() operate
1949 on a variant holding a string.
1951 @see wxDataViewChoiceByIndexRenderer
1957 class wxDataViewChoiceRenderer
: public wxDataViewRenderer
1963 wxDataViewChoiceRenderer( const wxArrayString
&choices
,
1964 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1965 int alignment
= wxDVR_DEFAULT_ALIGNMENT
);
1968 Returns the choice referred to by index.
1970 wxString
GetChoice(size_t index
) const;
1973 Returns all choices.
1975 const wxArrayString
& GetChoices() const;
1980 A wxDataViewCtrl renderer using wxChoice control and indexes into it.
1982 Unlike its base wxDataViewChoiceRenderer class, this one stores the choice
1983 index, i.e. an @c int, in the variant used by its SetValue() and
1989 class wxDataViewChoiceByIndexRenderer
: public wxDataViewChoiceRenderer
1995 wxDataViewChoiceByIndexRenderer( const wxArrayString
&choices
,
1996 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1997 int alignment
= wxDVR_DEFAULT_ALIGNMENT
);
2002 @class wxDataViewDateRenderer
2004 This class is used by wxDataViewCtrl to render calendar controls.
2009 class wxDataViewDateRenderer
: public wxDataViewRenderer
2015 wxDataViewDateRenderer(const wxString
& varianttype
= "datetime",
2016 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
2017 int align
= wxDVR_DEFAULT_ALIGNMENT
);
2023 @class wxDataViewCustomRenderer
2025 You need to derive a new class from wxDataViewCustomRenderer in
2026 order to write a new renderer.
2028 You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
2029 wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
2031 If you want your renderer to support in-place editing then you also need to override
2032 wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
2033 and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
2035 Note that a special event handler will be pushed onto that editor control
2036 which handles @e \<ENTER\> and focus out events in order to end the editing.
2041 class wxDataViewCustomRenderer
: public wxDataViewRenderer
2047 wxDataViewCustomRenderer(const wxString
& varianttype
= "string",
2048 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
2049 int align
= wxDVR_DEFAULT_ALIGNMENT
);
2054 virtual ~wxDataViewCustomRenderer();
2057 Override this to react to cell @em activation. Activating a cell is an
2058 alternative to showing inline editor when the value can be edited in a
2059 simple way that doesn't warrant full editor control. The most typical
2060 use of cell activation is toggling the checkbox in
2061 wxDataViewToggleRenderer; others would be e.g. an embedded volume
2062 slider or a five-star rating column.
2064 The exact means of activating a cell are platform-dependent, but they
2065 are usually similar to those used for inline editing of values.
2066 Typically, a cell would be activated by Space or Enter keys or by left
2069 This method will only be called if the cell has the
2070 wxDATAVIEW_CELL_ACTIVATABLE mode.
2073 Coordinates of the activated cell's area.
2075 The model to manipulate in response.
2079 Activated column of @a item.
2081 If the activation was triggered by mouse click, contains the
2082 corresponding event. Is @NULL otherwise (for keyboard activation).
2083 Mouse coordinates are adjusted to be relative to the cell.
2087 @note Do not confuse this method with item activation in wxDataViewCtrl
2088 and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is
2089 used for activating the item (or, to put it differently, the
2090 entire row) similarly to analogous messages in wxTreeCtrl and
2091 wxListCtrl, and the effect differs (play a song, open a file
2092 etc.). Cell activation, on the other hand, is all about
2093 interacting with the individual cell.
2095 @see CreateEditorCtrl()
2097 virtual bool ActivateCell(const wxRect
& cell
,
2098 wxDataViewModel
* model
,
2099 const wxDataViewItem
& item
,
2101 const wxMouseEvent
*mouseEvent
);
2104 Override this to create the actual editor control once editing
2107 This method will only be called if the cell has the
2108 wxDATAVIEW_CELL_EDITABLE mode. Editing is typically triggered by slowly
2109 double-clicking the cell or by a platform-dependent keyboard shortcut
2110 (F2 is typical on Windows, Space and/or Enter is common elsewhere and
2111 supported on Windows too).
2114 The parent of the editor control.
2116 Indicates the position and size of the editor control. The control
2117 should be created in place of the cell and @a labelRect should be
2118 respected as much as possible.
2120 Initial value of the editor.
2126 return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
2127 labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
2133 virtual wxWindow
* CreateEditorCtrl(wxWindow
* parent
,
2135 const wxVariant
& value
);
2138 Return the attribute to be used for rendering.
2140 This function may be called from Render() implementation to use the
2141 attributes defined for the item if the renderer supports them.
2143 Notice that when Render() is called, the wxDC object passed to it is
2144 already set up to use the correct attributes (e.g. its font is set to
2145 bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic()
2146 returns true) so it may not be necessary to call it explicitly if you
2147 only want to render text using the items attributes.
2151 const wxDataViewItemAttr
& GetAttr() const;
2154 Return size required to show content.
2156 virtual wxSize
GetSize() const = 0;
2159 Override this so that the renderer can get the value from the editor
2160 control (pointed to by @a editor):
2163 wxSpinCtrl *sc = (wxSpinCtrl*) editor;
2164 long l = sc->GetValue();
2170 virtual bool GetValueFromEditorCtrl(wxWindow
* editor
,
2174 Override this and make it return @true in order to
2175 indicate that this renderer supports in-place editing.
2177 virtual bool HasEditorCtrl() const;
2180 Override this to react to a left click. This method will only be
2181 called in @c wxDATAVIEW_CELL_ACTIVATABLE mode. This method is
2182 deprecated, please use ActivateCell instead.
2184 virtual bool LeftClick( wxPoint cursor
,
2186 wxDataViewModel
* model
,
2187 const wxDataViewItem
& item
,
2191 Override this to react to the activation of a cell. This method is
2192 deprecated, please use ActivateCell instead.
2194 virtual bool Activate(wxRect cell
,
2195 wxDataViewModel
* model
,
2196 const wxDataViewItem
& item
,
2201 Override this to render the cell.
2202 Before this is called, wxDataViewRenderer::SetValue was called
2203 so that this instance knows what to render.
2205 virtual bool Render(wxRect cell
, wxDC
* dc
, int state
) = 0;
2208 This method should be called from within Render() whenever you need to
2210 This will ensure that the correct colour, font and vertical alignment will
2211 be chosen so the text will look the same as text drawn by native renderers.
2213 void RenderText(const wxString
& text
, int xoffset
, wxRect cell
,
2214 wxDC
* dc
, int state
);
2217 Override this to start a drag operation. Not yet supported.
2219 virtual bool StartDrag(const wxPoint
& cursor
,
2221 wxDataViewModel
* model
,
2222 const wxDataViewItem
& item
,
2227 Helper for GetSize() implementations, respects attributes.
2229 wxSize
GetTextExtent(const wxString
& str
) const;
2235 @class wxDataViewBitmapRenderer
2237 This class is used by wxDataViewCtrl to render bitmap controls.
2242 class wxDataViewBitmapRenderer
: public wxDataViewRenderer
2248 wxDataViewBitmapRenderer(const wxString
& varianttype
= "wxBitmap",
2249 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
2250 int align
= wxDVR_DEFAULT_ALIGNMENT
);
2255 The flags used by wxDataViewColumn.
2256 Can be combined together.
2258 enum wxDataViewColumnFlags
2260 wxDATAVIEW_COL_RESIZABLE
= 1,
2261 wxDATAVIEW_COL_SORTABLE
= 2,
2262 wxDATAVIEW_COL_REORDERABLE
= 4,
2263 wxDATAVIEW_COL_HIDDEN
= 8
2267 @class wxDataViewColumn
2269 This class represents a column in a wxDataViewCtrl.
2270 One wxDataViewColumn is bound to one column in the data model to which the
2271 wxDataViewCtrl has been associated.
2273 An instance of wxDataViewRenderer is used by this class to render its data.
2278 class wxDataViewColumn
: public wxSettableHeaderColumn
2282 Constructs a text column.
2285 The title of the column.
2287 The class which will render the contents of this column.
2289 The index of the model's column which is associated with this object.
2291 The width of the column.
2292 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
2294 The alignment of the column title.
2296 One or more flags of the ::wxDataViewColumnFlags enumeration.
2298 wxDataViewColumn(const wxString
& title
,
2299 wxDataViewRenderer
* renderer
,
2300 unsigned int model_column
,
2301 int width
= wxDVC_DEFAULT_WIDTH
,
2302 wxAlignment align
= wxALIGN_CENTER
,
2303 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2306 Constructs a bitmap column.
2309 The bitmap of the column.
2311 The class which will render the contents of this column.
2313 The index of the model's column which is associated with this object.
2315 The width of the column.
2316 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
2318 The alignment of the column title.
2320 One or more flags of the ::wxDataViewColumnFlags enumeration.
2322 wxDataViewColumn(const wxBitmap
& bitmap
,
2323 wxDataViewRenderer
* renderer
,
2324 unsigned int model_column
,
2325 int width
= wxDVC_DEFAULT_WIDTH
,
2326 wxAlignment align
= wxALIGN_CENTER
,
2327 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2330 Returns the index of the column of the model, which this
2331 wxDataViewColumn is displaying.
2333 unsigned int GetModelColumn() const;
2336 Returns the owning wxDataViewCtrl.
2338 wxDataViewCtrl
* GetOwner() const;
2341 Returns the renderer of this wxDataViewColumn.
2343 @see wxDataViewRenderer.
2345 wxDataViewRenderer
* GetRenderer() const;
2351 @class wxDataViewListCtrl
2353 This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
2354 and forwards most of its API to that class.
2356 The purpose of this class is to offer a simple way to display and
2357 edit a small table of data without having to write your own wxDataViewModel.
2360 wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
2362 listctrl->AppendToggleColumn( "Toggle" );
2363 listctrl->AppendTextColumn( "Text" );
2365 wxVector<wxVariant> data;
2366 data.push_back( wxVariant(true) );
2367 data.push_back( wxVariant("row 1") );
2368 listctrl->AppendItem( data );
2371 data.push_back( wxVariant(false) );
2372 data.push_back( wxVariant("row 3") );
2373 listctrl->AppendItem( data );
2377 See wxDataViewCtrl for the list of supported styles.
2380 @beginEventEmissionTable
2381 See wxDataViewCtrl for the list of events emitted by this class.
2389 class wxDataViewListCtrl
: public wxDataViewCtrl
2395 wxDataViewListCtrl();
2398 Constructor. Calls Create().
2400 wxDataViewListCtrl( wxWindow
*parent
, wxWindowID id
,
2401 const wxPoint
& pos
= wxDefaultPosition
,
2402 const wxSize
& size
= wxDefaultSize
, long style
= wxDV_ROW_LINES
,
2403 const wxValidator
& validator
= wxDefaultValidator
);
2406 Destructor. Deletes the image list if any.
2408 ~wxDataViewListCtrl();
2411 Creates the control and a wxDataViewListStore as its internal model.
2413 bool Create( wxWindow
*parent
, wxWindowID id
,
2414 const wxPoint
& pos
= wxDefaultPosition
,
2415 const wxSize
& size
= wxDefaultSize
, long style
= wxDV_ROW_LINES
,
2416 const wxValidator
& validator
= wxDefaultValidator
);
2422 wxDataViewListStore
*GetStore();
2423 const wxDataViewListStore
*GetStore() const;
2427 Returns the position of given @e item or wxNOT_FOUND if it's
2432 int ItemToRow(const wxDataViewItem
&item
) const;
2435 Returns the wxDataViewItem at the given @e row.
2439 wxDataViewItem
RowToItem(int row
) const;
2443 @name Selection handling functions
2447 Returns index of the selected row or wxNOT_FOUND.
2449 @see wxDataViewCtrl::GetSelection()
2453 int GetSelectedRow() const;
2458 @see wxDataViewCtrl::Select()
2462 void SelectRow(unsigned row
);
2465 Unselects given row.
2467 @see wxDataViewCtrl::Unselect()
2471 void UnselectRow(unsigned row
);
2474 Returns true if @a row is selected.
2476 @see wxDataViewCtrl::IsSelected()
2480 bool IsRowSelected(unsigned row
) const;
2485 @name Column management functions
2490 Appends a column to the control and additionally appends a
2491 column to the store with the type string.
2493 virtual bool AppendColumn( wxDataViewColumn
*column
);
2496 Appends a column to the control and additionally appends a
2497 column to the list store with the type @a varianttype.
2499 void AppendColumn( wxDataViewColumn
*column
, const wxString
&varianttype
);
2502 Appends a text column to the control and the store.
2504 See wxDataViewColumn::wxDataViewColumn for more info about
2507 wxDataViewColumn
*AppendTextColumn( const wxString
&label
,
2508 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
2509 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
2510 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2513 Appends a toggle column to the control and the store.
2515 See wxDataViewColumn::wxDataViewColumn for more info about
2518 wxDataViewColumn
*AppendToggleColumn( const wxString
&label
,
2519 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
2520 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
2521 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2524 Appends a progress column to the control and the store.
2526 See wxDataViewColumn::wxDataViewColumn for more info about
2529 wxDataViewColumn
*AppendProgressColumn( const wxString
&label
,
2530 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
2531 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
2532 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2535 Appends an icon-and-text column to the control and the store.
2537 See wxDataViewColumn::wxDataViewColumn for more info about
2540 wxDataViewColumn
*AppendIconTextColumn( const wxString
&label
,
2541 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
2542 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
2543 int flags
= wxDATAVIEW_COL_RESIZABLE
);
2546 Inserts a column to the control and additionally inserts a
2547 column to the store with the type string.
2549 virtual bool InsertColumn( unsigned int pos
, wxDataViewColumn
*column
);
2552 Inserts a column to the control and additionally inserts a
2553 column to the list store with the type @a varianttype.
2555 void InsertColumn( unsigned int pos
, wxDataViewColumn
*column
,
2556 const wxString
&varianttype
);
2559 Prepends a column to the control and additionally prepends a
2560 column to the store with the type string.
2562 virtual bool PrependColumn( wxDataViewColumn
*column
);
2565 Prepends a column to the control and additionally prepends a
2566 column to the list store with the type @a varianttype.
2568 void PrependColumn( wxDataViewColumn
*column
, const wxString
&varianttype
);
2574 @name Item management functions
2579 Appends an item (=row) to the control and store.
2581 void AppendItem( const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2584 Prepends an item (=row) to the control and store.
2586 void PrependItem( const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2589 Inserts an item (=row) to the control and store.
2591 void InsertItem( unsigned int row
, const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2594 Delete the row at position @a row.
2596 void DeleteItem( unsigned row
);
2599 Delete all items (= all rows).
2601 void DeleteAllItems();
2604 Returns the number of items (=rows) in the control
2608 unsigned int GetItemCount() const;
2611 Returns the client data associated with the item.
2617 wxUIntPtr
GetItemData(const wxDataViewItem
& item
) const;
2620 Sets the value in the store and update the control.
2622 void SetValue( const wxVariant
&value
, unsigned int row
, unsigned int col
);
2625 Returns the value from the store.
2627 void GetValue( wxVariant
&value
, unsigned int row
, unsigned int col
);
2630 Sets the value in the store and update the control.
2632 This method assumes that the string is stored in respective
2635 void SetTextValue( const wxString
&value
, unsigned int row
, unsigned int col
);
2638 Returns the value from the store.
2640 This method assumes that the string is stored in respective
2643 wxString
GetTextValue( unsigned int row
, unsigned int col
) const;
2646 Sets the value in the store and update the control.
2648 This method assumes that the boolean value is stored in
2651 void SetToggleValue( bool value
, unsigned int row
, unsigned int col
);
2654 Returns the value from the store.
2656 This method assumes that the boolean value is stored in
2659 bool GetToggleValue( unsigned int row
, unsigned int col
) const;
2662 Associates a client data pointer with the given item.
2664 Notice that the control does @e not take ownership of the pointer for
2665 compatibility with wxListCtrl. I.e. it will @e not delete the pointer
2666 (if it is a pointer and not a number) itself, it is up to you to do it.
2672 void SetItemData(const wxDataViewItem
& item
, wxUIntPtr data
);
2679 @class wxDataViewTreeCtrl
2681 This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
2682 and forwards most of its API to that class.
2683 Additionally, it uses a wxImageList to store a list of icons.
2685 The main purpose of this class is to provide a simple upgrade path for code
2689 See wxDataViewCtrl for the list of supported styles.
2692 @beginEventEmissionTable
2693 See wxDataViewCtrl for the list of events emitted by this class.
2701 @appearance{dataviewtreectrl}
2703 class wxDataViewTreeCtrl
: public wxDataViewCtrl
2709 wxDataViewTreeCtrl();
2716 wxDataViewTreeCtrl(wxWindow
* parent
, wxWindowID id
,
2717 const wxPoint
& pos
= wxDefaultPosition
,
2718 const wxSize
& size
= wxDefaultSize
,
2719 long style
= wxDV_NO_HEADER
| wxDV_ROW_LINES
,
2720 const wxValidator
& validator
= wxDefaultValidator
);
2723 Destructor. Deletes the image list if any.
2725 virtual ~wxDataViewTreeCtrl();
2728 Appends a container to the given @a parent.
2730 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
2731 const wxString
& text
,
2734 wxClientData
* data
= NULL
);
2737 Appends an item to the given @a parent.
2739 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
2740 const wxString
& text
,
2742 wxClientData
* data
= NULL
);
2745 Creates the control and a wxDataViewTreeStore as its internal model.
2747 The default tree column created by this method is an editable column
2748 using wxDataViewIconTextRenderer as its renderer.
2750 bool Create(wxWindow
* parent
, wxWindowID id
,
2751 const wxPoint
& pos
= wxDefaultPosition
,
2752 const wxSize
& size
= wxDefaultSize
,
2753 long style
= wxDV_NO_HEADER
| wxDV_ROW_LINES
,
2754 const wxValidator
& validator
= wxDefaultValidator
);
2757 Calls the identical method from wxDataViewTreeStore.
2759 void DeleteAllItems();
2762 Calls the identical method from wxDataViewTreeStore.
2764 void DeleteChildren(const wxDataViewItem
& item
);
2767 Calls the identical method from wxDataViewTreeStore.
2769 void DeleteItem(const wxDataViewItem
& item
);
2772 Calls the identical method from wxDataViewTreeStore.
2774 int GetChildCount(const wxDataViewItem
& parent
) const;
2777 Returns the image list.
2779 wxImageList
* GetImageList();
2782 Calls the identical method from wxDataViewTreeStore.
2784 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
2787 Calls the identical method from wxDataViewTreeStore.
2789 const wxIcon
& GetItemExpandedIcon(const wxDataViewItem
& item
) const;
2792 Calls the identical method from wxDataViewTreeStore.
2794 const wxIcon
& GetItemIcon(const wxDataViewItem
& item
) const;
2797 Calls the identical method from wxDataViewTreeStore.
2799 wxString
GetItemText(const wxDataViewItem
& item
) const;
2802 Calls the identical method from wxDataViewTreeStore.
2804 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
2805 unsigned int pos
) const;
2811 wxDataViewTreeStore
* GetStore();
2812 const wxDataViewTreeStore
* GetStore() const;
2816 Calls the same method from wxDataViewTreeStore but uses
2817 an index position in the image list instead of a wxIcon.
2819 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
2820 const wxDataViewItem
& previous
,
2821 const wxString
& text
,
2824 wxClientData
* data
= NULL
);
2827 Calls the same method from wxDataViewTreeStore but uses
2828 an index position in the image list instead of a wxIcon.
2830 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
2831 const wxDataViewItem
& previous
,
2832 const wxString
& text
,
2834 wxClientData
* data
= NULL
);
2837 Returns true if item is a container.
2839 bool IsContainer( const wxDataViewItem
& item
);
2842 Calls the same method from wxDataViewTreeStore but uses
2843 an index position in the image list instead of a wxIcon.
2845 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
2846 const wxString
& text
,
2849 wxClientData
* data
= NULL
);
2852 Calls the same method from wxDataViewTreeStore but uses
2853 an index position in the image list instead of a wxIcon.
2855 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
2856 const wxString
& text
,
2858 wxClientData
* data
= NULL
);
2861 Sets the image list.
2863 void SetImageList(wxImageList
* imagelist
);
2866 Calls the identical method from wxDataViewTreeStore.
2868 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
2871 Calls the identical method from wxDataViewTreeStore.
2873 void SetItemExpandedIcon(const wxDataViewItem
& item
,
2874 const wxIcon
& icon
);
2877 Calls the identical method from wxDataViewTreeStore.
2879 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
2882 Calls the identical method from wxDataViewTreeStore.
2884 void SetItemText(const wxDataViewItem
& item
,
2885 const wxString
& text
);
2890 @class wxDataViewListStore
2892 wxDataViewListStore is a specialised wxDataViewModel for storing
2893 a simple table of data. Since it derives from wxDataViewIndexListModel
2894 its data is be accessed by row (i.e. by index) instead of only
2897 This class actually stores the values (therefore its name)
2898 and implements all virtual methods from the base classes so it can be
2899 used directly without having to derive any class from it, but it is
2900 mostly used from within wxDataViewListCtrl.
2906 class wxDataViewListStore
: public wxDataViewIndexListModel
2912 wxDataViewListStore();
2917 ~wxDataViewListStore();
2920 Prepends a data column.
2922 @a variantype indicates the type of values store in the column.
2924 This does not automatically fill in any (default) values in
2925 rows which exist in the store already.
2927 void PrependColumn( const wxString
&varianttype
);
2930 Inserts a data column before @a pos.
2932 @a variantype indicates the type of values store in the column.
2934 This does not automatically fill in any (default) values in
2935 rows which exist in the store already.
2937 void InsertColumn( unsigned int pos
, const wxString
&varianttype
);
2940 Appends a data column.
2942 @a variantype indicates the type of values store in the column.
2944 This does not automatically fill in any (default) values in
2945 rows which exist in the store already.
2947 void AppendColumn( const wxString
&varianttype
);
2950 Appends an item (=row) and fills it with @a values.
2952 The values must match the values specifies in the column
2953 in number and type. No (default) values are filled in
2956 void AppendItem( const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2959 Prepends an item (=row) and fills it with @a values.
2961 The values must match the values specifies in the column
2962 in number and type. No (default) values are filled in
2965 void PrependItem( const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2968 Inserts an item (=row) and fills it with @a values.
2970 The values must match the values specifies in the column
2971 in number and type. No (default) values are filled in
2974 void InsertItem( unsigned int row
, const wxVector
<wxVariant
> &values
, wxUIntPtr data
= NULL
);
2977 Delete the item (=row) at position @a pos.
2979 void DeleteItem( unsigned pos
);
2982 Delete all item (=all rows) in the store.
2984 void DeleteAllItems();
2987 Returns the number of items (=rows) in the control
2991 unsigned int GetItemCount() const;
2994 Returns the client data associated with the item.
3000 wxUIntPtr
GetItemData(const wxDataViewItem
& item
) const;
3003 Overridden from wxDataViewModel
3005 virtual unsigned int GetColumnCount() const;
3008 Overridden from wxDataViewModel
3010 virtual wxString
GetColumnType( unsigned int col
) const;
3013 Sets the client data associated with the item.
3015 Notice that this class does @e not take ownership of the passed in
3016 pointer and will not delete it.
3022 void SetItemData(const wxDataViewItem
& item
, wxUIntPtr data
);
3025 Overridden from wxDataViewIndexListModel
3027 virtual void GetValueByRow( wxVariant
&value
,
3028 unsigned int row
, unsigned int col
) const;
3031 Overridden from wxDataViewIndexListModel
3033 virtual bool SetValueByRow( const wxVariant
&value
,
3034 unsigned int row
, unsigned int col
);
3039 @class wxDataViewTreeStore
3041 wxDataViewTreeStore is a specialised wxDataViewModel for storing simple
3042 trees very much like wxTreeCtrl does and it offers a similar API.
3044 This class actually stores the entire tree and the values (therefore its name)
3045 and implements all virtual methods from the base class so it can be used directly
3046 without having to derive any class from it, but it is mostly used from within
3052 class wxDataViewTreeStore
: public wxDataViewModel
3056 Constructor. Creates the invisible root node internally.
3058 wxDataViewTreeStore();
3063 virtual ~wxDataViewTreeStore();
3068 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
3069 const wxString
& text
,
3070 const wxIcon
& icon
= wxNullIcon
,
3071 const wxIcon
& expanded
= wxNullIcon
,
3072 wxClientData
* data
= NULL
);
3077 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
3078 const wxString
& text
,
3079 const wxIcon
& icon
= wxNullIcon
,
3080 wxClientData
* data
= NULL
);
3083 Delete all item in the model.
3085 void DeleteAllItems();
3088 Delete all children of the item, but not the item itself.
3090 void DeleteChildren(const wxDataViewItem
& item
);
3095 void DeleteItem(const wxDataViewItem
& item
);
3098 Return the number of children of item.
3100 int GetChildCount(const wxDataViewItem
& parent
) const;
3103 Returns the client data associated with the item.
3105 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
3108 Returns the icon to display in expanded containers.
3110 const wxIcon
& GetItemExpandedIcon(const wxDataViewItem
& item
) const;
3113 Returns the icon of the item.
3115 const wxIcon
& GetItemIcon(const wxDataViewItem
& item
) const;
3118 Returns the text of the item.
3120 wxString
GetItemText(const wxDataViewItem
& item
) const;
3123 Returns the nth child item of item.
3125 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
3126 unsigned int pos
) const;
3129 Inserts a container after @a previous.
3131 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
3132 const wxDataViewItem
& previous
,
3133 const wxString
& text
,
3134 const wxIcon
& icon
= wxNullIcon
,
3135 const wxIcon
& expanded
= wxNullIcon
,
3136 wxClientData
* data
= NULL
);
3139 Inserts an item after @a previous.
3141 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
3142 const wxDataViewItem
& previous
,
3143 const wxString
& text
,
3144 const wxIcon
& icon
= wxNullIcon
,
3145 wxClientData
* data
= NULL
);
3148 Inserts a container before the first child item or @a parent.
3150 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
3151 const wxString
& text
,
3152 const wxIcon
& icon
= wxNullIcon
,
3153 const wxIcon
& expanded
= wxNullIcon
,
3154 wxClientData
* data
= NULL
);
3157 Inserts an item before the first child item or @a parent.
3159 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
3160 const wxString
& text
,
3161 const wxIcon
& icon
= wxNullIcon
,
3162 wxClientData
* data
= NULL
);
3165 Sets the client data associated with the item.
3167 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
3170 Sets the expanded icon for the item.
3172 void SetItemExpandedIcon(const wxDataViewItem
& item
,
3173 const wxIcon
& icon
);
3176 Sets the icon for the item.
3178 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
3183 @class wxDataViewIconText
3185 wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
3186 This class can be converted to and from a wxVariant.
3191 class wxDataViewIconText
: public wxObject
3198 wxDataViewIconText(const wxString
& text
= wxEmptyString
,
3199 const wxIcon
& icon
= wxNullIcon
);
3200 wxDataViewIconText(const wxDataViewIconText
& other
);
3206 const wxIcon
& GetIcon() const;
3211 wxString
GetText() const;
3216 void SetIcon(const wxIcon
& icon
);
3221 void SetText(const wxString
& text
);
3227 @class wxDataViewEvent
3229 This is the event class for the wxDataViewCtrl notifications.
3231 @beginEventTable{wxDataViewEvent}
3232 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
3233 Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
3234 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
3235 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
3236 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
3237 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
3238 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
3239 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
3240 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
3241 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
3242 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
3243 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
3244 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
3245 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
3246 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
3247 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
3248 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
3249 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
3250 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
3251 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
3252 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
3253 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK event.
3254 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
3255 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
3256 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
3257 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
3258 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
3259 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
3260 Currently this even is only generated when using the native OSX
3262 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
3263 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
3264 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
3265 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
3266 @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
3267 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
3268 @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
3269 Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
3273 @category{events,dvc}
3275 class wxDataViewEvent
: public wxNotifyEvent
3279 Constructor. Typically used by wxWidgets internals only.
3281 wxDataViewEvent(wxEventType commandType
= wxEVT_NULL
,
3285 Returns the position of the column in the control or -1
3286 if no column field was set by the event emitter.
3288 int GetColumn() const;
3291 Returns a pointer to the wxDataViewColumn from which
3292 the event was emitted or @NULL.
3294 wxDataViewColumn
* GetDataViewColumn() const;
3297 Returns the wxDataViewModel associated with the event.
3299 wxDataViewModel
* GetModel() const;
3302 Returns the position of a context menu event in screen coordinates.
3304 wxPoint
GetPosition() const;
3307 Returns a reference to a value.
3309 const wxVariant
& GetValue() const;
3312 Can be used to determine whether the new value is going to be accepted
3313 in wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE handler.
3315 Returns @true if editing the item was cancelled or if the user tried to
3316 enter an invalid value (refused by wxDataViewRenderer::Validate()). If
3317 this method returns @false, it means that the value in the model is
3318 about to be changed to the new one.
3320 Notice that wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event handler can
3321 call wxNotifyEvent::Veto() to prevent this from happening.
3323 Currently support for setting this field and for vetoing the change is
3324 only available in the generic version of wxDataViewCtrl, i.e. under MSW
3325 but not GTK nor OS X.
3329 bool IsEditCancelled() const;
3332 Sets the column index associated with this event.
3334 void SetColumn(int col
);
3337 For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK only.
3339 void SetDataViewColumn(wxDataViewColumn
* col
);
3342 Sets the dataview model associated with this event.
3344 void SetModel(wxDataViewModel
* model
);
3347 Sets the value associated with this event.
3349 void SetValue(const wxVariant
& value
);
3352 Set wxDataObject for data transfer within a drag operation.
3354 void SetDataObject( wxDataObject
*obj
);
3357 Gets the wxDataFormat during a drop operation.
3359 wxDataFormat
GetDataFormat() const;
3362 Gets the data size for a drop data transfer.
3364 size_t GetDataSize() const;
3367 Gets the data buffer for a drop data transfer.
3369 void *GetDataBuffer() const;
3372 Specify the kind of the drag operation to perform.
3374 This method can be used inside a wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG
3375 handler in order to configure the drag operation. Valid values are
3376 ::wxDrag_CopyOnly (default), ::wxDrag_AllowMove (allow the data to be
3377 moved) and ::wxDrag_DefaultMove.
3379 Currently it is only honoured by the generic version of wxDataViewCtrl
3380 (used e.g. under MSW) and not supported by the native GTK and OS X
3383 @see GetDropEffect()
3387 void SetDragFlags(int flags
);
3390 Returns the effect the user requested to happen to the dropped data.
3392 This function can be used inside
3393 wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE and
3394 wxEVT_COMMAND_DATAVIEW_ITEM_DROP handlers and returns whether the user
3395 is trying to copy (the return value is ::wxDragCopy) or move (if the
3396 return value is ::wxDragMove) the data.
3398 Currently this is only available when using the generic version of
3399 wxDataViewCtrl (used e.g. under MSW) and always returns ::wxDragNone in
3400 the GTK and OS X native versions.
3404 wxDragResult
GetDropEffect() const;
3407 Return the first row that will be displayed.
3409 int GetCacheFrom() const;
3412 Return the last row that will be displayed.
3414 int GetCacheTo() const;
3419 wxDataViewItem
GetItem() const;
3420 void SetItem( const wxDataViewItem
&item
);
3421 void SetEditCanceled(bool editCancelled
);
3422 void SetPosition( int x
, int y
);
3423 void SetCache(int from
, int to
);
3424 wxDataObject
*GetDataObject() const;
3425 void SetDataFormat( const wxDataFormat
&format
);
3426 void SetDataSize( size_t size
);
3427 void SetDataBuffer( void* buf
);
3428 int GetDragFlags() const;
3429 void SetDropEffect( wxDragResult effect
);