1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDataViewIconText
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
10 @class wxDataViewIconText
13 wxDataViewIconText is used by
14 wxDataViewIconTextRenderer
15 for data transfer. This class can be converted to a from
21 class wxDataViewIconText
: public wxObject
28 wxDataViewIconText(const wxString
& text
= wxEmptyString
,
29 const wxIcon
& icon
= wxNullIcon
);
30 wxDataViewIconText(const wxDataViewIconText
& other
);
36 const wxIcon
GetIcon() const;
41 wxString
GetText() const;
46 void SetIcon(const wxIcon
& icon
);
51 void SetText(const wxString
& text
);
57 @class wxDataViewEvent
60 wxDataViewEvent - the event class for the wxDataViewCtrl notifications
65 class wxDataViewEvent
: public wxNotifyEvent
72 wxDataViewEvent(wxEventType commandType
= wxEVT_NULL
,
74 wxDataViewEvent(const wxDataViewEvent
& event
);
78 Used to clone the event.
80 wxEvent
* Clone() const;
83 Returns the position of the column in the control or -1
84 if no column field was set by the event emitter.
86 int GetColumn() const;
89 Returns a pointer to the wxDataViewColumn from which
90 the event was emitted or @NULL.
92 wxDataViewColumn
* GetDataViewColumn();
95 Returns the wxDataViewModel associated with the event.
97 wxDataViewModel
* GetModel() const;
100 Returns a the position of a context menu event in screen coordinates.
102 wxPoint
GetPosition() const;
105 Returns a reference to a value.
107 const wxVariant
GetValue() const;
112 void SetColumn(int col
);
115 For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
117 void SetDataViewColumn(wxDataViewColumn
* col
);
122 void SetModel(wxDataViewModel
* model
);
127 void SetValue(const wxVariant
& value
);
133 @class wxDataViewModel
134 @wxheader{dataview.h}
136 wxDataViewModel is the base class for all data model to be
137 displayed by a wxDataViewCtrl.
138 All other models derive from it and must implement its
139 pure virtual functions in order to define a complete
140 data model. In detail, you need to override
141 wxDataViewModel::IsContainer,
142 wxDataViewModel::GetParent,
143 wxDataViewModel::GetChildren,
144 wxDataViewModel::GetColumnCount,
145 wxDataViewModel::GetColumnType and
146 wxDataViewModel::GetValue in order to
147 define the data model which acts as an interface between
148 your actual data and the wxDataViewCtrl. Since you will
149 usually also allow the wxDataViewCtrl to change your data
150 through its graphical interface, you will also have to override
151 wxDataViewModel::SetValue which the
152 wxDataViewCtrl will call when a change to some data has been
155 wxDataViewModel (as indeed the entire wxDataViewCtrl
156 code) is using wxVariant to store data and
157 its type in a generic way. wxVariant can be extended to contain
158 almost any data without changes to the original class.
160 The data that is presented through this data model is expected
161 to change at run-time. You need to inform the data model when
162 a change happened. Depending on what happened you need to call
163 one of the following methods:
164 wxDataViewModel::ValueChanged,
165 wxDataViewModel::ItemAdded,
166 wxDataViewModel::ItemDeleted,
167 wxDataViewModel::ItemChanged,
168 wxDataViewModel::Cleared. There are
169 plural forms for notification of addition, change
170 or removal of several item at once. See
171 wxDataViewModel::ItemsAdded,
172 wxDataViewModel::ItemsDeleted,
173 wxDataViewModel::ItemsChanged.
175 Note that wxDataViewModel does not define the position or
176 index of any item in the control because different controls
177 might display the same data differently. wxDataViewModel does
178 provide a wxDataViewModel::Compare method
179 which the wxDataViewCtrl may use to sort the data either
180 in conjunction with a column header or without (see
181 wxDataViewModel::HasDefaultCompare).
183 This class maintains a list of
184 wxDataViewModelNotifier
185 which link this class to the specific implementations on the
186 supported platforms so that e.g. calling
187 wxDataViewModel::ValueChanged
188 on this model will just call
189 wxDataViewModelNotifier::ValueChanged
190 for each notifier that has been added. You can also add
191 your own notifier in order to get informed about any changes
192 to the data in the list model.
194 Currently wxWidgets provides the following models apart
196 wxDataViewIndexListModel,
197 wxDataViewVirtualListModel,
200 Note that wxDataViewModel is reference counted, derives from
201 wxObjectRefData and cannot be deleted
202 directly as it can be shared by several wxDataViewCtrls. This
203 implies that you need to decrease the reference count after
204 associating the model with a control like this:
207 wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL );
208 wxDataViewModel *musicModel = new MyMusicModel;
209 m_musicCtrl-AssociateModel( musicModel );
210 musicModel-DecRef(); // avoid memory leak !!
218 class wxDataViewModel
: public wxObjectRefData
227 Destructor. This should not be called directly. Use DecRef() instead.
232 Adds a wxDataViewModelNotifier
235 void AddNotifier(wxDataViewModelNotifier
* notifier
);
238 Called to inform the model that all data has been cleared. The
239 control will reread the data from the model again.
241 virtual bool Cleared();
244 The compare function to be used by control. The default compare function
245 sorts by container and other items separately and in ascending order.
246 Override this for a different sorting behaviour.
247 See also HasDefaultCompare().
249 virtual int Compare(const wxDataViewItem
& item1
,
250 const wxDataViewItem
& item2
,
255 Oberride this to indicate that the item has special font attributes.
256 This only affects the
257 wxDataViewTextRendererText() renderer.
258 See also wxDataViewItemAttr.
260 bool GetAttr(const wxDataViewItem
& item
, unsigned int col
,
261 wxDataViewItemAttr
& attr
);
264 Override this so the control can query the child items of
265 an item. Returns the number of items.
267 virtual unsigned int GetChildren(const wxDataViewItem
& item
,
268 wxDataViewItemArray
& children
) const;
271 Override this to indicate the number of columns in the model.
273 virtual unsigned int GetColumnCount() const;
276 Override this to indicate what type of data is stored in the
277 column specified by @e col. This should return a string
278 indicating the type of data as reported by wxVariant.
280 virtual wxString
GetColumnType(unsigned int col
) const;
283 Override this to indicate which wxDataViewItem representing the parent
284 of @a item or an invalid wxDataViewItem if the the root item is
287 virtual wxDataViewItem
GetParent(const wxDataViewItem
& item
) const;
290 Override this to indicate the value of @e item
291 A wxVariant is used to store the data.
293 virtual void GetValue(wxVariant
& variant
,
294 const wxDataViewItem
& item
,
295 unsigned int col
) const;
298 Override this method to indicate if a container item merely
299 acts as a headline (or for categorisation) or if it also
300 acts a normal item with entries for futher columns. By
301 default returns @e @false.
303 virtual bool HasContainerColumns(const wxDataViewItem
& item
) const;
306 Override this to indicate that the model provides a default compare
307 function that the control should use if no wxDataViewColumn has been
308 chosen for sorting. Usually, the user clicks on a column header for
309 sorting, the data will be sorted alphanumerically. If any other
310 order (e.g. by index or order of appearance) is required, then this
311 should be used. See also wxDataViewIndexListModel
312 for a model which makes use of this.
314 virtual bool HasDefaultCompare() const;
317 Override this to indicate of @a item is a container, i.e. if
318 it can have child items.
320 virtual bool IsContainer(const wxDataViewItem
& item
) const;
323 Call this to inform the model that an item has been added
326 virtual bool ItemAdded(const wxDataViewItem
& parent
,
327 const wxDataViewItem
& item
);
330 Call this to inform the model that an item has changed.
331 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
332 event (in which the column fields will not be set) to the user.
334 virtual bool ItemChanged(const wxDataViewItem
& item
);
337 Call this to inform the model that an item has been deleted from the data.
339 virtual bool ItemDeleted(const wxDataViewItem
& parent
,
340 const wxDataViewItem
& item
);
343 Call this to inform the model that several items have been added
346 virtual bool ItemsAdded(const wxDataViewItem
& parent
,
347 const wxDataViewItemArray
& items
);
350 Call this to inform the model that several items have changed.
351 This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
352 events (in which the column fields will not be set) to the user.
354 virtual bool ItemsChanged(const wxDataViewItemArray
& items
);
357 Call this to inform the model that several items have been deleted.
359 virtual bool ItemsDeleted(const wxDataViewItem
& parent
,
360 const wxDataViewItemArray
& items
);
363 Remove the @a notifier from the list of notifiers.
365 void RemoveNotifier(wxDataViewModelNotifier
* notifier
);
368 Call this to initiate a resort after the sort function has
371 virtual void Resort();
374 This gets called in order to set a value in the data model.
375 The most common scenario is that the wxDataViewCtrl calls
376 this method after the user changed some data in the view.
377 Afterwards ValueChanged()
380 virtual bool SetValue(const wxVariant
& variant
,
381 const wxDataViewItem
& item
,
385 Call this to inform this model that a value in the model has
386 been changed. This is also called from wxDataViewCtrl's
387 internal editing code, e.g. when editing a text field
389 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
392 virtual bool ValueChanged(const wxDataViewItem
& item
,
399 @class wxDataViewIndexListModel
400 @wxheader{dataview.h}
402 wxDataViewIndexListModel is a specialized data model which lets
403 you address an item by its position (row) rather than its
404 wxDataViewItem (which you can obtain from this class).
405 This model also provides its own wxDataViewIndexListModel::Compare
406 method which sorts the model's data by the index.
408 This model is not a virtual model since the control stores
409 each wxDataViewItem. Use wxDataViewVirtualListModel if you
410 need to display millions of items or have other reason to
411 use a virtual control.
416 class wxDataViewIndexListModel
: public wxDataViewModel
422 wxDataViewIndexListModel(unsigned int initial_size
= 0);
427 ~wxDataViewIndexListModel();
430 Compare method that sorts the items by their index.
432 int Compare(const wxDataViewItem
& item1
,
433 const wxDataViewItem
& item2
,
434 unsigned int column
, bool ascending
);
437 Oberride this to indicate that the row has special font attributes.
438 This only affects the
439 wxDataViewTextRendererText() renderer.
440 See also wxDataViewItemAttr.
442 bool GetAttr(unsigned int row
, unsigned int col
,
443 wxDataViewItemAttr
& attr
);
446 Returns the wxDataViewItem at the given @e row.
448 wxDataViewItem
GetItem(unsigned int row
) const;
451 Returns the position of given @e item.
453 unsigned int GetRow(const wxDataViewItem
& item
) const;
456 Override this to allow getting values from the model.
458 void GetValue(wxVariant
& variant
, unsigned int row
,
459 unsigned int col
) const;
462 Call this after if the data has to be read again from
463 the model. This is useful after major changes when
464 calling the methods below (possibly thousands of times)
467 void Reset(unsigned int new_size
);
470 Call this after a row has been appended to the model.
475 Call this after a row has been changed.
477 void RowChanged(unsigned int row
);
480 Call this after a row has been deleted.
482 void RowDeleted(unsigned int row
);
485 Call this after a row has been inserted at the given position.
487 void RowInserted(unsigned int before
);
490 Call this after a row has been prepended to the model.
495 Call this after a value has been changed.
497 void RowValueChanged(unsigned int row
, unsigned int col
);
500 Call this after rows have been deleted. The array will internally
501 get copied and sorted in descending order so that the rows with
502 the highest position will be deleted first.
504 void RowsDeleted(const wxArrayInt
& rows
);
507 Called in order to set a value in the model.
509 bool SetValue(const wxVariant
& variant
, unsigned int row
,
516 @class wxDataViewVirtualListModel
517 @wxheader{dataview.h}
519 wxDataViewVirtualListModel is a specialized data model which lets
520 you address an item by its position (row) rather than its
521 wxDataViewItem and as such offers the exact same interface as
522 wxDataViewIndexListModel. The important difference is that under
523 platforms other than OS X, using this model will result in a
524 truely virtual control able to handle millions of items as the
525 control doesn't store any item (a feature not supported by the
526 Carbon API under OS X).
528 @see wxDataViewIndexListModel for the API.
533 class wxDataViewVirtualListModel
: public wxDataViewModel
539 wxDataViewVirtualListModel(unsigned int initial_size
= 0);
545 @class wxDataViewItemAttr
546 @wxheader{dataview.h}
548 This class is used to indicate to a wxDataViewCtrl
549 that a certain Item() has extra font attributes
550 for its renderer. For this, it is required to override
551 wxDataViewModel::GetAttr.
553 Attributes are currently only supported by
554 wxDataViewTextRendererText().
559 class wxDataViewItemAttr
565 wxDataViewItemAttr();
568 Call this to indicate that the item shall be displayed in bold text.
570 void SetBold(bool set
);
573 Call this to indicate that the item shall be displayed with
576 void SetColour(const wxColour
& colour
);
579 Call this to indicate that the item shall be displayed in italic text.
581 void SetItalic(bool set
);
587 @class wxDataViewItem
588 @wxheader{dataview.h}
590 wxDataViewItem is a small opaque class that represents an
591 item in a wxDataViewCtrl in a
592 persistent way, i.e. indepent of the position of the
593 item in the control or changes to its contents. It must
594 hold a unique ID of type @e void* in its only field
595 and can be converted to a from it.
597 If the ID is @e @NULL the wxDataViewItem is invalid and
598 wxDataViewItem::IsOk will return @e @false
599 which used in many places in the API of wxDataViewCtrl
600 to indicate that e.g. no item was found. An ID of @NULL
601 is also used to indicate the invisible root. Examples
603 wxDataViewModel::GetParent and
604 wxDataViewModel::GetChildren.
616 wxDataViewItem(void* id
= NULL
);
617 wxDataViewItem(const wxDataViewItem
& item
);
626 Returns @true if the ID is not @e @NULL.
634 @class wxDataViewCtrl
635 @wxheader{dataview.h}
637 wxDataViewCtrl is a control to display data either
638 in a tree like fashion or in a tabular form or both.
639 If you only need to display a simple tree structure
640 with an API more like the older wxTreeCtrl class,
641 then the specialized wxDataViewTreeCtrl
644 A wxDataViewItem is used
645 to represent a (visible) item in the control.
647 Unlike wxListCtrl wxDataViewCtrl doesn't
648 get its data from the user through virtual functions or by
649 setting it directly. Instead you need to write your own
650 wxDataViewModel and associate
651 it with this control. Then you need to add a number of
652 wxDataViewColumn to this control to
653 define what each column shall display. Each wxDataViewColumn
654 in turn owns 1 instance of a
655 wxDataViewRenderer to render its
656 cells. A number of standard renderers for rendering text, dates,
657 images, toggle, a progress bar etc. are provided. Additionally,
658 the user can write custom renderes deriving from
659 wxDataViewCustomRenderer
660 for displaying anything.
662 All data transfer from the control to the model and the user
663 code is done through wxVariant which can
664 be extended to support more data formats as necessary.
665 Accordingly, all type information uses the strings returned
666 from wxVariant::GetType.
670 Single selection mode. This is the default.
671 @style{wxDV_MULTIPLE}
672 Multiple selection mode.
673 @style{wxDV_ROW_LINES}
674 Use alternating colours for rows if supported by platform and theme.
675 @style{wxDV_HORIZ_RULES}
676 Display fine rules between row if supported.
677 @style{wxDV_VERT_RULES}
678 Display fine rules between columns is supported.
679 @style{wxDV_VARIABLE_LINE_HEIGHT}
680 Allow variable line heights. This can be inefficient when displaying large number of items.
685 <!-- @appearance{dataviewctrl.png} -->
687 class wxDataViewCtrl
: public wxControl
692 Constructor. Calls Create().
695 wxDataViewCtrl(wxWindow
* parent
, wxWindowID id
,
696 const wxPoint
& pos
= wxDefaultPosition
,
697 const wxSize
& size
= wxDefaultSize
,
699 const wxValidator
& validator
= wxDefaultValidator
);
708 Add a wxDataViewColumn to the control. Returns
710 Note that there is a number of short cut methods which implicitly create
711 a wxDataViewColumn and a wxDataViewRenderer for it (see below).
713 virtual bool AppendColumn(wxDataViewColumn
* col
);
717 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
718 created in the function or @NULL on failure.
720 wxDataViewColumn
* AppendBitmapColumn(const wxString
& label
,
721 unsigned int model_column
,
722 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
724 wxAlignment align
= wxALIGN_CENTER
,
725 int flags
= wxDATAVIEW_COL_RESIZABLE
);
726 wxDataViewColumn
* AppendBitmapColumn(const wxBitmap
& label
,
727 unsigned int model_column
,
728 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
730 wxAlignment align
= wxALIGN_CENTER
,
731 int flags
= wxDATAVIEW_COL_RESIZABLE
);
736 Appends a column for rendering a date. Returns the wxDataViewColumn
737 created in the function or @NULL on failure.
739 NB: The @e align parameter is applied to both the column header and
742 wxDataViewColumn
* AppendDateColumn(const wxString
& label
,
743 unsigned int model_column
,
744 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
746 wxAlignment align
= wxALIGN_CENTER
,
747 int flags
= wxDATAVIEW_COL_RESIZABLE
);
748 wxDataViewColumn
* AppendDateColumn(const wxBitmap
& label
,
749 unsigned int model_column
,
750 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
752 wxAlignment align
= wxALIGN_CENTER
,
753 int flags
= wxDATAVIEW_COL_RESIZABLE
);
758 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
759 created in the function or @NULL on failure. This method uses the
760 wxDataViewIconTextRenderer class.
762 NB: The @e align parameter is applied to both the column header and
765 wxDataViewColumn
* AppendIconTextColumn(const wxString
& label
,
766 unsigned int model_column
,
767 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
769 wxAlignment align
= wxALIGN_LEFT
,
770 int flags
= wxDATAVIEW_COL_RESIZABLE
);
771 wxDataViewColumn
* AppendIconTextColumn(const wxBitmap
& label
,
772 unsigned int model_column
,
773 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
775 wxAlignment align
= wxALIGN_LEFT
,
776 int flags
= wxDATAVIEW_COL_RESIZABLE
);
781 Appends a column for rendering a progress indicator. Returns the
782 wxDataViewColumn created in the function or @NULL on failure.
784 NB: The @e align parameter is applied to both the column header and
787 wxDataViewColumn
* AppendProgressColumn(const wxString
& label
,
788 unsigned int model_column
,
789 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
791 wxAlignment align
= wxALIGN_CENTER
,
792 int flags
= wxDATAVIEW_COL_RESIZABLE
);
793 wxDataViewColumn
* AppendProgressColumn(const wxBitmap
& label
,
794 unsigned int model_column
,
795 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
797 wxAlignment align
= wxALIGN_CENTER
,
798 int flags
= wxDATAVIEW_COL_RESIZABLE
);
803 Appends a column for rendering text. Returns the wxDataViewColumn
804 created in the function or @NULL on failure.
806 NB: The @e align parameter is applied to both the column header and
809 wxDataViewColumn
* AppendTextColumn(const wxString
& label
,
810 unsigned int model_column
,
811 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
813 wxAlignment align
= wxALIGN_LEFT
,
814 int flags
= wxDATAVIEW_COL_RESIZABLE
);
815 wxDataViewColumn
* AppendTextColumn(const wxBitmap
& label
,
816 unsigned int model_column
,
817 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
819 wxAlignment align
= wxALIGN_LEFT
,
820 int flags
= wxDATAVIEW_COL_RESIZABLE
);
825 Appends a column for rendering a toggle. Returns the wxDataViewColumn
826 created in the function or @NULL on failure.
828 NB: The @e align parameter is applied to both the column header and
831 wxDataViewColumn
* AppendToggleColumn(const wxString
& label
,
832 unsigned int model_column
,
833 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
835 wxAlignment align
= wxALIGN_CENTER
,
836 int flags
= wxDATAVIEW_COL_RESIZABLE
);
837 wxDataViewColumn
* AppendToggleColumn(const wxBitmap
& label
,
838 unsigned int model_column
,
839 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
841 wxAlignment align
= wxALIGN_CENTER
,
842 int flags
= wxDATAVIEW_COL_RESIZABLE
);
846 Associates a wxDataViewModel with the control. This increases the reference
847 count of the model by 1.
849 virtual bool AssociateModel(wxDataViewModel
* model
);
854 virtual bool ClearColumns();
859 void ClearSelection();
864 void Collapse(const wxDataViewItem
& item
);
867 Create the control. Useful for two step creation.
869 bool Create(wxWindow
* parent
, wxWindowID id
,
870 const wxPoint
& pos
= wxDefaultPosition
,
871 const wxSize
& size
= wxDefaultSize
,
873 const wxValidator
& validator
= wxDefaultValidator
);
876 Deletes given column.
878 virtual bool DeleteColumn(const wxDataViewColumn
* column
);
881 Call this to ensure that the given item is visible.
883 void EnsureVisible(const wxDataViewItem
& item
,
884 const wxDataViewColumn
* column
= NULL
);
889 void Expand(const wxDataViewItem
& item
);
892 Returns pointer to the column. @a pos refers to the
893 position in the control which may change after reordering
896 virtual wxDataViewColumn
* GetColumn(unsigned int pos
) const;
899 Returns the number of columns.
901 virtual unsigned int GetColumnCount() const;
904 Returns the position of the column or -1 if not found in the control.
906 virtual int GetColumnPosition(const wxDataViewColumn
* column
) const;
909 Returns column containing the expanders.
911 wxDataViewColumn
* GetExpanderColumn() const;
916 int GetIndent() const;
921 wxRect
GetItemRect(const wxDataViewItem
& item
,
922 const wxDataViewColumn
* col
= NULL
) const;
925 Returns pointer to the data model associated with the
928 virtual wxDataViewModel
* GetModel() const;
931 Returns first selected item or an invalid item if none is selected.
933 wxDataViewItem
GetSelection() const;
936 Fills @a sel with currently selected items and returns
939 int GetSelections(wxDataViewItemArray
& sel
) const;
942 Returns the wxDataViewColumn currently responsible for sorting
943 or @NULL if none has been selected.
945 virtual wxDataViewColumn
* GetSortingColumn() const;
950 void HitTest(const wxPoint
& point
, wxDataViewItem
& item
,
951 wxDataViewColumn
*& col
) const;
954 Return @true if the item is selected.
956 bool IsSelected(const wxDataViewItem
& item
) const;
959 Select the given item.
961 void Select(const wxDataViewItem
& item
);
969 Set which column shall contain the tree-like expanders.
971 void SetExpanderColumn(wxDataViewColumn
* col
);
974 Sets the indendation.
976 void SetIndent(int indent
);
979 Sets the selection to the array of wxDataViewItems.
981 void SetSelections(const wxDataViewItemArray
& sel
);
984 Unselect the given item.
986 void Unselect(const wxDataViewItem
& item
);
989 Unselect all item. This method only has effect if multiple
990 selections are allowed.
998 @class wxDataViewModelNotifier
999 @wxheader{dataview.h}
1001 A wxDataViewModelNotifier instance is owned by a
1003 and mirrors its notification interface. See
1004 the documentation of that class for further
1010 class wxDataViewModelNotifier
1016 wxDataViewModelNotifier();
1021 ~wxDataViewModelNotifier();
1024 Called by owning model.
1029 Get owning wxDataViewModel.
1031 wxDataViewModel
* GetOwner() const;
1034 Called by owning model.
1036 bool ItemAdded(const wxDataViewItem
& parent
,
1037 const wxDataViewItem
& item
);
1040 Called by owning model.
1042 bool ItemChanged(const wxDataViewItem
& item
);
1045 Called by owning model.
1047 bool ItemDeleted(const wxDataViewItem
& parent
,
1048 const wxDataViewItem
& item
);
1051 Called by owning model.
1053 bool ItemsAdded(const wxDataViewItem
& parent
,
1054 const wxDataViewItemArray
& items
);
1057 Called by owning model.
1059 bool ItemsChanged(const wxDataViewItemArray
& items
);
1062 Called by owning model.
1064 bool ItemsDeleted(const wxDataViewItem
& parent
,
1065 const wxDataViewItemArray
& items
);
1068 Called by owning model.
1073 Set owner of this notifier. Used internally.
1075 void SetOwner(wxDataViewModel
* owner
);
1078 Called by owning model.
1080 bool ValueChanged(const wxDataViewItem
& item
, unsigned int col
);
1086 @class wxDataViewRenderer
1087 @wxheader{dataview.h}
1089 This class is used by wxDataViewCtrl to render the individual cells.
1090 One instance of a renderer class is owned by a wxDataViewColumn. There
1091 is a number of ready-to-use renderers provided:
1092 wxDataViewTextRenderer,
1093 wxDataViewTextRendererAttr,
1094 wxDataViewIconTextRenderer,
1095 wxDataViewToggleRenderer,
1096 wxDataViewProgressRenderer,
1097 wxDataViewBitmapRenderer,
1098 wxDataViewDateRenderer.
1099 wxDataViewSpinRenderer.
1101 Additionally, the user can write own renderers by deriving from
1102 wxDataViewCustomRenderer.
1104 The @e wxDataViewCellMode flag controls, what actions
1105 the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE
1106 indicates that the user can double click the cell and
1107 something will happen (e.g. a window for editing a date
1108 will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates
1109 that the user can edit the data in-place, i.e. an control
1110 will show up after a slow click on the cell. This behaviour
1111 is best known from changing the filename in most file
1116 enum wxDataViewCellMode
1118 wxDATAVIEW_CELL_INERT,
1119 wxDATAVIEW_CELL_ACTIVATABLE,
1120 wxDATAVIEW_CELL_EDITABLE
1124 The @e wxDataViewCellRenderState flag controls how the
1125 the renderer should display its contents in a cell:
1128 enum wxDataViewCellRenderState
1130 wxDATAVIEW_CELL_SELECTED = 1,
1131 wxDATAVIEW_CELL_PRELIT = 2,
1132 wxDATAVIEW_CELL_INSENSITIVE = 4,
1133 wxDATAVIEW_CELL_FOCUSED = 8
1141 class wxDataViewRenderer
: public wxObject
1147 wxDataViewRenderer(const wxString
& varianttype
,
1148 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1149 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1152 Returns the alignment. See SetAlignment()
1154 virtual int GetAlignment() const;
1157 Returns the cell mode.
1159 virtual wxDataViewCellMode
GetMode();
1162 Returns pointer to the owning wxDataViewColumn.
1164 virtual wxDataViewColumn
* GetOwner() const;
1167 This methods retrieves the value from the renderer in order to
1168 transfer the value back to the data model. Returns @e @false
1171 virtual bool GetValue(wxVariant
& value
);
1174 Returns a string with the type of the wxVariant
1175 supported by this renderer.
1177 virtual wxString
GetVariantType();
1180 Sets the alignment of the renderer's content. The default value
1181 of wxDVR_DEFAULT_ALIGMENT indicates that the content should
1182 have the same alignment as the column header. The method is
1183 not implemented under OS X and the renderer always aligns its
1184 contents as the column header on that platform. The other platforms
1185 support both vertical and horizontal alignment.
1187 virtual void SetAlignment( int align
);
1189 Sets the owning wxDataViewColumn. This
1190 is usually called from within wxDataViewColumn.
1192 virtual void SetOwner(wxDataViewColumn
* owner
);
1195 Set the value of the renderer (and thus its cell) to @e value.
1196 The internal code will then render this cell with this data.
1198 virtual bool SetValue(const wxVariant
& value
);
1201 Before data is committed to the data model, it is passed to this
1202 method where it can be checked for validity. This can also be
1203 used for checking a valid range or limiting the user input in
1204 a certain aspect (e.g. max number of characters or only alphanumeric
1205 input, ASCII only etc.). Return @e @false if the value is
1207 Please note that due to implementation limitations, this validation
1208 is done after the editing control already is destroyed and the
1209 editing process finished.
1211 virtual bool Validate(wxVariant
& value
);
1217 @class wxDataViewTextRenderer
1218 @wxheader{dataview.h}
1220 wxDataViewTextRenderer is used for rendering text. It supports
1221 in-place editing if desired.
1226 class wxDataViewTextRenderer
: public wxDataViewRenderer
1232 wxDataViewTextRenderer(const wxString
& varianttype
= "string",
1233 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1234 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1240 @class wxDataViewIconTextRenderer
1241 @wxheader{dataview.h}
1243 The wxDataViewIconTextRenderer class is used to display text with
1244 a small icon next to it as it is typically done in a file manager.
1245 This classes uses the wxDataViewIconText
1246 helper class to store its data. wxDataViewIonText can be converted
1247 to a from a wxVariant using the left shift
1253 class wxDataViewIconTextRenderer
: public wxDataViewRenderer
1259 wxDataViewIconTextRenderer(const wxString
& varianttype
= "wxDataViewIconText",
1260 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1261 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1267 @class wxDataViewProgressRenderer
1268 @wxheader{dataview.h}
1270 wxDataViewProgressRenderer
1275 class wxDataViewProgressRenderer
: public wxDataViewRenderer
1281 wxDataViewProgressRenderer(const wxString
& label
= wxEmptyString
,
1282 const wxString
& varianttype
= "long",
1283 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1284 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1290 @class wxDataViewSpinRenderer
1291 @wxheader{dataview.h}
1293 This is a specialized renderer for rendering integer values. It
1294 supports modifying the values in-place by using a wxSpinCtrl.
1295 The renderer only support variants of type @e long.
1300 class wxDataViewSpinRenderer
: public wxDataViewCustomRenderer
1304 Constructor. @a min and @a max indicate the minimum und
1305 maximum values of for the wxSpinCtrl.
1307 wxDataViewSpinRenderer(int min
, int max
,
1308 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1309 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1315 @class wxDataViewToggleRenderer
1316 @wxheader{dataview.h}
1318 wxDataViewToggleRenderer
1323 class wxDataViewToggleRenderer
: public wxDataViewRenderer
1329 wxDataViewToggleRenderer(const wxString
& varianttype
= "bool",
1330 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
1336 @class wxDataViewDateRenderer
1337 @wxheader{dataview.h}
1339 wxDataViewDateRenderer
1344 class wxDataViewDateRenderer
: public wxDataViewRenderer
1350 wxDataViewDateRenderer(const wxString
& varianttype
= "datetime",
1351 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
);
1357 @class wxDataViewTextRendererAttr
1358 @wxheader{dataview.h}
1360 The same as wxDataViewTextRenderer but with
1361 support for font attributes. Font attributes are currently only supported
1364 See also wxDataViewModel::GetAttr and
1370 class wxDataViewTextRendererAttr
: public wxDataViewTextRenderer
1376 wxDataViewTextRendererAttr(const wxString
& varianttype
= "string",
1377 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1378 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1384 @class wxDataViewCustomRenderer
1385 @wxheader{dataview.h}
1387 You need to derive a new class from wxDataViewCustomRenderer in
1388 order to write a new renderer. You need to override at least
1389 wxDataViewRenderer::SetValue,
1390 wxDataViewRenderer::GetValue,
1391 wxDataViewCustomRenderer::GetSize
1392 and wxDataViewCustomRenderer::Render.
1394 If you want your renderer to support in-place editing then you
1395 also need to override
1396 wxDataViewCustomRenderer::HasEditorCtrl,
1397 wxDataViewCustomRenderer::CreateEditorCtrl
1398 and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1399 Note that a special event handler will be pushed onto that
1400 editor control which handles ENTER and focus out events
1401 in order to end the editing.
1406 class wxDataViewCustomRenderer
: public wxDataViewRenderer
1412 wxDataViewCustomRenderer(const wxString
& varianttype
= "string",
1413 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1414 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1419 ~wxDataViewCustomRenderer();
1422 Override this to react to double clicks or ENTER. This method will
1423 only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1425 virtual bool Activate( wxRect cell
,
1426 wxDataViewModel
* model
,
1427 const wxDataViewItem
& item
,
1431 Override this to create the actual editor control once editing
1432 is about to start. @a parent is the parent of the editor
1433 control, @a labelRect indicates the position and
1434 size of the editor control and @a value is its initial value:
1436 virtual wxControl
* CreateEditorCtrl(wxWindow
* parent
,
1438 const wxVariant
& value
);
1441 Create DC on request. Internal.
1443 virtual wxDC
* GetDC();
1446 Return size required to show content.
1448 virtual wxSize
GetSize();
1451 Overrride this so that the renderer can get the value
1452 from the editor control (pointed to by @e editor):
1454 virtual bool GetValueFromEditorCtrl(wxControl
* editor
,
1458 Override this and make it return @e @true in order to
1459 indicate that this renderer supports in-place editing.
1461 virtual bool HasEditorCtrl();
1464 Overrride this to react to a left click. This method will
1465 only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1467 virtual bool LeftClick( wxPoint cursor
,
1469 wxDataViewModel
* model
,
1470 const wxDataViewItem
& item
,
1474 Override this to render the cell. Before this is called,
1475 wxDataViewRenderer::SetValue was called
1476 so that this instance knows what to render.
1478 virtual bool Render(wxRect cell
, wxDC
* dc
, int state
);
1481 This method should be called from within Render()
1482 whenever you need to render simple text. This will ensure that the
1483 correct colour, font and vertical alignment will be chosen so the
1484 text will look the same as text drawn by native renderers.
1486 bool RenderText(const wxString
& text
, int xoffset
, wxRect cell
,
1487 wxDC
* dc
, int state
);
1490 Overrride this to start a drag operation. Not yet
1493 virtual bool StartDrag(wxPoint cursor
, wxRect cell
,
1494 wxDataViewModel
* model
,
1495 const wxDataViewItem
& item
,
1502 @class wxDataViewBitmapRenderer
1503 @wxheader{dataview.h}
1505 wxDataViewBitmapRenderer
1510 class wxDataViewBitmapRenderer
: public wxDataViewRenderer
1516 wxDataViewBitmapRenderer(const wxString
& varianttype
= "wxBitmap",
1517 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1518 int align
= wxDVR_DEFAULT_ALIGNMENT
,
1524 @class wxDataViewColumn
1525 @wxheader{dataview.h}
1527 This class represents a column in a wxDataViewCtrl.
1528 One wxDataViewColumn is bound to one column in the data model,
1529 to which the wxDataViewCtrl has been associated.
1531 An instance of wxDataViewRenderer is used by
1532 this class to render its data.
1537 class wxDataViewColumn
: public wxObject
1544 wxDataViewColumn(const wxString
& title
,
1545 wxDataViewRenderer
* renderer
,
1546 unsigned int model_column
,
1547 int width
= wxDVC_DEFAULT_WIDTH
,
1548 wxAlignment align
= wxALIGN_CENTRE
,
1549 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1550 wxDataViewColumn(const wxBitmap
& bitmap
,
1551 wxDataViewRenderer
* renderer
,
1552 unsigned int model_column
,
1553 int width
= wxDVC_DEFAULT_WIDTH
,
1554 wxAlignment align
= wxALIGN_CENTRE
,
1555 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1561 ~wxDataViewColumn();
1564 Returns the bitmap in the header of the column, if any.
1566 const wxBitmap
GetBitmap();
1569 Returns the index of the column of the model, which this
1570 wxDataViewColumn is displaying.
1572 unsigned int GetModelColumn();
1575 Returns the owning wxDataViewCtrl.
1577 wxDataViewCtrl
* GetOwner() const;
1580 Returns the renderer of this wxDataViewColumn.
1581 See also wxDataViewRenderer.
1583 wxDataViewRenderer
* GetRenderer();
1586 Returns @true if the column is reorderable.
1588 bool GetReorderable();
1591 Returns @true if the column is sortable.
1597 Returns the width of the column.
1602 Returns @true, if the sort order is ascending.
1603 See also SetSortOrder()
1605 bool IsSortOrderAscending();
1608 Set the alignment of the column header.
1610 void SetAlignment(wxAlignment align
);
1613 Set the bitmap of the column header.
1615 void SetBitmap(const wxBitmap
& bitmap
);
1618 Indicate wether the column can be reordered by the
1619 user using the mouse. This is typically implemented
1620 visually by dragging the header button around.
1622 void SetReorderable(bool reorderable
);
1625 Indicate the sort order if the implementation of the
1626 wxDataViewCtrl supports it, most commonly by showing
1629 void SetSortOrder(bool ascending
);
1632 Indicate that the column is sortable. This does
1633 not show any sorting indicate yet, but it does
1634 make the column header clickable. Call
1636 afterwards to actually make the sort indicator appear.
1637 If @a sortable is @false, the column header is
1638 no longer clickable and the sort indicator (little
1639 arrow) will disappear.
1641 void SetSortable(bool sortable
);
1644 Set the title of the column header to @e title.
1646 void SetTitle(const wxString
& title
);
1652 @class wxDataViewTreeCtrl
1653 @wxheader{dataview.h}
1655 This class is a wxDataViewCtrl which internally
1656 uses a wxDataViewTreeStore and forwards
1657 most of its API to that class. Additionally, it uses a wxImageList
1658 to store a list of icons. The main purpose of this class is to look
1659 like a wxTreeCtrl to make a transition from it
1660 to the wxDataViewCtrl class simpler.
1664 <!-- @appearance{dataviewtreectrl.png} -->
1666 class wxDataViewTreeCtrl
: public wxDataViewCtrl
1671 Constructor. Calls Create().
1673 wxDataViewTreeCtrl();
1674 wxDataViewTreeCtrl(wxWindow
* parent
, wxWindowID id
,
1675 const wxPoint
& pos
= wxDefaultPosition
,
1676 const wxSize
& size
= wxDefaultSize
,
1677 long style
= wxDV_NO_HEADER
,
1678 const wxValidator
& validator
= wxDefaultValidator
);
1682 Destructor. Deletes the image list if any.
1684 ~wxDataViewTreeCtrl();
1689 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1690 const wxString
& text
,
1693 wxClientData
* data
= NULL
);
1698 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1699 const wxString
& text
,
1701 wxClientData
* data
= NULL
);
1704 Creates the control and a wxDataViewTreeStore as
1707 bool Create(wxWindow
* parent
, wxWindowID id
,
1708 const wxPoint
& pos
= wxDefaultPosition
,
1709 const wxSize
& size
= wxDefaultSize
,
1710 long style
= wxDV_NO_HEADER
,
1711 const wxValidator
& validator
= wxDefaultValidator
);
1714 Calls the identical method from wxDataViewTreeStore.
1716 void DeleteAllItems();
1719 Calls the identical method from wxDataViewTreeStore.
1721 void DeleteChildren(const wxDataViewItem
& item
);
1724 Calls the identical method from wxDataViewTreeStore.
1726 void DeleteItem(const wxDataViewItem
& item
);
1729 Calls the identical method from wxDataViewTreeStore.
1731 int GetChildCount(const wxDataViewItem
& parent
) const;
1734 Returns the image list.
1736 wxImageList
* GetImageList();
1739 Calls the identical method from wxDataViewTreeStore.
1741 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1744 Calls the identical method from wxDataViewTreeStore.
1746 const wxIcon
GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1749 Calls the identical method from wxDataViewTreeStore.
1751 const wxIcon
GetItemIcon(const wxDataViewItem
& item
) const;
1754 Calls the identical method from wxDataViewTreeStore.
1756 wxString
GetItemText(const wxDataViewItem
& item
) const;
1759 Calls the identical method from wxDataViewTreeStore.
1761 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1762 unsigned int pos
) const;
1768 wxDataViewTreeStore
* GetStore() const;
1769 const wxDataViewTreeStore
* GetStore() const;
1773 Calls the same method from wxDataViewTreeStore but uess
1774 and index position in the image list instead of a wxIcon.
1776 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1777 const wxDataViewItem
& previous
,
1778 const wxString
& text
,
1781 wxClientData
* data
= NULL
);
1784 Calls the same method from wxDataViewTreeStore but uess
1785 and index position in the image list instead of a wxIcon.
1787 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1788 const wxDataViewItem
& previous
,
1789 const wxString
& text
,
1791 wxClientData
* data
= NULL
);
1794 Calls the same method from wxDataViewTreeStore but uess
1795 and index position in the image list instead of a wxIcon.
1797 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1798 const wxString
& text
,
1801 wxClientData
* data
= NULL
);
1804 Calls the same method from wxDataViewTreeStore but uess
1805 and index position in the image list instead of a wxIcon.
1807 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1808 const wxString
& text
,
1810 wxClientData
* data
= NULL
);
1813 Sets the image list.
1815 void SetImageList(wxImageList
* imagelist
);
1818 Calls the identical method from wxDataViewTreeStore.
1820 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
1823 Calls the identical method from wxDataViewTreeStore.
1825 void SetItemExpandedIcon(const wxDataViewItem
& item
,
1826 const wxIcon
& icon
);
1829 Calls the identical method from wxDataViewTreeStore.
1831 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
1834 Calls the identical method from wxDataViewTreeStore.
1836 void SetItemText(const wxDataViewItem
& item
,
1837 const wxString
& text
);
1843 @class wxDataViewTreeStore
1844 @wxheader{dataview.h}
1846 wxDataViewTreeStore is a specialised wxDataViewModel
1847 for displaying simple trees very much like wxTreeCtrl
1848 does and it offers a similar API. This class actually stores the entire
1849 tree (therefore its name) and implements all virtual methods from the base
1850 class so it can be used directly without having to derive any class from it.
1851 This comes at the price of much reduced flexibility.
1856 class wxDataViewTreeStore
: public wxDataViewModel
1860 Constructor. Creates the invisible root node internally.
1862 wxDataViewTreeStore();
1867 ~wxDataViewTreeStore();
1872 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1873 const wxString
& text
,
1874 const wxIcon
& icon
= wxNullIcon
,
1875 const wxIcon
& expanded
= wxNullIcon
,
1876 wxClientData
* data
= NULL
);
1881 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1882 const wxString
& text
,
1883 const wxIcon
& icon
= wxNullIcon
,
1884 wxClientData
* data
= NULL
);
1887 Delete all item in the model.
1889 void DeleteAllItems();
1892 Delete all children of the item, but not the item itself.
1894 void DeleteChildren(const wxDataViewItem
& item
);
1899 void DeleteItem(const wxDataViewItem
& item
);
1902 Return the number of children of item.
1904 int GetChildCount(const wxDataViewItem
& parent
) const;
1907 Returns the client data asoociated with the item.
1909 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1912 Returns the icon to display in expanded containers.
1914 const wxIcon
GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1917 Returns the icon of the item.
1919 const wxIcon
GetItemIcon(const wxDataViewItem
& item
) const;
1922 Returns the text of the item.
1924 wxString
GetItemText(const wxDataViewItem
& item
) const;
1927 Returns the nth child item of item.
1929 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1930 unsigned int pos
) const;
1933 Inserts a container after @e previous.
1935 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1936 const wxDataViewItem
& previous
,
1937 const wxString
& text
,
1938 const wxIcon
& icon
= wxNullIcon
,
1939 const wxIcon
& expanded
= wxNullIcon
,
1940 wxClientData
* data
= NULL
);
1943 Inserts an item after @e previous.
1945 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1946 const wxDataViewItem
& previous
,
1947 const wxString
& text
,
1948 const wxIcon
& icon
= wxNullIcon
,
1949 wxClientData
* data
= NULL
);
1952 Inserts a container before the first child item or @e parent.
1954 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1955 const wxString
& text
,
1956 const wxIcon
& icon
= wxNullIcon
,
1957 const wxIcon
& expanded
= wxNullIcon
,
1958 wxClientData
* data
= NULL
);
1961 Inserts an item before the first child item or @e parent.
1963 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1964 const wxString
& text
,
1965 const wxIcon
& icon
= wxNullIcon
,
1966 wxClientData
* data
= NULL
);
1969 Sets the client data associated with the item.
1971 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
1974 Sets the expanded icon for the item.
1976 void SetItemExpandedIcon(const wxDataViewItem
& item
,
1977 const wxIcon
& icon
);
1980 Sets the icon for the item.
1982 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);