1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDataView* classes
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
11 @class wxDataViewModel
13 wxDataViewModel is the base class for all data model to be displayed by a
16 All other models derive from it and must implement its pure virtual functions
17 in order to define a complete data model. In detail, you need to override
18 wxDataViewModel::IsContainer, wxDataViewModel::GetParent, wxDataViewModel::GetChildren,
19 wxDataViewModel::GetColumnCount, wxDataViewModel::GetColumnType and
20 wxDataViewModel::GetValue in order to define the data model which acts as an
21 interface between your actual data and the wxDataViewCtrl.
23 Since you will usually also allow the wxDataViewCtrl to change your data
24 through its graphical interface, you will also have to override
25 wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change
26 to some data has been committed.
28 wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant
29 to store data and its type in a generic way. wxVariant can be extended to contain
30 almost any data without changes to the original class.
32 The data that is presented through this data model is expected to change at
33 run-time. You need to inform the data model when a change happened.
34 Depending on what happened you need to call one of the following methods:
35 - wxDataViewModel::ValueChanged,
36 - wxDataViewModel::ItemAdded,
37 - wxDataViewModel::ItemDeleted,
38 - wxDataViewModel::ItemChanged,
39 - wxDataViewModel::Cleared.
41 There are plural forms for notification of addition, change or removal of
42 several item at once. See:
43 - wxDataViewModel::ItemsAdded,
44 - wxDataViewModel::ItemsDeleted,
45 - wxDataViewModel::ItemsChanged.
47 Note that wxDataViewModel does not define the position or index of any item
48 in the control because different controls might display the same data differently.
49 wxDataViewModel does provide a wxDataViewModel::Compare method which the
50 wxDataViewCtrl may use to sort the data either in conjunction with a column
51 header or without (see wxDataViewModel::HasDefaultCompare).
53 This class maintains a list of wxDataViewModelNotifier which link this class
54 to the specific implementations on the supported platforms so that e.g. calling
55 wxDataViewModel::ValueChanged on this model will just call
56 wxDataViewModelNotifier::ValueChanged for each notifier that has been added.
57 You can also add your own notifier in order to get informed about any changes
58 to the data in the list model.
60 Currently wxWidgets provides the following models apart from the base model:
61 wxDataViewIndexListModel, wxDataViewVirtualListModel, wxDataViewTreeStore,
64 Note that wxDataViewModel is reference counted, derives from wxRefCounter
65 and cannot be deleted directly as it can be shared by several wxDataViewCtrls.
66 This implies that you need to decrease the reference count after
67 associating the model with a control like this:
70 wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
71 wxDataViewModel *musicModel = new MyMusicModel;
72 m_musicCtrl->AssociateModel( musicModel );
73 musicModel->DecRef(); // avoid memory leak !!
81 class wxDataViewModel
: public wxRefCounter
90 Adds a wxDataViewModelNotifier to the model.
92 void AddNotifier(wxDataViewModelNotifier
* notifier
);
95 Change the value of the given item and update the control to reflect
98 This function simply calls SetValue() and, if it succeeded,
106 The item (row) to update.
108 The column to update.
110 @true if both SetValue() and ValueChanged() returned @true.
112 bool ChangeValue(const wxVariant
& variant
,
113 const wxDataViewItem
& item
,
117 Called to inform the model that all data has been cleared.
118 The control will reread the data from the model again.
120 virtual bool Cleared();
123 The compare function to be used by control. The default compare function
124 sorts by container and other items separately and in ascending order.
125 Override this for a different sorting behaviour.
127 @see HasDefaultCompare().
129 virtual int Compare(const wxDataViewItem
& item1
,
130 const wxDataViewItem
& item2
,
132 bool ascending
) const;
135 Override this to indicate that the item has special font attributes.
136 This only affects the wxDataViewTextRendererText renderer.
138 @see wxDataViewItemAttr.
140 virtual bool GetAttr(const wxDataViewItem
& item
, unsigned int col
,
141 wxDataViewItemAttr
& attr
);
144 Override this so the control can query the child items of an item.
145 Returns the number of items.
147 virtual unsigned int GetChildren(const wxDataViewItem
& item
,
148 wxDataViewItemArray
& children
) const = 0;
151 Override this to indicate the number of columns in the model.
153 virtual unsigned int GetColumnCount() const = 0;
156 Override this to indicate what type of data is stored in the
157 column specified by @a col.
159 This should return a string indicating the type of data as reported by wxVariant.
161 virtual wxString
GetColumnType(unsigned int col
) const = 0;
164 Override this to indicate which wxDataViewItem representing the parent
165 of @a item or an invalid wxDataViewItem if the the root item is
168 virtual wxDataViewItem
GetParent(const wxDataViewItem
& item
) const = 0;
171 Override this to indicate the value of @a item.
172 A wxVariant is used to store the data.
174 virtual void GetValue(wxVariant
& variant
, const wxDataViewItem
& item
,
175 unsigned int col
) const = 0;
178 Override this method to indicate if a container item merely acts as a
179 headline (or for categorisation) or if it also acts a normal item with
180 entries for futher columns. By default returns @false.
182 virtual bool HasContainerColumns(const wxDataViewItem
& item
) const;
185 Override this to indicate that the model provides a default compare
186 function that the control should use if no wxDataViewColumn has been
187 chosen for sorting. Usually, the user clicks on a column header for
188 sorting, the data will be sorted alphanumerically.
190 If any other order (e.g. by index or order of appearance) is required,
191 then this should be used.
192 See wxDataViewIndexListModel for a model which makes use of this.
194 virtual bool HasDefaultCompare() const;
197 Return true if there is a value in the given column of this item.
199 All normal items have values in all columns but the container items
200 only show their label in the first column (@a col == 0) by default (but
201 see HasContainerColumns()). So this function always returns true for
202 the first column while for the other ones it returns true only if the
203 item is not a container or HasContainerColumns() was overridden to
208 bool HasValue(const wxDataViewItem
& item
, unsigned col
) const;
211 Override this to indicate of @a item is a container, i.e. if
212 it can have child items.
214 virtual bool IsContainer(const wxDataViewItem
& item
) const = 0;
217 Call this to inform the model that an item has been added to the data.
219 virtual bool ItemAdded(const wxDataViewItem
& parent
,
220 const wxDataViewItem
& item
);
223 Call this to inform the model that an item has changed.
225 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
226 event (in which the column fields will not be set) to the user.
228 virtual bool ItemChanged(const wxDataViewItem
& item
);
231 Call this to inform the model that an item has been deleted from the data.
233 virtual bool ItemDeleted(const wxDataViewItem
& parent
,
234 const wxDataViewItem
& item
);
237 Call this to inform the model that several items have been added to the data.
239 virtual bool ItemsAdded(const wxDataViewItem
& parent
,
240 const wxDataViewItemArray
& items
);
243 Call this to inform the model that several items have changed.
245 This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
246 events (in which the column fields will not be set) to the user.
248 virtual bool ItemsChanged(const wxDataViewItemArray
& items
);
251 Call this to inform the model that several items have been deleted.
253 virtual bool ItemsDeleted(const wxDataViewItem
& parent
,
254 const wxDataViewItemArray
& items
);
257 Remove the @a notifier from the list of notifiers.
259 void RemoveNotifier(wxDataViewModelNotifier
* notifier
);
262 Call this to initiate a resort after the sort function has been changed.
264 virtual void Resort();
267 This gets called in order to set a value in the data model.
269 The most common scenario is that the wxDataViewCtrl calls this method
270 after the user changed some data in the view.
272 This is the function you need to override in your derived class but if
273 you want to call it, ChangeValue() is usually more convenient as
274 otherwise you need to manually call ValueChanged() to update the
277 virtual bool SetValue(const wxVariant
& variant
,
278 const wxDataViewItem
& item
,
279 unsigned int col
) = 0;
282 Call this to inform this model that a value in the model has been changed.
283 This is also called from wxDataViewCtrl's internal editing code, e.g. when
284 editing a text field in the control.
286 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
289 virtual bool ValueChanged(const wxDataViewItem
& item
,
295 Destructor. This should not be called directly. Use DecRef() instead.
297 virtual ~wxDataViewModel();
303 @class wxDataViewIndexListModel
305 wxDataViewIndexListModel is a specialized data model which lets you address
306 an item by its position (row) rather than its wxDataViewItem (which you can
307 obtain from this class).
308 This model also provides its own wxDataViewIndexListModel::Compare
309 method which sorts the model's data by the index.
311 This model is not a virtual model since the control stores each wxDataViewItem.
312 Use wxDataViewVirtualListModel if you need to display millions of items or
313 have other reason to use a virtual control.
318 class wxDataViewIndexListModel
: public wxDataViewModel
324 wxDataViewIndexListModel(unsigned int initial_size
= 0);
329 virtual ~wxDataViewIndexListModel();
332 Compare method that sorts the items by their index.
334 int Compare(const wxDataViewItem
& item1
,
335 const wxDataViewItem
& item2
,
336 unsigned int column
, bool ascending
);
339 Override this to indicate that the row has special font attributes.
340 This only affects the wxDataViewTextRendererText() renderer.
342 @see wxDataViewItemAttr.
344 virtual bool GetAttrByRow(unsigned int row
, unsigned int col
,
345 wxDataViewItemAttr
& attr
);
348 Returns the wxDataViewItem at the given @e row.
350 wxDataViewItem
GetItem(unsigned int row
) const;
353 Returns the position of given @e item.
355 unsigned int GetRow(const wxDataViewItem
& item
) const;
358 Override this to allow getting values from the model.
360 virtual void GetValueByRow(wxVariant
& variant
, unsigned int row
,
361 unsigned int col
) const = 0;
364 Call this after if the data has to be read again from the model.
365 This is useful after major changes when calling the methods below
366 (possibly thousands of times) doesn't make sense.
368 void Reset(unsigned int new_size
);
371 Call this after a row has been appended to the model.
376 Call this after a row has been changed.
378 void RowChanged(unsigned int row
);
381 Call this after a row has been deleted.
383 void RowDeleted(unsigned int row
);
386 Call this after a row has been inserted at the given position.
388 void RowInserted(unsigned int before
);
391 Call this after a row has been prepended to the model.
396 Call this after a value has been changed.
398 void RowValueChanged(unsigned int row
, unsigned int col
);
401 Call this after rows have been deleted.
402 The array will internally get copied and sorted in descending order so
403 that the rows with the highest position will be deleted first.
405 void RowsDeleted(const wxArrayInt
& rows
);
408 Called in order to set a value in the model.
410 virtual bool SetValueByRow(const wxVariant
& variant
, unsigned int row
,
411 unsigned int col
) = 0;
417 @class wxDataViewVirtualListModel
419 wxDataViewVirtualListModel is a specialized data model which lets you address
420 an item by its position (row) rather than its wxDataViewItem and as such offers
421 the exact same interface as wxDataViewIndexListModel.
422 The important difference is that under platforms other than OS X, using this
423 model will result in a truly virtual control able to handle millions of items
424 as the control doesn't store any item (a feature not supported by the
425 Carbon API under OS X).
427 @see wxDataViewIndexListModel for the API.
432 class wxDataViewVirtualListModel
: public wxDataViewModel
438 wxDataViewVirtualListModel(unsigned int initial_size
= 0);
444 @class wxDataViewItemAttr
446 This class is used to indicate to a wxDataViewCtrl that a certain item
447 (see wxDataViewItem) has extra font attributes for its renderer.
448 For this, it is required to override wxDataViewModel::GetAttr.
450 Attributes are currently only supported by wxDataViewTextRendererText.
455 class wxDataViewItemAttr
461 wxDataViewItemAttr();
464 Call this to indicate that the item shall be displayed in bold text.
466 void SetBold(bool set
);
469 Call this to indicate that the item shall be displayed with that colour.
471 void SetColour(const wxColour
& colour
);
474 Call this to indicate that the item shall be displayed in italic text.
476 void SetItalic(bool set
);
482 @class wxDataViewItem
484 wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl
485 in a persistent way, i.e. indepent of the position of the item in the control
486 or changes to its contents.
488 It must hold a unique ID of type @e void* in its only field and can be converted
491 If the ID is @NULL the wxDataViewItem is invalid and wxDataViewItem::IsOk will
492 return @false which used in many places in the API of wxDataViewCtrl to
493 indicate that e.g. no item was found. An ID of @NULL is also used to indicate
494 the invisible root. Examples for this are wxDataViewModel::GetParent and
495 wxDataViewModel::GetChildren.
507 wxDataViewItem(void* id
= NULL
);
508 wxDataViewItem(const wxDataViewItem
& item
);
517 Returns @true if the ID is not @NULL.
525 @class wxDataViewCtrl
527 wxDataViewCtrl is a control to display data either in a tree like fashion or
528 in a tabular form or both.
530 If you only need to display a simple tree structure with an API more like the
531 older wxTreeCtrl class, then the specialized wxDataViewTreeCtrl can be used.
532 Likewise, if you only want to display simple table structure you can use
533 the specialized wxDataViewListCtrl class. Both wxDataViewTreeCtrl and
534 wxDataViewListCtrl can be used without defining your own wxDataViewModel.
536 A wxDataViewItem is used to represent a (visible) item in the control.
538 Unlike wxListCtrl, wxDataViewCtrl doesn't get its data from the user through
539 virtual functions or by setting it directly. Instead you need to write your own
540 wxDataViewModel and associate it with this control.
541 Then you need to add a number of wxDataViewColumn to this control to define
542 what each column shall display. Each wxDataViewColumn in turn owns 1 instance
543 of a wxDataViewRenderer to render its cells.
545 A number of standard renderers for rendering text, dates, images, toggle,
546 a progress bar etc. are provided. Additionally, the user can write custom
547 renderers deriving from wxDataViewCustomRenderer for displaying anything.
549 All data transfer from the control to the model and the user code is done
550 through wxVariant which can be extended to support more data formats as necessary.
551 Accordingly, all type information uses the strings returned from wxVariant::GetType.
555 Single selection mode. This is the default.
556 @style{wxDV_MULTIPLE}
557 Multiple selection mode.
558 @style{wxDV_ROW_LINES}
559 Use alternating colours for rows if supported by platform and theme.
560 @style{wxDV_HORIZ_RULES}
561 Display fine rules between row if supported.
562 @style{wxDV_VERT_RULES}
563 Display fine rules between columns is supported.
564 @style{wxDV_VARIABLE_LINE_HEIGHT}
565 Allow variable line heights.
566 This can be inefficient when displaying large number of items.
569 @beginEventEmissionTable{wxDataViewEvent}
570 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
571 Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
572 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
573 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
574 @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}
575 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. This
576 event can be vetoed in order to prevent editing on an item by item
577 basis. Still experimental.
578 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
579 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
580 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
581 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
582 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
583 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
584 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
585 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
586 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
587 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
588 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
589 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
590 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
591 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
592 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
593 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
594 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
595 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
596 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
597 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
598 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
599 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
600 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
601 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
602 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
603 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
604 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
605 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
606 @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
607 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
612 @appearance{dataviewctrl.png}
614 class wxDataViewCtrl
: public wxControl
623 Constructor. Calls Create().
625 wxDataViewCtrl(wxWindow
* parent
, wxWindowID id
,
626 const wxPoint
& pos
= wxDefaultPosition
,
627 const wxSize
& size
= wxDefaultSize
,
629 const wxValidator
& validator
= wxDefaultValidator
);
634 virtual ~wxDataViewCtrl();
637 Appends a wxDataViewColumn to the control. Returns @true on success.
639 Note that there is a number of short cut methods which implicitly create
640 a wxDataViewColumn and a wxDataViewRenderer for it (see below).
642 virtual bool AppendColumn(wxDataViewColumn
* col
);
645 Prepends a wxDataViewColumn to the control. Returns @true on success.
647 Note that there is a number of short cut methods which implicitly create
648 a wxDataViewColumn and a wxDataViewRenderer for it.
650 virtual bool PrependColumn(wxDataViewColumn
* col
);
653 Inserts a wxDataViewColumn to the control. Returns @true on success.
655 virtual bool InsertColumn(unsigned int pos
, wxDataViewColumn
* col
);
659 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
660 created in the function or @NULL on failure.
662 wxDataViewColumn
* AppendBitmapColumn(const wxString
& label
,
663 unsigned int model_column
,
664 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
666 wxAlignment align
= wxALIGN_CENTER
,
667 int flags
= wxDATAVIEW_COL_RESIZABLE
);
668 wxDataViewColumn
* AppendBitmapColumn(const wxBitmap
& label
,
669 unsigned int model_column
,
670 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
672 wxAlignment align
= wxALIGN_CENTER
,
673 int flags
= wxDATAVIEW_COL_RESIZABLE
);
678 Appends a column for rendering a date. Returns the wxDataViewColumn
679 created in the function or @NULL on failure.
681 @note The @a align parameter is applied to both the column header and
684 wxDataViewColumn
* AppendDateColumn(const wxString
& label
,
685 unsigned int model_column
,
686 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
688 wxAlignment align
= wxALIGN_NOT
,
689 int flags
= wxDATAVIEW_COL_RESIZABLE
);
690 wxDataViewColumn
* AppendDateColumn(const wxBitmap
& label
,
691 unsigned int model_column
,
692 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
694 wxAlignment align
= wxALIGN_NOT
,
695 int flags
= wxDATAVIEW_COL_RESIZABLE
);
700 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
701 created in the function or @NULL on failure.
702 This method uses the wxDataViewIconTextRenderer class.
704 @note The @a align parameter is applied to both the column header and
707 wxDataViewColumn
* AppendIconTextColumn(const wxString
& label
,
708 unsigned int model_column
,
709 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
711 wxAlignment align
= wxALIGN_NOT
,
712 int flags
= wxDATAVIEW_COL_RESIZABLE
);
713 wxDataViewColumn
* AppendIconTextColumn(const wxBitmap
& label
,
714 unsigned int model_column
,
715 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
717 wxAlignment align
= wxALIGN_NOT
,
718 int flags
= wxDATAVIEW_COL_RESIZABLE
);
723 Appends a column for rendering a progress indicator. Returns the
724 wxDataViewColumn created in the function or @NULL on failure.
726 @note The @a align parameter is applied to both the column header and
729 wxDataViewColumn
* AppendProgressColumn(const wxString
& label
,
730 unsigned int model_column
,
731 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
733 wxAlignment align
= wxALIGN_CENTER
,
734 int flags
= wxDATAVIEW_COL_RESIZABLE
);
735 wxDataViewColumn
* AppendProgressColumn(const wxBitmap
& label
,
736 unsigned int model_column
,
737 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
739 wxAlignment align
= wxALIGN_CENTER
,
740 int flags
= wxDATAVIEW_COL_RESIZABLE
);
745 Appends a column for rendering text. Returns the wxDataViewColumn
746 created in the function or @NULL on failure.
748 @note The @a align parameter is applied to both the column header and
751 wxDataViewColumn
* AppendTextColumn(const wxString
& label
,
752 unsigned int model_column
,
753 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
755 wxAlignment align
= wxALIGN_NOT
,
756 int flags
= wxDATAVIEW_COL_RESIZABLE
);
757 wxDataViewColumn
* AppendTextColumn(const wxBitmap
& label
,
758 unsigned int model_column
,
759 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
761 wxAlignment align
= wxALIGN_NOT
,
762 int flags
= wxDATAVIEW_COL_RESIZABLE
);
767 Appends a column for rendering a toggle. Returns the wxDataViewColumn
768 created in the function or @NULL on failure.
770 @note The @a align parameter is applied to both the column header and
773 wxDataViewColumn
* AppendToggleColumn(const wxString
& label
,
774 unsigned int model_column
,
775 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
777 wxAlignment align
= wxALIGN_CENTER
,
778 int flags
= wxDATAVIEW_COL_RESIZABLE
);
779 wxDataViewColumn
* AppendToggleColumn(const wxBitmap
& label
,
780 unsigned int model_column
,
781 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
783 wxAlignment align
= wxALIGN_CENTER
,
784 int flags
= wxDATAVIEW_COL_RESIZABLE
);
788 Associates a wxDataViewModel with the control.
789 This increases the reference count of the model by 1.
791 virtual bool AssociateModel(wxDataViewModel
* model
);
796 virtual bool ClearColumns();
801 virtual void Collapse(const wxDataViewItem
& item
);
804 Create the control. Useful for two step creation.
806 bool Create(wxWindow
* parent
, wxWindowID id
,
807 const wxPoint
& pos
= wxDefaultPosition
,
808 const wxSize
& size
= wxDefaultSize
,
810 const wxValidator
& validator
= wxDefaultValidator
);
813 Deletes given column.
815 virtual bool DeleteColumn(wxDataViewColumn
* column
);
818 Enable drag operations using the given @a format.
820 virtual bool EnableDragSource( const wxDataFormat
&format
);
823 Enable drop operations using the given @a format.
825 virtual bool EnableDropTarget( const wxDataFormat
&format
);
828 Call this to ensure that the given item is visible.
830 virtual void EnsureVisible(const wxDataViewItem
& item
,
831 const wxDataViewColumn
* column
= NULL
);
836 virtual void Expand(const wxDataViewItem
& item
);
839 Expands all ancestors of the @a item. This method also
840 ensures that the item itself as well as all ancestor
841 items have been read from the model by the control.
843 virtual void ExpandAncestors( const wxDataViewItem
& item
);
846 Returns pointer to the column. @a pos refers to the position in the
847 control which may change after reordering columns by the user.
849 virtual wxDataViewColumn
* GetColumn(unsigned int pos
) const;
852 Returns the number of columns.
854 virtual unsigned int GetColumnCount() const;
857 Returns the position of the column or -1 if not found in the control.
859 virtual int GetColumnPosition(const wxDataViewColumn
* column
) const;
862 Returns column containing the expanders.
864 wxDataViewColumn
* GetExpanderColumn() const;
869 int GetIndent() const;
874 virtual wxRect
GetItemRect(const wxDataViewItem
& item
,
875 const wxDataViewColumn
* col
= NULL
) const;
878 Returns pointer to the data model associated with the control (if any).
880 wxDataViewModel
* GetModel();
883 Returns first selected item or an invalid item if none is selected.
885 virtual wxDataViewItem
GetSelection() const;
888 Fills @a sel with currently selected items and returns their number.
890 virtual int GetSelections(wxDataViewItemArray
& sel
) const;
893 Returns the wxDataViewColumn currently responsible for sorting
894 or @NULL if none has been selected.
896 virtual wxDataViewColumn
* GetSortingColumn() const;
901 virtual void HitTest(const wxPoint
& point
, wxDataViewItem
& item
,
902 wxDataViewColumn
*& col
) const;
905 Return @true if the item is expanded.
907 virtual bool IsExpanded(const wxDataViewItem
& item
) const;
910 Return @true if the item is selected.
912 virtual bool IsSelected(const wxDataViewItem
& item
) const;
915 Select the given item.
917 virtual void Select(const wxDataViewItem
& item
);
922 virtual void SelectAll();
925 Set which column shall contain the tree-like expanders.
927 void SetExpanderColumn(wxDataViewColumn
* col
);
930 Sets the indendation.
932 void SetIndent(int indent
);
935 Sets the selection to the array of wxDataViewItems.
937 virtual void SetSelections(const wxDataViewItemArray
& sel
);
940 Unselect the given item.
942 virtual void Unselect(const wxDataViewItem
& item
);
946 This method only has effect if multiple selections are allowed.
948 virtual void UnselectAll();
954 @class wxDataViewModelNotifier
956 A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
957 its notification interface.
958 See the documentation of that class for further information.
963 class wxDataViewModelNotifier
969 wxDataViewModelNotifier();
974 virtual ~wxDataViewModelNotifier();
977 Called by owning model.
979 virtual bool Cleared() = 0;
982 Get owning wxDataViewModel.
984 wxDataViewModel
* GetOwner() const;
987 Called by owning model.
989 virtual bool ItemAdded(const wxDataViewItem
& parent
,
990 const wxDataViewItem
& item
) = 0;
993 Called by owning model.
995 virtual bool ItemChanged(const wxDataViewItem
& item
) = 0;
998 Called by owning model.
1000 virtual bool ItemDeleted(const wxDataViewItem
& parent
,
1001 const wxDataViewItem
& item
) = 0;
1004 Called by owning model.
1006 virtual bool ItemsAdded(const wxDataViewItem
& parent
,
1007 const wxDataViewItemArray
& items
);
1010 Called by owning model.
1012 virtual bool ItemsChanged(const wxDataViewItemArray
& items
);
1015 Called by owning model.
1017 virtual bool ItemsDeleted(const wxDataViewItem
& parent
,
1018 const wxDataViewItemArray
& items
);
1021 Called by owning model.
1023 virtual void Resort() = 0;
1026 Set owner of this notifier. Used internally.
1028 void SetOwner(wxDataViewModel
* owner
);
1031 Called by owning model.
1033 virtual bool ValueChanged(const wxDataViewItem
& item
, unsigned int col
) = 0;
1038 The mode of a data-view cell; see wxDataViewRenderer for more info.
1040 enum wxDataViewCellMode
1042 wxDATAVIEW_CELL_INERT
,
1045 Indicates that the user can double click the cell and something will
1046 happen (e.g. a window for editing a date will pop up).
1048 wxDATAVIEW_CELL_ACTIVATABLE
,
1051 Indicates that the user can edit the data in-place, i.e. an control
1052 will show up after a slow click on the cell. This behaviour is best
1053 known from changing the filename in most file managers etc.
1055 wxDATAVIEW_CELL_EDITABLE
1059 The values of this enum controls how a wxDataViewRenderer should display
1060 its contents in a cell.
1062 enum wxDataViewCellRenderState
1064 wxDATAVIEW_CELL_SELECTED
= 1,
1065 wxDATAVIEW_CELL_PRELIT
= 2,
1066 wxDATAVIEW_CELL_INSENSITIVE
= 4,
1067 wxDATAVIEW_CELL_FOCUSED
= 8
1071 @class wxDataViewRenderer
1073 This class is used by wxDataViewCtrl to render the individual cells.
1074 One instance of a renderer class is owned by a wxDataViewColumn.
1075 There is a number of ready-to-use renderers provided:
1076 - wxDataViewTextRenderer,
1077 - wxDataViewIconTextRenderer,
1078 - wxDataViewToggleRenderer,
1079 - wxDataViewProgressRenderer,
1080 - wxDataViewBitmapRenderer,
1081 - wxDataViewDateRenderer,
1082 - wxDataViewSpinRenderer.
1084 Additionally, the user can write own renderers by deriving from
1085 wxDataViewCustomRenderer.
1087 The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1088 by the constructors respectively controls what actions the cell data allows
1089 and how the renderer should display its contents in a cell.
1094 class wxDataViewRenderer
: public wxObject
1100 wxDataViewRenderer(const wxString
& varianttype
,
1101 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1102 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1105 Enable or disable replacing parts of the item text with ellipsis to
1106 make it fit the column width.
1108 This method only makes sense for the renderers working with text, such
1109 as wxDataViewTextRenderer or wxDataViewIconTextRenderer.
1111 By default wxELLIPSIZE_MIDDLE is used.
1114 Ellipsization mode, use wxELLIPSIZE_NONE to disable.
1118 void EnableEllipsize(wxEllipsizeMode mode
= wxELLIPSIZE_MIDDLE
);
1121 Disable replacing parts of the item text with ellipsis.
1123 If ellipsizing is disabled, the string will be truncated if it doesn't
1126 This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode.
1130 void DisableEllipsize();
1133 Returns the alignment. See SetAlignment()
1135 virtual int GetAlignment() const;
1138 Returns the ellipsize mode used by the renderer.
1140 If the return value is wxELLIPSIZE_NONE, the text is simply truncated
1143 @see EnableEllipsize()
1145 wxEllipsizeMode
GetEllipsizeMode() const;
1148 Returns the cell mode.
1150 virtual wxDataViewCellMode
GetMode() const;
1153 Returns pointer to the owning wxDataViewColumn.
1155 wxDataViewColumn
* GetOwner() const;
1158 This methods retrieves the value from the renderer in order to
1159 transfer the value back to the data model.
1161 Returns @false on failure.
1163 virtual bool GetValue(wxVariant
& value
) const = 0;
1166 Returns a string with the type of the wxVariant supported by this renderer.
1168 wxString
GetVariantType() const;
1171 Sets the alignment of the renderer's content.
1172 The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1173 should have the same alignment as the column header.
1175 The method is not implemented under OS X and the renderer always aligns
1176 its contents as the column header on that platform. The other platforms
1177 support both vertical and horizontal alignment.
1179 virtual void SetAlignment( int align
);
1181 Sets the owning wxDataViewColumn.
1182 This is usually called from within wxDataViewColumn.
1184 void SetOwner(wxDataViewColumn
* owner
);
1187 Set the value of the renderer (and thus its cell) to @a value.
1188 The internal code will then render this cell with this data.
1190 virtual bool SetValue(const wxVariant
& value
) = 0;
1193 Before data is committed to the data model, it is passed to this
1194 method where it can be checked for validity. This can also be
1195 used for checking a valid range or limiting the user input in
1196 a certain aspect (e.g. max number of characters or only alphanumeric
1197 input, ASCII only etc.). Return @false if the value is not valid.
1199 Please note that due to implementation limitations, this validation
1200 is done after the editing control already is destroyed and the
1201 editing process finished.
1203 virtual bool Validate(wxVariant
& value
);
1209 @class wxDataViewTextRenderer
1211 wxDataViewTextRenderer is used for rendering text.
1212 It supports in-place editing if desired.
1217 class wxDataViewTextRenderer
: public wxDataViewRenderer
1223 wxDataViewTextRenderer(const wxString
& varianttype
= "string",
1224 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1225 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1231 @class wxDataViewIconTextRenderer
1233 The wxDataViewIconTextRenderer class is used to display text with
1234 a small icon next to it as it is typically done in a file manager.
1236 This classes uses the wxDataViewIconText helper class to store its data.
1237 wxDataViewIonText can be converted to and from a wxVariant using the left shift
1243 class wxDataViewIconTextRenderer
: public wxDataViewRenderer
1249 wxDataViewIconTextRenderer(const wxString
& varianttype
= "wxDataViewIconText",
1250 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1251 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1257 @class wxDataViewProgressRenderer
1259 This class is used by wxDataViewCtrl to render progress bars.
1264 class wxDataViewProgressRenderer
: public wxDataViewRenderer
1270 wxDataViewProgressRenderer(const wxString
& label
= wxEmptyString
,
1271 const wxString
& varianttype
= "long",
1272 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1273 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1279 @class wxDataViewSpinRenderer
1281 This is a specialized renderer for rendering integer values.
1282 It supports modifying the values in-place by using a wxSpinCtrl.
1283 The renderer only support variants of type @e long.
1288 class wxDataViewSpinRenderer
: public wxDataViewCustomRenderer
1293 @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1295 wxDataViewSpinRenderer(int min
, int max
,
1296 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1297 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1303 @class wxDataViewToggleRenderer
1305 This class is used by wxDataViewCtrl to render toggle controls.
1310 class wxDataViewToggleRenderer
: public wxDataViewRenderer
1316 wxDataViewToggleRenderer(const wxString
& varianttype
= "bool",
1317 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1318 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1324 @class wxDataViewDateRenderer
1326 This class is used by wxDataViewCtrl to render calendar controls.
1331 class wxDataViewDateRenderer
: public wxDataViewRenderer
1337 wxDataViewDateRenderer(const wxString
& varianttype
= "datetime",
1338 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1339 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1345 @class wxDataViewCustomRenderer
1347 You need to derive a new class from wxDataViewCustomRenderer in
1348 order to write a new renderer.
1350 You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1351 wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1353 If you want your renderer to support in-place editing then you also need to override
1354 wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1355 and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1357 Note that a special event handler will be pushed onto that editor control
1358 which handles @e \<ENTER\> and focus out events in order to end the editing.
1363 class wxDataViewCustomRenderer
: public wxDataViewRenderer
1369 wxDataViewCustomRenderer(const wxString
& varianttype
= "string",
1370 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1371 int align
= -1, bool no_init
= false);
1376 virtual ~wxDataViewCustomRenderer();
1379 Override this to react to double clicks or ENTER.
1380 This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1382 virtual bool Activate( wxRect cell
,
1383 wxDataViewModel
* model
,
1384 const wxDataViewItem
& item
,
1388 Override this to create the actual editor control once editing
1391 @a parent is the parent of the editor control, @a labelRect indicates the
1392 position and size of the editor control and @a value is its initial value:
1396 return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1397 labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1401 virtual wxControl
* CreateEditorCtrl(wxWindow
* parent
,
1403 const wxVariant
& value
);
1406 Create DC on request. Internal.
1408 virtual wxDC
* GetDC();
1411 Return size required to show content.
1413 virtual wxSize
GetSize() const = 0;
1416 Overrride this so that the renderer can get the value from the editor
1417 control (pointed to by @a editor):
1420 wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1421 long l = sc->GetValue();
1427 virtual bool GetValueFromEditorCtrl(wxControl
* editor
,
1431 Override this and make it return @true in order to
1432 indicate that this renderer supports in-place editing.
1434 virtual bool HasEditorCtrl() const;
1437 Overrride this to react to a left click.
1438 This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1440 virtual bool LeftClick( wxPoint cursor
,
1442 wxDataViewModel
* model
,
1443 const wxDataViewItem
& item
,
1447 Override this to render the cell.
1448 Before this is called, wxDataViewRenderer::SetValue was called
1449 so that this instance knows what to render.
1451 virtual bool Render(wxRect cell
, wxDC
* dc
, int state
) = 0;
1454 This method should be called from within Render() whenever you need to
1456 This will ensure that the correct colour, font and vertical alignment will
1457 be chosen so the text will look the same as text drawn by native renderers.
1459 void RenderText(const wxString
& text
, int xoffset
, wxRect cell
,
1460 wxDC
* dc
, int state
);
1463 Overrride this to start a drag operation. Not yet supported.
1465 virtual bool StartDrag(wxPoint cursor
, wxRect cell
,
1466 wxDataViewModel
* model
,
1467 const wxDataViewItem
& item
,
1474 @class wxDataViewBitmapRenderer
1476 This class is used by wxDataViewCtrl to render bitmap controls.
1481 class wxDataViewBitmapRenderer
: public wxDataViewRenderer
1487 wxDataViewBitmapRenderer(const wxString
& varianttype
= "wxBitmap",
1488 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1489 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1494 The flags used by wxDataViewColumn.
1495 Can be combined together.
1497 enum wxDataViewColumnFlags
1499 wxDATAVIEW_COL_RESIZABLE
= 1,
1500 wxDATAVIEW_COL_SORTABLE
= 2,
1501 wxDATAVIEW_COL_REORDERABLE
= 4,
1502 wxDATAVIEW_COL_HIDDEN
= 8
1506 @class wxDataViewColumn
1508 This class represents a column in a wxDataViewCtrl.
1509 One wxDataViewColumn is bound to one column in the data model to which the
1510 wxDataViewCtrl has been associated.
1512 An instance of wxDataViewRenderer is used by this class to render its data.
1517 class wxDataViewColumn
: public wxSettableHeaderColumn
1521 Constructs a text column.
1524 The title of the column.
1526 The class which will render the contents of this column.
1528 The index of the model's column which is associated with this object.
1530 The width of the column.
1531 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1533 The alignment of the column title.
1535 One or more flags of the ::wxDataViewColumnFlags enumeration.
1537 wxDataViewColumn(const wxString
& title
,
1538 wxDataViewRenderer
* renderer
,
1539 unsigned int model_column
,
1540 int width
= wxDVC_DEFAULT_WIDTH
,
1541 wxAlignment align
= wxALIGN_CENTER
,
1542 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1545 Constructs a bitmap column.
1548 The bitmap of the column.
1550 The class which will render the contents of this column.
1552 The index of the model's column which is associated with this object.
1554 The width of the column.
1555 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1557 The alignment of the column title.
1559 One or more flags of the ::wxDataViewColumnFlags enumeration.
1561 wxDataViewColumn(const wxBitmap
& bitmap
,
1562 wxDataViewRenderer
* renderer
,
1563 unsigned int model_column
,
1564 int width
= wxDVC_DEFAULT_WIDTH
,
1565 wxAlignment align
= wxALIGN_CENTER
,
1566 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1569 Returns the index of the column of the model, which this
1570 wxDataViewColumn is displaying.
1572 unsigned int GetModelColumn() const;
1575 Returns the owning wxDataViewCtrl.
1577 wxDataViewCtrl
* GetOwner() const;
1580 Returns the renderer of this wxDataViewColumn.
1582 @see wxDataViewRenderer.
1584 wxDataViewRenderer
* GetRenderer() const;
1590 @class wxDataViewListCtrl
1592 This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
1593 and forwards most of its API to that class.
1595 The purpose of this class is to offer a simple way to display and
1596 edit a small table of data without having to write your own wxDataViewModel.
1599 wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
1601 listctrl->AppendToggleColumn( "Toggle" );
1602 listctrl->AppendTextColumn( "Text" );
1604 wxVector<wxVariant> data;
1605 data.push_back( wxVariant(true) );
1606 data.push_back( wxVariant("row 1") );
1607 listctrl->AppendItem( data );
1610 data.push_back( wxVariant(false) );
1611 data.push_back( wxVariant("row 3") );
1612 listctrl->AppendItem( data );
1616 See wxDataViewCtrl for the list of supported styles.
1619 @beginEventEmissionTable
1620 See wxDataViewCtrl for the list of events emitted by this class.
1626 class wxDataViewListCtrl
: public wxDataViewCtrl
1632 wxDataViewListCtrl();
1635 Constructor. Calls Create().
1637 wxDataViewListCtrl( wxWindow
*parent
, wxWindowID id
,
1638 const wxPoint
& pos
= wxDefaultPosition
,
1639 const wxSize
& size
= wxDefaultSize
, long style
= wxDV_ROW_LINES
,
1640 const wxValidator
& validator
= wxDefaultValidator
);
1643 Destructor. Deletes the image list if any.
1645 ~wxDataViewListCtrl();
1648 Creates the control and a wxDataViewListStore as its internal model.
1650 bool Create( wxWindow
*parent
, wxWindowID id
,
1651 const wxPoint
& pos
= wxDefaultPosition
,
1652 const wxSize
& size
= wxDefaultSize
, long style
= wxDV_ROW_LINES
,
1653 const wxValidator
& validator
= wxDefaultValidator
);
1659 wxDataViewListStore
*GetStore();
1660 const wxDataViewListStore
*GetStore() const;
1664 @name Column management functions
1669 Appends a column to the control and additionally appends a
1670 column to the store with the type string.
1672 virtual void AppendColumn( wxDataViewColumn
*column
);
1675 Appends a column to the control and additionally appends a
1676 column to the list store with the type @a varianttype.
1678 void AppendColumn( wxDataViewColumn
*column
, const wxString
&varianttype
);
1681 Appends a text column to the control and the store.
1683 See wxDataViewColumn::wxDataViewColumn for more info about
1686 wxDataViewColumn
*AppendTextColumn( const wxString
&label
,
1687 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1688 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
1689 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1692 Appends a toggle column to the control and the store.
1694 See wxDataViewColumn::wxDataViewColumn for more info about
1697 wxDataViewColumn
*AppendToggleColumn( const wxString
&label
,
1698 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1699 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
1700 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1703 Appends a progress column to the control and the store.
1705 See wxDataViewColumn::wxDataViewColumn for more info about
1708 wxDataViewColumn
*AppendProgressColumn( const wxString
&label
,
1709 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1710 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
1711 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1714 Appends an icon-and-text column to the control and the store.
1716 See wxDataViewColumn::wxDataViewColumn for more info about
1719 wxDataViewColumn
*AppendIconTextColumn( const wxString
&label
,
1720 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1721 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
1722 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1725 Inserts a column to the control and additionally inserts a
1726 column to the store with the type string.
1728 virtual void InsertColumn( unsigned int pos
, wxDataViewColumn
*column
);
1731 Inserts a column to the control and additionally inserts a
1732 column to the list store with the type @a varianttype.
1734 void InsertColumn( unsigned int pos
, wxDataViewColumn
*column
,
1735 const wxString
&varianttype
);
1738 Prepends a column to the control and additionally prepends a
1739 column to the store with the type string.
1741 virtual void PrependColumn( wxDataViewColumn
*column
);
1744 Prepends a column to the control and additionally prepends a
1745 column to the list store with the type @a varianttype.
1747 void PrependColumn( wxDataViewColumn
*column
, const wxString
&varianttype
);
1753 @name Item management functions
1758 Appends an item (=row) to the control and store.
1760 void AppendItem( const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
1763 Prepends an item (=row) to the control and store.
1765 void PrependItem( const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
1768 Inserts an item (=row) to the control and store.
1770 void InsertItem( unsigned int row
, const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
1773 Delete the row at position @a row.
1775 void DeleteItem( unsigned row
);
1778 Delete all items (= all rows).
1780 void DeleteAllItems();
1783 Sets the value in the store and update the control.
1785 void SetValue( const wxVariant
&value
, unsigned int row
, unsigned int col
);
1788 Returns the value from the store.
1790 void GetValue( wxVariant
&value
, unsigned int row
, unsigned int col
);
1793 Sets the value in the store and update the control.
1795 This method assumes that the a string is stored in respective
1798 void SetTextValue( const wxString
&value
, unsigned int row
, unsigned int col
);
1801 Returns the value from the store.
1803 This method assumes that the a string is stored in respective
1806 wxString
GetTextValue( unsigned int row
, unsigned int col
) const;
1809 Sets the value in the store and update the control.
1811 This method assumes that the a boolean value is stored in
1814 void SetToggleValue( bool value
, unsigned int row
, unsigned int col
);
1817 Returns the value from the store.
1819 This method assumes that the a boolean value is stored in
1822 bool GetToggleValue( unsigned int row
, unsigned int col
) const;
1829 @class wxDataViewTreeCtrl
1831 This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
1832 and forwards most of its API to that class.
1833 Additionally, it uses a wxImageList to store a list of icons.
1835 The main purpose of this class is to provide a simple upgrade path for code
1839 See wxDataViewCtrl for the list of supported styles.
1842 @beginEventEmissionTable
1843 See wxDataViewCtrl for the list of events emitted by this class.
1848 @appearance{dataviewtreectrl.png}
1850 class wxDataViewTreeCtrl
: public wxDataViewCtrl
1856 wxDataViewTreeCtrl();
1863 wxDataViewTreeCtrl(wxWindow
* parent
, wxWindowID id
,
1864 const wxPoint
& pos
= wxDefaultPosition
,
1865 const wxSize
& size
= wxDefaultSize
,
1866 long style
= wxDV_NO_HEADER
| wxDV_ROW_LINES
,
1867 const wxValidator
& validator
= wxDefaultValidator
);
1870 Destructor. Deletes the image list if any.
1872 virtual ~wxDataViewTreeCtrl();
1875 Appends a container to the given @a parent.
1877 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1878 const wxString
& text
,
1881 wxClientData
* data
= NULL
);
1884 Appends an item to the given @a parent.
1886 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1887 const wxString
& text
,
1889 wxClientData
* data
= NULL
);
1892 Creates the control and a wxDataViewTreeStore as its internal model.
1894 The default tree column created by this method is an editable column
1895 using wxDataViewIconTextRenderer as its renderer.
1897 bool Create(wxWindow
* parent
, wxWindowID id
,
1898 const wxPoint
& pos
= wxDefaultPosition
,
1899 const wxSize
& size
= wxDefaultSize
,
1900 long style
= wxDV_NO_HEADER
| wxDV_ROW_LINES
,
1901 const wxValidator
& validator
= wxDefaultValidator
);
1904 Calls the identical method from wxDataViewTreeStore.
1906 void DeleteAllItems();
1909 Calls the identical method from wxDataViewTreeStore.
1911 void DeleteChildren(const wxDataViewItem
& item
);
1914 Calls the identical method from wxDataViewTreeStore.
1916 void DeleteItem(const wxDataViewItem
& item
);
1919 Calls the identical method from wxDataViewTreeStore.
1921 int GetChildCount(const wxDataViewItem
& parent
) const;
1924 Returns the image list.
1926 wxImageList
* GetImageList();
1929 Calls the identical method from wxDataViewTreeStore.
1931 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1934 Calls the identical method from wxDataViewTreeStore.
1936 const wxIcon
& GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1939 Calls the identical method from wxDataViewTreeStore.
1941 const wxIcon
& GetItemIcon(const wxDataViewItem
& item
) const;
1944 Calls the identical method from wxDataViewTreeStore.
1946 wxString
GetItemText(const wxDataViewItem
& item
) const;
1949 Calls the identical method from wxDataViewTreeStore.
1951 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1952 unsigned int pos
) const;
1958 wxDataViewTreeStore
* GetStore();
1959 const wxDataViewTreeStore
* GetStore() const;
1963 Calls the same method from wxDataViewTreeStore but uses
1964 an index position in the image list instead of a wxIcon.
1966 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1967 const wxDataViewItem
& previous
,
1968 const wxString
& text
,
1971 wxClientData
* data
= NULL
);
1974 Calls the same method from wxDataViewTreeStore but uses
1975 an index position in the image list instead of a wxIcon.
1977 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
1978 const wxDataViewItem
& previous
,
1979 const wxString
& text
,
1981 wxClientData
* data
= NULL
);
1984 Calls the same method from wxDataViewTreeStore but uses
1985 an index position in the image list instead of a wxIcon.
1987 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
1988 const wxString
& text
,
1991 wxClientData
* data
= NULL
);
1994 Calls the same method from wxDataViewTreeStore but uses
1995 an index position in the image list instead of a wxIcon.
1997 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
1998 const wxString
& text
,
2000 wxClientData
* data
= NULL
);
2003 Sets the image list.
2005 void SetImageList(wxImageList
* imagelist
);
2008 Calls the identical method from wxDataViewTreeStore.
2010 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
2013 Calls the identical method from wxDataViewTreeStore.
2015 void SetItemExpandedIcon(const wxDataViewItem
& item
,
2016 const wxIcon
& icon
);
2019 Calls the identical method from wxDataViewTreeStore.
2021 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
2024 Calls the identical method from wxDataViewTreeStore.
2026 void SetItemText(const wxDataViewItem
& item
,
2027 const wxString
& text
);
2032 @class wxDataViewListStore
2034 wxDataViewListStore is a specialised wxDataViewModel for storing
2035 a simple table of data. Since it derives from wxDataViewIndexListModel
2036 its data is be accessed by row (i.e. by index) instead of only
2039 This class actually stores the values (therefore its name)
2040 and implements all virtual methods from the base classes so it can be
2041 used directly without having to derive any class from it, but it is
2042 mostly used from within wxDataViewListCtrl.
2048 class wxDataViewListStore
: public wxDataViewIndexListModel
2054 wxDataViewListStore();
2059 ~wxDataViewListStore();
2062 Prepends a data column.
2064 @a variantype indicates the type of values store in the column.
2066 This does not automatically fill in any (default) values in
2067 rows which exist in the store already.
2069 void PrependColumn( const wxString
&varianttype
);
2072 Inserts a data column before @a pos.
2074 @a variantype indicates the type of values store in the column.
2076 This does not automatically fill in any (default) values in
2077 rows which exist in the store already.
2079 void InsertColumn( unsigned int pos
, const wxString
&varianttype
);
2082 Appends a data column.
2084 @a variantype indicates the type of values store in the column.
2086 This does not automatically fill in any (default) values in
2087 rows which exist in the store already.
2089 void AppendColumn( const wxString
&varianttype
);
2092 Appends an item (=row) and fills it with @a values.
2094 The values must match the values specifies in the column
2095 in number and type. No (default) values are filled in
2098 void AppendItem( const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
2101 Prepends an item (=row) and fills it with @a values.
2103 The values must match the values specifies in the column
2104 in number and type. No (default) values are filled in
2107 void PrependItem( const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
2110 Inserts an item (=row) and fills it with @a values.
2112 The values must match the values specifies in the column
2113 in number and type. No (default) values are filled in
2116 void InsertItem( unsigned int row
, const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
2119 Delete the item (=row) at position @a pos.
2121 void DeleteItem( unsigned pos
);
2124 Delete all item (=all rows) in the store.
2126 void DeleteAllItems();
2129 Overriden from wxDataViewModel
2131 virtual unsigned int GetColumnCount() const;
2134 Overriden from wxDataViewModel
2136 virtual wxString
GetColumnType( unsigned int col
) const;
2139 Overriden from wxDataViewIndexListModel
2141 virtual void GetValueByRow( wxVariant
&value
,
2142 unsigned int row
, unsigned int col
) const;
2145 Overriden from wxDataViewIndexListModel
2147 virtual bool SetValueByRow( const wxVariant
&value
,
2148 unsigned int row
, unsigned int col
);
2153 @class wxDataViewTreeStore
2155 wxDataViewTreeStore is a specialised wxDataViewModel for stroing simple
2156 trees very much like wxTreeCtrl does and it offers a similar API.
2158 This class actually stores the entire tree and the values (therefore its name)
2159 and implements all virtual methods from the base class so it can be used directly
2160 without having to derive any class from it, but it is mostly used from within
2166 class wxDataViewTreeStore
: public wxDataViewModel
2170 Constructor. Creates the invisible root node internally.
2172 wxDataViewTreeStore();
2177 virtual ~wxDataViewTreeStore();
2182 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
2183 const wxString
& text
,
2184 const wxIcon
& icon
= wxNullIcon
,
2185 const wxIcon
& expanded
= wxNullIcon
,
2186 wxClientData
* data
= NULL
);
2191 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
2192 const wxString
& text
,
2193 const wxIcon
& icon
= wxNullIcon
,
2194 wxClientData
* data
= NULL
);
2197 Delete all item in the model.
2199 void DeleteAllItems();
2202 Delete all children of the item, but not the item itself.
2204 void DeleteChildren(const wxDataViewItem
& item
);
2209 void DeleteItem(const wxDataViewItem
& item
);
2212 Return the number of children of item.
2214 int GetChildCount(const wxDataViewItem
& parent
) const;
2217 Returns the client data asoociated with the item.
2219 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
2222 Returns the icon to display in expanded containers.
2224 const wxIcon
& GetItemExpandedIcon(const wxDataViewItem
& item
) const;
2227 Returns the icon of the item.
2229 const wxIcon
& GetItemIcon(const wxDataViewItem
& item
) const;
2232 Returns the text of the item.
2234 wxString
GetItemText(const wxDataViewItem
& item
) const;
2237 Returns the nth child item of item.
2239 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
2240 unsigned int pos
) const;
2243 Inserts a container after @a previous.
2245 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
2246 const wxDataViewItem
& previous
,
2247 const wxString
& text
,
2248 const wxIcon
& icon
= wxNullIcon
,
2249 const wxIcon
& expanded
= wxNullIcon
,
2250 wxClientData
* data
= NULL
);
2253 Inserts an item after @a previous.
2255 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
2256 const wxDataViewItem
& previous
,
2257 const wxString
& text
,
2258 const wxIcon
& icon
= wxNullIcon
,
2259 wxClientData
* data
= NULL
);
2262 Inserts a container before the first child item or @a parent.
2264 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
2265 const wxString
& text
,
2266 const wxIcon
& icon
= wxNullIcon
,
2267 const wxIcon
& expanded
= wxNullIcon
,
2268 wxClientData
* data
= NULL
);
2271 Inserts an item before the first child item or @a parent.
2273 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
2274 const wxString
& text
,
2275 const wxIcon
& icon
= wxNullIcon
,
2276 wxClientData
* data
= NULL
);
2279 Sets the client data associated with the item.
2281 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
2284 Sets the expanded icon for the item.
2286 void SetItemExpandedIcon(const wxDataViewItem
& item
,
2287 const wxIcon
& icon
);
2290 Sets the icon for the item.
2292 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
2297 @class wxDataViewIconText
2299 wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2300 This class can be converted to and from a wxVariant.
2305 class wxDataViewIconText
: public wxObject
2312 wxDataViewIconText(const wxString
& text
= wxEmptyString
,
2313 const wxIcon
& icon
= wxNullIcon
);
2314 wxDataViewIconText(const wxDataViewIconText
& other
);
2320 const wxIcon
& GetIcon() const;
2325 wxString
GetText() const;
2330 void SetIcon(const wxIcon
& icon
);
2335 void SetText(const wxString
& text
);
2341 @class wxDataViewEvent
2343 This is the event class for the wxDataViewCtrl notifications.
2345 @beginEventTable{wxDataViewEvent}
2346 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2347 Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2348 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2349 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2350 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2351 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2352 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2353 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2354 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2355 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2356 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2357 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2358 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2359 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2360 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2361 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2362 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2363 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2364 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2365 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2366 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2367 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
2368 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2369 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2370 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2371 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2372 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2373 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2374 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2375 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2376 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2377 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
2378 @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
2379 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
2380 @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
2381 Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
2385 @category{events,dvc}
2387 class wxDataViewEvent
: public wxNotifyEvent
2391 Constructor. Typically used by wxWidgets internals only.
2393 wxDataViewEvent(wxEventType commandType
= wxEVT_NULL
,
2397 Returns the position of the column in the control or -1
2398 if no column field was set by the event emitter.
2400 int GetColumn() const;
2403 Returns a pointer to the wxDataViewColumn from which
2404 the event was emitted or @NULL.
2406 wxDataViewColumn
* GetDataViewColumn() const;
2409 Returns the wxDataViewModel associated with the event.
2411 wxDataViewModel
* GetModel() const;
2414 Returns a the position of a context menu event in screen coordinates.
2416 wxPoint
GetPosition() const;
2419 Returns a reference to a value.
2421 const wxVariant
& GetValue() const;
2424 Sets the column index associated with this event.
2426 void SetColumn(int col
);
2429 For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
2431 void SetDataViewColumn(wxDataViewColumn
* col
);
2434 Sets the dataview model associated with this event.
2436 void SetModel(wxDataViewModel
* model
);
2439 Sets the value associated with this event.
2441 void SetValue(const wxVariant
& value
);
2444 Set wxDataObject for data transfer within a drag operation.
2446 void SetDataObject( wxDataObject
*obj
);
2449 Used internally. Gets associated wxDataObject for data transfer
2450 within a drag operation.
2452 wxDataObject
*GetDataObject() const;
2455 Used internally. Sets the wxDataFormat during a drop operation.
2457 void SetDataFormat( const wxDataFormat
&format
);
2460 Gets the wxDataFormat during a drop operation.
2462 wxDataFormat
GetDataFormat() const;
2465 Used internally. Sets the data size for a drop data transfer.
2467 void SetDataSize( size_t size
);
2470 Gets the data size for a drop data transfer.
2472 size_t GetDataSize() const;
2475 Used internally. Sets the data buffer for a drop data transfer.
2477 void SetDataBuffer( void* buf
);
2480 Gets the data buffer for a drop data transfer.
2482 void *GetDataBuffer() const;
2485 Return the first row that will be displayed.
2487 int GetCacheFrom() const;
2490 Return the last row that will be displayed.
2492 int GetCacheTo() const;