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
,
545 @class wxDataViewCustomRenderer
546 @wxheader{dataview.h}
548 You need to derive a new class from wxDataViewCustomRenderer in
549 order to write a new renderer. You need to override at least
550 wxDataViewRenderer::SetValue,
551 wxDataViewRenderer::GetValue,
552 wxDataViewCustomRenderer::GetSize
553 and wxDataViewCustomRenderer::Render.
555 If you want your renderer to support in-place editing then you
556 also need to override
557 wxDataViewCustomRenderer::HasEditorCtrl,
558 wxDataViewCustomRenderer::CreateEditorCtrl
559 and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
560 Note that a special event handler will be pushed onto that
561 editor control which handles ENTER and focus out events
562 in order to end the editing.
567 class wxDataViewCustomRenderer
: public wxDataViewRenderer
573 wxDataViewCustomRenderer(const wxString
& varianttype
= "string",
574 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
575 bool no_init
= false);
580 ~wxDataViewCustomRenderer();
583 Override this to react to double clicks or ENTER. This method will
584 only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
586 virtual bool Activate( wxRect cell
,
587 wxDataViewModel
* model
,
588 const wxDataViewItem
& item
,
592 Override this to create the actual editor control once editing
593 is about to start. @a parent is the parent of the editor
594 control, @a labelRect indicates the position and
595 size of the editor control and @a value is its initial value:
597 virtual wxControl
* CreateEditorCtrl(wxWindow
* parent
,
599 const wxVariant
& value
);
602 Create DC on request. Internal.
604 virtual wxDC
* GetDC();
607 Return size required to show content.
609 virtual wxSize
GetSize();
612 Overrride this so that the renderer can get the value
613 from the editor control (pointed to by @e editor):
615 virtual bool GetValueFromEditorCtrl(wxControl
* editor
,
619 Override this and make it return @e @true in order to
620 indicate that this renderer supports in-place editing.
622 virtual bool HasEditorCtrl();
625 Overrride this to react to a left click. This method will
626 only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
628 virtual bool LeftClick( wxPoint cursor
,
630 wxDataViewModel
* model
,
631 const wxDataViewItem
& item
,
635 Override this to render the cell. Before this is called,
636 wxDataViewRenderer::SetValue was called
637 so that this instance knows what to render.
639 virtual bool Render(wxRect cell
, wxDC
* dc
, int state
);
642 This method should be called from within Render()
643 whenever you need to render simple text. This will ensure that the
644 correct colour, font and vertical alignment will be chosen so the
645 text will look the same as text drawn by native renderers.
647 bool RenderText(const wxString
& text
, int xoffset
, wxRect cell
,
648 wxDC
* dc
, int state
);
651 Overrride this to start a drag operation. Not yet
654 virtual bool StartDrag(wxPoint cursor
, wxRect cell
,
655 wxDataViewModel
* model
,
656 const wxDataViewItem
& item
,
663 @class wxDataViewBitmapRenderer
664 @wxheader{dataview.h}
666 wxDataViewBitmapRenderer
671 class wxDataViewBitmapRenderer
: public wxDataViewRenderer
677 wxDataViewBitmapRenderer(const wxString
& varianttype
= "wxBitmap",
678 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
684 @class wxDataViewItemAttr
685 @wxheader{dataview.h}
687 This class is used to indicate to a wxDataViewCtrl
688 that a certain Item() has extra font attributes
689 for its renderer. For this, it is required to override
690 wxDataViewModel::GetAttr.
692 Attributes are currently only supported by
693 wxDataViewTextRendererText().
698 class wxDataViewItemAttr
704 wxDataViewItemAttr();
707 Call this to indicate that the item shall be displayed in bold text.
709 void SetBold(bool set
);
712 Call this to indicate that the item shall be displayed with
715 void SetColour(const wxColour
& colour
);
718 Call this to indicate that the item shall be displayed in italic text.
720 void SetItalic(bool set
);
726 @class wxDataViewItem
727 @wxheader{dataview.h}
729 wxDataViewItem is a small opaque class that represents an
730 item in a wxDataViewCtrl in a
731 persistent way, i.e. indepent of the position of the
732 item in the control or changes to its contents. It must
733 hold a unique ID of type @e void* in its only field
734 and can be converted to a from it.
736 If the ID is @e @NULL the wxDataViewItem is invalid and
737 wxDataViewItem::IsOk will return @e @false
738 which used in many places in the API of wxDataViewCtrl
739 to indicate that e.g. no item was found. An ID of @NULL
740 is also used to indicate the invisible root. Examples
742 wxDataViewModel::GetParent and
743 wxDataViewModel::GetChildren.
755 wxDataViewItem(void* id
= NULL
);
756 wxDataViewItem(const wxDataViewItem
& item
);
765 Returns @true if the ID is not @e @NULL.
773 @class wxDataViewCtrl
774 @wxheader{dataview.h}
776 wxDataViewCtrl is a control to display data either
777 in a tree like fashion or in a tabular form or both.
778 If you only need to display a simple tree structure
779 with an API more like the older wxTreeCtrl class,
780 then the specialized wxDataViewTreeCtrl
783 A wxDataViewItem is used
784 to represent a (visible) item in the control.
786 Unlike wxListCtrl wxDataViewCtrl doesn't
787 get its data from the user through virtual functions or by
788 setting it directly. Instead you need to write your own
789 wxDataViewModel and associate
790 it with this control. Then you need to add a number of
791 wxDataViewColumn to this control to
792 define what each column shall display. Each wxDataViewColumn
793 in turn owns 1 instance of a
794 wxDataViewRenderer to render its
795 cells. A number of standard renderers for rendering text, dates,
796 images, toggle, a progress bar etc. are provided. Additionally,
797 the user can write custom renderes deriving from
798 wxDataViewCustomRenderer
799 for displaying anything.
801 All data transfer from the control to the model and the user
802 code is done through wxVariant which can
803 be extended to support more data formats as necessary.
804 Accordingly, all type information uses the strings returned
805 from wxVariant::GetType.
809 Single selection mode. This is the default.
810 @style{wxDV_MULTIPLE}
811 Multiple selection mode.
812 @style{wxDV_ROW_LINES}
813 Use alternating colours for rows if supported by platform and theme.
814 @style{wxDV_HORIZ_RULES}
815 Display fine rules between row if supported.
816 @style{wxDV_VERT_RULES}
817 Display fine rules between columns is supported.
822 @appearance{dataviewctrl.png}
824 class wxDataViewCtrl
: public wxControl
829 Constructor. Calls Create().
832 wxDataViewCtrl(wxWindow
* parent
, wxWindowID id
,
833 const wxPoint
& pos
= wxDefaultPosition
,
834 const wxSize
& size
= wxDefaultSize
,
836 const wxValidator
& validator
= wxDefaultValidator
);
846 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
847 created in the function or @NULL on failure.
849 wxDataViewColumn
* AppendBitmapColumn(const wxString
& label
,
850 unsigned int model_column
,
851 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
853 wxAlignment align
= wxALIGN_CENTER
,
854 int flags
= wxDATAVIEW_COL_RESIZABLE
);
855 wxDataViewColumn
* AppendBitmapColumn(const wxBitmap
& label
,
856 unsigned int model_column
,
857 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
859 wxAlignment align
= wxALIGN_CENTER
,
860 int flags
= wxDATAVIEW_COL_RESIZABLE
);
864 Add a wxDataViewColumn to the control. Returns
866 Note that there is a number of short cut methods which implicitly create
867 a wxDataViewColumn and a
868 wxDataViewRenderer for it (see below).
870 virtual bool AppendColumn(wxDataViewColumn
* col
);
874 Appends a column for rendering a date. Returns the wxDataViewColumn
875 created in the function or @NULL on failure.
877 wxDataViewColumn
* AppendDateColumn(const wxString
& label
,
878 unsigned int model_column
,
879 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
881 wxAlignment align
= wxALIGN_CENTER
,
882 int flags
= wxDATAVIEW_COL_RESIZABLE
);
883 wxDataViewColumn
* AppendDateColumn(const wxBitmap
& label
,
884 unsigned int model_column
,
885 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
887 wxAlignment align
= wxALIGN_CENTER
,
888 int flags
= wxDATAVIEW_COL_RESIZABLE
);
893 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
894 created in the function or @NULL on failure. This uses the
895 wxDataViewIconTextRenderer.
897 wxDataViewColumn
* AppendIconTextColumn(const wxString
& label
,
898 unsigned int model_column
,
899 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
901 wxAlignment align
= wxALIGN_LEFT
,
902 int flags
= wxDATAVIEW_COL_RESIZABLE
);
903 wxDataViewColumn
* AppendIconTextColumn(const wxBitmap
& label
,
904 unsigned int model_column
,
905 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
907 wxAlignment align
= wxALIGN_LEFT
,
908 int flags
= wxDATAVIEW_COL_RESIZABLE
);
913 Appends a column for rendering a progress indicator. Returns the
915 created in the function or @NULL on failure.
917 wxDataViewColumn
* AppendProgressColumn(const wxString
& label
,
918 unsigned int model_column
,
919 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
921 wxAlignment align
= wxALIGN_CENTER
,
922 int flags
= wxDATAVIEW_COL_RESIZABLE
);
923 wxDataViewColumn
* AppendProgressColumn(const wxBitmap
& label
,
924 unsigned int model_column
,
925 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
927 wxAlignment align
= wxALIGN_CENTER
,
928 int flags
= wxDATAVIEW_COL_RESIZABLE
);
933 Appends a column for rendering text. Returns the wxDataViewColumn
934 created in the function or @NULL on failure.
936 wxDataViewColumn
* AppendTextColumn(const wxString
& label
,
937 unsigned int model_column
,
938 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
940 wxAlignment align
= wxALIGN_LEFT
,
941 int flags
= wxDATAVIEW_COL_RESIZABLE
);
942 wxDataViewColumn
* AppendTextColumn(const wxBitmap
& label
,
943 unsigned int model_column
,
944 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
946 wxAlignment align
= wxALIGN_LEFT
,
947 int flags
= wxDATAVIEW_COL_RESIZABLE
);
952 Appends a column for rendering a toggle. Returns the wxDataViewColumn
953 created in the function or @NULL on failure.
955 wxDataViewColumn
* AppendToggleColumn(const wxString
& label
,
956 unsigned int model_column
,
957 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
959 wxAlignment align
= wxALIGN_CENTER
,
960 int flags
= wxDATAVIEW_COL_RESIZABLE
);
961 wxDataViewColumn
* AppendToggleColumn(const wxBitmap
& label
,
962 unsigned int model_column
,
963 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
965 wxAlignment align
= wxALIGN_CENTER
,
966 int flags
= wxDATAVIEW_COL_RESIZABLE
);
970 Associates a wxDataViewModel with the
971 control. This increases the reference count of the model by 1.
973 virtual bool AssociateModel(wxDataViewModel
* model
);
978 virtual bool ClearColumns();
983 void ClearSelection();
988 void Collapse(const wxDataViewItem
& item
);
991 Create the control. Useful for two step creation.
993 bool Create(wxWindow
* parent
, wxWindowID id
,
994 const wxPoint
& pos
= wxDefaultPosition
,
995 const wxSize
& size
= wxDefaultSize
,
997 const wxValidator
& validator
= wxDefaultValidator
);
1000 Deletes given column.
1002 virtual bool DeleteColumn(const wxDataViewColumn
* column
);
1005 Call this to ensure that the given item is visible.
1007 void EnsureVisible(const wxDataViewItem
& item
,
1008 const wxDataViewColumn
* column
= NULL
);
1013 void Expand(const wxDataViewItem
& item
);
1016 Returns pointer to the column. @a pos refers to the
1017 position in the control which may change after reordering
1018 columns by the user.
1020 virtual wxDataViewColumn
* GetColumn(unsigned int pos
) const;
1023 Returns the number of columns.
1025 virtual unsigned int GetColumnCount() const;
1028 Returns the position of the column or -1 if not found in the control.
1030 virtual int GetColumnPosition(const wxDataViewColumn
* column
) const;
1033 Returns column containing the expanders.
1035 wxDataViewColumn
* GetExpanderColumn() const;
1038 Returns indentation.
1040 int GetIndent() const;
1045 wxRect
GetItemRect(const wxDataViewItem
& item
,
1046 const wxDataViewColumn
* col
= NULL
) const;
1049 Returns pointer to the data model associated with the
1052 virtual wxDataViewModel
* GetModel() const;
1055 Returns first selected item or an invalid item if none is selected.
1057 wxDataViewItem
GetSelection() const;
1060 Fills @a sel with currently selected items and returns
1063 int GetSelections(wxDataViewItemArray
& sel
) const;
1066 Returns the wxDataViewColumn currently responsible for sorting
1067 or @NULL if none has been selected.
1069 virtual wxDataViewColumn
* GetSortingColumn() const;
1074 void HitTest(const wxPoint
& point
, wxDataViewItem
& item
,
1075 wxDataViewColumn
*& col
) const;
1078 Return @true if the item is selected.
1080 bool IsSelected(const wxDataViewItem
& item
) const;
1083 Select the given item.
1085 void Select(const wxDataViewItem
& item
);
1093 Set which column shall contain the tree-like expanders.
1095 void SetExpanderColumn(wxDataViewColumn
* col
);
1098 Sets the indendation.
1100 void SetIndent(int indent
);
1103 Sets the selection to the array of wxDataViewItems.
1105 void SetSelections(const wxDataViewItemArray
& sel
);
1108 Unselect the given item.
1110 void Unselect(const wxDataViewItem
& item
);
1113 Unselect all item. This method only has effect if multiple
1114 selections are allowed.
1122 @class wxDataViewModelNotifier
1123 @wxheader{dataview.h}
1125 A wxDataViewModelNotifier instance is owned by a
1127 and mirrors its notification interface. See
1128 the documentation of that class for further
1134 class wxDataViewModelNotifier
1140 wxDataViewModelNotifier();
1145 ~wxDataViewModelNotifier();
1148 Called by owning model.
1153 Get owning wxDataViewModel.
1155 wxDataViewModel
* GetOwner();
1158 Called by owning model.
1160 bool ItemAdded(const wxDataViewItem
& parent
,
1161 const wxDataViewItem
& item
);
1164 Called by owning model.
1166 bool ItemChanged(const wxDataViewItem
& item
);
1169 Called by owning model.
1171 bool ItemDeleted(const wxDataViewItem
& parent
,
1172 const wxDataViewItem
& item
);
1175 Called by owning model.
1177 bool ItemsAdded(const wxDataViewItem
& parent
,
1178 const wxDataViewItemArray
& items
);
1181 Called by owning model.
1183 bool ItemsChanged(const wxDataViewItemArray
& items
);
1186 Called by owning model.
1188 bool ItemsDeleted(const wxDataViewItem
& parent
,
1189 const wxDataViewItemArray
& items
);
1192 Called by owning model.
1197 Set owner of this notifier. Used internally.
1199 void SetOwner(wxDataViewModel
* owner
);
1202 Called by owning model.
1204 bool ValueChanged(const wxDataViewItem
& item
, unsigned int col
);
1210 @class wxDataViewRenderer
1211 @wxheader{dataview.h}
1213 This class is used by wxDataViewCtrl to
1214 render the individual cells. One instance of a renderer class is
1215 owned by wxDataViewColumn. There is
1216 a number of ready-to-use renderers provided:
1217 wxDataViewTextRenderer,
1218 wxDataViewTextRendererAttr,
1219 wxDataViewIconTextRenderer,
1220 wxDataViewToggleRenderer,
1221 wxDataViewProgressRenderer,
1222 wxDataViewBitmapRenderer,
1223 wxDataViewDateRenderer.
1224 wxDataViewSpinRenderer.
1226 Additionally, the user can write own renderers by deriving from
1227 wxDataViewCustomRenderer.
1229 The @e wxDataViewCellMode flag controls, what actions
1230 the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE
1231 indicates that the user can double click the cell and
1232 something will happen (e.g. a window for editing a date
1233 will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates
1234 that the user can edit the data in-place, i.e. an control
1235 will show up after a slow click on the cell. This behaviour
1236 is best known from changing the filename in most file
1241 enum wxDataViewCellMode
1243 wxDATAVIEW_CELL_INERT,
1244 wxDATAVIEW_CELL_ACTIVATABLE,
1245 wxDATAVIEW_CELL_EDITABLE
1249 The @e wxDataViewCellRenderState flag controls how the
1250 the renderer should display its contents in a cell:
1253 enum wxDataViewCellRenderState
1255 wxDATAVIEW_CELL_SELECTED = 1,
1256 wxDATAVIEW_CELL_PRELIT = 2,
1257 wxDATAVIEW_CELL_INSENSITIVE = 4,
1258 wxDATAVIEW_CELL_FOCUSED = 8
1266 class wxDataViewRenderer
: public wxObject
1272 wxDataViewRenderer(const wxString
& varianttype
,
1273 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1274 int alignment
= wxALIGN_LEFT
|wxALIGN_CENTRE_VERTICAL
);
1277 Returns the alignment.
1279 virtual int GetAlignment() const;
1282 Returns the cell mode.
1284 virtual wxDataViewCellMode
GetMode();
1287 Returns pointer to the owning wxDataViewColumn.
1289 virtual wxDataViewColumn
* GetOwner();
1292 This methods retrieves the value from the renderer in order to
1293 transfer the value back to the data model. Returns @e @false
1296 virtual bool GetValue(wxVariant
& value
);
1299 Returns a string with the type of the wxVariant
1300 supported by this renderer.
1302 virtual wxString
GetVariantType();
1307 virtual void SetAlignment( int align
);
1309 Sets the owning wxDataViewColumn. This
1310 is usually called from within wxDataViewColumn.
1312 virtual void SetOwner(wxDataViewColumn
* owner
);
1315 Set the value of the renderer (and thus its cell) to @e value.
1316 The internal code will then render this cell with this data.
1318 virtual bool SetValue(const wxVariant
& value
);
1321 Before data is committed to the data model, it is passed to this
1322 method where it can be checked for validity. This can also be
1323 used for checking a valid range or limiting the user input in
1324 a certain aspect (e.g. max number of characters or only alphanumeric
1325 input, ASCII only etc.). Return @e @false if the value is
1327 Please note that due to implementation limitations, this validation
1328 is done after the editing control already is destroyed and the
1329 editing process finished.
1331 virtual bool Validate(wxVariant
& value
);
1337 @class wxDataViewTextRenderer
1338 @wxheader{dataview.h}
1340 wxDataViewTextRenderer is used for rendering text. It supports
1341 in-place editing if desired.
1346 class wxDataViewTextRenderer
: public wxDataViewRenderer
1352 wxDataViewTextRenderer(const wxString
& varianttype
= "string",
1353 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
1359 @class wxDataViewProgressRenderer
1360 @wxheader{dataview.h}
1362 wxDataViewProgressRenderer
1367 class wxDataViewProgressRenderer
: public wxDataViewRenderer
1373 wxDataViewProgressRenderer(const wxString
& label
= wxEmptyString
,
1374 const wxString
& varianttype
= "long",
1375 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
1381 @class wxDataViewSpinRenderer
1382 @wxheader{dataview.h}
1384 This is a specialized renderer for rendering integer values. It
1385 supports modifying the values in-place by using a wxSpinCtrl.
1386 The renderer only support variants of type @e long.
1391 class wxDataViewSpinRenderer
: public wxDataViewCustomRenderer
1395 Constructor. @a min and @a max indicate the minimum und
1396 maximum values of for the wxSpinCtrl.
1398 wxDataViewSpinRenderer(int min
, int max
,
1399 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1400 int alignment
= wxDVR_DEFAULT_ALIGNMENT
);
1406 @class wxDataViewToggleRenderer
1407 @wxheader{dataview.h}
1409 wxDataViewToggleRenderer
1414 class wxDataViewToggleRenderer
: public wxDataViewRenderer
1420 wxDataViewToggleRenderer(const wxString
& varianttype
= "bool",
1421 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
1427 @class wxDataViewTreeCtrl
1428 @wxheader{dataview.h}
1430 This class is a wxDataViewCtrl which internally
1431 uses a wxDataViewTreeStore and forwards
1432 most of its API to that class. Additionally, it uses a wxImageList
1433 to store a list of icons. The main purpose of this class is to look
1434 like a wxTreeCtrl to make a transition from it
1435 to the wxDataViewCtrl class simpler.
1439 @appearance{dataviewtreectrl.png}
1441 class wxDataViewTreeCtrl
: public wxDataViewCtrl
1446 Constructor. Calls Create().
1448 wxDataViewTreeCtrl();
1449 wxDataViewTreeCtrl(wxWindow
* parent
, wxWindowID id
,
1450 const wxPoint
& pos
= wxDefaultPosition
,
1451 const wxSize
& size
= wxDefaultSize
,
1452 long style
= wxDV_NO_HEADER
,
1453 const wxValidator
& validator
= wxDefaultValidator
);
1457 Destructor. Deletes the image list if any.
1459 ~wxDataViewTreeCtrl();
1464 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1465 const wxString
& text
,
1468 wxClientData
* data
= NULL
);
1473 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1474 const wxString
& text
,
1476 wxClientData
* data
= NULL
);
1479 Creates the control and a wxDataViewTreeStore as
1482 bool Create(wxWindow
* parent
, wxWindowID id
,
1483 const wxPoint
& pos
= wxDefaultPosition
,
1484 const wxSize
& size
= wxDefaultSize
,
1485 long style
= wxDV_NO_HEADER
,
1486 const wxValidator
& validator
= wxDefaultValidator
);
1489 Calls the identical method from wxDataViewTreeStore.
1491 void DeleteAllItems();
1494 Calls the identical method from wxDataViewTreeStore.
1496 void DeleteChildren(const wxDataViewItem
& item
);
1499 Calls the identical method from wxDataViewTreeStore.
1501 void DeleteItem(const wxDataViewItem
& item
);
1504 Calls the identical method from wxDataViewTreeStore.
1506 int GetChildCount(const wxDataViewItem
& parent
) const;
1509 Returns the image list.
1511 wxImageList
* GetImageList();
1514 Calls the identical method from wxDataViewTreeStore.
1516 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1519 Calls the identical method from wxDataViewTreeStore.
1521 const wxIcon
GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1524 Calls the identical method from wxDataViewTreeStore.
1526 const wxIcon
GetItemIcon(const wxDataViewItem
& item
) const;
1529 Calls the identical method from wxDataViewTreeStore.
1531 wxString
GetItemText(const wxDataViewItem
& item
) const;
1534 Calls the identical method from wxDataViewTreeStore.
1536 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1537 unsigned int pos
) const;
1543 wxDataViewTreeStore
* GetStore() const;
1544 const wxDataViewTreeStore
* GetStore() const;
1548 Calls the same method from wxDataViewTreeStore but uess
1549 and index position in the image list instead of a wxIcon.
1551 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1552 const wxDataViewItem
& previous
,
1553 const wxString
& text
,
1556 wxClientData
* data
= NULL
);
1559 Calls the same method from wxDataViewTreeStore but uess
1560 and index position in the image list instead of a wxIcon.
1562 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1563 const wxDataViewItem
& previous
,
1564 const wxString
& text
,
1566 wxClientData
* data
= NULL
);
1569 Calls the same method from wxDataViewTreeStore but uess
1570 and index position in the image list instead of a wxIcon.
1572 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1573 const wxString
& text
,
1576 wxClientData
* data
= NULL
);
1579 Calls the same method from wxDataViewTreeStore but uess
1580 and index position in the image list instead of a wxIcon.
1582 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1583 const wxString
& text
,
1585 wxClientData
* data
= NULL
);
1588 Sets the image list.
1590 void SetImageList(wxImageList
* imagelist
);
1593 Calls the identical method from wxDataViewTreeStore.
1595 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
1598 Calls the identical method from wxDataViewTreeStore.
1600 void SetItemExpandedIcon(const wxDataViewItem
& item
,
1601 const wxIcon
& icon
);
1604 Calls the identical method from wxDataViewTreeStore.
1606 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
1609 Calls the identical method from wxDataViewTreeStore.
1611 void SetItemText(const wxDataViewItem
& item
,
1612 const wxString
& text
);
1618 @class wxDataViewTreeStore
1619 @wxheader{dataview.h}
1621 wxDataViewTreeStore is a specialised wxDataViewModel
1622 for displaying simple trees very much like wxTreeCtrl
1623 does and it offers a similar API. This class actually stores the entire
1624 tree (therefore its name) and implements all virtual methods from the base
1625 class so it can be used directly without having to derive any class from it.
1626 This comes at the price of much reduced flexibility.
1631 class wxDataViewTreeStore
: public wxDataViewModel
1635 Constructor. Creates the invisible root node internally.
1637 wxDataViewTreeStore();
1642 ~wxDataViewTreeStore();
1647 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1648 const wxString
& text
,
1649 const wxIcon
& icon
= wxNullIcon
,
1650 const wxIcon
& expanded
= wxNullIcon
,
1651 wxClientData
* data
= NULL
);
1656 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1657 const wxString
& text
,
1658 const wxIcon
& icon
= wxNullIcon
,
1659 wxClientData
* data
= NULL
);
1662 Delete all item in the model.
1664 void DeleteAllItems();
1667 Delete all children of the item, but not the item itself.
1669 void DeleteChildren(const wxDataViewItem
& item
);
1674 void DeleteItem(const wxDataViewItem
& item
);
1677 Return the number of children of item.
1679 int GetChildCount(const wxDataViewItem
& parent
) const;
1682 Returns the client data asoociated with the item.
1684 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1687 Returns the icon to display in expanded containers.
1689 const wxIcon
GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1692 Returns the icon of the item.
1694 const wxIcon
GetItemIcon(const wxDataViewItem
& item
) const;
1697 Returns the text of the item.
1699 wxString
GetItemText(const wxDataViewItem
& item
) const;
1702 Returns the nth child item of item.
1704 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1705 unsigned int pos
) const;
1708 Inserts a container after @e previous.
1710 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1711 const wxDataViewItem
& previous
,
1712 const wxString
& text
,
1713 const wxIcon
& icon
= wxNullIcon
,
1714 const wxIcon
& expanded
= wxNullIcon
,
1715 wxClientData
* data
= NULL
);
1718 Inserts an item after @e previous.
1720 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1721 const wxDataViewItem
& previous
,
1722 const wxString
& text
,
1723 const wxIcon
& icon
= wxNullIcon
,
1724 wxClientData
* data
= NULL
);
1727 Inserts a container before the first child item or @e parent.
1729 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1730 const wxString
& text
,
1731 const wxIcon
& icon
= wxNullIcon
,
1732 const wxIcon
& expanded
= wxNullIcon
,
1733 wxClientData
* data
= NULL
);
1736 Inserts an item before the first child item or @e parent.
1738 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1739 const wxString
& text
,
1740 const wxIcon
& icon
= wxNullIcon
,
1741 wxClientData
* data
= NULL
);
1744 Sets the client data associated with the item.
1746 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
1749 Sets the expanded icon for the item.
1751 void SetItemExpandedIcon(const wxDataViewItem
& item
,
1752 const wxIcon
& icon
);
1755 Sets the icon for the item.
1757 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
1763 @class wxDataViewDateRenderer
1764 @wxheader{dataview.h}
1766 wxDataViewDateRenderer
1771 class wxDataViewDateRenderer
: public wxDataViewRenderer
1777 wxDataViewDateRenderer(const wxString
& varianttype
= "datetime",
1778 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
);
1784 @class wxDataViewTextRendererAttr
1785 @wxheader{dataview.h}
1787 The same as wxDataViewTextRenderer but with
1788 support for font attributes. Font attributes are currently only supported
1791 See also wxDataViewModel::GetAttr and
1797 class wxDataViewTextRendererAttr
: public wxDataViewTextRenderer
1803 wxDataViewTextRendererAttr(const wxString
& varianttype
= "string",
1804 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1805 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1811 @class wxDataViewColumn
1812 @wxheader{dataview.h}
1814 This class represents a column in a wxDataViewCtrl.
1815 One wxDataViewColumn is bound to one column in the data model,
1816 to which the wxDataViewCtrl has been associated.
1818 An instance of wxDataViewRenderer is used by
1819 this class to render its data.
1824 class wxDataViewColumn
: public wxObject
1831 wxDataViewColumn(const wxString
& title
,
1832 wxDataViewRenderer
* renderer
,
1833 unsigned int model_column
,
1834 int width
= wxDVC_DEFAULT_WIDTH
,
1835 wxAlignment align
= wxALIGN_CENTRE
,
1836 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1837 wxDataViewColumn(const wxBitmap
& bitmap
,
1838 wxDataViewRenderer
* renderer
,
1839 unsigned int model_column
,
1840 int width
= wxDVC_DEFAULT_WIDTH
,
1841 wxAlignment align
= wxALIGN_CENTRE
,
1842 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1848 ~wxDataViewColumn();
1851 Returns the bitmap in the header of the column, if any.
1853 const wxBitmap
GetBitmap();
1856 Returns the index of the column of the model, which this
1857 wxDataViewColumn is displaying.
1859 unsigned int GetModelColumn();
1862 Returns the owning wxDataViewCtrl.
1864 wxDataViewCtrl
* GetOwner();
1867 Returns the renderer of this wxDataViewColumn.
1868 See also wxDataViewRenderer.
1870 wxDataViewRenderer
* GetRenderer();
1873 Returns @true if the column is reorderable.
1875 bool GetReorderable();
1878 Returns @true if the column is sortable.
1884 Returns the width of the column.
1889 Returns @true, if the sort order is ascending.
1890 See also SetSortOrder()
1892 bool IsSortOrderAscending();
1895 Set the alignment of the column header.
1897 void SetAlignment(wxAlignment align
);
1900 Set the bitmap of the column header.
1902 void SetBitmap(const wxBitmap
& bitmap
);
1905 Indicate wether the column can be reordered by the
1906 user using the mouse. This is typically implemented
1907 visually by dragging the header button around.
1909 void SetReorderable(bool reorderable
);
1912 Indicate the sort order if the implementation of the
1913 wxDataViewCtrl supports it, most commonly by showing
1916 void SetSortOrder(bool ascending
);
1919 Indicate that the column is sortable. This does
1920 not show any sorting indicate yet, but it does
1921 make the column header clickable. Call
1923 afterwards to actually make the sort indicator appear.
1924 If @a sortable is @false, the column header is
1925 no longer clickable and the sort indicator (little
1926 arrow) will disappear.
1928 void SetSortable(bool sortable
);
1931 Set the title of the column header to @e title.
1933 void SetTitle(const wxString
& title
);