documentation for window ids allocation and wxIdManager (patch 1870570)

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

diff --git a/docs/latex/wx/dataviewmodel.tex b/docs/latex/wx/dataviewmodel.tex
index b80c86fe7a605fe92161e6b3ecad54362f11c03d..c14c20776c123a546a3f07bd4254e73eecc71e91 100644 (file)
--- a/docs/latex/wx/dataviewmodel.tex
+++ b/docs/latex/wx/dataviewmodel.tex
@@ -33,15 +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
 which the wxDataViewCtrl may use to sort the data either
 in conjunction with a column header or without (see
 provide a \helpref{Compare}{wxdataviewmodelcompare} method
 which the wxDataViewCtrl may use to sort the data either
 in conjunction with a column header or without (see

-\helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
+\helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}).

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


@@ -56,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}
 


@@ -76,12 +96,14 @@ and list stores in the future.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

+

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

+

 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
 
 \func{}{\destruct{wxDataViewModel}}{\void}
 \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor}
 
 \func{}{\destruct{wxDataViewModel}}{\void}


@@ -89,6 +111,7 @@ 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}}


@@ -96,11 +119,14 @@ Destructor. This should not be called directly. Use DecRef() instead.
 Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
 to the model.
 
 Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier}
 to the model.
 

+

 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
 
 \func{virtual bool}{Cleared}{\void}
 
 \membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared}
 
 \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 cleared. The
+control will reread the data from the model again.
+

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


@@ -112,12 +138,24 @@ Override this for a different sorting behaviour.
 
 See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}.
 
 
 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}
 
 \constfunc{virtual unsigned int}{GetColumnCount}{\void}
 
 Override this to indicate the number of columns in the model.
 
 \membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount}
 
 \constfunc{virtual unsigned int}{GetColumnCount}{\void}
 
 Override this to indicate the number of columns in the model.
 

+

 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 
 \constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}
 \membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype}
 
 \constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}}


@@ -126,6 +164,7 @@ 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}.
 
 column specified by {\it col}. This should return a string
 indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 

+

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


@@ -133,12 +172,15 @@ indicating the type of data as reported by \helpref{wxVariant}{wxvariant}.
 Override this so the control can query the child items of
 an item. Returns the number of items.
 
 Override this so the control can query the child items of
 an item. Returns the number of items.
 

+

 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 
 \constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
 
 Override this to indicate which wxDataViewItem representing the parent
 \membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent}
 
 \constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}}
 
 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}
 


@@ -147,6 +189,18 @@ of {\it item} or an invalid wxDataViewItem if {\it item} is the root item.
 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}
 \membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare}
 
 \constfunc{virtual bool}{HasDefaultCompare}{\void}


@@ -159,6 +213,7 @@ 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.
 
 should be used. See also \helpref{wxDataViewIndexListModel}{wxdataviewindexlistmodel}
 for a model which makes use of this.
 

+

 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 
 \constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}
 \membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer}
 
 \constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}}


@@ -166,6 +221,7 @@ for a model which makes use of this.
 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}
 
 \func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 \membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded}
 
 \func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}


@@ -173,17 +229,48 @@ it can have child items.
 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}
 
 \func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}}
 
 Call this to inform the model that an item has changed.
 
 \membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged}
 
 \func{virtual bool}{ItemChanged}{\param{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. 
+
+

 \membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}
 
 \func{virtual bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 
 \membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted}
 
 \func{virtual bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}}
 

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

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


@@ -191,6 +278,7 @@ 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}
 
 \func{virtual void}{Resort}{\void}
 \membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort}
 
 \func{virtual void}{Resort}{\void}


@@ -198,6 +286,7 @@ Remove the {\it notifier} from the list of notifiers.
 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}
 
 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 \membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue}
 
 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}


@@ -208,10 +297,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}
 
 \func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}}
 
 \membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged}
 
 \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.
+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.