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 The base class version always simply returns @false.
140 @see wxDataViewItemAttr.
143 The item for which the attribute is requested.
145 The column of the item for which the attribute is requested.
147 The attribute to be filled in if the function returns @true.
149 @true if this item has an attribute or @false otherwise.
151 virtual bool GetAttr(const wxDataViewItem
& item
, unsigned int col
,
152 wxDataViewItemAttr
& attr
) const;
155 Override this so the control can query the child items of an item.
156 Returns the number of items.
158 virtual unsigned int GetChildren(const wxDataViewItem
& item
,
159 wxDataViewItemArray
& children
) const = 0;
162 Override this to indicate the number of columns in the model.
164 virtual unsigned int GetColumnCount() const = 0;
167 Override this to indicate what type of data is stored in the
168 column specified by @a col.
170 This should return a string indicating the type of data as reported by wxVariant.
172 virtual wxString
GetColumnType(unsigned int col
) const = 0;
175 Override this to indicate which wxDataViewItem representing the parent
176 of @a item or an invalid wxDataViewItem if the the root item is
179 virtual wxDataViewItem
GetParent(const wxDataViewItem
& item
) const = 0;
182 Override this to indicate the value of @a item.
183 A wxVariant is used to store the data.
185 virtual void GetValue(wxVariant
& variant
, const wxDataViewItem
& item
,
186 unsigned int col
) const = 0;
189 Override this method to indicate if a container item merely acts as a
190 headline (or for categorisation) or if it also acts a normal item with
191 entries for futher columns. By default returns @false.
193 virtual bool HasContainerColumns(const wxDataViewItem
& item
) const;
196 Override this to indicate that the model provides a default compare
197 function that the control should use if no wxDataViewColumn has been
198 chosen for sorting. Usually, the user clicks on a column header for
199 sorting, the data will be sorted alphanumerically.
201 If any other order (e.g. by index or order of appearance) is required,
202 then this should be used.
203 See wxDataViewIndexListModel for a model which makes use of this.
205 virtual bool HasDefaultCompare() const;
208 Return true if there is a value in the given column of this item.
210 All normal items have values in all columns but the container items
211 only show their label in the first column (@a col == 0) by default (but
212 see HasContainerColumns()). So this function always returns true for
213 the first column while for the other ones it returns true only if the
214 item is not a container or HasContainerColumns() was overridden to
219 bool HasValue(const wxDataViewItem
& item
, unsigned col
) const;
222 Override this to indicate of @a item is a container, i.e. if
223 it can have child items.
225 virtual bool IsContainer(const wxDataViewItem
& item
) const = 0;
228 Call this to inform the model that an item has been added to the data.
230 virtual bool ItemAdded(const wxDataViewItem
& parent
,
231 const wxDataViewItem
& item
);
234 Call this to inform the model that an item has changed.
236 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
237 event (in which the column fields will not be set) to the user.
239 virtual bool ItemChanged(const wxDataViewItem
& item
);
242 Call this to inform the model that an item has been deleted from the data.
244 virtual bool ItemDeleted(const wxDataViewItem
& parent
,
245 const wxDataViewItem
& item
);
248 Call this to inform the model that several items have been added to the data.
250 virtual bool ItemsAdded(const wxDataViewItem
& parent
,
251 const wxDataViewItemArray
& items
);
254 Call this to inform the model that several items have changed.
256 This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
257 events (in which the column fields will not be set) to the user.
259 virtual bool ItemsChanged(const wxDataViewItemArray
& items
);
262 Call this to inform the model that several items have been deleted.
264 virtual bool ItemsDeleted(const wxDataViewItem
& parent
,
265 const wxDataViewItemArray
& items
);
268 Remove the @a notifier from the list of notifiers.
270 void RemoveNotifier(wxDataViewModelNotifier
* notifier
);
273 Call this to initiate a resort after the sort function has been changed.
275 virtual void Resort();
278 This gets called in order to set a value in the data model.
280 The most common scenario is that the wxDataViewCtrl calls this method
281 after the user changed some data in the view.
283 This is the function you need to override in your derived class but if
284 you want to call it, ChangeValue() is usually more convenient as
285 otherwise you need to manually call ValueChanged() to update the
288 virtual bool SetValue(const wxVariant
& variant
,
289 const wxDataViewItem
& item
,
290 unsigned int col
) = 0;
293 Call this to inform this model that a value in the model has been changed.
294 This is also called from wxDataViewCtrl's internal editing code, e.g. when
295 editing a text field in the control.
297 This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
300 virtual bool ValueChanged(const wxDataViewItem
& item
,
306 Destructor. This should not be called directly. Use DecRef() instead.
308 virtual ~wxDataViewModel();
314 @class wxDataViewIndexListModel
316 wxDataViewIndexListModel is a specialized data model which lets you address
317 an item by its position (row) rather than its wxDataViewItem (which you can
318 obtain from this class).
319 This model also provides its own wxDataViewIndexListModel::Compare
320 method which sorts the model's data by the index.
322 This model is not a virtual model since the control stores each wxDataViewItem.
323 Use wxDataViewVirtualListModel if you need to display millions of items or
324 have other reason to use a virtual control.
329 class wxDataViewIndexListModel
: public wxDataViewModel
335 wxDataViewIndexListModel(unsigned int initial_size
= 0);
340 virtual ~wxDataViewIndexListModel();
343 Compare method that sorts the items by their index.
345 int Compare(const wxDataViewItem
& item1
,
346 const wxDataViewItem
& item2
,
347 unsigned int column
, bool ascending
);
350 Override this to indicate that the row has special font attributes.
351 This only affects the wxDataViewTextRendererText() renderer.
353 The base class version always simply returns @false.
355 @see wxDataViewItemAttr.
358 The row for which the attribute is requested.
360 The column for which the attribute is requested.
362 The attribute to be filled in if the function returns @true.
364 @true if this item has an attribute or @false otherwise.
366 virtual bool GetAttrByRow(unsigned int row
, unsigned int col
,
367 wxDataViewItemAttr
& attr
) const;
370 Returns the number of items (i.e. rows) in the list.
372 unsigned int GetCount() const;
375 Returns the wxDataViewItem at the given @e row.
377 wxDataViewItem
GetItem(unsigned int row
) const;
380 Returns the position of given @e item.
382 unsigned int GetRow(const wxDataViewItem
& item
) const;
385 Override this to allow getting values from the model.
387 virtual void GetValueByRow(wxVariant
& variant
, unsigned int row
,
388 unsigned int col
) const = 0;
391 Call this after if the data has to be read again from the model.
392 This is useful after major changes when calling the methods below
393 (possibly thousands of times) doesn't make sense.
395 void Reset(unsigned int new_size
);
398 Call this after a row has been appended to the model.
403 Call this after a row has been changed.
405 void RowChanged(unsigned int row
);
408 Call this after a row has been deleted.
410 void RowDeleted(unsigned int row
);
413 Call this after a row has been inserted at the given position.
415 void RowInserted(unsigned int before
);
418 Call this after a row has been prepended to the model.
423 Call this after a value has been changed.
425 void RowValueChanged(unsigned int row
, unsigned int col
);
428 Call this after rows have been deleted.
429 The array will internally get copied and sorted in descending order so
430 that the rows with the highest position will be deleted first.
432 void RowsDeleted(const wxArrayInt
& rows
);
435 Called in order to set a value in the model.
437 virtual bool SetValueByRow(const wxVariant
& variant
, unsigned int row
,
438 unsigned int col
) = 0;
444 @class wxDataViewVirtualListModel
446 wxDataViewVirtualListModel is a specialized data model which lets you address
447 an item by its position (row) rather than its wxDataViewItem and as such offers
448 the exact same interface as wxDataViewIndexListModel.
449 The important difference is that under platforms other than OS X, using this
450 model will result in a truly virtual control able to handle millions of items
451 as the control doesn't store any item (a feature not supported by the
452 Carbon API under OS X).
454 @see wxDataViewIndexListModel for the API.
459 class wxDataViewVirtualListModel
: public wxDataViewModel
465 wxDataViewVirtualListModel(unsigned int initial_size
= 0);
468 Returns the number of virtual items (i.e. rows) in the list.
470 unsigned int GetCount() const;
476 @class wxDataViewItemAttr
478 This class is used to indicate to a wxDataViewCtrl that a certain item
479 (see wxDataViewItem) has extra font attributes for its renderer.
480 For this, it is required to override wxDataViewModel::GetAttr.
482 Attributes are currently only supported by wxDataViewTextRendererText.
487 class wxDataViewItemAttr
493 wxDataViewItemAttr();
496 Call this to indicate that the item shall be displayed in bold text.
498 void SetBold(bool set
);
501 Call this to indicate that the item shall be displayed with that colour.
503 void SetColour(const wxColour
& colour
);
506 Call this to indicate that the item shall be displayed in italic text.
508 void SetItalic(bool set
);
514 @class wxDataViewItem
516 wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl
517 in a persistent way, i.e. indepent of the position of the item in the control
518 or changes to its contents.
520 It must hold a unique ID of type @e void* in its only field and can be converted
523 If the ID is @NULL the wxDataViewItem is invalid and wxDataViewItem::IsOk will
524 return @false which used in many places in the API of wxDataViewCtrl to
525 indicate that e.g. no item was found. An ID of @NULL is also used to indicate
526 the invisible root. Examples for this are wxDataViewModel::GetParent and
527 wxDataViewModel::GetChildren.
539 wxDataViewItem(void* id
= NULL
);
540 wxDataViewItem(const wxDataViewItem
& item
);
549 Returns @true if the ID is not @NULL.
557 @class wxDataViewCtrl
559 wxDataViewCtrl is a control to display data either in a tree like fashion or
560 in a tabular form or both.
562 If you only need to display a simple tree structure with an API more like the
563 older wxTreeCtrl class, then the specialized wxDataViewTreeCtrl can be used.
564 Likewise, if you only want to display simple table structure you can use
565 the specialized wxDataViewListCtrl class. Both wxDataViewTreeCtrl and
566 wxDataViewListCtrl can be used without defining your own wxDataViewModel.
568 A wxDataViewItem is used to represent a (visible) item in the control.
570 Unlike wxListCtrl, wxDataViewCtrl doesn't get its data from the user through
571 virtual functions or by setting it directly. Instead you need to write your own
572 wxDataViewModel and associate it with this control.
573 Then you need to add a number of wxDataViewColumn to this control to define
574 what each column shall display. Each wxDataViewColumn in turn owns 1 instance
575 of a wxDataViewRenderer to render its cells.
577 A number of standard renderers for rendering text, dates, images, toggle,
578 a progress bar etc. are provided. Additionally, the user can write custom
579 renderers deriving from wxDataViewCustomRenderer for displaying anything.
581 All data transfer from the control to the model and the user code is done
582 through wxVariant which can be extended to support more data formats as necessary.
583 Accordingly, all type information uses the strings returned from wxVariant::GetType.
587 Single selection mode. This is the default.
588 @style{wxDV_MULTIPLE}
589 Multiple selection mode.
590 @style{wxDV_ROW_LINES}
591 Use alternating colours for rows if supported by platform and theme.
592 @style{wxDV_HORIZ_RULES}
593 Display fine rules between row if supported.
594 @style{wxDV_VERT_RULES}
595 Display fine rules between columns is supported.
596 @style{wxDV_VARIABLE_LINE_HEIGHT}
597 Allow variable line heights.
598 This can be inefficient when displaying large number of items.
601 @beginEventEmissionTable{wxDataViewEvent}
602 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
603 Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
604 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
605 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
606 @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}
607 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event. This
608 event can be vetoed in order to prevent editing on an item by item
609 basis. Still experimental.
610 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
611 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
612 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
613 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
614 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
615 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
616 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
617 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
618 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
619 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
620 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
621 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
622 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
623 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
624 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
625 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
626 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
627 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
628 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
629 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
630 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
631 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
632 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
633 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
634 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
635 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
636 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
637 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
638 @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
639 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
644 @appearance{dataviewctrl.png}
646 class wxDataViewCtrl
: public wxControl
655 Constructor. Calls Create().
657 wxDataViewCtrl(wxWindow
* parent
, wxWindowID id
,
658 const wxPoint
& pos
= wxDefaultPosition
,
659 const wxSize
& size
= wxDefaultSize
,
661 const wxValidator
& validator
= wxDefaultValidator
);
666 virtual ~wxDataViewCtrl();
669 Appends a wxDataViewColumn to the control. Returns @true on success.
671 Note that there is a number of short cut methods which implicitly create
672 a wxDataViewColumn and a wxDataViewRenderer for it (see below).
674 virtual bool AppendColumn(wxDataViewColumn
* col
);
677 Prepends a wxDataViewColumn to the control. Returns @true on success.
679 Note that there is a number of short cut methods which implicitly create
680 a wxDataViewColumn and a wxDataViewRenderer for it.
682 virtual bool PrependColumn(wxDataViewColumn
* col
);
685 Inserts a wxDataViewColumn to the control. Returns @true on success.
687 virtual bool InsertColumn(unsigned int pos
, wxDataViewColumn
* col
);
691 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
692 created in the function or @NULL on failure.
694 wxDataViewColumn
* AppendBitmapColumn(const wxString
& label
,
695 unsigned int model_column
,
696 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
698 wxAlignment align
= wxALIGN_CENTER
,
699 int flags
= wxDATAVIEW_COL_RESIZABLE
);
700 wxDataViewColumn
* AppendBitmapColumn(const wxBitmap
& label
,
701 unsigned int model_column
,
702 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
704 wxAlignment align
= wxALIGN_CENTER
,
705 int flags
= wxDATAVIEW_COL_RESIZABLE
);
710 Appends a column for rendering a date. Returns the wxDataViewColumn
711 created in the function or @NULL on failure.
713 @note The @a align parameter is applied to both the column header and
716 wxDataViewColumn
* AppendDateColumn(const wxString
& label
,
717 unsigned int model_column
,
718 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
720 wxAlignment align
= wxALIGN_NOT
,
721 int flags
= wxDATAVIEW_COL_RESIZABLE
);
722 wxDataViewColumn
* AppendDateColumn(const wxBitmap
& label
,
723 unsigned int model_column
,
724 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
726 wxAlignment align
= wxALIGN_NOT
,
727 int flags
= wxDATAVIEW_COL_RESIZABLE
);
732 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
733 created in the function or @NULL on failure.
734 This method uses the wxDataViewIconTextRenderer class.
736 @note The @a align parameter is applied to both the column header and
739 wxDataViewColumn
* AppendIconTextColumn(const wxString
& label
,
740 unsigned int model_column
,
741 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
743 wxAlignment align
= wxALIGN_NOT
,
744 int flags
= wxDATAVIEW_COL_RESIZABLE
);
745 wxDataViewColumn
* AppendIconTextColumn(const wxBitmap
& label
,
746 unsigned int model_column
,
747 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
749 wxAlignment align
= wxALIGN_NOT
,
750 int flags
= wxDATAVIEW_COL_RESIZABLE
);
755 Appends a column for rendering a progress indicator. Returns the
756 wxDataViewColumn created in the function or @NULL on failure.
758 @note The @a align parameter is applied to both the column header and
761 wxDataViewColumn
* AppendProgressColumn(const wxString
& label
,
762 unsigned int model_column
,
763 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
765 wxAlignment align
= wxALIGN_CENTER
,
766 int flags
= wxDATAVIEW_COL_RESIZABLE
);
767 wxDataViewColumn
* AppendProgressColumn(const wxBitmap
& label
,
768 unsigned int model_column
,
769 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
771 wxAlignment align
= wxALIGN_CENTER
,
772 int flags
= wxDATAVIEW_COL_RESIZABLE
);
777 Appends a column for rendering text. Returns the wxDataViewColumn
778 created in the function or @NULL on failure.
780 @note The @a align parameter is applied to both the column header and
783 wxDataViewColumn
* AppendTextColumn(const wxString
& label
,
784 unsigned int model_column
,
785 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
787 wxAlignment align
= wxALIGN_NOT
,
788 int flags
= wxDATAVIEW_COL_RESIZABLE
);
789 wxDataViewColumn
* AppendTextColumn(const wxBitmap
& label
,
790 unsigned int model_column
,
791 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
793 wxAlignment align
= wxALIGN_NOT
,
794 int flags
= wxDATAVIEW_COL_RESIZABLE
);
799 Appends a column for rendering a toggle. Returns the wxDataViewColumn
800 created in the function or @NULL on failure.
802 @note The @a align parameter is applied to both the column header and
805 wxDataViewColumn
* AppendToggleColumn(const wxString
& label
,
806 unsigned int model_column
,
807 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
809 wxAlignment align
= wxALIGN_CENTER
,
810 int flags
= wxDATAVIEW_COL_RESIZABLE
);
811 wxDataViewColumn
* AppendToggleColumn(const wxBitmap
& label
,
812 unsigned int model_column
,
813 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
815 wxAlignment align
= wxALIGN_CENTER
,
816 int flags
= wxDATAVIEW_COL_RESIZABLE
);
820 Associates a wxDataViewModel with the control.
821 This increases the reference count of the model by 1.
823 virtual bool AssociateModel(wxDataViewModel
* model
);
828 virtual bool ClearColumns();
833 virtual void Collapse(const wxDataViewItem
& item
);
836 Create the control. Useful for two step creation.
838 bool Create(wxWindow
* parent
, wxWindowID id
,
839 const wxPoint
& pos
= wxDefaultPosition
,
840 const wxSize
& size
= wxDefaultSize
,
842 const wxValidator
& validator
= wxDefaultValidator
);
845 Deletes given column.
847 virtual bool DeleteColumn(wxDataViewColumn
* column
);
850 Enable drag operations using the given @a format.
852 virtual bool EnableDragSource( const wxDataFormat
&format
);
855 Enable drop operations using the given @a format.
857 virtual bool EnableDropTarget( const wxDataFormat
&format
);
860 Call this to ensure that the given item is visible.
862 virtual void EnsureVisible(const wxDataViewItem
& item
,
863 const wxDataViewColumn
* column
= NULL
);
868 virtual void Expand(const wxDataViewItem
& item
);
871 Expands all ancestors of the @a item. This method also
872 ensures that the item itself as well as all ancestor
873 items have been read from the model by the control.
875 virtual void ExpandAncestors( const wxDataViewItem
& item
);
878 Returns pointer to the column. @a pos refers to the position in the
879 control which may change after reordering columns by the user.
881 virtual wxDataViewColumn
* GetColumn(unsigned int pos
) const;
884 Returns the number of columns.
886 virtual unsigned int GetColumnCount() const;
889 Returns the position of the column or -1 if not found in the control.
891 virtual int GetColumnPosition(const wxDataViewColumn
* column
) const;
894 Returns column containing the expanders.
896 wxDataViewColumn
* GetExpanderColumn() const;
901 int GetIndent() const;
906 virtual wxRect
GetItemRect(const wxDataViewItem
& item
,
907 const wxDataViewColumn
* col
= NULL
) const;
910 Returns pointer to the data model associated with the control (if any).
912 wxDataViewModel
* GetModel();
915 Returns first selected item or an invalid item if none is selected.
917 virtual wxDataViewItem
GetSelection() const;
920 Fills @a sel with currently selected items and returns their number.
922 virtual int GetSelections(wxDataViewItemArray
& sel
) const;
925 Returns the wxDataViewColumn currently responsible for sorting
926 or @NULL if none has been selected.
928 virtual wxDataViewColumn
* GetSortingColumn() const;
933 virtual void HitTest(const wxPoint
& point
, wxDataViewItem
& item
,
934 wxDataViewColumn
*& col
) const;
937 Return @true if the item is expanded.
939 virtual bool IsExpanded(const wxDataViewItem
& item
) const;
942 Return @true if the item is selected.
944 virtual bool IsSelected(const wxDataViewItem
& item
) const;
947 Select the given item.
949 virtual void Select(const wxDataViewItem
& item
);
954 virtual void SelectAll();
957 Set which column shall contain the tree-like expanders.
959 void SetExpanderColumn(wxDataViewColumn
* col
);
962 Sets the indendation.
964 void SetIndent(int indent
);
967 Sets the selection to the array of wxDataViewItems.
969 virtual void SetSelections(const wxDataViewItemArray
& sel
);
972 Unselect the given item.
974 virtual void Unselect(const wxDataViewItem
& item
);
978 This method only has effect if multiple selections are allowed.
980 virtual void UnselectAll();
986 @class wxDataViewModelNotifier
988 A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
989 its notification interface.
990 See the documentation of that class for further information.
995 class wxDataViewModelNotifier
1001 wxDataViewModelNotifier();
1006 virtual ~wxDataViewModelNotifier();
1009 Called by owning model.
1011 virtual bool Cleared() = 0;
1014 Get owning wxDataViewModel.
1016 wxDataViewModel
* GetOwner() const;
1019 Called by owning model.
1021 virtual bool ItemAdded(const wxDataViewItem
& parent
,
1022 const wxDataViewItem
& item
) = 0;
1025 Called by owning model.
1027 virtual bool ItemChanged(const wxDataViewItem
& item
) = 0;
1030 Called by owning model.
1032 virtual bool ItemDeleted(const wxDataViewItem
& parent
,
1033 const wxDataViewItem
& item
) = 0;
1036 Called by owning model.
1038 virtual bool ItemsAdded(const wxDataViewItem
& parent
,
1039 const wxDataViewItemArray
& items
);
1042 Called by owning model.
1044 virtual bool ItemsChanged(const wxDataViewItemArray
& items
);
1047 Called by owning model.
1049 virtual bool ItemsDeleted(const wxDataViewItem
& parent
,
1050 const wxDataViewItemArray
& items
);
1053 Called by owning model.
1055 virtual void Resort() = 0;
1058 Set owner of this notifier. Used internally.
1060 void SetOwner(wxDataViewModel
* owner
);
1063 Called by owning model.
1065 virtual bool ValueChanged(const wxDataViewItem
& item
, unsigned int col
) = 0;
1070 The mode of a data-view cell; see wxDataViewRenderer for more info.
1072 enum wxDataViewCellMode
1074 wxDATAVIEW_CELL_INERT
,
1077 Indicates that the user can double click the cell and something will
1078 happen (e.g. a window for editing a date will pop up).
1080 wxDATAVIEW_CELL_ACTIVATABLE
,
1083 Indicates that the user can edit the data in-place, i.e. an control
1084 will show up after a slow click on the cell. This behaviour is best
1085 known from changing the filename in most file managers etc.
1087 wxDATAVIEW_CELL_EDITABLE
1091 The values of this enum controls how a wxDataViewRenderer should display
1092 its contents in a cell.
1094 enum wxDataViewCellRenderState
1096 wxDATAVIEW_CELL_SELECTED
= 1,
1097 wxDATAVIEW_CELL_PRELIT
= 2,
1098 wxDATAVIEW_CELL_INSENSITIVE
= 4,
1099 wxDATAVIEW_CELL_FOCUSED
= 8
1103 @class wxDataViewRenderer
1105 This class is used by wxDataViewCtrl to render the individual cells.
1106 One instance of a renderer class is owned by a wxDataViewColumn.
1107 There is a number of ready-to-use renderers provided:
1108 - wxDataViewTextRenderer,
1109 - wxDataViewIconTextRenderer,
1110 - wxDataViewToggleRenderer,
1111 - wxDataViewProgressRenderer,
1112 - wxDataViewBitmapRenderer,
1113 - wxDataViewDateRenderer,
1114 - wxDataViewSpinRenderer.
1116 Additionally, the user can write own renderers by deriving from
1117 wxDataViewCustomRenderer.
1119 The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1120 by the constructors respectively controls what actions the cell data allows
1121 and how the renderer should display its contents in a cell.
1126 class wxDataViewRenderer
: public wxObject
1132 wxDataViewRenderer(const wxString
& varianttype
,
1133 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1134 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1137 Enable or disable replacing parts of the item text with ellipsis to
1138 make it fit the column width.
1140 This method only makes sense for the renderers working with text, such
1141 as wxDataViewTextRenderer or wxDataViewIconTextRenderer.
1143 By default wxELLIPSIZE_MIDDLE is used.
1146 Ellipsization mode, use wxELLIPSIZE_NONE to disable.
1150 void EnableEllipsize(wxEllipsizeMode mode
= wxELLIPSIZE_MIDDLE
);
1153 Disable replacing parts of the item text with ellipsis.
1155 If ellipsizing is disabled, the string will be truncated if it doesn't
1158 This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode.
1162 void DisableEllipsize();
1165 Returns the alignment. See SetAlignment()
1167 virtual int GetAlignment() const;
1170 Returns the ellipsize mode used by the renderer.
1172 If the return value is wxELLIPSIZE_NONE, the text is simply truncated
1175 @see EnableEllipsize()
1177 wxEllipsizeMode
GetEllipsizeMode() const;
1180 Returns the cell mode.
1182 virtual wxDataViewCellMode
GetMode() const;
1185 Returns pointer to the owning wxDataViewColumn.
1187 wxDataViewColumn
* GetOwner() const;
1190 This methods retrieves the value from the renderer in order to
1191 transfer the value back to the data model.
1193 Returns @false on failure.
1195 virtual bool GetValue(wxVariant
& value
) const = 0;
1198 Returns a string with the type of the wxVariant supported by this renderer.
1200 wxString
GetVariantType() const;
1203 Sets the alignment of the renderer's content.
1204 The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1205 should have the same alignment as the column header.
1207 The method is not implemented under OS X and the renderer always aligns
1208 its contents as the column header on that platform. The other platforms
1209 support both vertical and horizontal alignment.
1211 virtual void SetAlignment( int align
);
1213 Sets the owning wxDataViewColumn.
1214 This is usually called from within wxDataViewColumn.
1216 void SetOwner(wxDataViewColumn
* owner
);
1219 Set the value of the renderer (and thus its cell) to @a value.
1220 The internal code will then render this cell with this data.
1222 virtual bool SetValue(const wxVariant
& value
) = 0;
1225 Before data is committed to the data model, it is passed to this
1226 method where it can be checked for validity. This can also be
1227 used for checking a valid range or limiting the user input in
1228 a certain aspect (e.g. max number of characters or only alphanumeric
1229 input, ASCII only etc.). Return @false if the value is not valid.
1231 Please note that due to implementation limitations, this validation
1232 is done after the editing control already is destroyed and the
1233 editing process finished.
1235 virtual bool Validate(wxVariant
& value
);
1241 @class wxDataViewTextRenderer
1243 wxDataViewTextRenderer is used for rendering text.
1244 It supports in-place editing if desired.
1249 class wxDataViewTextRenderer
: public wxDataViewRenderer
1255 wxDataViewTextRenderer(const wxString
& varianttype
= "string",
1256 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1257 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1263 @class wxDataViewIconTextRenderer
1265 The wxDataViewIconTextRenderer class is used to display text with
1266 a small icon next to it as it is typically done in a file manager.
1268 This classes uses the wxDataViewIconText helper class to store its data.
1269 wxDataViewIonText can be converted to and from a wxVariant using the left shift
1275 class wxDataViewIconTextRenderer
: public wxDataViewRenderer
1281 wxDataViewIconTextRenderer(const wxString
& varianttype
= "wxDataViewIconText",
1282 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1283 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1289 @class wxDataViewProgressRenderer
1291 This class is used by wxDataViewCtrl to render progress bars.
1296 class wxDataViewProgressRenderer
: public wxDataViewRenderer
1302 wxDataViewProgressRenderer(const wxString
& label
= wxEmptyString
,
1303 const wxString
& varianttype
= "long",
1304 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1305 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1311 @class wxDataViewSpinRenderer
1313 This is a specialized renderer for rendering integer values.
1314 It supports modifying the values in-place by using a wxSpinCtrl.
1315 The renderer only support variants of type @e long.
1320 class wxDataViewSpinRenderer
: public wxDataViewCustomRenderer
1325 @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1327 wxDataViewSpinRenderer(int min
, int max
,
1328 wxDataViewCellMode mode
= wxDATAVIEW_CELL_EDITABLE
,
1329 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1335 @class wxDataViewToggleRenderer
1337 This class is used by wxDataViewCtrl to render toggle controls.
1342 class wxDataViewToggleRenderer
: public wxDataViewRenderer
1348 wxDataViewToggleRenderer(const wxString
& varianttype
= "bool",
1349 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1350 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1356 @class wxDataViewDateRenderer
1358 This class is used by wxDataViewCtrl to render calendar controls.
1363 class wxDataViewDateRenderer
: public wxDataViewRenderer
1369 wxDataViewDateRenderer(const wxString
& varianttype
= "datetime",
1370 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1371 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1377 @class wxDataViewCustomRenderer
1379 You need to derive a new class from wxDataViewCustomRenderer in
1380 order to write a new renderer.
1382 You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1383 wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1385 If you want your renderer to support in-place editing then you also need to override
1386 wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1387 and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1389 Note that a special event handler will be pushed onto that editor control
1390 which handles @e \<ENTER\> and focus out events in order to end the editing.
1395 class wxDataViewCustomRenderer
: public wxDataViewRenderer
1401 wxDataViewCustomRenderer(const wxString
& varianttype
= "string",
1402 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1403 int align
= -1, bool no_init
= false);
1408 virtual ~wxDataViewCustomRenderer();
1411 Override this to react to double clicks or ENTER.
1412 This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1414 virtual bool Activate( wxRect cell
,
1415 wxDataViewModel
* model
,
1416 const wxDataViewItem
& item
,
1420 Override this to create the actual editor control once editing
1423 @a parent is the parent of the editor control, @a labelRect indicates the
1424 position and size of the editor control and @a value is its initial value:
1428 return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1429 labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1433 virtual wxControl
* CreateEditorCtrl(wxWindow
* parent
,
1435 const wxVariant
& value
);
1438 Create DC on request. Internal.
1440 virtual wxDC
* GetDC();
1443 Return size required to show content.
1445 virtual wxSize
GetSize() const = 0;
1448 Override this so that the renderer can get the value from the editor
1449 control (pointed to by @a editor):
1452 wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1453 long l = sc->GetValue();
1459 virtual bool GetValueFromEditorCtrl(wxControl
* editor
,
1463 Override this and make it return @true in order to
1464 indicate that this renderer supports in-place editing.
1466 virtual bool HasEditorCtrl() const;
1469 Override this to react to a left click.
1470 This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1472 virtual bool LeftClick( wxPoint cursor
,
1474 wxDataViewModel
* model
,
1475 const wxDataViewItem
& item
,
1479 Override this to render the cell.
1480 Before this is called, wxDataViewRenderer::SetValue was called
1481 so that this instance knows what to render.
1483 virtual bool Render(wxRect cell
, wxDC
* dc
, int state
) = 0;
1486 This method should be called from within Render() whenever you need to
1488 This will ensure that the correct colour, font and vertical alignment will
1489 be chosen so the text will look the same as text drawn by native renderers.
1491 void RenderText(const wxString
& text
, int xoffset
, wxRect cell
,
1492 wxDC
* dc
, int state
);
1495 Override this to start a drag operation. Not yet supported.
1497 virtual bool StartDrag(wxPoint cursor
, wxRect cell
,
1498 wxDataViewModel
* model
,
1499 const wxDataViewItem
& item
,
1506 @class wxDataViewBitmapRenderer
1508 This class is used by wxDataViewCtrl to render bitmap controls.
1513 class wxDataViewBitmapRenderer
: public wxDataViewRenderer
1519 wxDataViewBitmapRenderer(const wxString
& varianttype
= "wxBitmap",
1520 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1521 int align
= wxDVR_DEFAULT_ALIGNMENT
);
1526 The flags used by wxDataViewColumn.
1527 Can be combined together.
1529 enum wxDataViewColumnFlags
1531 wxDATAVIEW_COL_RESIZABLE
= 1,
1532 wxDATAVIEW_COL_SORTABLE
= 2,
1533 wxDATAVIEW_COL_REORDERABLE
= 4,
1534 wxDATAVIEW_COL_HIDDEN
= 8
1538 @class wxDataViewColumn
1540 This class represents a column in a wxDataViewCtrl.
1541 One wxDataViewColumn is bound to one column in the data model to which the
1542 wxDataViewCtrl has been associated.
1544 An instance of wxDataViewRenderer is used by this class to render its data.
1549 class wxDataViewColumn
: public wxSettableHeaderColumn
1553 Constructs a text column.
1556 The title of the column.
1558 The class which will render the contents of this column.
1560 The index of the model's column which is associated with this object.
1562 The width of the column.
1563 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1565 The alignment of the column title.
1567 One or more flags of the ::wxDataViewColumnFlags enumeration.
1569 wxDataViewColumn(const wxString
& title
,
1570 wxDataViewRenderer
* renderer
,
1571 unsigned int model_column
,
1572 int width
= wxDVC_DEFAULT_WIDTH
,
1573 wxAlignment align
= wxALIGN_CENTER
,
1574 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1577 Constructs a bitmap column.
1580 The bitmap of the column.
1582 The class which will render the contents of this column.
1584 The index of the model's column which is associated with this object.
1586 The width of the column.
1587 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1589 The alignment of the column title.
1591 One or more flags of the ::wxDataViewColumnFlags enumeration.
1593 wxDataViewColumn(const wxBitmap
& bitmap
,
1594 wxDataViewRenderer
* renderer
,
1595 unsigned int model_column
,
1596 int width
= wxDVC_DEFAULT_WIDTH
,
1597 wxAlignment align
= wxALIGN_CENTER
,
1598 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1601 Returns the index of the column of the model, which this
1602 wxDataViewColumn is displaying.
1604 unsigned int GetModelColumn() const;
1607 Returns the owning wxDataViewCtrl.
1609 wxDataViewCtrl
* GetOwner() const;
1612 Returns the renderer of this wxDataViewColumn.
1614 @see wxDataViewRenderer.
1616 wxDataViewRenderer
* GetRenderer() const;
1622 @class wxDataViewListCtrl
1624 This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
1625 and forwards most of its API to that class.
1627 The purpose of this class is to offer a simple way to display and
1628 edit a small table of data without having to write your own wxDataViewModel.
1631 wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
1633 listctrl->AppendToggleColumn( "Toggle" );
1634 listctrl->AppendTextColumn( "Text" );
1636 wxVector<wxVariant> data;
1637 data.push_back( wxVariant(true) );
1638 data.push_back( wxVariant("row 1") );
1639 listctrl->AppendItem( data );
1642 data.push_back( wxVariant(false) );
1643 data.push_back( wxVariant("row 3") );
1644 listctrl->AppendItem( data );
1648 See wxDataViewCtrl for the list of supported styles.
1651 @beginEventEmissionTable
1652 See wxDataViewCtrl for the list of events emitted by this class.
1658 class wxDataViewListCtrl
: public wxDataViewCtrl
1664 wxDataViewListCtrl();
1667 Constructor. Calls Create().
1669 wxDataViewListCtrl( wxWindow
*parent
, wxWindowID id
,
1670 const wxPoint
& pos
= wxDefaultPosition
,
1671 const wxSize
& size
= wxDefaultSize
, long style
= wxDV_ROW_LINES
,
1672 const wxValidator
& validator
= wxDefaultValidator
);
1675 Destructor. Deletes the image list if any.
1677 ~wxDataViewListCtrl();
1680 Creates the control and a wxDataViewListStore as its internal model.
1682 bool Create( wxWindow
*parent
, wxWindowID id
,
1683 const wxPoint
& pos
= wxDefaultPosition
,
1684 const wxSize
& size
= wxDefaultSize
, long style
= wxDV_ROW_LINES
,
1685 const wxValidator
& validator
= wxDefaultValidator
);
1691 wxDataViewListStore
*GetStore();
1692 const wxDataViewListStore
*GetStore() const;
1696 @name Column management functions
1701 Appends a column to the control and additionally appends a
1702 column to the store with the type string.
1704 virtual void AppendColumn( wxDataViewColumn
*column
);
1707 Appends a column to the control and additionally appends a
1708 column to the list store with the type @a varianttype.
1710 void AppendColumn( wxDataViewColumn
*column
, const wxString
&varianttype
);
1713 Appends a text column to the control and the store.
1715 See wxDataViewColumn::wxDataViewColumn for more info about
1718 wxDataViewColumn
*AppendTextColumn( const wxString
&label
,
1719 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1720 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
1721 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1724 Appends a toggle column to the control and the store.
1726 See wxDataViewColumn::wxDataViewColumn for more info about
1729 wxDataViewColumn
*AppendToggleColumn( const wxString
&label
,
1730 wxDataViewCellMode mode
= wxDATAVIEW_CELL_ACTIVATABLE
,
1731 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
1732 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1735 Appends a progress column to the control and the store.
1737 See wxDataViewColumn::wxDataViewColumn for more info about
1740 wxDataViewColumn
*AppendProgressColumn( const wxString
&label
,
1741 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1742 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
1743 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1746 Appends an icon-and-text column to the control and the store.
1748 See wxDataViewColumn::wxDataViewColumn for more info about
1751 wxDataViewColumn
*AppendIconTextColumn( const wxString
&label
,
1752 wxDataViewCellMode mode
= wxDATAVIEW_CELL_INERT
,
1753 int width
= -1, wxAlignment align
= wxALIGN_LEFT
,
1754 int flags
= wxDATAVIEW_COL_RESIZABLE
);
1757 Inserts a column to the control and additionally inserts a
1758 column to the store with the type string.
1760 virtual void InsertColumn( unsigned int pos
, wxDataViewColumn
*column
);
1763 Inserts a column to the control and additionally inserts a
1764 column to the list store with the type @a varianttype.
1766 void InsertColumn( unsigned int pos
, wxDataViewColumn
*column
,
1767 const wxString
&varianttype
);
1770 Prepends a column to the control and additionally prepends a
1771 column to the store with the type string.
1773 virtual void PrependColumn( wxDataViewColumn
*column
);
1776 Prepends a column to the control and additionally prepends a
1777 column to the list store with the type @a varianttype.
1779 void PrependColumn( wxDataViewColumn
*column
, const wxString
&varianttype
);
1785 @name Item management functions
1790 Appends an item (=row) to the control and store.
1792 void AppendItem( const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
1795 Prepends an item (=row) to the control and store.
1797 void PrependItem( const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
1800 Inserts an item (=row) to the control and store.
1802 void InsertItem( unsigned int row
, const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
1805 Delete the row at position @a row.
1807 void DeleteItem( unsigned row
);
1810 Delete all items (= all rows).
1812 void DeleteAllItems();
1815 Sets the value in the store and update the control.
1817 void SetValue( const wxVariant
&value
, unsigned int row
, unsigned int col
);
1820 Returns the value from the store.
1822 void GetValue( wxVariant
&value
, unsigned int row
, unsigned int col
);
1825 Sets the value in the store and update the control.
1827 This method assumes that the a string is stored in respective
1830 void SetTextValue( const wxString
&value
, unsigned int row
, unsigned int col
);
1833 Returns the value from the store.
1835 This method assumes that the a string is stored in respective
1838 wxString
GetTextValue( unsigned int row
, unsigned int col
) const;
1841 Sets the value in the store and update the control.
1843 This method assumes that the a boolean value is stored in
1846 void SetToggleValue( bool value
, unsigned int row
, unsigned int col
);
1849 Returns the value from the store.
1851 This method assumes that the a boolean value is stored in
1854 bool GetToggleValue( unsigned int row
, unsigned int col
) const;
1861 @class wxDataViewTreeCtrl
1863 This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
1864 and forwards most of its API to that class.
1865 Additionally, it uses a wxImageList to store a list of icons.
1867 The main purpose of this class is to provide a simple upgrade path for code
1871 See wxDataViewCtrl for the list of supported styles.
1874 @beginEventEmissionTable
1875 See wxDataViewCtrl for the list of events emitted by this class.
1880 @appearance{dataviewtreectrl.png}
1882 class wxDataViewTreeCtrl
: public wxDataViewCtrl
1888 wxDataViewTreeCtrl();
1895 wxDataViewTreeCtrl(wxWindow
* parent
, wxWindowID id
,
1896 const wxPoint
& pos
= wxDefaultPosition
,
1897 const wxSize
& size
= wxDefaultSize
,
1898 long style
= wxDV_NO_HEADER
| wxDV_ROW_LINES
,
1899 const wxValidator
& validator
= wxDefaultValidator
);
1902 Destructor. Deletes the image list if any.
1904 virtual ~wxDataViewTreeCtrl();
1907 Appends a container to the given @a parent.
1909 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
1910 const wxString
& text
,
1913 wxClientData
* data
= NULL
);
1916 Appends an item to the given @a parent.
1918 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
1919 const wxString
& text
,
1921 wxClientData
* data
= NULL
);
1924 Creates the control and a wxDataViewTreeStore as its internal model.
1926 The default tree column created by this method is an editable column
1927 using wxDataViewIconTextRenderer as its renderer.
1929 bool Create(wxWindow
* parent
, wxWindowID id
,
1930 const wxPoint
& pos
= wxDefaultPosition
,
1931 const wxSize
& size
= wxDefaultSize
,
1932 long style
= wxDV_NO_HEADER
| wxDV_ROW_LINES
,
1933 const wxValidator
& validator
= wxDefaultValidator
);
1936 Calls the identical method from wxDataViewTreeStore.
1938 void DeleteAllItems();
1941 Calls the identical method from wxDataViewTreeStore.
1943 void DeleteChildren(const wxDataViewItem
& item
);
1946 Calls the identical method from wxDataViewTreeStore.
1948 void DeleteItem(const wxDataViewItem
& item
);
1951 Calls the identical method from wxDataViewTreeStore.
1953 int GetChildCount(const wxDataViewItem
& parent
) const;
1956 Returns the image list.
1958 wxImageList
* GetImageList();
1961 Calls the identical method from wxDataViewTreeStore.
1963 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
1966 Calls the identical method from wxDataViewTreeStore.
1968 const wxIcon
& GetItemExpandedIcon(const wxDataViewItem
& item
) const;
1971 Calls the identical method from wxDataViewTreeStore.
1973 const wxIcon
& GetItemIcon(const wxDataViewItem
& item
) const;
1976 Calls the identical method from wxDataViewTreeStore.
1978 wxString
GetItemText(const wxDataViewItem
& item
) const;
1981 Calls the identical method from wxDataViewTreeStore.
1983 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
1984 unsigned int pos
) const;
1990 wxDataViewTreeStore
* GetStore();
1991 const wxDataViewTreeStore
* GetStore() const;
1995 Calls the same method from wxDataViewTreeStore but uses
1996 an index position in the image list instead of a wxIcon.
1998 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
1999 const wxDataViewItem
& previous
,
2000 const wxString
& text
,
2003 wxClientData
* data
= NULL
);
2006 Calls the same method from wxDataViewTreeStore but uses
2007 an index position in the image list instead of a wxIcon.
2009 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
2010 const wxDataViewItem
& previous
,
2011 const wxString
& text
,
2013 wxClientData
* data
= NULL
);
2016 Calls the same method from wxDataViewTreeStore but uses
2017 an index position in the image list instead of a wxIcon.
2019 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
2020 const wxString
& text
,
2023 wxClientData
* data
= NULL
);
2026 Calls the same method from wxDataViewTreeStore but uses
2027 an index position in the image list instead of a wxIcon.
2029 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
2030 const wxString
& text
,
2032 wxClientData
* data
= NULL
);
2035 Sets the image list.
2037 void SetImageList(wxImageList
* imagelist
);
2040 Calls the identical method from wxDataViewTreeStore.
2042 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
2045 Calls the identical method from wxDataViewTreeStore.
2047 void SetItemExpandedIcon(const wxDataViewItem
& item
,
2048 const wxIcon
& icon
);
2051 Calls the identical method from wxDataViewTreeStore.
2053 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
2056 Calls the identical method from wxDataViewTreeStore.
2058 void SetItemText(const wxDataViewItem
& item
,
2059 const wxString
& text
);
2064 @class wxDataViewListStore
2066 wxDataViewListStore is a specialised wxDataViewModel for storing
2067 a simple table of data. Since it derives from wxDataViewIndexListModel
2068 its data is be accessed by row (i.e. by index) instead of only
2071 This class actually stores the values (therefore its name)
2072 and implements all virtual methods from the base classes so it can be
2073 used directly without having to derive any class from it, but it is
2074 mostly used from within wxDataViewListCtrl.
2080 class wxDataViewListStore
: public wxDataViewIndexListModel
2086 wxDataViewListStore();
2091 ~wxDataViewListStore();
2094 Prepends a data column.
2096 @a variantype indicates the type of values store in the column.
2098 This does not automatically fill in any (default) values in
2099 rows which exist in the store already.
2101 void PrependColumn( const wxString
&varianttype
);
2104 Inserts a data column before @a pos.
2106 @a variantype indicates the type of values store in the column.
2108 This does not automatically fill in any (default) values in
2109 rows which exist in the store already.
2111 void InsertColumn( unsigned int pos
, const wxString
&varianttype
);
2114 Appends a data column.
2116 @a variantype indicates the type of values store in the column.
2118 This does not automatically fill in any (default) values in
2119 rows which exist in the store already.
2121 void AppendColumn( const wxString
&varianttype
);
2124 Appends an item (=row) and fills it with @a values.
2126 The values must match the values specifies in the column
2127 in number and type. No (default) values are filled in
2130 void AppendItem( const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
2133 Prepends an item (=row) and fills it with @a values.
2135 The values must match the values specifies in the column
2136 in number and type. No (default) values are filled in
2139 void PrependItem( const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
2142 Inserts an item (=row) and fills it with @a values.
2144 The values must match the values specifies in the column
2145 in number and type. No (default) values are filled in
2148 void InsertItem( unsigned int row
, const wxVector
<wxVariant
> &values
, wxClientData
*data
= NULL
);
2151 Delete the item (=row) at position @a pos.
2153 void DeleteItem( unsigned pos
);
2156 Delete all item (=all rows) in the store.
2158 void DeleteAllItems();
2161 Overriden from wxDataViewModel
2163 virtual unsigned int GetColumnCount() const;
2166 Overriden from wxDataViewModel
2168 virtual wxString
GetColumnType( unsigned int col
) const;
2171 Overriden from wxDataViewIndexListModel
2173 virtual void GetValueByRow( wxVariant
&value
,
2174 unsigned int row
, unsigned int col
) const;
2177 Overriden from wxDataViewIndexListModel
2179 virtual bool SetValueByRow( const wxVariant
&value
,
2180 unsigned int row
, unsigned int col
);
2185 @class wxDataViewTreeStore
2187 wxDataViewTreeStore is a specialised wxDataViewModel for stroing simple
2188 trees very much like wxTreeCtrl does and it offers a similar API.
2190 This class actually stores the entire tree and the values (therefore its name)
2191 and implements all virtual methods from the base class so it can be used directly
2192 without having to derive any class from it, but it is mostly used from within
2198 class wxDataViewTreeStore
: public wxDataViewModel
2202 Constructor. Creates the invisible root node internally.
2204 wxDataViewTreeStore();
2209 virtual ~wxDataViewTreeStore();
2214 wxDataViewItem
AppendContainer(const wxDataViewItem
& parent
,
2215 const wxString
& text
,
2216 const wxIcon
& icon
= wxNullIcon
,
2217 const wxIcon
& expanded
= wxNullIcon
,
2218 wxClientData
* data
= NULL
);
2223 wxDataViewItem
AppendItem(const wxDataViewItem
& parent
,
2224 const wxString
& text
,
2225 const wxIcon
& icon
= wxNullIcon
,
2226 wxClientData
* data
= NULL
);
2229 Delete all item in the model.
2231 void DeleteAllItems();
2234 Delete all children of the item, but not the item itself.
2236 void DeleteChildren(const wxDataViewItem
& item
);
2241 void DeleteItem(const wxDataViewItem
& item
);
2244 Return the number of children of item.
2246 int GetChildCount(const wxDataViewItem
& parent
) const;
2249 Returns the client data asoociated with the item.
2251 wxClientData
* GetItemData(const wxDataViewItem
& item
) const;
2254 Returns the icon to display in expanded containers.
2256 const wxIcon
& GetItemExpandedIcon(const wxDataViewItem
& item
) const;
2259 Returns the icon of the item.
2261 const wxIcon
& GetItemIcon(const wxDataViewItem
& item
) const;
2264 Returns the text of the item.
2266 wxString
GetItemText(const wxDataViewItem
& item
) const;
2269 Returns the nth child item of item.
2271 wxDataViewItem
GetNthChild(const wxDataViewItem
& parent
,
2272 unsigned int pos
) const;
2275 Inserts a container after @a previous.
2277 wxDataViewItem
InsertContainer(const wxDataViewItem
& parent
,
2278 const wxDataViewItem
& previous
,
2279 const wxString
& text
,
2280 const wxIcon
& icon
= wxNullIcon
,
2281 const wxIcon
& expanded
= wxNullIcon
,
2282 wxClientData
* data
= NULL
);
2285 Inserts an item after @a previous.
2287 wxDataViewItem
InsertItem(const wxDataViewItem
& parent
,
2288 const wxDataViewItem
& previous
,
2289 const wxString
& text
,
2290 const wxIcon
& icon
= wxNullIcon
,
2291 wxClientData
* data
= NULL
);
2294 Inserts a container before the first child item or @a parent.
2296 wxDataViewItem
PrependContainer(const wxDataViewItem
& parent
,
2297 const wxString
& text
,
2298 const wxIcon
& icon
= wxNullIcon
,
2299 const wxIcon
& expanded
= wxNullIcon
,
2300 wxClientData
* data
= NULL
);
2303 Inserts an item before the first child item or @a parent.
2305 wxDataViewItem
PrependItem(const wxDataViewItem
& parent
,
2306 const wxString
& text
,
2307 const wxIcon
& icon
= wxNullIcon
,
2308 wxClientData
* data
= NULL
);
2311 Sets the client data associated with the item.
2313 void SetItemData(const wxDataViewItem
& item
, wxClientData
* data
);
2316 Sets the expanded icon for the item.
2318 void SetItemExpandedIcon(const wxDataViewItem
& item
,
2319 const wxIcon
& icon
);
2322 Sets the icon for the item.
2324 void SetItemIcon(const wxDataViewItem
& item
, const wxIcon
& icon
);
2329 @class wxDataViewIconText
2331 wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2332 This class can be converted to and from a wxVariant.
2337 class wxDataViewIconText
: public wxObject
2344 wxDataViewIconText(const wxString
& text
= wxEmptyString
,
2345 const wxIcon
& icon
= wxNullIcon
);
2346 wxDataViewIconText(const wxDataViewIconText
& other
);
2352 const wxIcon
& GetIcon() const;
2357 wxString
GetText() const;
2362 void SetIcon(const wxIcon
& icon
);
2367 void SetText(const wxString
& text
);
2373 @class wxDataViewEvent
2375 This is the event class for the wxDataViewCtrl notifications.
2377 @beginEventTable{wxDataViewEvent}
2378 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2379 Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2380 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2381 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2382 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2383 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2384 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2385 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2386 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2387 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2388 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2389 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2390 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2391 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2392 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2393 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2394 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2395 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2396 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2397 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2398 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2399 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
2400 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2401 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2402 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2403 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2404 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2405 Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2406 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2407 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2408 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2409 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
2410 @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
2411 Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
2412 @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
2413 Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
2417 @category{events,dvc}
2419 class wxDataViewEvent
: public wxNotifyEvent
2423 Constructor. Typically used by wxWidgets internals only.
2425 wxDataViewEvent(wxEventType commandType
= wxEVT_NULL
,
2429 Returns the position of the column in the control or -1
2430 if no column field was set by the event emitter.
2432 int GetColumn() const;
2435 Returns a pointer to the wxDataViewColumn from which
2436 the event was emitted or @NULL.
2438 wxDataViewColumn
* GetDataViewColumn() const;
2441 Returns the wxDataViewModel associated with the event.
2443 wxDataViewModel
* GetModel() const;
2446 Returns a the position of a context menu event in screen coordinates.
2448 wxPoint
GetPosition() const;
2451 Returns a reference to a value.
2453 const wxVariant
& GetValue() const;
2456 Sets the column index associated with this event.
2458 void SetColumn(int col
);
2461 For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
2463 void SetDataViewColumn(wxDataViewColumn
* col
);
2466 Sets the dataview model associated with this event.
2468 void SetModel(wxDataViewModel
* model
);
2471 Sets the value associated with this event.
2473 void SetValue(const wxVariant
& value
);
2476 Set wxDataObject for data transfer within a drag operation.
2478 void SetDataObject( wxDataObject
*obj
);
2481 Used internally. Gets associated wxDataObject for data transfer
2482 within a drag operation.
2484 wxDataObject
*GetDataObject() const;
2487 Used internally. Sets the wxDataFormat during a drop operation.
2489 void SetDataFormat( const wxDataFormat
&format
);
2492 Gets the wxDataFormat during a drop operation.
2494 wxDataFormat
GetDataFormat() const;
2497 Used internally. Sets the data size for a drop data transfer.
2499 void SetDataSize( size_t size
);
2502 Gets the data size for a drop data transfer.
2504 size_t GetDataSize() const;
2507 Used internally. Sets the data buffer for a drop data transfer.
2509 void SetDataBuffer( void* buf
);
2512 Gets the data buffer for a drop data transfer.
2514 void *GetDataBuffer() const;
2517 Return the first row that will be displayed.
2519 int GetCacheFrom() const;
2522 Return the last row that will be displayed.
2524 int GetCacheTo() const;