Phoenix Logo

phoenix_title 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 , wx.dataview.DataViewModel.GetColumnCount , wx.dataview.DataViewModel.GetColumnType 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:

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

musicCtrl = wx.dataview.DataViewCtrl(self, wx.ID_ANY)
musicModel = MyMusicModel()
musicCtrl.AssociateModel(musicModel.get())

# add columns now

class_hierarchy Class Hierarchy

Inheritance diagram for class DataViewModel:


method_summary Methods Summary

__init__ Constructor.
AddNotifier Adds a wx.dataview.DataViewModelNotifier to the model.
ChangeValue Change the value of the given item and update the control to reflect it.
Cleared Called to inform the model that all data has been cleared.
Compare The compare function to be used by control.
GetAttr Override this to indicate that the item has special font attributes.
GetChildren Override this so the control can query the child items of an item.
GetColumnCount Override this to indicate the number of columns in the model.
GetColumnType Override this to indicate what type of data is stored in the column specified by col.
GetParent 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.
GetValue Override this to indicate the value of item.
HasContainerColumns 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.
HasDefaultCompare 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.
HasValue Return True if there is a value in the given column of this item.
IsContainer Override this to indicate of item is a container, i.e. if it can have child items.
IsEnabled Override this to indicate that the item should be disabled.
IsListModel  
IsVirtualListModel  
ItemAdded Call this to inform the model that an item has been added to the data.
ItemChanged Call this to inform the model that an item has changed.
ItemDeleted Call this to inform the model that an item has been deleted from the data.
ItemsAdded Call this to inform the model that several items have been added to the data.
ItemsChanged Call this to inform the model that several items have changed.
ItemsDeleted Call this to inform the model that several items have been deleted.
RemoveNotifier Remove the notifier from the list of notifiers.
Resort Call this to initiate a resort after the sort function has been changed.
SetValue This gets called in order to set a value in the data model.
ValueChanged Call this to inform this model that a value in the model has been changed.
~wxDataViewModel Destructor.

property_summary Properties Summary

ColumnCount See GetColumnCount

api Class API



class wx.dataview.DataViewModel(RefCounter)

Possible constructors:

DataViewModel()

DataViewModel is the base class for all data model to be displayed by a DataViewCtrl.


Methods



__init__(self)

Constructor.



AddNotifier(self, notifier)

Adds a wx.dataview.DataViewModelNotifier to the model.

Parameters:notifier (wx.dataview.DataViewModelNotifier) –


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 both SetValue and ValueChanged returned True.

New in version 2.9.1.



Cleared(self)

Called to inform the model that all data has been cleared.

The control will reread the data from the model again.

Return type:bool


Compare(self, item1, item2, column, ascending)

The compare function to be used by control.

The default compare function sorts by container and other items separately and in ascending order. Override this for a different sorting behaviour.

Parameters:
Return type:

int

See also

HasDefaultCompare .



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:
Return type:

bool

Returns:

True if this item has an attribute or False otherwise.



GetChildren(self, item, children)

Override this so the control can query the child items of an item.

Returns the number of items.

Parameters:
Return type:

int



GetColumnCount(self)

Override this to indicate the number of columns in the model.

Return type:int


GetColumnType(self, col)

Override this to indicate what type of data is stored in the column specified by col.

This should return a string indicating the type of data as reported by Variant .

Parameters:col (int) –
Return type:string


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: wx.dataview.DataViewItem


GetValue(self, item, col)

Override this to indicate the value of item.

A Variant is used to store the data.

Parameters:
Return type:

variant



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. See wx.dataview.DataViewIndexListModel for a model which makes use of this.

Return type:bool


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 always returns True for the first column while for the other ones it returns True only if the item is not a container or HasContainerColumns was overridden to return True for it.

Parameters:
Return type:

bool

New in version 2.9.1.



IsContainer(self, item)

Override this to indicate of 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.

New in version 2.9.2.

Note

Currently disabling items is not supported by the OSX/Carbon implementation.



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:
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:
Return type:

bool



ItemsAdded(self, parent, items)

Call this to inform the model that several items have been added to the data.

Parameters:
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:
Return type:

bool



RemoveNotifier(self, notifier)

Remove the notifier from the list of notifiers.

Parameters:notifier (wx.dataview.DataViewModelNotifier) –


Resort(self)

Call this to initiate a resort after the sort function has been changed.



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 call ValueChanged to update the control itself.

Parameters:
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:
Return type:

bool



~wxDataViewModel(self)

Destructor.

This should not be called directly. Use DecRef instead.


Properties



ColumnCount

See GetColumnCount