X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/1be9182df86e9a902fe9ab6edef960fdc449fed6..380740af5dd112601916704a6d78d1112ebb31b5:/docs/latex/wx/dataviewmodel.tex diff --git a/docs/latex/wx/dataviewmodel.tex b/docs/latex/wx/dataviewmodel.tex index 095ce8918e..7279f240e8 100644 --- a/docs/latex/wx/dataviewmodel.tex +++ b/docs/latex/wx/dataviewmodel.tex @@ -3,13 +3,82 @@ wxDataViewModel is the base class for all data model to be displayed by a \helpref{wxDataViewCtrl}{wxdataviewctrl}. -Currently, this class has no functionality at all and the -only existing implementation of it is the -\helpref{wxDataViewListModel}{wxdataviewlistmodel}. The -plan is to move all functionality of wxDataViewListModel -and a to-be-written wxDataViewTreeModel into wxDataViewModel -and make wxDataViewListModel and wxDataViewTreeModel subsets -of the abstract wxDataViewModel. +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 +\helpref{IsContainer}{wxdataviewmodeliscontainer}, +\helpref{GetParent}{wxdataviewmodelgetparent}, +\helpref{GetChildren}{wxdataviewmodelgetchildren}, +\helpref{GetColumnCount}{wxdataviewmodelgetcolumncount}, +\helpref{GetColumnType}{wxdataviewmodelgetcolumntype} and +\helpref{GetValue}{wxdataviewmodelgetvalue} in order to +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 +\helpref{SetValue}{wxdataviewmodelsetvalue} which the +wxDataViewCtrl will call when a change to some data has been +commited. + +wxDataViewModel (as indeed the entire wxDataViewCtrl +code) is using \helpref{wxVariant}{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. + +The data that is presented through this data model is expected +to change at run-time. You need to inform the data model when +a change happened. Depending on what happened you need to call +one of the following methods: +\helpref{ValueChanged}{wxdataviewmodelvaluechanged}, +\helpref{ItemAdded}{wxdataviewmodelitemadded}, +\helpref{ItemDeleted}{wxdataviewmodelitemdeleted}, +\helpref{ItemChanged}{wxdataviewmodelitemchanged}, +\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 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}). + +This class maintains a list of +\helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier} +which link this class to the specific implementations on the +supported platforms so that e.g. calling +\helpref{ValueChanged}{wxdataviewmodelvaluechanged} +on this model will just call +\helpref{wxDataViewModelNotifier::ValueChanged}{wxdataviewmodelnotifiervaluechanged} +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: +\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} @@ -19,267 +88,224 @@ of the abstract wxDataViewModel. +\wxheading{Library} + +\helpref{wxAdv}{librarieslist} + + + +\latexignore{\rtfignore{\wxheading{Members}}} + + \membersection{wxDataViewModel::wxDataViewModel}\label{wxdataviewmodelwxdataviewmodel} \func{}{wxDataViewModel}{\void} Constructor. + \membersection{wxDataViewModel::\destruct{wxDataViewModel}}\label{wxdataviewmodeldtor} \func{}{\destruct{wxDataViewModel}}{\void} -Destructor. +Destructor. This should not be called directly. Use DecRef() instead. -\section{\class{wxDataViewListModel}}\label{wxdataviewlistmodel} -wxDataViewListModel is currently the only existing variant -of a \helpref{wxDataViewModel}{wxdataviewmodel}. It allows -to define a table like data model to be displayed by a -\helpref{wxDataViewCtrl}{wxdataviewctrl}. You need to derive -from this class to define your own data model. -You need to override \helpref{GetRowCount}{wxdataviewlistmodelgetrowcount}, -\helpref{GetColumnCount}{wxdataviewlistmodelgetcolumncount}, -\helpref{GetColumnType}{wxdataviewlistmodelgetcolumntype} and -\helpref{GetValue}{wxdataviewlistmodelgetvalue} in order to -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 -\helpref{SetValue}{wxdataviewlistmodelsetvalue} which the -wxDataViewCtrl will call when a change to some data has been -commited. +\membersection{wxDataViewModel::AddNotifier}\label{wxdataviewmodeladdnotifier} -The data that is presented through this data model is expected -to change at run-time. You need to inform the data model that -a change happens. Depending on what happened you need to call -one of the following methods: -\helpref{ValueChanged}{wxdataviewlistmodelvaluechanged}, -\helpref{RowChanged}{wxdataviewlistmodelrowchanged}, -\helpref{RowAppended}{wxdataviewlistmodelrowappended}, -\helpref{RowPrepended}{wxdataviewlistmodelrowprepended}, -\helpref{RowInserted}{wxdataviewlistmodelrowinserted}, -\helpref{RowDeleted}{wxdataviewlistmodelrowdeleted}, -\helpref{RowsReordered}{wxdataviewlistmodelrowsreordered} or -\helpref{RowsCleared}{wxdataviewlistmodelcleared}. +\func{void}{AddNotifier}{\param{wxDataViewModelNotifier* }{notifier}} +Adds a \helpref{wxDataViewModelNotifier}{wxdataviewmodelnotifier} +to the model. -wxDataViewModel and this class (as indeed the entire wxDataViewCtrl -code) is using \helpref{wxVariant}{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. +\membersection{wxDataViewModel::Cleared}\label{wxdataviewmodelcleared} -This class maintains a list of -\helpref{wxDataListViewListModelNotifier}{wxdataviewlistmodelnotifier} -which link this class to the specific implementations on the -supported platforms so that e.g. calling -\helpref{ValueChanged}{wxdataviewlistmodelvaluechanged} -on this model will just call -\helpref{wxDataListViewListModelNotifier::ValueChanged}{wxdataviewlistmodelnotifiervaluechanged} -for each notifier that has been added. This is used both for -informing the native controls to redraw themselves and for informing -e.g. the \helpref{wxDataViewSortedListModel}{wxdataviewsortedlistmodel} -to resort itself. You can also add your own notifier in order -to get informed about any changes to the data in the list model. - -Additionally, this class maintains a list of all -\helpref{wxDataViewColumns}{wxdataviewcolumn} which -display a certain column of this list model. This is -mostly used internally. +\func{virtual bool}{Cleared}{\void} -\wxheading{Derived from} +Called to inform the model that all data has been deleted. -\helpref{wxDataViewModel}{wxdataviewmodel}\\ -\helpref{wxObject}{wxobject} -\wxheading{Include files} +\membersection{wxDataViewModel::Compare}\label{wxdataviewmodelcompare} - +\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. -\membersection{wxDataViewListModel::wxDataViewListModel}\label{wxdataviewlistmodelwxdataviewlistmodel} +See also \helpref{HasDefaultCompare}{wxdataviewmodelhasdefaultcompare}. -\func{}{wxDataViewListModel}{\void} -Constructor. - -\membersection{wxDataViewListModel::\destruct{wxDataViewListModel}}\label{wxdataviewlistmodeldtor} - -\func{}{\destruct{wxDataViewListModel}}{\void} +\membersection{wxDataViewModel::GetAttr}\label{wxdataviewmodelgetattr} -Destructor. +\func{bool}{GetAttr}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}, \param{wxDataViewItemAttr\& }{attr}} -\membersection{wxDataViewListModel::AddNotifier}\label{wxdataviewlistmodeladdnotifier} +Oberride this to indicate that the item has special font attributes. +This only affects the +\helpref{wxDataViewTextRendererText}{wxdataviewtextrendererattr} renderer. -\func{void}{AddNotifier}{\param{wxDataViewListModelNotifier* }{notifier}} +See also \helpref{wxDataViewItemAttr}{wxdataviewitemattr}. -Adds {\it notifier} to the internal list of notifers. +\membersection{wxDataViewModel::GetColumnCount}\label{wxdataviewmodelgetcolumncount} -See also \helpref{RemoveNotifier}{wxdataviewlistmodelremovenotifier}. +\constfunc{virtual unsigned int}{GetColumnCount}{\void} -\membersection{wxDataViewListModel::AddViewingColumn}\label{wxdataviewlistmodeladdviewingcolumn} +Override this to indicate the number of columns in the model. -\func{void}{AddViewingColumn}{\param{wxDataViewColumn* }{view\_column}, \param{unsigned int }{model\_column}} -Used internally. Used for maintaining a list of -\helpref{wxDataViewColumn}{wxdataviewcolumn} that -display a certain column of this model. +\membersection{wxDataViewModel::GetColumnType}\label{wxdataviewmodelgetcolumntype} -\membersection{wxDataViewListModel::Cleared}\label{wxdataviewlistmodelcleared} +\constfunc{virtual wxString}{GetColumnType}{\param{unsigned int }{col}} -\func{bool}{virtual Cleared}{\void} +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}. -Call this if all data in your model has been cleared. -\membersection{wxDataViewListModel::GetColumnCount}\label{wxdataviewlistmodelgetcolumncount} +\membersection{wxDataViewModel::GetChildren}\label{wxdataviewmodelgetchildren} -\func{virtual unsigned int}{GetColumnCount}{\void} +\constfunc{virtual unsigned int}{GetChildren}{\param{const wxDataViewItem\& }{item}, \param{wxDataViewItemArray\& }{children} } -Override this to indicate, how many columns the list -model has. +Override this so the control can query the child items of +an item. Returns the number of items. -\membersection{wxDataViewListModel::GetColumnType}\label{wxdataviewlistmodelgetcolumntype} -\func{virtual wxString}{GetColType}{\param{unsigned int }{col}} +\membersection{wxDataViewModel::GetParent}\label{wxdataviewmodelgetparent} -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}. +\constfunc{virtual wxDataViewItem}{GetParent}{\param{const wxDataViewItem\& }{item}} -\membersection{wxDataViewListModel::GetRowCount}\label{wxdataviewlistmodelgetrowcount} +Override this to indicate which wxDataViewItem representing the parent +of {\it item} or an invalid wxDataViewItem if the the root item is +the parent item. -\func{virtual unsigned int}{GetRowCount}{\void} -Override this to indicate, how many rows the list -model has. +\membersection{wxDataViewModel::GetValue}\label{wxdataviewmodelgetvalue} -\membersection{wxDataViewListModel::GetValue}\label{wxdataviewlistmodelgetvalue} +\constfunc{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}} -\func{virtual void}{GetValue}{\param{wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}} +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 a given value -in the list model. A \helpref{wxVariant}{wxvariant} -is used to store the data. -\membersection{wxDataViewListModel::RemoveNotifier}\label{wxdataviewlistmodelremovenotifier} -\func{void}{RemoveNotifier}{\param{wxDataViewListModelNotifier* }{notifier}} +\membersection{wxDataViewModel::HasContainerColumns}\label{wxdataviewmodelhascontainercolumns} -Removes the notifier from the list of notifiers. +\constfunc{virtual bool}{HasContainerColumns}{\param{const wxDataViewItem\& }{item}} -See also \helpref{AddNotifier}{wxdataviewlistmodeladdnotifier}. +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{wxDataViewListModel::RemoveViewingColumn}\label{wxdataviewlistmodelremoveviewingcolumn} -\func{void}{RemoveViewingColumn}{\param{wxDataViewColumn* }{column}} +\membersection{wxDataViewModel::HasDefaultCompare}\label{wxdataviewmodelhasdefaultcompare} -Used internally. Used for maintaining a list of -\helpref{wxDataViewColumn}{wxdataviewcolumn} that -display a certain column of this model. +\constfunc{virtual bool}{HasDefaultCompare}{\void} -\membersection{wxDataViewListModel::RowAppended}\label{wxdataviewlistmodelrowappended} +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. -\func{virtual bool}{RowAppended}{\void} -Call this if a row has been appended to the list model. +\membersection{wxDataViewModel::IsContainer}\label{wxdataviewmodeliscontainer} -\membersection{wxDataViewListModel::RowChanged}\label{wxdataviewlistmodelrowchanged} +\constfunc{virtual bool}{IsContainer}{\param{const wxDataViewItem\& }{item}} -\func{virtual bool}{RowChanged}{\param{unsigned int }{row}} +Override this to indicate of {\it item} is a container, i.e. if +it can have child items. -Call this if the values of this row have been changed. -\membersection{wxDataViewListModel::RowDeleted}\label{wxdataviewlistmodelrowdeleted} +\membersection{wxDataViewModel::ItemAdded}\label{wxdataviewmodelitemadded} -\func{virtual bool}{RowDeleted}{\param{unsigned int }{row}} +\func{virtual bool}{ItemAdded}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}} -Call this if this row has been deleted. +Call this to inform the model that an item has been added +to the data. -\membersection{wxDataViewListModel::RowInserted}\label{wxdataviewlistmodelrowinserted} -\func{virtual bool}{RowInserted}{\param{unsigned int }{before}} +\membersection{wxDataViewModel::ItemChanged}\label{wxdataviewmodelitemchanged} -Call this if a row has been inserted. +\func{virtual bool}{ItemChanged}{\param{const wxDataViewItem\& }{item}} -\membersection{wxDataViewListModel::RowPrepended}\label{wxdataviewlistmodelrowprepended} +Call this to inform the model that an item has changed. -\func{virtual bool}{RowPrepended}{\void} +This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED +event (in which the column fields will not be set) to the user. -Call this if a row has been prepended. -\membersection{wxDataViewListModel::RowsReordered}\label{wxdataviewlistmodelrowsreordered} +\membersection{wxDataViewModel::ItemDeleted}\label{wxdataviewmodelitemdeleted} -\func{virtual bool}{RowsReordered}{\param{unsigned int* }{new\_order}} +\func{virtual bool}{ItemDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItem\& }{item}} -Call this if the rows have been reorderd. +Call this to inform the model that an item has been deleted from the data. -\membersection{wxDataViewListModel::SetValue}\label{wxdataviewlistmodelsetvalue} -\func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{unsigned int }{col}, \param{unsigned int }{row}} +\membersection{wxDataViewModel::ItemsAdded}\label{wxdataviewmodelitemsadded} -This method gets called by e.g. the wxDataViewCtrl class if a -value has been changed through its graphical interface. You -need to override this method in order to update the data in -the underlying data structur. Afterwards, -\helpref{ValueChanged}{wxdataviewlistmodelvaluechanged} is called. +\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{wxDataViewListModel::ValueChanged}\label{wxdataviewlistmodelvaluechanged} -\func{virtual bool}{ValueChanged}{\param{unsigned int }{col}, \param{unsigned int }{row}} +\membersection{wxDataViewModel::ItemsChanged}\label{wxdataviewmodelitemschanged} -Call this if a value in the model has been changed. +\func{virtual bool}{ItemsChanged}{\param{const wxDataViewItemArray\& }{items}} +Call this to inform the model that several items have changed. -\section{\class{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodel} +This will eventually emit wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED +events (in which the column fields will not be set) to the user. -This class is used for sorting data. It does not contain any -data itself. Rather, it provides a sorted interface for -another list model. -Currently, the sorting algorithm isn't thread safe. This needs -to be fixed. +\membersection{wxDataViewModel::ItemsDeleted}\label{wxdataviewmodelitemsdeleted} -\wxheading{Derived from} +\func{virtual bool}{ItemsDeleted}{\param{const wxDataViewItem\& }{parent}, \param{const wxDataViewItemArray\& }{items}} -\helpref{wxDataViewListModel}{wxdataviewlistmodel}\\ -\helpref{wxDataViewModel}{wxdataviewmodel}\\ -\helpref{wxObject}{wxobject} +Call this to inform the model that several items have been deleted. -\wxheading{Include files} - +\membersection{wxDataViewModel::RemoveNotifier}\label{wxdataviewmodelremovenotifier} -\membersection{wxDataViewSortedListModel::wxDataViewSortedListModel}\label{wxdataviewsortedlistmodelwxdataviewsortedlistmodel} +\func{void}{RemoveNotifier}{\param{wxDataViewModelNotifier* }{notifier}} -\func{}{wxDataViewSortedListModel}{\param{wxDataViewListModel* }{child}} +Remove the {\it notifier} from the list of notifiers. -Constructor. {\it child} is the child data model the data of -which this model is supposed to present in a sorted way. -\membersection{wxDataViewSortedListModel::\destruct{wxDataViewSortedListModel}}\label{wxdataviewsortedlistmodeldtor} +\membersection{wxDataViewModel::Resort}\label{wxdataviewmodelresort} -\func{}{\destruct{wxDataViewSortedListModel}}{\void} +\func{virtual void}{Resort}{\void} -Destructor. +Call this to initiate a resort after the sort function has +been changed. -\membersection{wxDataViewSortedListModel::GetAscending}\label{wxdataviewsortedlistmodelgetascending} -\func{bool}{GetAscending}{\void} +\membersection{wxDataViewModel::SetValue}\label{wxdataviewmodelsetvalue} -Returns true if the data is sorted in ascending order. +\func{virtual bool}{SetValue}{\param{const wxVariant\& }{variant}, \param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}} -\membersection{wxDataViewSortedListModel::Resort}\label{wxdataviewsortedlistmodelresort} +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. +Afterwards \helpref{ValueChanged}{wxdataviewmodelvaluechanged} +has to be called! -\func{void}{Resort}{\void} -Tell the model to resort its data. +\membersection{wxDataViewModel::ValueChanged}\label{wxdataviewmodelvaluechanged} -\membersection{wxDataViewSortedListModel::SetAscending}\label{wxdataviewsortedlistmodelsetascending} +\func{virtual bool}{ValueChanged}{\param{const wxDataViewItem\& }{item}, \param{unsigned int }{col}} -\func{void}{SetAscending}{\param{bool }{ascending}} +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. -Set the sort order of the data. +This will eventually emit a wxEVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED +event to the user.