non-pch build fixes

[wxWidgets.git] / docs / latex / wx / dataviewmodel.tex

diff --git a/docs/latex/wx/dataviewmodel.tex b/docs/latex/wx/dataviewmodel.tex
index c5063807b171a1339e6f8efa5411266b1f60ed3a..7279f240e8ed9dbdea7781a7b0633ed0e68199de 100644 (file)
--- a/docs/latex/wx/dataviewmodel.tex
+++ b/docs/latex/wx/dataviewmodel.tex
@@ -8,6 +8,7 @@ pure virtual functions in order to define a complete
 data model. In detail, you need to override 
 \helpref{IsContainer}{wxdataviewmodeliscontainer},
 \helpref{GetParent}{wxdataviewmodelgetparent},
 data model. In detail, you need to override 
 \helpref{IsContainer}{wxdataviewmodeliscontainer},
 \helpref{GetParent}{wxdataviewmodelgetparent},

+\helpref{GetChildren}{wxdataviewmodelgetchildren},

 \helpref{GetColumnCount}{wxdataviewmodelgetcolumncount},
 \helpref{GetColumnType}{wxdataviewmodelgetcolumntype} and
 \helpref{GetValue}{wxdataviewmodelgetvalue} in order to
 \helpref{GetColumnCount}{wxdataviewmodelgetcolumncount},
 \helpref{GetColumnType}{wxdataviewmodelgetcolumntype} and
 \helpref{GetValue}{wxdataviewmodelgetvalue} in order to


@@ -15,7 +16,7 @@ define the data model which acts as an interface between
 your actual data and the wxDataViewCtrl. Since you will
 usually also allow the wxDataViewCtrl to change your data
 through its graphical interface, you will also have to override
 your actual data and the wxDataViewCtrl. Since you will
 usually also allow the wxDataViewCtrl to change your data
 through its graphical interface, you will also have to override

-\helpref{SetValue}{wxdataviewlistmodelsetvalue} which the
+\helpref{SetValue}{wxdataviewmodelsetvalue} which the

 wxDataViewCtrl will call when a change to some data has been
 commited.
 
 wxDataViewCtrl will call when a change to some data has been
 commited.
 


@@ -32,13 +33,20 @@ one of the following methods:
 \helpref{ItemAdded}{wxdataviewmodelitemadded},
 \helpref{ItemDeleted}{wxdataviewmodelitemdeleted},
 \helpref{ItemChanged}{wxdataviewmodelitemchanged},
 \helpref{ItemAdded}{wxdataviewmodelitemadded},
 \helpref{ItemDeleted}{wxdataviewmodelitemdeleted},
 \helpref{ItemChanged}{wxdataviewmodelitemchanged},

-\helpref{Cleared}{wxdataviewmodelcleared}.
+\helpref{Cleared}{wxdataviewmodelcleared}. There are
+plural forms for notification of addition, change
+or removal of several item at once. See 
+\helpref{ItemsAdded}{wxdataviewmodelitemsadded},
+\helpref{ItemsDeleted}{wxdataviewmodelitemsdeleted},
+\helpref{ItemsChanged}{wxdataviewmodelitemschanged}.

 
 Note that wxDataViewModel does not define the position or
 
 Note that wxDataViewModel does not define the position or

-index of any item in the control since several control might
-display the data differently, but wxDataViewModel does
+index of any item in the control because different controls
+might display the same data differently. wxDataViewModel does

 provide a \helpref{Compare}{wxdataviewmodelcompare} method
 provide a \helpref{Compare}{wxdataviewmodelcompare} method

-which the wxDataViewCtrl may use to sort the data.
+which the wxDataViewCtrl may use to sort the data either
+in conjunction with a column header or without (see
+\helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}).

 
 This class maintains a list of 
 \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
 
 This class maintains a list of 
 \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}


@@ -53,9 +61,24 @@ to the data in the list model.
 
 Currently wxWidgets provides the following models apart
 from the base model: 
 
 Currently wxWidgets provides the following models apart
 from the base model: 

-\helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}. 
-It is planned to add helper classes for simple tree
-and list stores in the future.
+\helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel},
+\helpref{wxDataViewTreeStore}{wxdataviewtreestore}.
+
+Note that wxDataViewModel is reference counted, derives from 
+\helpref{wxObjectRefData}{wxobjectrefdata} 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:
+
+{\small%
+\begin{verbatim}
+    wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL );
+    wxDataViewModel *musicModel = new MyMusicModel;
+    m_musicCtrl->AssociateModel( musicModel );
+    musicModel->DecRef();  // avoid memory leak !!
+    // add columns now
+\end{verbatim}
+}%

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -69,6 +92,11 @@ and list stores in the future.
 
 \helpref{wxAdv}{librarieslist}
 
 
 \helpref{wxAdv}{librarieslist}
 

+
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+

 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
 
 \func{}{wxDataViewModel}{\void}
 \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel}
 
 \func{}{wxDataViewModel}{\void}


@@ -83,92 +111,165 @@ Constructor.
 Destructor. This should not be called directly. Use DecRef() instead.
 
 
 Destructor. This should not be called directly. Use DecRef() instead.
 
 

