sorting support for generic version (patch 1765087 from Bo)

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

\section{\class{wxDataViewCtrl}}\label{wxdataviewctrl}

This class and its documentation are work in progress and
therefore subject to change.

wxDataViewCtrl is planned to be a control to display data either
in a tree like fashion or in a tabular form or both. So far,
only the tabular form is implemented. 

Unlike \helpref{wxListCtrl}{wxlistctrl} wxDataViewCtrl doesn't 
get its data from the user through virtual functions or events,
instead you need to write your own 
\helpref{wxDataViewListModel}{wxdataviewlistmodel} and associate
it with this control. Then you need to add a number of
\helpref{wxDataViewColumn}{wxdataviewcolumn} to this control to
define what each column shall display. Each wxDataViewColumn
in turn owns 1 instance of a 
\helpref{wxDataViewRenderer}{wxdataviewrenderer} to render its
cells. A number of standard renderers for rendering text, dates,
images, toggle, a progress bar etc. are provided. Additionally,
the user can write custom renderes deriving from 
\helpref{wxDataViewCustomRenderer}{wxdataviewcustomrenderer}
for displaying anything.

All data transfer from the control to the model and the user
code is done through \helpref{wxVariant}{wxvariant} which can
be extended to support more data formats as necessary. 
Accordingly, all type information uses the strings returned
from \helpref{wxVariant::GetType}{wxvariantgettype}.

So far, this control has been implemented for GTK+ and there
is an almost complete generic implementation including several
additions for a native Windows look and feel (in particular
concerning the header). It is planned to implement the control
natively under OS X.

\wxheading{Window styles}

\twocolwidtha{5cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxDV\_SINGLE}}{Single selection mode. This is the default.}
\twocolitem{\windowstyle{wxDV\_MULTIPLE}}{Multiple selection mode.}
\end{twocollist}


\wxheading{Event handling}

To process input from a dataview control, use the following event handler
macros to direct input to member functions that take a 
\helpref{wxDataViewEvent}{wxdataviewevent} argument.

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt

\twocolitem{{\bf EVT\_DATAVIEW\_ROW\_SELECTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ROW\_SELECTED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_ROW\_ACTIVATED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ROW\_ACTIVATED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_CLICK(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_CLICKED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_RIGHT\_CLICK(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_RIGHT\_CLICKED event.}

\end{twocollist}

Additionally, you can get informed about changes to the
\helpref{model}{wxdataviewlistmodel}, to which a wxDataViewCtrl
has been associated. These events correspond to the interface
offered by \helpref{wxDataViewListModelNotifier}{wxdataviewlistmodelnotifier}.

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt

\twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_PREPENDED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_PREPENDED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_APPENDED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_APPENDED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_INSERTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_INSERTED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_DELETED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_DELETED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_CHANGED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_CHANGED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_VALUE\_CHANGED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_VALUE\_CHANGED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROWS\_REORDERED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROWS\_REORDERED event.}
\twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_CLEARED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_CLEARED event.}

\end{twocollist}


\wxheading{Derived from}

\helpref{wxControl}{wxcontrol}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}


\membersection{wxDataViewCtrl::wxDataViewCtrl}\label{wxdataviewctrlwxdataviewctrl}

\func{}{wxDataViewCtrl}{\void}

\func{}{wxDataViewCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID }{id}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}}

Constructor. Calls \helpref{Create}{wxdataviewctrlcreate}.

\membersection{wxDataViewCtrl::\destruct{wxDataViewCtrl}}\label{wxdataviewctrldtor}

\func{}{\destruct{wxDataViewCtrl}}{\void}

Destructor.

\membersection{wxDataViewCtrl::AppendColumn}\label{wxdataviewctrlappendcolumn}

\func{virtual bool}{AppendColumn}{\param{wxDataViewColumn* }{col}}

Add a \helpref{wxDataViewColumn}{wxdataviewcolumn} to the control. Note
that there is a number of short cut methods which implicitly create
a \helpref{wxDataViewColumn}{wxdataviewcolumn} and a 
\helpref{wxDataViewRenderer}{wxdataviewrenderer} for it (see below).


\membersection{wxDataViewCtrl::AppendBitmapColumn}\label{wxdataviewctrlappendbitmapcolumn}

\func{bool}{AppendBitmapColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}

\func{bool}{AppendBitmapColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}

Appends a column for rendering a bitmap.

