.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2018 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.dataview.DataViewModel:

==========================================================================================================================================
|phoenix_title|  **wx.dataview.DataViewModel**
==========================================================================================================================================

:ref:`wx.dataview.DataViewModel`  is the base class for all data model to be displayed by a :ref:`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 :meth:`wx.dataview.DataViewModel.IsContainer` , :meth:`wx.dataview.DataViewModel.GetParent` , :meth:`wx.dataview.DataViewModel.GetChildren` , :meth:`wx.dataview.DataViewModel.GetColumnCount` , :meth:`wx.dataview.DataViewModel.GetColumnType`   and :meth:`wx.dataview.DataViewModel.GetValue`   in order to define the data model which acts as an interface between your actual data and the :ref:`wx.dataview.DataViewCtrl`. 

Note that :ref:`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. :ref:`wx.dataview.DataViewModel`  does provide a :meth:`wx.dataview.DataViewModel.Compare`   method which the :ref:`wx.dataview.DataViewCtrl`  may use to sort the data either in conjunction with a column header or without (see :meth:`wx.dataview.DataViewModel.HasDefaultCompare` ). 

:ref:`wx.dataview.DataViewModel`  (as indeed the entire :ref:`wx.dataview.DataViewCtrl`  code) is using :ref:`Variant`  to store data and its type in a generic way. :ref:`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) :ref:`Any`  instead of :ref:`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 :ref:`wx.dataview.DataViewCtrl`  to change your data through its graphical interface, you will also have to override :meth:`wx.dataview.DataViewModel.SetValue`   which the :ref:`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 :ref:`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:

- :meth:`wx.dataview.DataViewModel.ValueChanged` , 
- :meth:`wx.dataview.DataViewModel.ItemAdded` , 
- :meth:`wx.dataview.DataViewModel.ItemDeleted` , 
- :meth:`wx.dataview.DataViewModel.ItemChanged` , 
- :meth:`wx.dataview.DataViewModel.Cleared` . 




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

- :meth:`wx.dataview.DataViewModel.ItemsAdded` , 
- :meth:`wx.dataview.DataViewModel.ItemsDeleted` , 
- :meth:`wx.dataview.DataViewModel.ItemsChanged` . 




This class maintains a list of :ref:`wx.dataview.DataViewModelNotifier`  which link this class to the specific implementations on the supported platforms so that e.g. calling :meth:`wx.dataview.DataViewModel.ValueChanged`   on this model will just call :meth:`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: :ref:`wx.dataview.DataViewIndexListModel`, :ref:`wx.dataview.DataViewVirtualListModel`, :ref:`wx.dataview.DataViewTreeStore`, :ref:`wx.dataview.DataViewListStore`. 

Note that :ref:`wx.dataview.DataViewModel`  is reference counted, derives from :ref:`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| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>DataViewModel</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.dataview.DataViewModel_inheritance.png" alt="Inheritance diagram of DataViewModel" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.RefCounter.html" title="wx.RefCounter" alt="" coords="48,5,159,35"/> <area shape="rect" id="node2" href="wx.dataview.DataViewModel.html" title="wx.dataview.DataViewModel" alt="" coords="5,83,203,112"/> </map> 
   </p>

|


|sub_classes| Known Subclasses
==============================

:ref:`wx.dataview.DataViewListModel`, :ref:`wx.dataview.DataViewTreeStore`

|


