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.
585 virtual bool Activate(wxRect cell
, wxDataViewModel
* model
,
590 Override this to create the actual editor control once editing
591 is about to start. @a parent is the parent of the editor
592 control, @a labelRect indicates the position and
593 size of the editor control and @a value is its initial value:
595 virtual wxControl
* CreateEditorCtrl(wxWindow
* parent
,
597 const wxVariant
& value
);
600 Create DC on request. Internal.
602 virtual wxDC
* GetDC();
605 Return size required to show content.
607 virtual wxSize
GetSize();
610 Overrride this so that the renderer can get the value
611 from the editor control (pointed to by @e editor):
613 virtual bool GetValueFromEditorCtrl(wxControl
* editor
,
617 Override this and make it return @e @true in order to
618 indicate that this renderer supports in-place editing.
620 virtual bool HasEditorCtrl();
623 Overrride this to react to a left click.
625 virtual bool LeftClick(wxPoint cursor
, wxRect cell
,
626 wxDataViewModel
* model
,
631 Override this to render the cell. Before this is called,
632 wxDataViewRenderer::SetValue was called
633 so that this instance knows what to render.
635 virtual bool Render(wxRect cell
, wxDC
* dc
, int state
);
638 This method should be called from within Render()
639 whenever you need to render simple text. This will ensure that the
640 correct colour, font and vertical alignment will be chosen so the
641 text will look the same as text drawn by native renderers.
643 bool RenderText(const wxString
& text
, int xoffset
, wxRect cell
,
644 wxDC
* dc
, int state
);
647 Overrride this to react to a right click.
649 virtual bool RightClick(wxPoint cursor
, wxRect cell
,
650 wxDataViewModel
* model
,
655 Overrride this to start a drag operation.
657 virtual bool StartDrag(wxPoint cursor
, wxRect cell
,
658 wxDataViewModel
* model
,
666 @class wxDataViewBitmapRenderer
667 @wxheader{dataview.h}
669 wxDataViewBitmapRenderer
674 class wxDataViewBitmapRenderer
: public wxDataViewRenderer
680 wxDataViewBitmapRenderer(const wxString
& varianttype
= "wxBitmap",
681 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
687 @class wxDataViewItemAttr
688 @wxheader{dataview.h}
690 This class is used to indicate to a wxDataViewCtrl
691 that a certain Item() has extra font attributes
692 for its renderer. For this, it is required to override
693 wxDataViewModel::GetAttr.
695 Attributes are currently only supported by
696 wxDataViewTextRendererText().
701 class wxDataViewItemAttr
707 wxDataViewItemAttr();
710 Call this to indicate that the item shall be displayed in bold text.
712 void SetBold(bool set
);
715 Call this to indicate that the item shall be displayed with
718 void SetColour(const wxColour
& colour
);
721 Call this to indicate that the item shall be displayed in italic text.
723 void SetItalic(bool set
);
729 @class wxDataViewItem
730 @wxheader{dataview.h}
732 wxDataViewItem is a small opaque class that represents an
733 item in a wxDataViewCtrl in a
734 persistent way, i.e. indepent of the position of the
735 item in the control or changes to its contents. It must
736 hold a unique ID of type @e void* in its only field
737 and can be converted to a from it.
739 If the ID is @e @NULL the wxDataViewItem is invalid and
740 wxDataViewItem::IsOk will return @e @false
741 which used in many places in the API of wxDataViewCtrl
742 to indicate that e.g. no item was found. An ID of @NULL
743 is also used to indicate the invisible root. Examples
745 wxDataViewModel::GetParent and
746 wxDataViewModel::GetChildren.
758 wxDataViewItem(void* id
= NULL
);
759 wxDataViewItem(const wxDataViewItem
& item
);
768 Returns @true if the ID is not @e @NULL.
776 @class wxDataViewCtrl
777 @wxheader{dataview.h}
779 wxDataViewCtrl is a control to display data either
780 in a tree like fashion or in a tabular form or both.
781 If you only need to display a simple tree structure
782 with an API more like the older wxTreeCtrl class,
783 then the specialized wxDataViewTreeCtrl
786 A wxDataViewItem is used
787 to represent a (visible) item in the control.
789 Unlike wxListCtrl wxDataViewCtrl doesn't
790 get its data from the user through virtual functions or by
791 setting it directly. Instead you need to write your own
792 wxDataViewModel and associate
793 it with this control. Then you need to add a number of
794 wxDataViewColumn to this control to
795 define what each column shall display. Each wxDataViewColumn
796 in turn owns 1 instance of a
797 wxDataViewRenderer to render its
798 cells. A number of standard renderers for rendering text, dates,
799 images, toggle, a progress bar etc. are provided. Additionally,
800 the user can write custom renderes deriving from
801 wxDataViewCustomRenderer
802 for displaying anything.
804 All data transfer from the control to the model and the user
805 code is done through wxVariant which can
806 be extended to support more data formats as necessary.
807 Accordingly, all type information uses the strings returned
808 from wxVariant::GetType.
812 Single selection mode. This is the default.
813 @style{wxDV_MULTIPLE}:
814 Multiple selection mode.
815 @style{wxDV_ROW_LINES}:
816 Use alternating colours for rows if supported by platform and theme.
817 @style{wxDV_HORIZ_RULES}:
818 Display fine rules between row if supported.
819 @style{wxDV_VERT_RULES}:
820 Display fine rules between columns is supported.
825 @appearance{dataviewctrl.png}
827 class wxDataViewCtrl
: public wxControl
832 Constructor. Calls Create().
835 wxDataViewCtrl(wxWindow
* parent
, wxWindowID id
,
836 const wxPoint
& pos
= wxDefaultPosition
,
837 const wxSize
& size
= wxDefaultSize
,
839 const wxValidator
& validator
= wxDefaultValidator
);
849 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
850 created in the function or @NULL on failure.
852 wxDataViewColumn
* AppendBitmapColumn(const wxString
& label
,
853 unsigned int model_column
,
854 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
856 wxAlignment align
= wxALIGN_CENTER
,
857 int flags
= wxDATAVIEW_COL_RESIZABLE
);
858 wxDataViewColumn
* AppendBitmapColumn(const wxBitmap
& label
,
859 unsigned int model_column
,
860 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
862 wxAlignment align
= wxALIGN_CENTER
,
863 int flags
= wxDATAVIEW_COL_RESIZABLE
);
867 Add a wxDataViewColumn to the control. Returns
869 Note that there is a number of short cut methods which implicitly create
870 a wxDataViewColumn and a
871 wxDataViewRenderer for it (see below).
873 virtual bool AppendColumn(wxDataViewColumn
* col
);
877 Appends a column for rendering a date. Returns the wxDataViewColumn
878 created in the function or @NULL on failure.
880 wxDataViewColumn
* AppendDateColumn(const wxString
& label
,
881 unsigned int model_column
,
882 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
884 wxAlignment align
= wxALIGN_CENTER
,
885 int flags
= wxDATAVIEW_COL_RESIZABLE
);
886 wxDataViewColumn
* AppendDateColumn(const wxBitmap
& label
,
887 unsigned int model_column
,
888 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
890 wxAlignment align
= wxALIGN_CENTER
,
891 int flags
= wxDATAVIEW_COL_RESIZABLE
);
896 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
897 created in the function or @NULL on failure. This uses the
898 wxDataViewIconTextRenderer.
900 wxDataViewColumn
* AppendIconTextColumn(const wxString
& label
,
901 unsigned int model_column
,
902 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
904 wxAlignment align
= wxALIGN_LEFT
,
905 int flags
= wxDATAVIEW_COL_RESIZABLE
);
906 wxDataViewColumn
* AppendIconTextColumn(const wxBitmap
& label
,
907 unsigned int model_column
,
908 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
910 wxAlignment align
= wxALIGN_LEFT
,
911 int flags
= wxDATAVIEW_COL_RESIZABLE
);
916 Appends a column for rendering a progress indicator. Returns the
918 created in the function or @NULL on failure.
920 wxDataViewColumn
* AppendProgressColumn(const wxString
& label
,
921 unsigned int model_column
,
922 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
924 wxAlignment align
= wxALIGN_CENTER
,
925 int flags
= wxDATAVIEW_COL_RESIZABLE
);
926 wxDataViewColumn
* AppendProgressColumn(const wxBitmap
& label
,
927 unsigned int model_column
,
928 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
930 wxAlignment align
= wxALIGN_CENTER
,
931 int flags
= wxDATAVIEW_COL_RESIZABLE
);
936 Appends a column for rendering text. Returns the wxDataViewColumn
937 created in the function or @NULL on failure.
939 wxDataViewColumn
* AppendTextColumn(const wxString
& label
,
940 unsigned int model_column
,
941 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
943 wxAlignment align
= wxALIGN_LEFT
,
944 int flags
= wxDATAVIEW_COL_RESIZABLE
);
945 wxDataViewColumn
* AppendTextColumn(const wxBitmap
& label
,
946 unsigned int model_column
,
947 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
949 wxAlignment align
= wxALIGN_LEFT
,
950 int flags
= wxDATAVIEW_COL_RESIZABLE
);
955 Appends a column for rendering a toggle. Returns the wxDataViewColumn
956 created in the function or @NULL on failure.
958 wxDataViewColumn
* AppendToggleColumn(const wxString
& label
,
959 unsigned int model_column
,
960 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
962 wxAlignment align
= wxALIGN_CENTER
,
963 int flags
= wxDATAVIEW_COL_RESIZABLE
);
964 wxDataViewColumn
* AppendToggleColumn(const wxBitmap
& label
,
965 unsigned int model_column
,
966 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
968 wxAlignment align
= wxALIGN_CENTER
,
969 int flags
= wxDATAVIEW_COL_RESIZABLE
);
973 Associates a wxDataViewModel with the
974 control. This increases the reference count of the model by 1.
976 virtual bool AssociateModel(wxDataViewModel
* model
);
981 virtual bool ClearColumns();
986 void ClearSelection();
991 void Collapse(const wxDataViewItem
& item
);
994 Create the control. Useful for two step creation.
996 bool Create(wxWindow
* parent
, wxWindowID id
,
997 const wxPoint
& pos
= wxDefaultPosition
,
998 const wxSize
& size
= wxDefaultSize
,
1000 const wxValidator
& validator
= wxDefaultValidator
);
1003 Deletes given column.
1005 virtual bool DeleteColumn(const wxDataViewColumn
* column
);
1008 Call this to ensure that the given item is visible.
1010 void EnsureVisible(const wxDataViewItem
& item
,
1011 const wxDataViewColumn
* column
= NULL
);
1016 void Expand(const wxDataViewItem
& item
);
1019 Returns pointer to the column. @a pos refers to the
1020 position in the control which may change after reordering
1021 columns by the user.
1023 virtual wxDataViewColumn
* GetColumn(unsigned int pos
) const;
1026 Returns the number of columns.
1028 virtual unsigned int GetColumnCount() const;
1031 Returns the position of the column or -1 if not found in the control.
1033 virtual int GetColumnPosition(const wxDataViewColumn
* column
) const;
1036 Returns column containing the expanders.
1038 wxDataViewColumn
* GetExpanderColumn() const;
1041 Returns indentation.
1043 int GetIndent() const;
1048 wxRect
GetItemRect(const wxDataViewItem
& item
,
1049 const wxDataViewColumn
* col
= NULL
) const;
1052 Returns pointer to the data model associated with the
1055 virtual wxDataViewModel
* GetModel() const;
1058 Returns first selected item or an invalid item if none is selected.
1060 wxDataViewItem
GetSelection() const;
1063 Fills @a sel with currently selected items and returns
1066 int GetSelections(wxDataViewItemArray
& sel
) const;
1069 Returns the wxDataViewColumn currently responsible for sorting
1070 or @NULL if none has been selected.
1072 virtual wxDataViewColumn
* GetSortingColumn() const;
1077 void HitTest(const wxPoint
& point
, wxDataViewItem
& item
,
1078 wxDataViewColumn
*& col
) const;
1081 Return @true if the item is selected.
1083 bool IsSelected(const wxDataViewItem
& item
) const;
1086 Select the given item.
1088 void Select(const wxDataViewItem
& item
);
1096 Set which column shall contain the tree-like expanders.
1098 void SetExpanderColumn(wxDataViewColumn
* col
);
1101 Sets the indendation.
1103 void SetIndent(int indent
);
1106 Sets the selection to the array of wxDataViewItems.
1108 void SetSelections(const wxDataViewItemArray
& sel
);
1111 Unselect the given item.
1113 void Unselect(const wxDataViewItem
& item
);
1116 Unselect all item. This method only has effect if multiple
1117 selections are allowed.
1125 @class wxDataViewModelNotifier
1126 @wxheader{dataview.h}
1128 A wxDataViewModelNotifier instance is owned by a
1130 and mirrors its notification interface. See
1131 the documentation of that class for further
1137 class wxDataViewModelNotifier
1143 wxDataViewModelNotifier();
1148 ~wxDataViewModelNotifier();
1151 Called by owning model.
1156 Get owning wxDataViewModel.
1158 wxDataViewModel
* GetOwner();
1161 Called by owning model.
1163 bool ItemAdded(const wxDataViewItem
& parent
,
1164 const wxDataViewItem
& item
);
1167 Called by owning model.
1169 bool ItemChanged(const wxDataViewItem
& item
);
1172 Called by owning model.
1174 bool ItemDeleted(const wxDataViewItem
& parent
,
1175 const wxDataViewItem
& item
);
1178 Called by owning model.
1180 bool ItemsAdded(const wxDataViewItem
& parent
,
1181 const wxDataViewItemArray
& items
);
1184 Called by owning model.
1186 bool ItemsChanged(const wxDataViewItemArray
& items
);
1189 Called by owning model.
1191 bool ItemsDeleted(const wxDataViewItem
& parent
,
1192 const wxDataViewItemArray
& items
);
1195 Called by owning model.
1200 Set owner of this notifier. Used internally.
1202 void SetOwner(wxDataViewModel
* owner
);
1205 Called by owning model.
1207 bool ValueChanged(const wxDataViewItem
& item
, unsigned int col
);
1213 @class wxDataViewRenderer
1214 @wxheader{dataview.h}
1216 This class is used by wxDataViewCtrl to
1217 render the individual cells. One instance of a renderer class is
1218 owned by wxDataViewColumn. There is
1219 a number of ready-to-use renderers provided:
1220 wxDataViewTextRenderer,
1221 wxDataViewTextRendererAttr,
1222 wxDataViewIconTextRenderer,
1223 wxDataViewToggleRenderer,
1224 wxDataViewProgressRenderer,
1225 wxDataViewBitmapRenderer,
1226 wxDataViewDateRenderer.
1227 wxDataViewSpinRenderer.
1229 Additionally, the user can write own renderers by deriving from
1230 wxDataViewCustomRenderer.
1232 The @e wxDataViewCellMode flag controls, what actions
1233 the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE
1234 indicates that the user can double click the cell and
1235 something will happen (e.g. a window for editing a date
1236 will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates
1237 that the user can edit the data in-place, i.e. an control
1238 will show up after a slow click on the cell. This behaviour
1239 is best known from changing the filename in most file
1244 enum wxDataViewCellMode
1246 wxDATAVIEW_CELL_INERT,
1247 wxDATAVIEW_CELL_ACTIVATABLE,
1248 wxDATAVIEW_CELL_EDITABLE
1252 The @e wxDataViewCellRenderState flag controls how the
1253 the renderer should display its contents in a cell:
1256 enum wxDataViewCellRenderState
1258 wxDATAVIEW_CELL_SELECTED = 1,
1259 wxDATAVIEW_CELL_PRELIT = 2,
1260 wxDATAVIEW_CELL_INSENSITIVE = 4,
1261 wxDATAVIEW_CELL_FOCUSED = 8
1269 class wxDataViewRenderer
: public wxObject
1275 wxDataViewRenderer(const wxString
& varianttype
,
1276 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1277 int alignment
= wxALIGN_LEFT
|wxALIGN_CENTRE_VERTICAL
);
1280 Returns the cell mode.
1282 virtual wxDataViewCellMode
GetMode();
1285 Returns pointer to the owning wxDataViewColumn.
1287 virtual wxDataViewColumn
* GetOwner();
1290 This methods retrieves the value from the renderer in order to
1291 transfer the value back to the data model. Returns @e @false
1294 virtual bool GetValue(wxVariant
& value
);
1297 Returns a string with the type of the wxVariant
1298 supported by this renderer.
1300 virtual wxString
GetVariantType();
1303 Sets the owning wxDataViewColumn. This
1304 is usually called from within wxDataViewColumn.
1306 virtual void SetOwner(wxDataViewColumn
* owner
);
1309 Set the value of the renderer (and thus its cell) to @e value.
1310 The internal code will then render this cell with this data.
1312 virtual bool SetValue(const wxVariant
& value
);
1315 Before data is committed to the data model, it is passed to this
1316 method where it can be checked for validity. This can also be
1317 used for checking a valid range or limiting the user input in
1318 a certain aspect (e.g. max number of characters or only alphanumeric
1319 input, ASCII only etc.). Return @e @false if the value is
1321 Please note that due to implementation limitations, this validation
1322 is done after the editing control already is destroyed and the
1323 editing process finished.
1325 virtual bool Validate(wxVariant
& value
);
1331 @class wxDataViewTextRenderer
1332 @wxheader{dataview.h}
1334 wxDataViewTextRenderer is used for rendering text. It supports
1335 in-place editing if desired.
1340 class wxDataViewTextRenderer
: public wxDataViewRenderer
1346 wxDataViewTextRenderer(const wxString
& varianttype
= "string",
1347 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
1353 @class wxDataViewProgressRenderer
1354 @wxheader{dataview.h}
1356 wxDataViewProgressRenderer
1361 class wxDataViewProgressRenderer
: public wxDataViewRenderer
1367 wxDataViewProgressRenderer(const wxString
& label
= wxEmptyString
,
1368 const wxString
& varianttype
= "long",
1369 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
1375 @class wxDataViewSpinRenderer
1376 @wxheader{dataview.h}
1378 This is a specialized renderer for rendering integer values. It
1379 supports modifying the values in-place by using a wxSpinCtrl.
1380 The renderer only support variants of type @e long.
1385 class wxDataViewSpinRenderer
: public wxDataViewCustomRenderer
1389 Constructor. @a min and @a max indicate the minimum und
1390 maximum values of for the wxSpinCtrl.
1392 wxDataViewSpinRenderer(int min
, int max
,
1393 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1394 int alignment
= wxDVR_DEFAULT_ALIGNMENT
);
1400 @class wxDataViewToggleRenderer
1401 @wxheader{dataview.h}
1403 wxDataViewToggleRenderer
1408 class wxDataViewToggleRenderer
: public wxDataViewRenderer
1414 wxDataViewToggleRenderer(const wxString
& varianttype
= "bool",
1415 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
);
1421 @class wxDataViewTreeCtrl
1422 @wxheader{dataview.h}
1424 This class is a wxDataViewCtrl which internally
1425 uses a wxDataViewTreeStore and forwards
1426 most of its API to that class. Additionally, it uses a wxImageList
1427 to store a list of icons. The main purpose of this class is to look
1428 like a wxTreeCtrl to make a transition from it
1429 to the wxDataViewCtrl class simpler.
1433 @appearance{dataviewtreectrl.png}
1435 class wxDataViewTreeCtrl
: public wxDataViewCtrl
1440 Constructor. Calls Create().
1442 wxDataViewTreeCtrl();
1443 wxDataViewTreeCtrl(wxWindow
* parent
, wxWindowID id
,
1444 const wxPoint
& pos
= wxDefaultPosition
,
1445 const wxSize
& size
= wxDefaultSize
,
1446 long style
= wxDV_NO_HEADER
,
1447 const wxValidator
& validator
= wxDefaultValidator
);
1451 Destructor. Deletes the image list if any.
1453 ~wxDataViewTreeCtrl();
1458 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1459 const wxString
& text
,
1462 wxClientData
* data
= NULL
);
1467 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1468 const wxString
& text
,
1470 wxClientData
* data
= NULL
);
1473 Creates the control and a wxDataViewTreeStore as
1476 bool Create(wxWindow
* parent
, wxWindowID id
,
1477 const wxPoint
& pos
= wxDefaultPosition
,
1478 const wxSize
& size
= wxDefaultSize
,
1479 long style
= wxDV_NO_HEADER
,
1480 const wxValidator
& validator
= wxDefaultValidator
);
1483 Calls the identical method from wxDataViewTreeStore.
1485 void DeleteAllItems();
1488 Calls the identical method from wxDataViewTreeStore.
1490 void DeleteChildren(const wxDataViewItem
& item
);
1493 Calls the identical method from wxDataViewTreeStore.
1495 void DeleteItem(const wxDataViewItem
& item
);
1498 Calls the identical method from wxDataViewTreeStore.
1500 int GetChildCount(const wxDataViewItem
& parent
) const;
1503 Returns the image list.
1505 wxImageList
* GetImageList();
1508 Calls the identical method from wxDataViewTreeStore.
1510 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1513 Calls the identical method from wxDataViewTreeStore.
1515 const wxIcon
GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1518 Calls the identical method from wxDataViewTreeStore.
1520 const wxIcon
GetItemIcon(const wxDataViewItem
& item
) const;
1523 Calls the identical method from wxDataViewTreeStore.
1525 wxString
GetItemText(const wxDataViewItem
& item
) const;
1528 Calls the identical method from wxDataViewTreeStore.
1530 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1531 unsigned int pos
) const;
1537 wxDataViewTreeStore
* GetStore() const;
1538 const wxDataViewTreeStore
* GetStore() const;
1542 Calls the same method from wxDataViewTreeStore but uess
1543 and index position in the image list instead of a wxIcon.
1545 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1546 const wxDataViewItem
& previous
,
1547 const wxString
& text
,
1550 wxClientData
* data
= NULL
);
1553 Calls the same method from wxDataViewTreeStore but uess
1554 and index position in the image list instead of a wxIcon.
1556 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1557 const wxDataViewItem
& previous
,
1558 const wxString
& text
,
1560 wxClientData
* data
= NULL
);
1563 Calls the same method from wxDataViewTreeStore but uess
1564 and index position in the image list instead of a wxIcon.
1566 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1567 const wxString
& text
,
1570 wxClientData
* data
= NULL
);
1573 Calls the same method from wxDataViewTreeStore but uess
1574 and index position in the image list instead of a wxIcon.
1576 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1577 const wxString
& text
,
1579 wxClientData
* data
= NULL
);
1582 Sets the image list.
1584 void SetImageList(wxImageList
* imagelist
);
1587 Calls the identical method from wxDataViewTreeStore.
1589 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
1592 Calls the identical method from wxDataViewTreeStore.
1594 void SetItemExpandedIcon(const wxDataViewItem
& item
,
1595 const wxIcon
& icon
);
1598 Calls the identical method from wxDataViewTreeStore.
1600 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
1603 Calls the identical method from wxDataViewTreeStore.
1605 void SetItemText(const wxDataViewItem
& item
,
1606 const wxString
& text
);
1612 @class wxDataViewTreeStore
1613 @wxheader{dataview.h}
1615 wxDataViewTreeStore is a specialised wxDataViewModel
1616 for displaying simple trees very much like wxTreeCtrl
1617 does and it offers a similar API. This class actually stores the entire
1618 tree (therefore its name) and implements all virtual methods from the base
1619 class so it can be used directly without having to derive any class from it.
1620 This comes at the price of much reduced flexibility.
1625 class wxDataViewTreeStore
: public wxDataViewModel
1629 Constructor. Creates the invisible root node internally.
1631 wxDataViewTreeStore();
1636 ~wxDataViewTreeStore();
1641 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1642 const wxString
& text
,
1643 const wxIcon
& icon
= wxNullIcon
,
1644 const wxIcon
& expanded
= wxNullIcon
,
1645 wxClientData
* data
= NULL
);
1650 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1651 const wxString
& text
,
1652 const wxIcon
& icon
= wxNullIcon
,
1653 wxClientData
* data
= NULL
);
1656 Delete all item in the model.
1658 void DeleteAllItems();
1661 Delete all children of the item, but not the item itself.
1663 void DeleteChildren(const wxDataViewItem
& item
);
1668 void DeleteItem(const wxDataViewItem
& item
);
1671 Return the number of children of item.
1673 int GetChildCount(const wxDataViewItem
& parent
) const;
1676 Returns the client data asoociated with the item.
1678 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1681 Returns the icon to display in expanded containers.
1683 const wxIcon
GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1686 Returns the icon of the item.
1688 const wxIcon
GetItemIcon(const wxDataViewItem
& item
) const;
1691 Returns the text of the item.
1693 wxString
GetItemText(const wxDataViewItem
& item
) const;
1696 Returns the nth child item of item.
1698 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1699 unsigned int pos
) const;
1702 Inserts a container after @e previous.
1704 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1705 const wxDataViewItem
& previous
,
1706 const wxString
& text
,
1707 const wxIcon
& icon
= wxNullIcon
,
1708 const wxIcon
& expanded
= wxNullIcon
,
1709 wxClientData
* data
= NULL
);
1712 Inserts an item after @e previous.
1714 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1715 const wxDataViewItem
& previous
,
1716 const wxString
& text
,
1717 const wxIcon
& icon
= wxNullIcon
,
1718 wxClientData
* data
= NULL
);
1721 Inserts a container before the first child item or @e parent.
1723 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1724 const wxString
& text
,
1725 const wxIcon
& icon
= wxNullIcon
,
1726 const wxIcon
& expanded
= wxNullIcon
,
1727 wxClientData
* data
= NULL
);
1730 Inserts an item before the first child item or @e parent.
1732 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1733 const wxString
& text
,
1734 const wxIcon
& icon
= wxNullIcon
,
1735 wxClientData
* data
= NULL
);
1738 Sets the client data associated with the item.
1740 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
1743 Sets the expanded icon for the item.
1745 void SetItemExpandedIcon(const wxDataViewItem
& item
,
1746 const wxIcon
& icon
);
1749 Sets the icon for the item.
1751 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
1757 @class wxDataViewDateRenderer
1758 @wxheader{dataview.h}
1760 wxDataViewDateRenderer
1765 class wxDataViewDateRenderer
: public wxDataViewRenderer
1771 wxDataViewDateRenderer(const wxString
& varianttype
= "datetime",
1772 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
);
1778 @class wxDataViewTextRendererAttr
1779 @wxheader{dataview.h}
1781 The same as wxDataViewTextRenderer but with
1782 support for font attributes. Font attributes are currently only supported
1785 See also wxDataViewModel::GetAttr and
1791 class wxDataViewTextRendererAttr
: public wxDataViewTextRenderer
1797 wxDataViewTextRendererAttr(const wxString
& varianttype
= "string",
1798 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1799 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1805 @class wxDataViewColumn
1806 @wxheader{dataview.h}
1808 This class represents a column in a wxDataViewCtrl.
1809 One wxDataViewColumn is bound to one column in the data model,
1810 to which the wxDataViewCtrl has been associated.
1812 An instance of wxDataViewRenderer is used by
1813 this class to render its data.
1818 class wxDataViewColumn
: public wxObject
1825 wxDataViewColumn(const wxString
& title
,
1826 wxDataViewRenderer
* renderer
,
1827 unsigned int model_column
,
1828 int width
= wxDVC_DEFAULT_WIDTH
,
1829 wxAlignment align
= wxALIGN_CENTRE
,
1830 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1831 wxDataViewColumn(const wxBitmap
& bitmap
,
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
);
1842 ~wxDataViewColumn();
1845 Returns the bitmap in the header of the column, if any.
1847 const wxBitmap
GetBitmap();
1850 Returns the index of the column of the model, which this
1851 wxDataViewColumn is displaying.
1853 unsigned int GetModelColumn();
1856 Returns the owning wxDataViewCtrl.
1858 wxDataViewCtrl
* GetOwner();
1861 Returns the renderer of this wxDataViewColumn.
1862 See also wxDataViewRenderer.
1864 wxDataViewRenderer
* GetRenderer();
1867 Returns @true if the column is reorderable.
1869 bool GetReorderable();
1872 Returns @true if the column is sortable.
1878 Returns the width of the column.
1883 Returns @true, if the sort order is ascending.
1884 See also SetSortOrder()
1886 bool IsSortOrderAscending();
1889 Set the alignment of the column header.
1891 void SetAlignment(wxAlignment align
);
1894 Set the bitmap of the column header.
1896 void SetBitmap(const wxBitmap
& bitmap
);
1899 Indicate wether the column can be reordered by the
1900 user using the mouse. This is typically implemented
1901 visually by dragging the header button around.
1903 void SetReorderable(bool reorderable
);
1906 Indicate the sort order if the implementation of the
1907 wxDataViewCtrl supports it, most commonly by showing
1910 void SetSortOrder(bool ascending
);
1913 Indicate that the column is sortable. This does
1914 not show any sorting indicate yet, but it does
1915 make the column header clickable. Call
1917 afterwards to actually make the sort indicator appear.
1918 If @a sortable is @false, the column header is
1919 no longer clickable and the sort indicator (little
1920 arrow) will disappear.
1922 void SetSortable(bool sortable
);
1925 Set the title of the column header to @e title.
1927 void SetTitle(const wxString
& title
);