#include <wx/dataview.h>

Inheritance diagram for wxDataViewModel:

Detailed Description

wxDataViewModel is the base class for all data model to be displayed by a wxDataViewCtrl.

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 wxDataViewModel::IsContainer, wxDataViewModel::GetParent, wxDataViewModel::GetChildren, wxDataViewModel::GetColumnCount, wxDataViewModel::GetColumnType and wxDataViewModel::GetValue in order to define the data model which acts as an interface between your actual data and the wxDataViewCtrl.

Note that wxDataViewModel does not define the position or index of any item in the control because different controls might display the same data differently. wxDataViewModel does provide a wxDataViewModel::Compare method which the wxDataViewCtrl may use to sort the data either in conjunction with a column header or without (see wxDataViewModel::HasDefaultCompare).

wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant to store data and its type in a generic way. wxVariant 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) wxAny instead of wxVariant 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 wxDataViewCtrl to change your data through its graphical interface, you will also have to override wxDataViewModel::SetValue which the wxDataViewCtrl 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 wxDataViewCtrl, 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 wxDataViewModelNotifier which link this class to the specific implementations on the supported platforms so that e.g. calling wxDataViewModel::ValueChanged on this model will just call wxDataViewModelNotifier::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: wxDataViewIndexListModel, wxDataViewVirtualListModel, wxDataViewTreeStore, wxDataViewListStore.

Note that wxDataViewModel is reference counted, derives from wxRefCounter and cannot be deleted directly as it can be shared by several wxDataViewCtrls. This implies that you need to decrease the reference count after associating the model with a control like this:

wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
wxDataViewModel *musicModel = new MyMusicModel;
m_musicCtrl->AssociateModel( musicModel );
musicModel->DecRef();  // avoid memory leak !!
// add columns now

A potentially better way to avoid memory leaks is to use wxObjectDataPtr

wxObjectDataPtr<MyMusicModel> musicModel;
wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
musicModel = new MyMusicModel;
m_musicCtrl->AssociateModel( musicModel.get() );
// add columns now

Library: wxAdvanced

Category: wxDataViewCtrl Related Classes

Public Member Functions
	wxDataViewModel ()
	Constructor. More...

void	AddNotifier (wxDataViewModelNotifier *notifier)
	Adds a wxDataViewModelNotifier to the model. More...

bool	ChangeValue (const wxVariant &variant, const wxDataViewItem &item, unsigned int col)
	Change the value of the given item and update the control to reflect it. More...

virtual bool	Cleared ()
	Called to inform the model that all data has been cleared. More...

virtual int	Compare (const wxDataViewItem &item1, const wxDataViewItem &item2, unsigned int column, bool ascending) const
	The compare function to be used by control. More...

virtual bool	GetAttr (const wxDataViewItem &item, unsigned int col, wxDataViewItemAttr &attr) const
	Override this to indicate that the item has special font attributes. More...

virtual bool	IsEnabled (const wxDataViewItem &item, unsigned int col) const
	Override this to indicate that the item should be disabled. More...

virtual unsigned int	GetChildren (const wxDataViewItem &item, wxDataViewItemArray &children) const =0
	Override this so the control can query the child items of an item. More...

virtual unsigned int	GetColumnCount () const =0
	Override this to indicate the number of columns in the model. More...

virtual wxString	GetColumnType (unsigned int col) const =0
	Override this to indicate what type of data is stored in the column specified by col. More...

virtual wxDataViewItem	GetParent (const wxDataViewItem &item) const =0
	Override this to indicate which wxDataViewItem representing the parent of item or an invalid wxDataViewItem if the root item is the parent item. More...

virtual void	GetValue (wxVariant &variant, const wxDataViewItem &item, unsigned int col) const =0
	Override this to indicate the value of item. More...

virtual bool	HasContainerColumns (const wxDataViewItem &item) const
	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. More...