|method_summary| Methods Summary
================================

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


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.dataview.DataViewModel.ColumnCount`                                   See :meth:`~wx.dataview.DataViewModel.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.



   .. method:: __init__(self)

      Constructor.                   





   .. method:: AddNotifier(self, notifier)

      Adds a :ref:`wx.dataview.DataViewModelNotifier`  to the model.                  


      :param `notifier`: 
      :type `notifier`: wx.dataview.DataViewModelNotifier







   .. method:: ChangeValue(self, variant, item, col)

      Change the value of the given item and update the control to reflect it.                  

      This function simply calls :meth:`SetValue`   and, if it succeeded, :meth:`ValueChanged` . 




      :param `variant`: The new value.   
      :type `variant`: DVCVariant
      :param `item`: The item (row) to update.   
      :type `item`: wx.dataview.DataViewItem
      :param `col`: The column to update.   
      :type `col`: int










      :rtype: `bool`



                  



      :returns: 

         ``True`` if both :meth:`SetValue`   and :meth:`ValueChanged`   returned ``True``.   







      .. versionadded:: 2.9.1 
    








   .. method:: Cleared(self)

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

      The control will reread the data from the model again.                  

      :rtype: `bool`








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

                


      :param `item1`: 
      :type `item1`: wx.dataview.DataViewItem
      :param `item2`: 
      :type `item2`: wx.dataview.DataViewItem
      :param `column`: 
      :type `column`: int
      :param `ascending`: 
      :type `ascending`: bool




      :rtype: `int`







      .. seealso:: :meth:`HasDefaultCompare` .   








   .. method:: 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``. 




      :param `item`: The item for which the attribute is requested.   
      :type `item`: wx.dataview.DataViewItem
      :param `col`: The column of the item for which the attribute is requested.   
      :type `col`: int
      :param `attr`: The attribute to be filled in if the function returns ``True``.   
      :type `attr`: wx.dataview.DataViewItemAttr










      :rtype: `bool`



                  



      :returns: 

         ``True`` if this item has an attribute or ``False`` otherwise.   







      .. seealso:: :ref:`wx.dataview.DataViewItemAttr`.  








   .. method:: GetChildren(self, item, children)

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

      Returns the number of items.                  


      :param `item`: 
      :type `item`: wx.dataview.DataViewItem
      :param `children`: 
      :type `children`: DataViewItemArray




      :rtype: `int`








   .. method:: GetColumnCount(self)

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

      :rtype: `int`








   .. method:: 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 :ref:`Variant`.                  


      :param `col`: 
      :type `col`: int




      :rtype: `string`








   .. method:: GetParent(self, item)

      Override this to indicate which :ref:`wx.dataview.DataViewItem`  representing the parent of `item`  or an invalid :ref:`wx.dataview.DataViewItem`  if the root item is the parent item.                  


      :param `item`: 
      :type `item`: wx.dataview.DataViewItem




      :rtype: :ref:`wx.dataview.DataViewItem`








   .. method:: GetValue(self, item, col)

      Override this to indicate the value of `item`.                  

      A :ref:`Variant`  is used to store the data.                  


      :param `item`: 
      :type `item`: wx.dataview.DataViewItem
      :param `col`: 
      :type `col`: int




      :rtype: `variant`








   .. method:: 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``.                  


      :param `item`: 
      :type `item`: wx.dataview.DataViewItem




      :rtype: `bool`








   .. method:: HasDefaultCompare(self)

      Override this to indicate that the model provides a default compare function that the control should use if no :ref:`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 :ref:`wx.dataview.DataViewIndexListModel`  for a model which makes use of this.                  

      :rtype: `bool`








   .. method:: 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 :meth:`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 :meth:`HasContainerColumns`   was overridden to return ``True`` for it. 

                


      :param `item`: 
      :type `item`: wx.dataview.DataViewItem
      :param `col`: 




      :rtype: `bool`







      .. versionadded:: 2.9.1 
     








   .. method:: IsContainer(self, item)

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


      :param `item`: 
      :type `item`: wx.dataview.DataViewItem




      :rtype: `bool`








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




      :param `item`: The item whose enabled status is requested.   
      :type `item`: wx.dataview.DataViewItem
      :param `col`: The column of the item whose enabled status is requested.   
      :type `col`: int








      :rtype: `bool`



                  



      :returns: 

         ``True`` if this item should be enabled, ``False`` otherwise.  







      .. versionadded:: 2.9.2 
     







      .. note:: 

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








   .. method:: IsListModel(self)



      :rtype: `bool`








   .. method:: IsVirtualListModel(self)



      :rtype: `bool`








   .. method:: ItemAdded(self, parent, item)

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


      :param `parent`: 
      :type `parent`: wx.dataview.DataViewItem
      :param `item`: 
      :type `item`: wx.dataview.DataViewItem




      :rtype: `bool`








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


      :param `item`: 
      :type `item`: wx.dataview.DataViewItem




      :rtype: `bool`








   .. method:: ItemDeleted(self, parent, item)

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


      :param `parent`: 
      :type `parent`: wx.dataview.DataViewItem
      :param `item`: 
      :type `item`: wx.dataview.DataViewItem




      :rtype: `bool`








   .. method:: ItemsAdded(self, parent, items)

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


      :param `parent`: 
      :type `parent`: wx.dataview.DataViewItem
      :param `items`: 
      :type `items`: DataViewItemArray




      :rtype: `bool`








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


      :param `items`: 
      :type `items`: DataViewItemArray




      :rtype: `bool`








   .. method:: ItemsDeleted(self, parent, items)

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


      :param `parent`: 
      :type `parent`: wx.dataview.DataViewItem
      :param `items`: 
      :type `items`: DataViewItemArray




      :rtype: `bool`








   .. method:: RemoveNotifier(self, notifier)

      Remove the `notifier`  from the list of notifiers.                  


      :param `notifier`: 
      :type `notifier`: wx.dataview.DataViewModelNotifier







   .. method:: Resort(self)

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





   .. method:: 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 :ref:`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, :meth:`ChangeValue`   is usually more convenient as otherwise you need to manually call :meth:`ValueChanged`   to update the control itself.                  


      :param `variant`: 
      :type `variant`: DVCVariant
      :param `item`: 
      :type `item`: wx.dataview.DataViewItem
      :param `col`: 
      :type `col`: int




      :rtype: `bool`








   .. method:: ValueChanged(self, item, col)

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

      This is also called from :ref:`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.                   


      :param `item`: 
      :type `item`: wx.dataview.DataViewItem
      :param `col`: 
      :type `col`: int




      :rtype: `bool`








   .. method:: ~wxDataViewModel(self)

      Destructor.                  

      This should not be called directly. Use :meth:`DecRef`   instead.                   





   .. attribute:: ColumnCount

      See :meth:`~wx.dataview.DataViewModel.GetColumnCount`