+

 \membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}
 
 \func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 
 \membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier}
 
 \func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}}
 

-Adds a \helpref{wxDataViewModelNotifier}{wxdataviewlistmodelnotifier}
+Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}

 to the model.
 
 to the model.
 

+

 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
 
 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
 

-\func{bool}{Cleared}{\void}
+\func{virtual bool}{Cleared}{\void}

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

+

 \membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}
 
 \membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare}
 

-\func{int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{ascending}}
+\func{virtual int}{Compare}{\param{const wxDataViewItem\& }{item1}, \param{const wxDataViewItem\& }{item2}, \param{unsigned int }{column}, \param{bool }{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.
 
 
 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 \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
+
+
+\membersection{wxDataViewModel::GetAttr}\label{wxdataviewmodelgetattr}
+
+\func{bool}{GetAttr}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}, \param{wxDataViewItemAttr\& }{attr}}
+
+Oberride this to indicate that the item has special font attributes.
+This only affects the 
+\helpref{wxDataViewTextRendererText}{wxdataviewtextrendererattr} renderer.
+
+See also \helpref{wxDataViewItemAttr}{wxdataviewitemattr}.
+

 \membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
 
 \membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
 

-\constfunc{unsigned int}{GetColumnCount}{\void}
+\constfunc{virtual unsigned int}{GetColumnCount}{\void}

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

+

 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 
 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 

-\constfunc{wxString}{GetColumnType}{\param{unsigned int }{col}}
+\constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}

 
 Override this to indicate what type of data is stored in the
 column specified by {\it col}. This should return a string
 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 
 
 Override this to indicate what type of data is stored in the
 column specified by {\it col}. This should return a string
 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 

-\membersection{wxDataViewModel::GetFirstChild}\label{wxdataviewmodelgetfirstchild}
-
-\constfunc{wxDataViewItem}{GetFirstChild}{\param{const wxDataViewItem\& }{parent}}

 
 

-To be removed.
+\membersection{wxDataViewModel::GetChildren}\label{wxdataviewmodelgetchildren}

 
 

-\membersection{wxDataViewModel::GetNextSibling}\label{wxdataviewmodelgetnextsibling}
+\constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} }

 
 

-\constfunc{wxDataViewItem}{GetNextSibling}{\param{const wxDataViewItem\& }{item}}
+Override this so the control can query the child items of
+an item. Returns the number of items.

 
 

-To be removed.

 
 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 
 
 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 

-\constfunc{wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
+\constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}

 
 Override this to indicate which wxDataViewItem representing the parent
 
 Override this to indicate which wxDataViewItem representing the parent

-of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.
+of {\it item} or an invalid wxDataViewItem if the the root item is
+the parent item.
+

 
 \membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
 
 
 \membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue}
 

-\constfunc{void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
+\constfunc{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}

 
 Override this to indicate the value of {\it item}
 A \helpref{wxVariant}{wxvariant} is used to store the data.
 
 
 Override this to indicate the value of {\it item}
 A \helpref{wxVariant}{wxvariant} is used to store the data.
 

+
+
+\membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns}
+
+\constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{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 futher columns. By 
+default returns {\it false}.
+
+
+\membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}
+
+\constfunc{virtual bool}{HasDefaultCompare}{\void}
+
+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 also \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}
+for a model which makes use of this.
+
+

 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 
 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 

-\constfunc{bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
+\constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}

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

+

 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 
 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 

-\func{bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
+\func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}

 
 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 been added
 to the data.
 

+

 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 
 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 

-\func{bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
+\func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}

 
 Call this to inform the model that an item has changed.
 
 
 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. 
+
+

 \membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}
 
 \membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}
 

-\func{bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
+\func{virtual bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
+
+Call this to inform the model that an item has been deleted from the data.
+
+
+\membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded}
+
+\func{virtual bool}{ItemsAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
+
+Call this to inform the model that several items have been added
+to the data.
+
+
+\membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged}
+
+\func{virtual bool}{ItemsChanged}{\param{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. 
+
+
+\membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted}
+
+\func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}}
+
+Call this to inform the model that several items have been deleted.

 
 

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

 
 \membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
 
 
 \membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier}
 


@@ -176,16 +277,18 @@ Call this to inform the model that an item has been deleted.
 
 Remove the {\it notifier} from the list of notifiers.
 
 
 Remove the {\it notifier} from the list of notifiers.
 

+

 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 
 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 

-\func{void}{Resort}{\void}
+\func{virtual void}{Resort}{\void}

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

+

 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 
 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 

-\func{bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
+\func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}

 
 This gets called in order to set a value in the data model.
 The most common scenario is that the wxDataViewCtrl calls
 
 This gets called in order to set a value in the data model.
 The most common scenario is that the wxDataViewCtrl calls


@@ -193,10 +296,16 @@ this method after the user changed some data in the view.
 Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
 has to be called!
 
 Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged}
 has to be called!
 

+

 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 
 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 

-\func{bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
+\func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{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.

 
 

-Call this to inform this model that a value in
-the model has been changed.
+This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED
+event to the user.