virtual bool	HasDefaultCompare () const
	Override this to indicate that the model provides a default compare function that the control should use if no wxDataViewColumn has been chosen for sorting. More...

bool	HasValue (const wxDataViewItem &item, unsigned col) const
	Return true if there is a value in the given column of this item. More...

virtual bool	IsContainer (const wxDataViewItem &item) const =0
	Override this to indicate of item is a container, i.e. if it can have child items. More...

bool	ItemAdded (const wxDataViewItem &parent, const wxDataViewItem &item)
	Call this to inform the model that an item has been added to the data. More...

bool	ItemChanged (const wxDataViewItem &item)
	Call this to inform the model that an item has changed. More...

bool	ItemDeleted (const wxDataViewItem &parent, const wxDataViewItem &item)
	Call this to inform the model that an item has been deleted from the data. More...

bool	ItemsAdded (const wxDataViewItem &parent, const wxDataViewItemArray &items)
	Call this to inform the model that several items have been added to the data. More...

bool	ItemsChanged (const wxDataViewItemArray &items)
	Call this to inform the model that several items have changed. More...

bool	ItemsDeleted (const wxDataViewItem &parent, const wxDataViewItemArray &items)
	Call this to inform the model that several items have been deleted. More...

void	RemoveNotifier (wxDataViewModelNotifier *notifier)
	Remove the notifier from the list of notifiers. More...

virtual void	Resort ()
	Call this to initiate a resort after the sort function has been changed. More...

virtual bool	SetValue (const wxVariant &variant, const wxDataViewItem &item, unsigned int col)=0
	This gets called in order to set a value in the data model. More...

virtual bool	ValueChanged (const wxDataViewItem &item, unsigned int col)
	Call this to inform this model that a value in the model has been changed. More...

virtual bool	IsListModel () const

virtual bool	IsVirtualListModel () const

Public Member Functions inherited from wxRefCounter
	wxRefCounter ()
	Default constructor. More...

void	DecRef ()
	Decrements the reference count associated with this shared data and, if it reaches zero, destroys this instance of wxRefCounter releasing its memory. More...

int	GetRefCount () const
	Returns the reference count associated with this shared data. More...

void	IncRef ()
	Increments the reference count associated with this shared data. More...

Protected Member Functions
virtual	~wxDataViewModel ()
	Destructor. More...

Protected Member Functions inherited from wxRefCounter
virtual	~wxRefCounter ()
	Destructor. More...

Constructor & Destructor Documentation

wxDataViewModel::wxDataViewModel ( )

Constructor.

virtual wxDataViewModel::~wxDataViewModel ( )

protectedvirtual

Destructor.

This should not be called directly. Use DecRef() instead.

Member Function Documentation

void wxDataViewModel::AddNotifier ( wxDataViewModelNotifier * notifier )

Adds a wxDataViewModelNotifier to the model.

