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 wxDataViewIconTextRenderer
134 @wxheader{dataview.h}
136 The wxDataViewIconTextRenderer class is used to display text with
137 a small icon next to it as it is typically done in a file manager.
138 This classes uses the wxDataViewIconText
139 helper class to store its data. wxDataViewIonText can be converted
140 to a from a wxVariant using the left shift
146 class wxDataViewIconTextRenderer
: public wxDataViewRenderer
152 wxDataViewIconTextRenderer(const wxString
& varianttype
= "wxDataViewIconText",
153 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
159 @class wxDataViewIndexListModel
160 @wxheader{dataview.h}
162 wxDataViewIndexListModel is a specialized data model which lets
163 you address an item by its position (row) rather than its
164 wxDataViewItem (which you can obtain from this class).
165 This model also provides its own
166 wxDataViewIndexListModel::Compare method
167 which sorts the model's data by the index.
169 This model is special in the it is implemented differently under OS X
170 and other platforms. Under OS X a wxDataViewItem is always persistent
171 and this is also the case for this class. Under other platforms, the
172 meaning of a wxDataViewItem is changed to reflect a row number for
173 wxDataViewIndexListModel. The consequence of this is that
174 wxDataViewIndexListModel can be used as a virtual model with an
175 almost infinate number of items on platforms other than OS X.
180 class wxDataViewIndexListModel
: public wxDataViewModel
186 wxDataViewIndexListModel(unsigned int initial_size
= 0);
191 ~wxDataViewIndexListModel();
194 Compare method that sorts the items by their index.
196 int Compare(const wxDataViewItem
& item1
,
197 const wxDataViewItem
& item2
,
198 unsigned int column
, bool ascending
);
201 Oberride this to indicate that the row has special font attributes.
202 This only affects the
203 wxDataViewTextRendererText() renderer.
204 See also wxDataViewItemAttr.
206 bool GetAttr(unsigned int row
, unsigned int col
,
207 wxDataViewItemAttr
& attr
);
210 Returns the wxDataViewItem at the given @e row.
212 wxDataViewItem
GetItem(unsigned int row
) const;
215 Returns the position of given @e item.
217 unsigned int GetRow(const wxDataViewItem
& item
) const;
220 Override this to allow getting values from the model.
222 void GetValue(wxVariant
& variant
, unsigned int row
,
223 unsigned int col
) const;
226 Call this after if the data has to be read again from
227 the model. This is useful after major changes when
228 calling the methods below (possibly thousands of times)
231 void Reset(unsigned int new_size
);
234 Call this after a row has been appended to the model.
239 Call this after a row has been changed.
241 void RowChanged(unsigned int row
);
244 Call this after a row has been deleted.
246 void RowDeleted(unsigned int row
);
249 Call this after a row has been inserted at the given position.
251 void RowInserted(unsigned int before
);
254 Call this after a row has been prepended to the model.
259 Call this after a value has been changed.
261 void RowValueChanged(unsigned int row
, unsigned int col
);
264 Call this after rows have been deleted. The array will internally
265 get copied and sorted in descending order so that the rows with
266 the highest position will be deleted first.
268 void RowsDeleted(const wxArrayInt
& rows
);
271 Called in order to set a value in the model.
273 bool SetValue(const wxVariant
& variant
, unsigned int row
,
280 @class wxDataViewModel
281 @wxheader{dataview.h}
283 wxDataViewModel is the base class for all data model to be
284 displayed by a wxDataViewCtrl.
285 All other models derive from it and must implement its
286 pure virtual functions in order to define a complete
287 data model. In detail, you need to override
288 wxDataViewModel::IsContainer,
289 wxDataViewModel::GetParent,
290 wxDataViewModel::GetChildren,
291 wxDataViewModel::GetColumnCount,
292 wxDataViewModel::GetColumnType and
293 wxDataViewModel::GetValue in order to
294 define the data model which acts as an interface between
295 your actual data and the wxDataViewCtrl. Since you will
296 usually also allow the wxDataViewCtrl to change your data
297 through its graphical interface, you will also have to override
298 wxDataViewModel::SetValue which the
299 wxDataViewCtrl will call when a change to some data has been
302 wxDataViewModel (as indeed the entire wxDataViewCtrl
303 code) is using wxVariant to store data and
304 its type in a generic way. wxVariant can be extended to contain
305 almost any data without changes to the original class.
307 The data that is presented through this data model is expected
308 to change at run-time. You need to inform the data model when
309 a change happened. Depending on what happened you need to call
310 one of the following methods:
311 wxDataViewModel::ValueChanged,
312 wxDataViewModel::ItemAdded,
313 wxDataViewModel::ItemDeleted,
314 wxDataViewModel::ItemChanged,
315 wxDataViewModel::Cleared. There are
316 plural forms for notification of addition, change
317 or removal of several item at once. See
318 wxDataViewModel::ItemsAdded,
319 wxDataViewModel::ItemsDeleted,
320 wxDataViewModel::ItemsChanged.
322 Note that wxDataViewModel does not define the position or
323 index of any item in the control because different controls
324 might display the same data differently. wxDataViewModel does
325 provide a wxDataViewModel::Compare method
326 which the wxDataViewCtrl may use to sort the data either
327 in conjunction with a column header or without (see
328 wxDataViewModel::HasDefaultCompare).
330 This class maintains a list of
331 wxDataViewModelNotifier
332 which link this class to the specific implementations on the
333 supported platforms so that e.g. calling
334 wxDataViewModel::ValueChanged
335 on this model will just call
336 wxDataViewModelNotifier::ValueChanged
337 for each notifier that has been added. You can also add
338 your own notifier in order to get informed about any changes
339 to the data in the list model.
341 Currently wxWidgets provides the following models apart
343 wxDataViewIndexListModel,
346 Note that wxDataViewModel is reference counted, derives from
347 wxObjectRefData and cannot be deleted
348 directly as it can be shared by several wxDataViewCtrls. This
349 implies that you need to decrease the reference count after
350 associating the model with a control like this:
353 wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL );
354 wxDataViewModel *musicModel = new MyMusicModel;
355 m_musicCtrl-AssociateModel( musicModel );
356 musicModel-DecRef(); // avoid memory leak !!
364 class wxDataViewModel
: public wxObjectRefData
373 Destructor. This should not be called directly. Use DecRef() instead.
378 Adds a wxDataViewModelNotifier
381 void AddNotifier(wxDataViewModelNotifier
* notifier
);
384 Called to inform the model that all data has been cleared. The
385 control will reread the data from the model again.
387 virtual bool Cleared();
390 The compare function to be used by control. The default compare function
391 sorts by container and other items separately and in ascending order.
392 Override this for a different sorting behaviour.
393 See also HasDefaultCompare().
395 virtual int Compare(const wxDataViewItem
& item1
,
396 const wxDataViewItem
& item2
,
401 Oberride this to indicate that the item has special font attributes.
402 This only affects the
403 wxDataViewTextRendererText() renderer.
404 See also wxDataViewItemAttr.
406 bool GetAttr(const wxDataViewItem
& item
, unsigned int col
,
407 wxDataViewItemAttr
& attr
);
410 Override this so the control can query the child items of
411 an item. Returns the number of items.
413 virtual unsigned int GetChildren(const wxDataViewItem
& item
,
414 wxDataViewItemArray
& children
) const;
417 Override this to indicate the number of columns in the model.
419 virtual unsigned int GetColumnCount() const;
422 Override this to indicate what type of data is stored in the
423 column specified by @e col. This should return a string
424 indicating the type of data as reported by wxVariant.
426 virtual wxString
GetColumnType(unsigned int col
) const;
429 Override this to indicate which wxDataViewItem representing the parent
430 of @a item or an invalid wxDataViewItem if the the root item is
433 virtual wxDataViewItem
GetParent(const wxDataViewItem
& item
) const;
436 Override this to indicate the value of @e item
437 A wxVariant is used to store the data.
439 virtual void GetValue(wxVariant
& variant
,
440 const wxDataViewItem
& item
,
441 unsigned int col
) const;
444 Override this method to indicate if a container item merely
445 acts as a headline (or for categorisation) or if it also
446 acts a normal item with entries for futher columns. By
447 default returns @e @false.
449 virtual bool HasContainerColumns(const wxDataViewItem
& item
) const;
452 Override this to indicate that the model provides a default compare
453 function that the control should use if no wxDataViewColumn has been
454 chosen for sorting. Usually, the user clicks on a column header for
455 sorting, the data will be sorted alphanumerically. If any other
456 order (e.g. by index or order of appearance) is required, then this
457 should be used. See also wxDataViewIndexListModel
458 for a model which makes use of this.
460 virtual bool HasDefaultCompare() const;
463 Override this to indicate of @a item is a container, i.e. if
464 it can have child items.
466 virtual bool IsContainer(const wxDataViewItem
& item
) const;
469 Call this to inform the model that an item has been added
472 virtual bool ItemAdded(const wxDataViewItem
& parent
,
473 const wxDataViewItem
& item
);
476 Call this to inform the model that an item has changed.
477 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
478 event (in which the column fields will not be set) to the user.
480 virtual bool ItemChanged(const wxDataViewItem
& item
);
483 Call this to inform the model that an item has been deleted from the data.
485 virtual bool ItemDeleted(const wxDataViewItem
& parent
,
486 const wxDataViewItem
& item
);
489 Call this to inform the model that several items have been added
492 virtual bool ItemsAdded(const wxDataViewItem
& parent
,
493 const wxDataViewItemArray
& items
);
496 Call this to inform the model that several items have changed.
497 This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
498 events (in which the column fields will not be set) to the user.
500 virtual bool ItemsChanged(const wxDataViewItemArray
& items
);
503 Call this to inform the model that several items have been deleted.
505 virtual bool ItemsDeleted(const wxDataViewItem
& parent
,
506 const wxDataViewItemArray
& items
);
509 Remove the @a notifier from the list of notifiers.
511 void RemoveNotifier(wxDataViewModelNotifier
* notifier
);
514 Call this to initiate a resort after the sort function has
517 virtual void Resort();
520 This gets called in order to set a value in the data model.
521 The most common scenario is that the wxDataViewCtrl calls
522 this method after the user changed some data in the view.
523 Afterwards ValueChanged()
526 virtual bool SetValue(const wxVariant
& variant
,
527 const wxDataViewItem
& item
,
531 Call this to inform this model that a value in the model has
532 been changed. This is also called from wxDataViewCtrl's
533 internal editing code, e.g. when editing a text field
535 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
538 virtual bool ValueChanged(const wxDataViewItem
& item
,
546 @class wxDataViewItemAttr
547 @wxheader{dataview.h}
549 This class is used to indicate to a wxDataViewCtrl
550 that a certain Item() has extra font attributes
551 for its renderer. For this, it is required to override
552 wxDataViewModel::GetAttr.
554 Attributes are currently only supported by
555 wxDataViewTextRendererText().
560 class wxDataViewItemAttr
566 wxDataViewItemAttr();
569 Call this to indicate that the item shall be displayed in bold text.
571 void SetBold(bool set
);
574 Call this to indicate that the item shall be displayed with
577 void SetColour(const wxColour
& colour
);
580 Call this to indicate that the item shall be displayed in italic text.
582 void SetItalic(bool set
);
588 @class wxDataViewItem
589 @wxheader{dataview.h}
591 wxDataViewItem is a small opaque class that represents an
592 item in a wxDataViewCtrl in a
593 persistent way, i.e. indepent of the position of the
594 item in the control or changes to its contents. It must
595 hold a unique ID of type @e void* in its only field
596 and can be converted to a from it.
598 If the ID is @e @NULL the wxDataViewItem is invalid and
599 wxDataViewItem::IsOk will return @e @false
600 which used in many places in the API of wxDataViewCtrl
601 to indicate that e.g. no item was found. An ID of @NULL
602 is also used to indicate the invisible root. Examples
604 wxDataViewModel::GetParent and
605 wxDataViewModel::GetChildren.
617 wxDataViewItem(void* id
= NULL
);
618 wxDataViewItem(const wxDataViewItem
& item
);
627 Returns @true if the ID is not @e @NULL.
635 @class wxDataViewCtrl
636 @wxheader{dataview.h}
638 wxDataViewCtrl is a control to display data either
639 in a tree like fashion or in a tabular form or both.
640 If you only need to display a simple tree structure
641 with an API more like the older wxTreeCtrl class,
642 then the specialized wxDataViewTreeCtrl
645 A wxDataViewItem is used
646 to represent a (visible) item in the control.
648 Unlike wxListCtrl wxDataViewCtrl doesn't
649 get its data from the user through virtual functions or by
650 setting it directly. Instead you need to write your own
651 wxDataViewModel and associate
652 it with this control. Then you need to add a number of
653 wxDataViewColumn to this control to
654 define what each column shall display. Each wxDataViewColumn
655 in turn owns 1 instance of a
656 wxDataViewRenderer to render its
657 cells. A number of standard renderers for rendering text, dates,
658 images, toggle, a progress bar etc. are provided. Additionally,
659 the user can write custom renderes deriving from
660 wxDataViewCustomRenderer
661 for displaying anything.
663 All data transfer from the control to the model and the user
664 code is done through wxVariant which can
665 be extended to support more data formats as necessary.
666 Accordingly, all type information uses the strings returned
667 from wxVariant::GetType.
671 Single selection mode. This is the default.
672 @style{wxDV_MULTIPLE}
673 Multiple selection mode.
674 @style{wxDV_ROW_LINES}
675 Use alternating colours for rows if supported by platform and theme.
676 @style{wxDV_HORIZ_RULES}
677 Display fine rules between row if supported.
678 @style{wxDV_VERT_RULES}
679 Display fine rules between columns is supported.
684 @appearance{dataviewctrl.png}
686 class wxDataViewCtrl
: public wxControl
691 Constructor. Calls Create().
694 wxDataViewCtrl(wxWindow
* parent
, wxWindowID id
,
695 const wxPoint
& pos
= wxDefaultPosition
,
696 const wxSize
& size
= wxDefaultSize
,
698 const wxValidator
& validator
= wxDefaultValidator
);
708 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
709 created in the function or @NULL on failure.
711 wxDataViewColumn
* AppendBitmapColumn(const wxString
& label
,
712 unsigned int model_column
,
713 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
715 wxAlignment align
= wxALIGN_CENTER
,
716 int flags
= wxDATAVIEW_COL_RESIZABLE
);
717 wxDataViewColumn
* AppendBitmapColumn(const wxBitmap
& label
,
718 unsigned int model_column
,
719 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
721 wxAlignment align
= wxALIGN_CENTER
,
722 int flags
= wxDATAVIEW_COL_RESIZABLE
);
726 Add a wxDataViewColumn to the control. Returns
728 Note that there is a number of short cut methods which implicitly create
729 a wxDataViewColumn and a
730 wxDataViewRenderer for it (see below).
732 virtual bool AppendColumn(wxDataViewColumn
* col
);
736 Appends a column for rendering a date. Returns the wxDataViewColumn
737 created in the function or @NULL on failure.
739 wxDataViewColumn
* AppendDateColumn(const wxString
& label
,
740 unsigned int model_column
,
741 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
743 wxAlignment align
= wxALIGN_CENTER
,
744 int flags
= wxDATAVIEW_COL_RESIZABLE
);
745 wxDataViewColumn
* AppendDateColumn(const wxBitmap
& label
,
746 unsigned int model_column
,
747 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
749 wxAlignment align
= wxALIGN_CENTER
,
750 int flags
= wxDATAVIEW_COL_RESIZABLE
);
755 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
756 created in the function or @NULL on failure. This uses the
757 wxDataViewIconTextRenderer.
759 wxDataViewColumn
* AppendIconTextColumn(const wxString
& label
,
760 unsigned int model_column
,
761 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
763 wxAlignment align
= wxALIGN_LEFT
,
764 int flags
= wxDATAVIEW_COL_RESIZABLE
);
765 wxDataViewColumn
* AppendIconTextColumn(const wxBitmap
& label
,
766 unsigned int model_column
,
767 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
769 wxAlignment align
= wxALIGN_LEFT
,
770 int flags
= wxDATAVIEW_COL_RESIZABLE
);
775 Appends a column for rendering a progress indicator. Returns the
777 created in the function or @NULL on failure.
779 wxDataViewColumn
* AppendProgressColumn(const wxString
& label
,
780 unsigned int model_column
,
781 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
783 wxAlignment align
= wxALIGN_CENTER
,
784 int flags
= wxDATAVIEW_COL_RESIZABLE
);
785 wxDataViewColumn
* AppendProgressColumn(const wxBitmap
& label
,
786 unsigned int model_column
,
787 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
789 wxAlignment align
= wxALIGN_CENTER
,
790 int flags
= wxDATAVIEW_COL_RESIZABLE
);
795 Appends a column for rendering text. Returns the wxDataViewColumn
796 created in the function or @NULL on failure.
798 wxDataViewColumn
* AppendTextColumn(const wxString
& label
,
799 unsigned int model_column
,
800 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
802 wxAlignment align
= wxALIGN_LEFT
,
803 int flags
= wxDATAVIEW_COL_RESIZABLE
);
804 wxDataViewColumn
* AppendTextColumn(const wxBitmap
& label
,
805 unsigned int model_column
,
806 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
808 wxAlignment align
= wxALIGN_LEFT
,
809 int flags
= wxDATAVIEW_COL_RESIZABLE
);
814 Appends a column for rendering a toggle. Returns the wxDataViewColumn
815 created in the function or @NULL on failure.
817 wxDataViewColumn
* AppendToggleColumn(const wxString
& label
,
818 unsigned int model_column
,
819 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
821 wxAlignment align
= wxALIGN_CENTER
,
822 int flags
= wxDATAVIEW_COL_RESIZABLE
);
823 wxDataViewColumn
* AppendToggleColumn(const wxBitmap
& label
,
824 unsigned int model_column
,
825 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
827 wxAlignment align
= wxALIGN_CENTER
,
828 int flags
= wxDATAVIEW_COL_RESIZABLE
);
832 Associates a wxDataViewModel with the
833 control. This increases the reference count of the model by 1.
835 virtual bool AssociateModel(wxDataViewModel
* model
);
840 virtual bool ClearColumns();
845 void ClearSelection();
850 void Collapse(const wxDataViewItem
& item
);
853 Create the control. Useful for two step creation.
855 bool Create(wxWindow
* parent
, wxWindowID id
,
856 const wxPoint
& pos
= wxDefaultPosition
,
857 const wxSize
& size
= wxDefaultSize
,
859 const wxValidator
& validator
= wxDefaultValidator
);
862 Deletes given column.
864 virtual bool DeleteColumn(const wxDataViewColumn
* column
);
867 Call this to ensure that the given item is visible.
869 void EnsureVisible(const wxDataViewItem
& item
,
870 const wxDataViewColumn
* column
= NULL
);
875 void Expand(const wxDataViewItem
& item
);
878 Returns pointer to the column. @a pos refers to the
879 position in the control which may change after reordering
882 virtual wxDataViewColumn
* GetColumn(unsigned int pos
) const;
885 Returns the number of columns.
887 virtual unsigned int GetColumnCount() const;
890 Returns the position of the column or -1 if not found in the control.
892 virtual int GetColumnPosition(const wxDataViewColumn
* column
) const;
895 Returns column containing the expanders.
897 wxDataViewColumn
* GetExpanderColumn() const;
902 int GetIndent() const;
907 wxRect
GetItemRect(const wxDataViewItem
& item
,
908 const wxDataViewColumn
* col
= NULL
) const;
911 Returns pointer to the data model associated with the
914 virtual wxDataViewModel
* GetModel() const;
917 Returns first selected item or an invalid item if none is selected.
919 wxDataViewItem
GetSelection() const;
922 Fills @a sel with currently selected items and returns
925 int GetSelections(wxDataViewItemArray
& sel
) const;
928 Returns the wxDataViewColumn currently responsible for sorting
929 or @NULL if none has been selected.
931 virtual wxDataViewColumn
* GetSortingColumn() const;
936 void HitTest(const wxPoint
& point
, wxDataViewItem
& item
,
937 wxDataViewColumn
*& col
) const;
940 Return @true if the item is selected.
942 bool IsSelected(const wxDataViewItem
& item
) const;
945 Select the given item.
947 void Select(const wxDataViewItem
& item
);
955 Set which column shall contain the tree-like expanders.
957 void SetExpanderColumn(wxDataViewColumn
* col
);
960 Sets the indendation.
962 void SetIndent(int indent
);
965 Sets the selection to the array of wxDataViewItems.
967 void SetSelections(const wxDataViewItemArray
& sel
);
970 Unselect the given item.
972 void Unselect(const wxDataViewItem
& item
);
975 Unselect all item. This method only has effect if multiple
976 selections are allowed.
984 @class wxDataViewModelNotifier
985 @wxheader{dataview.h}
987 A wxDataViewModelNotifier instance is owned by a
989 and mirrors its notification interface. See
990 the documentation of that class for further
996 class wxDataViewModelNotifier
1002 wxDataViewModelNotifier();
1007 ~wxDataViewModelNotifier();
1010 Called by owning model.
1015 Get owning wxDataViewModel.
1017 wxDataViewModel
* GetOwner();
1020 Called by owning model.
1022 bool ItemAdded(const wxDataViewItem
& parent
,
1023 const wxDataViewItem
& item
);
1026 Called by owning model.
1028 bool ItemChanged(const wxDataViewItem
& item
);
1031 Called by owning model.
1033 bool ItemDeleted(const wxDataViewItem
& parent
,
1034 const wxDataViewItem
& item
);
1037 Called by owning model.
1039 bool ItemsAdded(const wxDataViewItem
& parent
,
1040 const wxDataViewItemArray
& items
);
1043 Called by owning model.
1045 bool ItemsChanged(const wxDataViewItemArray
& items
);
1048 Called by owning model.
1050 bool ItemsDeleted(const wxDataViewItem
& parent
,
1051 const wxDataViewItemArray
& items
);
1054 Called by owning model.
1059 Set owner of this notifier. Used internally.
1061 void SetOwner(wxDataViewModel
* owner
);
1064 Called by owning model.
1066 bool ValueChanged(const wxDataViewItem
& item
, unsigned int col
);
1072 @class wxDataViewRenderer
1073 @wxheader{dataview.h}
1075 This class is used by wxDataViewCtrl to render the individual cells.
1076 One instance of a renderer class is owned by a wxDataViewColumn. There
1077 is a number of ready-to-use renderers provided:
1078 wxDataViewTextRenderer,
1079 wxDataViewTextRendererAttr,
1080 wxDataViewIconTextRenderer,
1081 wxDataViewToggleRenderer,
1082 wxDataViewProgressRenderer,
1083 wxDataViewBitmapRenderer,
1084 wxDataViewDateRenderer.
1085 wxDataViewSpinRenderer.
1087 Note that the @e alignment parameter is ignored under OS X and
1088 the alignment is controlled by wxDataViewColumn::GetAlignment()
1089 so that under OS X, column header alignment and column content
1090 alignment are always the same and cannot be set independently.
1092 Additionally, the user can write own renderers by deriving from
1093 wxDataViewCustomRenderer.
1095 The @e wxDataViewCellMode flag controls, what actions
1096 the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE
1097 indicates that the user can double click the cell and
1098 something will happen (e.g. a window for editing a date
1099 will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates
1100 that the user can edit the data in-place, i.e. an control
1101 will show up after a slow click on the cell. This behaviour
1102 is best known from changing the filename in most file
1107 enum wxDataViewCellMode
1109 wxDATAVIEW_CELL_INERT,
1110 wxDATAVIEW_CELL_ACTIVATABLE,
1111 wxDATAVIEW_CELL_EDITABLE
1115 The @e wxDataViewCellRenderState flag controls how the
1116 the renderer should display its contents in a cell:
1119 enum wxDataViewCellRenderState
1121 wxDATAVIEW_CELL_SELECTED = 1,
1122 wxDATAVIEW_CELL_PRELIT = 2,
1123 wxDATAVIEW_CELL_INSENSITIVE = 4,
1124 wxDATAVIEW_CELL_FOCUSED = 8
1132 class wxDataViewRenderer
: public wxObject
1138 wxDataViewRenderer(const wxString
& varianttype
,
1139 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1140 int align
= wxALIGN_LEFT
|wxALIGN_CENTRE_VERTICAL
);
1143 Returns the alignment.
1145 virtual int GetAlignment() const;
1148 Returns the cell mode.
1150 virtual wxDataViewCellMode
GetMode();
1153 Returns pointer to the owning wxDataViewColumn.
1155 virtual wxDataViewColumn
* GetOwner();
1158 This methods retrieves the value from the renderer in order to
1159 transfer the value back to the data model. Returns @e @false
1162 virtual bool GetValue(wxVariant
& value
);
1165 Returns a string with the type of the wxVariant
1166 supported by this renderer.
1168 virtual wxString
GetVariantType();
1173 virtual void SetAlignment( int align
);
1175 Sets the owning wxDataViewColumn. This
1176 is usually called from within wxDataViewColumn.
1178 virtual void SetOwner(wxDataViewColumn
* owner
);
1181 Set the value of the renderer (and thus its cell) to @e value.
1182 The internal code will then render this cell with this data.
1184 virtual bool SetValue(const wxVariant
& value
);
1187 Before data is committed to the data model, it is passed to this
1188 method where it can be checked for validity. This can also be
1189 used for checking a valid range or limiting the user input in
1190 a certain aspect (e.g. max number of characters or only alphanumeric
1191 input, ASCII only etc.). Return @e @false if the value is
1193 Please note that due to implementation limitations, this validation
1194 is done after the editing control already is destroyed and the
1195 editing process finished.
1197 virtual bool Validate(wxVariant
& value
);
1203 @class wxDataViewTextRenderer
1204 @wxheader{dataview.h}
1206 wxDataViewTextRenderer is used for rendering text. It supports
1207 in-place editing if desired.
1212 class wxDataViewTextRenderer
: public wxDataViewRenderer
1218 wxDataViewTextRenderer(const wxString
& varianttype
= "string",
1219 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1220 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1226 @class wxDataViewProgressRenderer
1227 @wxheader{dataview.h}
1229 wxDataViewProgressRenderer
1234 class wxDataViewProgressRenderer
: public wxDataViewRenderer
1240 wxDataViewProgressRenderer(const wxString
& label
= wxEmptyString
,
1241 const wxString
& varianttype
= "long",
1242 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1243 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1249 @class wxDataViewSpinRenderer
1250 @wxheader{dataview.h}
1252 This is a specialized renderer for rendering integer values. It
1253 supports modifying the values in-place by using a wxSpinCtrl.
1254 The renderer only support variants of type @e long.
1259 class wxDataViewSpinRenderer
: public wxDataViewCustomRenderer
1263 Constructor. @a min and @a max indicate the minimum und
1264 maximum values of for the wxSpinCtrl.
1266 wxDataViewSpinRenderer(int min
, int max
,
1267 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1268 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1274 @class wxDataViewToggleRenderer
1275 @wxheader{dataview.h}
1277 wxDataViewToggleRenderer
1282 class wxDataViewToggleRenderer
: public wxDataViewRenderer
1288 wxDataViewToggleRenderer(const wxString
& varianttype
= "bool",
1289 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
1295 @class wxDataViewDateRenderer
1296 @wxheader{dataview.h}
1298 wxDataViewDateRenderer
1303 class wxDataViewDateRenderer
: public wxDataViewRenderer
1309 wxDataViewDateRenderer(const wxString
& varianttype
= "datetime",
1310 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
);
1316 @class wxDataViewTextRendererAttr
1317 @wxheader{dataview.h}
1319 The same as wxDataViewTextRenderer but with
1320 support for font attributes. Font attributes are currently only supported
1323 See also wxDataViewModel::GetAttr and
1329 class wxDataViewTextRendererAttr
: public wxDataViewTextRenderer
1335 wxDataViewTextRendererAttr(const wxString
& varianttype
= "string",
1336 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1337 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1342 @class wxDataViewCustomRenderer
1343 @wxheader{dataview.h}
1345 You need to derive a new class from wxDataViewCustomRenderer in
1346 order to write a new renderer. You need to override at least
1347 wxDataViewRenderer::SetValue,
1348 wxDataViewRenderer::GetValue,
1349 wxDataViewCustomRenderer::GetSize
1350 and wxDataViewCustomRenderer::Render.
1352 If you want your renderer to support in-place editing then you
1353 also need to override
1354 wxDataViewCustomRenderer::HasEditorCtrl,
1355 wxDataViewCustomRenderer::CreateEditorCtrl
1356 and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1357 Note that a special event handler will be pushed onto that
1358 editor control which handles ENTER and focus out events
1359 in order to end the editing.
1364 class wxDataViewCustomRenderer
: public wxDataViewRenderer
1370 wxDataViewCustomRenderer(const wxString
& varianttype
= "string",
1371 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1372 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1377 ~wxDataViewCustomRenderer();
1380 Override this to react to double clicks or ENTER. This method will
1381 only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1383 virtual bool Activate( wxRect cell
,
1384 wxDataViewModel
* model
,
1385 const wxDataViewItem
& item
,
1389 Override this to create the actual editor control once editing
1390 is about to start. @a parent is the parent of the editor
1391 control, @a labelRect indicates the position and
1392 size of the editor control and @a value is its initial value:
1394 virtual wxControl
* CreateEditorCtrl(wxWindow
* parent
,
1396 const wxVariant
& value
);
1399 Create DC on request. Internal.
1401 virtual wxDC
* GetDC();
1404 Return size required to show content.
1406 virtual wxSize
GetSize();
1409 Overrride this so that the renderer can get the value
1410 from the editor control (pointed to by @e editor):
1412 virtual bool GetValueFromEditorCtrl(wxControl
* editor
,
1416 Override this and make it return @e @true in order to
1417 indicate that this renderer supports in-place editing.
1419 virtual bool HasEditorCtrl();
1422 Overrride this to react to a left click. This method will
1423 only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1425 virtual bool LeftClick( wxPoint cursor
,
1427 wxDataViewModel
* model
,
1428 const wxDataViewItem
& item
,
1432 Override this to render the cell. Before this is called,
1433 wxDataViewRenderer::SetValue was called
1434 so that this instance knows what to render.
1436 virtual bool Render(wxRect cell
, wxDC
* dc
, int state
);
1439 This method should be called from within Render()
1440 whenever you need to render simple text. This will ensure that the
1441 correct colour, font and vertical alignment will be chosen so the
1442 text will look the same as text drawn by native renderers.
1444 bool RenderText(const wxString
& text
, int xoffset
, wxRect cell
,
1445 wxDC
* dc
, int state
);
1448 Overrride this to start a drag operation. Not yet
1451 virtual bool StartDrag(wxPoint cursor
, wxRect cell
,
1452 wxDataViewModel
* model
,
1453 const wxDataViewItem
& item
,
1460 @class wxDataViewBitmapRenderer
1461 @wxheader{dataview.h}
1463 wxDataViewBitmapRenderer
1468 class wxDataViewBitmapRenderer
: public wxDataViewRenderer
1474 wxDataViewBitmapRenderer(const wxString
& varianttype
= "wxBitmap",
1475 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1476 int align
= wxDVR_DEFAULT_ALIGNMENT
,
1483 @class wxDataViewColumn
1484 @wxheader{dataview.h}
1486 This class represents a column in a wxDataViewCtrl.
1487 One wxDataViewColumn is bound to one column in the data model,
1488 to which the wxDataViewCtrl has been associated.
1490 An instance of wxDataViewRenderer is used by
1491 this class to render its data.
1496 class wxDataViewColumn
: public wxObject
1503 wxDataViewColumn(const wxString
& title
,
1504 wxDataViewRenderer
* renderer
,
1505 unsigned int model_column
,
1506 int width
= wxDVC_DEFAULT_WIDTH
,
1507 wxAlignment align
= wxALIGN_CENTRE
,
1508 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1509 wxDataViewColumn(const wxBitmap
& bitmap
,
1510 wxDataViewRenderer
* renderer
,
1511 unsigned int model_column
,
1512 int width
= wxDVC_DEFAULT_WIDTH
,
1513 wxAlignment align
= wxALIGN_CENTRE
,
1514 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1520 ~wxDataViewColumn();
1523 Returns the bitmap in the header of the column, if any.
1525 const wxBitmap
GetBitmap();
1528 Returns the index of the column of the model, which this
1529 wxDataViewColumn is displaying.
1531 unsigned int GetModelColumn();
1534 Returns the owning wxDataViewCtrl.
1536 wxDataViewCtrl
* GetOwner();
1539 Returns the renderer of this wxDataViewColumn.
1540 See also wxDataViewRenderer.
1542 wxDataViewRenderer
* GetRenderer();
1545 Returns @true if the column is reorderable.
1547 bool GetReorderable();
1550 Returns @true if the column is sortable.
1556 Returns the width of the column.
1561 Returns @true, if the sort order is ascending.
1562 See also SetSortOrder()
1564 bool IsSortOrderAscending();
1567 Set the alignment of the column header.
1569 void SetAlignment(wxAlignment align
);
1572 Set the bitmap of the column header.
1574 void SetBitmap(const wxBitmap
& bitmap
);
1577 Indicate wether the column can be reordered by the
1578 user using the mouse. This is typically implemented
1579 visually by dragging the header button around.
1581 void SetReorderable(bool reorderable
);
1584 Indicate the sort order if the implementation of the
1585 wxDataViewCtrl supports it, most commonly by showing
1588 void SetSortOrder(bool ascending
);
1591 Indicate that the column is sortable. This does
1592 not show any sorting indicate yet, but it does
1593 make the column header clickable. Call
1595 afterwards to actually make the sort indicator appear.
1596 If @a sortable is @false, the column header is
1597 no longer clickable and the sort indicator (little
1598 arrow) will disappear.
1600 void SetSortable(bool sortable
);
1603 Set the title of the column header to @e title.
1605 void SetTitle(const wxString
& title
);
1611 @class wxDataViewTreeCtrl
1612 @wxheader{dataview.h}
1614 This class is a wxDataViewCtrl which internally
1615 uses a wxDataViewTreeStore and forwards
1616 most of its API to that class. Additionally, it uses a wxImageList
1617 to store a list of icons. The main purpose of this class is to look
1618 like a wxTreeCtrl to make a transition from it
1619 to the wxDataViewCtrl class simpler.
1623 @appearance{dataviewtreectrl.png}
1625 class wxDataViewTreeCtrl
: public wxDataViewCtrl
1630 Constructor. Calls Create().
1632 wxDataViewTreeCtrl();
1633 wxDataViewTreeCtrl(wxWindow
* parent
, wxWindowID id
,
1634 const wxPoint
& pos
= wxDefaultPosition
,
1635 const wxSize
& size
= wxDefaultSize
,
1636 long style
= wxDV_NO_HEADER
,
1637 const wxValidator
& validator
= wxDefaultValidator
);
1641 Destructor. Deletes the image list if any.
1643 ~wxDataViewTreeCtrl();
1648 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1649 const wxString
& text
,
1652 wxClientData
* data
= NULL
);
1657 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1658 const wxString
& text
,
1660 wxClientData
* data
= NULL
);
1663 Creates the control and a wxDataViewTreeStore as
1666 bool Create(wxWindow
* parent
, wxWindowID id
,
1667 const wxPoint
& pos
= wxDefaultPosition
,
1668 const wxSize
& size
= wxDefaultSize
,
1669 long style
= wxDV_NO_HEADER
,
1670 const wxValidator
& validator
= wxDefaultValidator
);
1673 Calls the identical method from wxDataViewTreeStore.
1675 void DeleteAllItems();
1678 Calls the identical method from wxDataViewTreeStore.
1680 void DeleteChildren(const wxDataViewItem
& item
);
1683 Calls the identical method from wxDataViewTreeStore.
1685 void DeleteItem(const wxDataViewItem
& item
);
1688 Calls the identical method from wxDataViewTreeStore.
1690 int GetChildCount(const wxDataViewItem
& parent
) const;
1693 Returns the image list.
1695 wxImageList
* GetImageList();
1698 Calls the identical method from wxDataViewTreeStore.
1700 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1703 Calls the identical method from wxDataViewTreeStore.
1705 const wxIcon
GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1708 Calls the identical method from wxDataViewTreeStore.
1710 const wxIcon
GetItemIcon(const wxDataViewItem
& item
) const;
1713 Calls the identical method from wxDataViewTreeStore.
1715 wxString
GetItemText(const wxDataViewItem
& item
) const;
1718 Calls the identical method from wxDataViewTreeStore.
1720 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1721 unsigned int pos
) const;
1727 wxDataViewTreeStore
* GetStore() const;
1728 const wxDataViewTreeStore
* GetStore() const;
1732 Calls the same method from wxDataViewTreeStore but uess
1733 and index position in the image list instead of a wxIcon.
1735 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1736 const wxDataViewItem
& previous
,
1737 const wxString
& text
,
1740 wxClientData
* data
= NULL
);
1743 Calls the same method from wxDataViewTreeStore but uess
1744 and index position in the image list instead of a wxIcon.
1746 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1747 const wxDataViewItem
& previous
,
1748 const wxString
& text
,
1750 wxClientData
* data
= NULL
);
1753 Calls the same method from wxDataViewTreeStore but uess
1754 and index position in the image list instead of a wxIcon.
1756 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1757 const wxString
& text
,
1760 wxClientData
* data
= NULL
);
1763 Calls the same method from wxDataViewTreeStore but uess
1764 and index position in the image list instead of a wxIcon.
1766 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1767 const wxString
& text
,
1769 wxClientData
* data
= NULL
);
1772 Sets the image list.
1774 void SetImageList(wxImageList
* imagelist
);
1777 Calls the identical method from wxDataViewTreeStore.
1779 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
1782 Calls the identical method from wxDataViewTreeStore.
1784 void SetItemExpandedIcon(const wxDataViewItem
& item
,
1785 const wxIcon
& icon
);
1788 Calls the identical method from wxDataViewTreeStore.
1790 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
1793 Calls the identical method from wxDataViewTreeStore.
1795 void SetItemText(const wxDataViewItem
& item
,
1796 const wxString
& text
);
1802 @class wxDataViewTreeStore
1803 @wxheader{dataview.h}
1805 wxDataViewTreeStore is a specialised wxDataViewModel
1806 for displaying simple trees very much like wxTreeCtrl
1807 does and it offers a similar API. This class actually stores the entire
1808 tree (therefore its name) and implements all virtual methods from the base
1809 class so it can be used directly without having to derive any class from it.
1810 This comes at the price of much reduced flexibility.
1815 class wxDataViewTreeStore
: public wxDataViewModel
1819 Constructor. Creates the invisible root node internally.
1821 wxDataViewTreeStore();
1826 ~wxDataViewTreeStore();
1831 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1832 const wxString
& text
,
1833 const wxIcon
& icon
= wxNullIcon
,
1834 const wxIcon
& expanded
= wxNullIcon
,
1835 wxClientData
* data
= NULL
);
1840 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1841 const wxString
& text
,
1842 const wxIcon
& icon
= wxNullIcon
,
1843 wxClientData
* data
= NULL
);
1846 Delete all item in the model.
1848 void DeleteAllItems();
1851 Delete all children of the item, but not the item itself.
1853 void DeleteChildren(const wxDataViewItem
& item
);
1858 void DeleteItem(const wxDataViewItem
& item
);
1861 Return the number of children of item.
1863 int GetChildCount(const wxDataViewItem
& parent
) const;
1866 Returns the client data asoociated with the item.
1868 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1871 Returns the icon to display in expanded containers.
1873 const wxIcon
GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1876 Returns the icon of the item.
1878 const wxIcon
GetItemIcon(const wxDataViewItem
& item
) const;
1881 Returns the text of the item.
1883 wxString
GetItemText(const wxDataViewItem
& item
) const;
1886 Returns the nth child item of item.
1888 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1889 unsigned int pos
) const;
1892 Inserts a container after @e previous.
1894 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1895 const wxDataViewItem
& previous
,
1896 const wxString
& text
,
1897 const wxIcon
& icon
= wxNullIcon
,
1898 const wxIcon
& expanded
= wxNullIcon
,
1899 wxClientData
* data
= NULL
);
1902 Inserts an item after @e previous.
1904 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1905 const wxDataViewItem
& previous
,
1906 const wxString
& text
,
1907 const wxIcon
& icon
= wxNullIcon
,
1908 wxClientData
* data
= NULL
);
1911 Inserts a container before the first child item or @e parent.
1913 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1914 const wxString
& text
,
1915 const wxIcon
& icon
= wxNullIcon
,
1916 const wxIcon
& expanded
= wxNullIcon
,
1917 wxClientData
* data
= NULL
);
1920 Inserts an item before the first child item or @e parent.
1922 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1923 const wxString
& text
,
1924 const wxIcon
& icon
= wxNullIcon
,
1925 wxClientData
* data
= NULL
);
1928 Sets the client data associated with the item.
1930 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
1933 Sets the expanded icon for the item.
1935 void SetItemExpandedIcon(const wxDataViewItem
& item
,
1936 const wxIcon
& icon
);
1939 Sets the icon for the item.
1941 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);