wx.dataview.DataViewModel¶
wx.dataview.DataViewModel is the base class for all data model to be displayed by a wx.dataview.DataViewCtrl.
All other models derive from it and must implement its pure virtual functions in order to define a complete data model. In detail, you need to override wx.dataview.DataViewModel.IsContainer
, wx.dataview.DataViewModel.GetParent
, wx.dataview.DataViewModel.GetChildren
, and wx.dataview.DataViewModel.GetValue
in order to define the data model which acts as an interface between your actual data and the wx.dataview.DataViewCtrl.
Note that wx.dataview.DataViewModel does not define the position or index of any item in the control because different controls might display the same data differently. wx.dataview.DataViewModel does provide a wx.dataview.DataViewModel.Compare
method which the wx.dataview.DataViewCtrl may use to sort the data either in conjunction with a column header or without (see wx.dataview.DataViewModel.HasDefaultCompare
).
wx.dataview.DataViewModel (as indeed the entire wx.dataview.DataViewCtrl code) is using Variant to store data and its type in a generic way. Variant can be extended to contain almost any data without changes to the original class. To a certain extent, you can use (the somewhat more elegant) Any instead of Variant as there is code to convert between the two, but it is unclear what impact this will have on performance.
Since you will usually allow the wx.dataview.DataViewCtrl to change your data through its graphical interface, you will also have to override wx.dataview.DataViewModel.SetValue
which the wx.dataview.DataViewCtrl will call when a change to some data has been committed.
If the data represented by the model is changed by something else than its associated wx.dataview.DataViewCtrl, the control has to be notified about the change. Depending on what happened you need to call one of the following methods:
There are plural forms for notification of addition, change or removal of several item at once. See:
Note that Cleared
can be called for all changes involving many, or all, of the model items and not only for deleting all of them (i.e. clearing the model).
This class maintains a list of wx.dataview.DataViewModelNotifier which link this class to the specific implementations on the supported platforms so that e.g. calling wx.dataview.DataViewModel.ValueChanged
on this model will just call wx.dataview.DataViewModelNotifier.ValueChanged
for each notifier that has been added. You can also add your own notifier in order to get informed about any changes to the data in the list model.
Currently wxWidgets provides the following models apart from the base model: wx.dataview.DataViewIndexListModel, wx.dataview.DataViewVirtualListModel, wx.dataview.DataViewTreeStore, wx.dataview.DataViewListStore.
Note that wx.dataview.DataViewModel is reference counted, derives from wx.RefCounter and cannot be deleted directly as it can be shared by several DataViewCtrls. This implies that you need to decrease the reference count after associating the model with a control like this:
musicCtrl = wx.dataview.DataViewCtrl(self, wx.ID_ANY)
musicModel = MyMusicModel()
musicCtrl.AssociateModel(musicModel)
musicModel.DecRef() # avoid memory leak !!
# add columns now
A potentially better way to avoid memory leaks is to use ObjectDataPtr
### wxPython does not provide wrappers for wxObjectDataPtr
Class Hierarchy¶
Known Subclasses¶
wx.dataview.DataViewListModel, wx.dataview.DataViewTreeStore
Methods Summary¶
Constructor. |
|
Adds a wx.dataview.DataViewModelNotifier to the model. |
|
Change the value of the given item and update the control to reflect it. |
|
Called to inform the model that all of its data has been changed. |
|
The compare function to be used by the control. |
|
Override this to indicate that the item has special font attributes. |
|
Override this so the control can query the child items of an item. |
|
Override this to indicate which wx.dataview.DataViewItem representing the parent of item or an invalid wx.dataview.DataViewItem if the root item is the parent item. |
|
Override this to indicate the value of item. |
|
Override this method to indicate if a container item merely acts as a headline (or for categorisation) or if it also acts a normal item with entries for further columns. |
|
Override this to indicate that the model provides a default compare function that the control should use if no wx.dataview.DataViewColumn has been chosen for sorting. |
|
Return |
|
Override this to indicate if item is a container, i.e. if it can have child items. |
|
Override this to indicate that the item should be disabled. |
|
Call this to inform the model that an item has been added to the data. |
|
Call this to inform the model that an item has changed. |
|
Call this to inform the model that an item has been deleted from the data. |
|
Call this to inform the model that several items have been added to the data. |
|
Call this to inform the model that several items have changed. |
|
Call this to inform the model that several items have been deleted. |
|
Remove the notifier from the list of notifiers. |
|
Call this to initiate a resort after the sort function has been changed. |
|
This gets called in order to set a value in the data model. |
|
Call this to inform this model that a value in the model has been changed. |
|
|
Destructor. |
Class API¶
- class wx.dataview.DataViewModel(RefCounter)¶
Possible constructors:
DataViewModel() -> None
DataViewModel is the base class for all data model to be displayed by a DataViewCtrl.
Methods¶
- __init__(self)¶
Constructor.
- Return type:
None
- AddNotifier(self, notifier)¶
Adds a wx.dataview.DataViewModelNotifier to the model.
- Parameters:
notifier (wx.dataview.DataViewModelNotifier)
- Return type:
None
- ChangeValue(self, variant, item, col)¶
Change the value of the given item and update the control to reflect it.
This function simply calls
SetValue
and, if it succeeded,ValueChanged
.- Parameters:
variant (DVCVariant) – The new value.
item (wx.dataview.DataViewItem) – The item (row) to update.
col (int) – The column to update.
- Return type:
bool
- Returns:
True
if bothSetValue
andValueChanged
returnedTrue
.
Added in version 2.9.1.
- Cleared(self)¶
Called to inform the model that all of its data has been changed.
This method should be called if so many of the model items have changed, that the control should just reread all of them, repopulating itself entirely.
Note that, contrary to the name of the method, it doesn’t necessarily indicate that model has become empty – although this is the right method to call, rather than
ItemsDeleted
, if it was indeed cleared, which explains the origin of its name.- Return type:
bool
- Compare(self, item1, item2, column, ascending)¶
The compare function to be used by the control.
The default compare function sorts most data types implemented by Variant (i.e. bool, int, long, double, string) as well as datetime and wx.dataview.DataViewIconText. Override this method to implement a different sorting behaviour or override just
DoCompareValues
to extend it to support other Variant types.The function should return negative, null or positive for an ascending comparison, depending on whether the first item is less than, equal to or greater than the second one. The reverse is
True
for descending comparisons. The items should be compared using the appropriate type for the column passed.- Parameters:
item1 (wx.dataview.DataViewItem) – First item to compare.
item2 (wx.dataview.DataViewItem) – Second item to compare.
column (int) – The column holding the items to be compared. If the model class overrides
HasDefaultCompare
to returnTrue
, this parameter will beascending (bool) – Indicates whether the sort is being performed in ascending or descending order.
- Return type:
int
- Returns:
For an ascending comparison: a negative value if the item1 is less than (i.e. should appear above) item2, zero if the two items are equal or a positive value if item1 is greater than (i.e. should appear below) the second one. The reverse for a descending comparison.
Note
If there can be multiple rows with the same value, consider differentiating them form each other by their IDs rather than returning zero. This to prevent rows with the same value jumping positions when items are added etc. For example:
obj1 = self.ItemToObject(item1) obj2 = self.ItemToObject(item2) if obj1[column] == obj2[column]: return 1 if ascending == (item1.GetId() > item2.GetId()) else -1 else: return 1 if ascending == (obj1[column] > obj2[column]) else -1
See also
HasDefaultCompare
,DoCompareValues
- GetAttr(self, item, col, attr)¶
Override this to indicate that the item has special font attributes.
This only affects the DataViewTextRendererText renderer.
The base class version always simply returns
False
.- Parameters:
item (wx.dataview.DataViewItem) – The item for which the attribute is requested.
col (int) – The column of the item for which the attribute is requested.
attr (wx.dataview.DataViewItemAttr) – The attribute to be filled in if the function returns
True
.
- Return type:
bool
- Returns:
True
if this item has an attribute orFalse
otherwise.
See also
- GetChildren(self, item, children)¶
Override this so the control can query the child items of an item.
Returns the number of items.
- Parameters:
item (wx.dataview.DataViewItem)
children (DataViewItemArray)
- Return type:
int
- GetParent(self, item)¶
Override this to indicate which wx.dataview.DataViewItem representing the parent of item or an invalid wx.dataview.DataViewItem if the root item is the parent item.
- Parameters:
item (wx.dataview.DataViewItem)
- Return type:
- GetValue(self, item, col)¶
Override this to indicate the value of item.
This function should fill the provided variant with the value to be shown for the specified item in the given column. The value returned in this Variant must have the appropriate type, e.g. string for the text columns, boolean for the columns using wx.dataview.DataViewToggleRenderer etc, and if there is a type mismatch, nothing will be shown and a debug error message will be logged.
It is also possible to not return any value, in which case nothing will be shown in the corresponding cell, in the same way as if
HasValue
returnedFalse
.- Parameters:
item (wx.dataview.DataViewItem)
col (int)
- Return type:
DVCVariant
- HasContainerColumns(self, item)¶
Override this method to indicate if a container item merely acts as a headline (or for categorisation) or if it also acts a normal item with entries for further columns.
By default returns
False
.- Parameters:
item (wx.dataview.DataViewItem)
- Return type:
bool
- HasDefaultCompare(self)¶
Override this to indicate that the model provides a default compare function that the control should use if no wx.dataview.DataViewColumn has been chosen for sorting.
Usually, the user clicks on a column header for sorting, the data will be sorted alphanumerically.
If any other order (e.g. by index or order of appearance) is required, then this should be used.
Note that if this method is overridden to return
True
, the implementation ofCompare
should be ready to acceptSee wx.dataview.DataViewIndexListModel for a model which makes use of this.
- Return type:
bool
See also
- HasValue(self, item, col)¶
Return
True
if there is a value in the given column of this item.All normal items have values in all columns but the container items only show their label in the first column (col == 0) by default (but see
HasContainerColumns
). So this function by default returnsTrue
for the first column while for the other ones it returnsTrue
only if the item is not a container orHasContainerColumns
was overridden to returnTrue
for it.Since wxWidgets 3.1.4, this method is virtual and can be overridden to explicitly specify for which columns a given item has, and doesn’t have, values.
- Parameters:
item (wx.dataview.DataViewItem)
col
- Return type:
bool
Added in version 2.9.1.
- IsContainer(self, item)¶
Override this to indicate if item is a container, i.e. if it can have child items.
- Parameters:
item (wx.dataview.DataViewItem)
- Return type:
bool
- IsEnabled(self, item, col)¶
Override this to indicate that the item should be disabled.
Disabled items are displayed differently (e.g. grayed out) and cannot be interacted with.
The base class version always returns
True
, thus making all items enabled by default.- Parameters:
item (wx.dataview.DataViewItem) – The item whose enabled status is requested.
col (int) – The column of the item whose enabled status is requested.
- Return type:
bool
- Returns:
True
if this item should be enabled,False
otherwise.
Added in version 2.9.2.
- IsListModel(self)¶
- Return type:
bool
- IsVirtualListModel(self)¶
- Return type:
bool
- ItemAdded(self, parent, item)¶
Call this to inform the model that an item has been added to the data.
- Parameters:
parent (wx.dataview.DataViewItem)
item (wx.dataview.DataViewItem)
- Return type:
bool
- ItemChanged(self, item)¶
Call this to inform the model that an item has changed.
This will eventually emit a
wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
event (in which the column fields will not be set) to the user.- Parameters:
item (wx.dataview.DataViewItem)
- Return type:
bool
- ItemDeleted(self, parent, item)¶
Call this to inform the model that an item has been deleted from the data.
- Parameters:
parent (wx.dataview.DataViewItem)
item (wx.dataview.DataViewItem)
- Return type:
bool
- ItemsAdded(self, parent, items)¶
Call this to inform the model that several items have been added to the data.
- Parameters:
parent (wx.dataview.DataViewItem)
items (DataViewItemArray)
- Return type:
bool
- ItemsChanged(self, items)¶
Call this to inform the model that several items have changed.
This will eventually emit
wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
events (in which the column fields will not be set) to the user.- Parameters:
items (DataViewItemArray)
- Return type:
bool
- ItemsDeleted(self, parent, items)¶
Call this to inform the model that several items have been deleted.
- Parameters:
parent (wx.dataview.DataViewItem)
items (DataViewItemArray)
- Return type:
bool
- RemoveNotifier(self, notifier)¶
Remove the notifier from the list of notifiers.
- Parameters:
notifier (wx.dataview.DataViewModelNotifier)
- Return type:
None
- Resort(self)¶
Call this to initiate a resort after the sort function has been changed.
- Return type:
None
- SetValue(self, variant, item, col)¶
This gets called in order to set a value in the data model.
The most common scenario is that the wx.dataview.DataViewCtrl calls this method after the user changed some data in the view.
This is the function you need to override in your derived class but if you want to call it,
ChangeValue
is usually more convenient as otherwise you need to manually callValueChanged
to update the control itself.- Parameters:
variant (DVCVariant)
item (wx.dataview.DataViewItem)
col (int)
- Return type:
bool
- ValueChanged(self, item, col)¶
Call this to inform this model that a value in the model has been changed.
This is also called from wx.dataview.DataViewCtrl’s internal editing code, e.g. when editing a text field in the control.
This will eventually emit a
wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
event to the user.- Parameters:
item (wx.dataview.DataViewItem)
col (int)
- Return type:
bool
- ~wxDataViewModel(self)
Destructor.
This should not be called directly. Use
DecRef
instead.- Return type:
None