\membersection{wxDataViewCtrl::AppendDateColumn}\label{wxdataviewctrlappenddatecolumn}

\func{bool}{AppendDateColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}}

\func{bool}{AppendDateColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}}

Appends a column for rendering a date.

\membersection{wxDataViewCtrl::AppendProgressColumn}\label{wxdataviewctrlappendprogresscolumn}

\func{bool}{AppendProgressColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}}

\func{bool}{AppendProgressColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}}

Appends a column for rendering a progress indicator.

\membersection{wxDataViewCtrl::AppendTextColumn}\label{wxdataviewctrlappendtextcolumn}

\func{bool}{AppendTextColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}

\func{bool}{AppendTextColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}

Appends a column for rendering text.

\membersection{wxDataViewCtrl::AppendToggleColumn}\label{wxdataviewctrlappendtogglecolumn}

\func{bool}{AppendToggleColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}}

\func{bool}{AppendToggleColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}}

Appends a column for rendering a toggle.

\membersection{wxDataViewCtrl::AssociateModel}\label{wxdataviewctrlassociatemodel}

\func{virtual bool}{AssociateModel}{\param{wxDataViewListModel* }{model}}

Associates a \helpref{wxDataViewListModel}{wxdataviewlistmodel} with the
control. In the future this should be changed to supporting any data
model including a to-be-written wxDataViewTreeModel.

\membersection{wxDataViewCtrl::Create}\label{wxdataviewctrlcreate}

\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}}

Create the control. Useful for two step creation.

\membersection{wxDataViewCtrl::ClearColumns}\label{wxdataviewctrlclearcolumns}

\func{virtual bool}{ClearColumns}{\void}

Removes all columns.

\membersection{wxDataViewCtrl::ClearSelection}\label{wxdataviewctrlclearselection}

\func{void}{ClearSelection}{\void}

Unselects all rows.

\membersection{wxDataViewCtrl::DeleteColumn}\label{wxdataviewctrldeletecolumn}

\func{virtual bool}{DeleteColumn}{\param{unsigned int }{pos}}

Deletes given column.

\membersection{wxDataViewCtrl::GetColumn}\label{wxdataviewctrlgetcolumn}

\func{virtual wxDataViewColumn*}{GetColumn}{\param{unsigned int }{pos}}

Returns pointer to the column.

\membersection{wxDataViewCtrl::GetModel}\label{wxdataviewctrlgetmodel}

\func{virtual wxDataViewListModel*}{GetModel}{\void}

Returns pointer to the data model associated with the
control (if any).

\membersection{wxDataViewCtrl::GetColumnCount}\label{wxdataviewctrlgetcolumncount}

\func{virtual unsigned int}{GetColumnCount}{\void}

Returns the number of columns.

\membersection{wxDataViewCtrl::GetSelection}\label{wxdataviewctrlgetselection}

\constfunc{virtual int}{GetSelection}{\void}

Returns the index of the currently selected row. It will 
return -1 if no row is selected and the index of the first
selected row if more than one row are selected.

\membersection{wxDataViewCtrl::GetSelections}\label{wxdataviewctrlgetselections}

\constfunc{virtual int}{GetSelections}{\param{wxArrayInt\& }{aSelections}}

Returns the number of selected rows and fills an array of int
with the indeces of the selected rows.

\membersection{wxDataViewCtrl::IsSelected}\label{wxdataviewctrlisselected}

\constfunc{virtual bool}{IsSelected}{\param{unsigned int }{row}}

Returns {\it true} if the row is selected, {\it false} otherwise.

\membersection{wxDataViewCtrl::SetSelection}\label{wxdataviewctrlsetselection}

\func{virtual void}{SetSelection}{\param{int }{row}}

Sets the selection. Use -1 to unselect all rows.

\membersection{wxDataViewCtrl::SetSelectionRange}\label{wxdataviewctrlsetselectionrange}

\func{virtual void}{SetSelectionRange}{\param{unsigned int }{from}, \param{unsigned int }{to}}

Set a range of selection.

\membersection{wxDataViewCtrl::SetSelections}\label{wxdataviewctrlsetselections}

\func{virtual void}{SetSelections}{\param{const wxArrayInt\& }{aSelections}}

Set the selection to the array of int.

\membersection{wxDataViewCtrl::Unselect}\label{wxdataviewctrlunselect}

\func{virtual void}{Unselect}{\param{unsigned int }{row}}

Unselect a particular row.