bool wxDataViewModel::ChangeValue	(	const wxVariant &	variant,
		const wxDataViewItem &	item,
		unsigned int	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().

Since: 2.9.1

Parameters

variant	The new value.
item	The item (row) to update.
col	The column to update.

Returns: true if both SetValue() and ValueChanged() returned true.

virtual bool wxDataViewModel::Cleared ( )

virtual

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

The control will reread the data from the model again.

virtual int wxDataViewModel::Compare	(	const wxDataViewItem &	item1,
		const wxDataViewItem &	item2,
		unsigned int	column,
		bool	ascending
	)		const

virtual

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.

See also: HasDefaultCompare().

Reimplemented in wxDataViewListModel.

virtual bool wxDataViewModel::GetAttr	(	const wxDataViewItem &	item,
		unsigned int	col,
		wxDataViewItemAttr &	attr
	)		const

virtual

Override this to indicate that the item has special font attributes.

This only affects the wxDataViewTextRendererText renderer.

The base class version always simply returns false.

See also: wxDataViewItemAttr.

Parameters

item	The item for which the attribute is requested.
col	The column of the item for which the attribute is requested.
attr	The attribute to be filled in if the function returns true.

Returns: true if this item has an attribute or false otherwise.

virtual unsigned int wxDataViewModel::GetChildren	(	const wxDataViewItem &	item,
		wxDataViewItemArray &	children
	)		const

pure virtual

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

Returns the number of items.

virtual unsigned int wxDataViewModel::GetColumnCount ( ) const

pure virtual

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

Implemented in wxDataViewListStore.

virtual wxString wxDataViewModel::GetColumnType ( unsigned int col ) const

pure virtual

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 wxVariant.

Implemented in wxDataViewListStore.

virtual wxDataViewItem wxDataViewModel::GetParent ( const wxDataViewItem & item ) const

pure virtual

Override this to indicate which wxDataViewItem representing the parent of item or an invalid wxDataViewItem if the root item is the parent item.

virtual void wxDataViewModel::GetValue	(	wxVariant &	variant,
		const wxDataViewItem &	item,
		unsigned int	col
	)		const

pure virtual

Override this to indicate the value of item.

A wxVariant is used to store the data.

virtual bool wxDataViewModel::HasContainerColumns ( const wxDataViewItem & item ) const

virtual

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.

virtual bool wxDataViewModel::HasDefaultCompare ( ) const

virtual

Override this to indicate that the model provides a default compare function that the control should use if no wxDataViewColumn 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 wxDataViewIndexListModel for a model which makes use of this.

bool wxDataViewModel::HasValue	(	const wxDataViewItem &	item,
		unsigned	col
	)		const

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.

Since: 2.9.1

virtual bool wxDataViewModel::IsContainer ( const wxDataViewItem & item ) const

pure virtual

Override this to indicate of item is a container, i.e. if it can have child items.

virtual bool wxDataViewModel::IsEnabled	(	const wxDataViewItem &	item,
		unsigned int	col
	)		const

virtual

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	The item whose enabled status is requested.
col	The column of the item whose enabled status is requested.

Returns: true if this item should be enabled, false otherwise.

Note: Currently disabling items is not supported by the wxOSX/Carbon implementation.

Since: 2.9.2

virtual bool wxDataViewModel::IsListModel ( ) const

virtual

virtual bool wxDataViewModel::IsVirtualListModel ( ) const

virtual

bool wxDataViewModel::ItemAdded	(	const wxDataViewItem &	parent,
		const wxDataViewItem &	item
	)

Call this to inform the model that an item has been added to the data.

bool wxDataViewModel::ItemChanged ( const wxDataViewItem & 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.

bool wxDataViewModel::ItemDeleted	(	const wxDataViewItem &	parent,
		const wxDataViewItem &	item
	)

Call this to inform the model that an item has been deleted from the data.

bool wxDataViewModel::ItemsAdded	(	const wxDataViewItem &	parent,
		const wxDataViewItemArray &	items
	)

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

bool wxDataViewModel::ItemsChanged ( const wxDataViewItemArray & 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.

bool wxDataViewModel::ItemsDeleted	(	const wxDataViewItem &	parent,
		const wxDataViewItemArray &	items
	)

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

void wxDataViewModel::RemoveNotifier ( wxDataViewModelNotifier * notifier )

Remove the notifier from the list of notifiers.

virtual void wxDataViewModel::Resort ( )

virtual

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

virtual bool wxDataViewModel::SetValue	(	const wxVariant &	variant,
		const wxDataViewItem &	item,
		unsigned int	col
	)

pure virtual

This gets called in order to set a value in the data model.

The most common scenario is that the wxDataViewCtrl 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.

virtual bool wxDataViewModel::ValueChanged	(	const wxDataViewItem &	item,
		unsigned int	col
	)

virtual

Call this to inform this model that a value in the model has been changed.

This is also called from wxDataViewCtrl'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.

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation