| Version: 3.2.5

Public Member Functions | Protected Member Functions | List of all members
wxDataViewModel Class Referenceabstract
Class List by Category » wxDataViewCtrl Related Classes

`#include <wx/dataview.h>`

Inheritance diagram for wxDataViewModel:
[legend]

## 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, 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:

- wxDataViewModel::ValueChanged,
- wxDataViewModel::ItemAdded,
- wxDataViewModel::ItemDeleted,
- wxDataViewModel::ItemChanged,
- wxDataViewModel::Cleared.

There are plural forms for notification of addition, change or removal of several item at once. See:

- wxDataViewModel::ItemsAdded,
- wxDataViewModel::ItemsDeleted,
- wxDataViewModel::ItemsChanged.

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 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;
musicCtrl->AssociateModel(musicModel);
musicModel->DecRef(); // avoid memory leak !!
// add columns now
wxDataViewCtrl
wxDataViewCtrl is a control to display data either in a tree like fashion or in a tabular form or bot...
Definition: dataview.h:1010
wxDataViewCtrl::AssociateModel
virtual bool AssociateModel(wxDataViewModel *model)
Associates a wxDataViewModel with the control.
wxDataViewModel
wxDataViewModel is the base class for all data model to be displayed by a wxDataViewCtrl.
Definition: dataview.h:100
wxRefCounter::DecRef
void DecRef()
Decrements the reference count associated with this shared data and, if it reaches zero,...
wxID_ANY
@ wxID_ANY
Any id: means that we don't care about the id, whether when installing an event handler or when creat...
Definition: defs.h:597

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

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

##

Library: wxCore
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...
bool | Cleared ()
| Called to inform the model that all of its data has been changed. More...
virtual int | Compare (const wxDataViewItem &item1, const wxDataViewItem &item2, unsigned int column, bool ascending) const
| The compare function to be used by the 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 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...
virtual 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 if 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...
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...
virtual int | DoCompareValues (const wxVariant &value1, const wxVariant &value2) const
| Virtual method that can be overridden to define comparison for values of non-standard types. More...
Protected Member Functions inherited from wxRefCounter
virtual | ~wxRefCounter ()
| Destructor. More...

## Constructor & Destructor Documentation

## ◆ wxDataViewModel()

wxDataViewModel::wxDataViewModel | ( |  | ) |

Constructor.

## ◆ ~wxDataViewModel()

virtual wxDataViewModel::~wxDataViewModel | ( |  | ) |

protected virtual

Destructor.

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

## Member Function Documentation

## ◆ AddNotifier()

void wxDataViewModel::AddNotifier | ( | wxDataViewModelNotifier * | notifier | ) |

Adds a wxDataViewModelNotifier to the model.

## ◆ ChangeValue()

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.

## ◆ Cleared()

bool wxDataViewModel::Cleared | ( |  | ) |

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.

## ◆ Compare()

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

virtual

The compare function to be used by the control.

The default compare function sorts most data types implemented by wxVariant (i.e. bool, int, long, double, string) as well as datetime and wxDataViewIconText. Override this method to implement a different sorting behaviour or override just DoCompareValues() to extend it to support other wxVariant 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 | First item to compare.
  item2 | Second item to compare.
  column | The column holding the items to be compared. If the model class overrides HasDefaultCompare() to return true, this parameter will be ``(unsigned)-1 when sorting items if no column is selected for sorting them.
  ascending | Indicates whether the sort is being performed in ascending or descending order.

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:
  // Note that we need to distinguish between items with the same
  // value.
  wxUIntPtr id1 = wxPtrToUInt(item1.GetID()),
  id2 = wxPtrToUInt(item2.GetID());
  return (ascending == (id1 > id2)) ? : 1 : -1;
  wxUIntPtr
  size_t wxUIntPtr
  Signed and unsigned integral types big enough to contain all of long, size_t and void*.
  Definition: defs.h:1424

See also
  HasDefaultCompare(), DoCompareValues()

Reimplemented in wxDataViewListModel.

## ◆ DoCompareValues()

virtual int wxDataViewModel::DoCompareValues | ( | const wxVariant & | value1,
|  | const wxVariant & | value2
| ) |  | const

protected virtual

Virtual method that can be overridden to define comparison for values of non-standard types.

This function is called from the default Compare() implementation to compare values of types it is not aware about (i.e. not any of the standard ones). As Compare() itself, this method should return a negative value if value1 is less than (i.e. should appear above) value2 and a positive value if value2 is less than value1.

Unlike Compare(), if the values are equal, this method should just return 0 to indicate it and let Compare() order them by their items values. It also doesn't have to care about the sort order direction, making it simpler to override than Compare() itself.

The default implementation just returns 0, so the derived class version can simply forward to it if it doesn't know how to compare the given values.

See also
  Compare()

Since
  3.1.1

## ◆ GetAttr()

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.

## ◆ GetChildren()

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.

## ◆ GetParent()

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.

## ◆ GetValue()

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

pure virtual

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 wxVariant must have the appropriate type, e.g. string for the text columns, boolean for the columns using wxDataViewToggleRenderer 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() returned false.

## ◆ HasContainerColumns()

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.

## ◆ HasDefaultCompare()

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.

Note that if this method is overridden to return true, the implementation of Compare() should be ready to accept ``(unsigned)-1 as the value for the column index parameter.

See wxDataViewIndexListModel for a model which makes use of this.

See also
  Compare()

## ◆ HasValue()

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

virtual

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

Since
  2.9.1

## ◆ IsContainer()

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

pure virtual

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

## ◆ IsEnabled()

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.

Since
  2.9.2

## ◆ IsListModel()

virtual bool wxDataViewModel::IsListModel | ( |  | ) | const

virtual

## ◆ IsVirtualListModel()

virtual bool wxDataViewModel::IsVirtualListModel | ( |  | ) | const

virtual

## ◆ ItemAdded()

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

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

## ◆ ItemChanged()

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.

## ◆ ItemDeleted()

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

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

## ◆ ItemsAdded()

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

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

## ◆ ItemsChanged()

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.

## ◆ ItemsDeleted()

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

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

## ◆ RemoveNotifier()

void wxDataViewModel::RemoveNotifier | ( | wxDataViewModelNotifier * | notifier | ) |

Remove the notifier from the list of notifiers.

## ◆ Resort()

virtual void wxDataViewModel::Resort | ( |  | ) |

virtual

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

## ◆ SetValue()

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.

## ◆ ValueChanged()

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

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.