X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/61cec318da9631b35a2e7c8d58c3b011006724d1..380740af5dd112601916704a6d78d1112ebb31b5:/docs/latex/wx/dataviewmodel.tex diff --git a/docs/latex/wx/dataviewmodel.tex b/docs/latex/wx/dataviewmodel.tex index 662f99c131..7279f240e8 100644 --- 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}, +\helpref{GetChildren}{wxdataviewmodelgetchildren}, \helpref{GetColumnCount}{wxdataviewmodelgetcolumncount}, \helpref{GetColumnType}{wxdataviewmodelgetcolumntype} and \helpref{GetValue}{wxdataviewmodelgetvalue} in order to @@ -32,15 +33,20 @@ one of the following methods: \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 -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 -\helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}. +\helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}). This class maintains a list of \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier} @@ -55,9 +61,24 @@ to the data in the list 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} @@ -75,12 +96,14 @@ and list stores in the future. \latexignore{\rtfignore{\wxheading{Members}}} + \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel} \func{}{wxDataViewModel}{\void} Constructor. + \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor} \func{}{\destruct{wxDataViewModel}}{\void} @@ -88,6 +111,7 @@ Constructor. Destructor. This should not be called directly. Use DecRef() instead. + \membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier} \func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}} @@ -95,15 +119,17 @@ Destructor. This should not be called directly. Use DecRef() instead. Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier} to the model. + \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. + \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. @@ -111,49 +137,72 @@ 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} -\constfunc{unsigned int}{GetColumnCount}{\void} +\constfunc{virtual unsigned int}{GetColumnCount}{\void} Override this to indicate the number of columns in the model. + \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}. -\membersection{wxDataViewModel::GetFirstChild}\label{wxdataviewmodelgetfirstchild} -\constfunc{wxDataViewItem}{GetFirstChild}{\param{const wxDataViewItem\& }{parent}} +\membersection{wxDataViewModel::GetChildren}\label{wxdataviewmodelgetchildren} -To be removed. +\constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} } -\membersection{wxDataViewModel::GetNextSibling}\label{wxdataviewmodelgetnextsibling} +Override this so the control can query the child items of +an item. Returns the number of items. -\constfunc{wxDataViewItem}{GetNextSibling}{\param{const wxDataViewItem\& }{item}} - -To be removed. \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 -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} -\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. + + +\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} -\func{bool}{HasDefaultCompare}{\void} +\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 @@ -163,31 +212,64 @@ 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} -\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. + \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. + \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. +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{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} @@ -195,16 +277,18 @@ Call this to inform the model that an item has been deleted. Remove the {\it notifier} from the list of notifiers. + \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. + \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 @@ -212,10 +296,16 @@ this method after the user changed some data in the view. Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged} has to be called! + \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.