docs/latex/wx/dataviewctrl.tex

   1
   2 \section{\class{wxDataViewCtrl}}\label{wxdataviewctrl}
   3
   4 This class and its documentation are work in progress and
   5 therefore subject to change.
   6
   7 wxDataViewCtrl is planned to be a control to display data either
   8 in a tree like fashion or in a tabular form or both. So far,
   9 only the tabular form is implemented.
  10
  11 Unlike \helpref{wxListCtrl}{wxlistctrl} wxDataViewCtrl doesn't
  12 get its data from the user through virtual functions or events,
  13 instead you need to write your own
  14 \helpref{wxDataViewListModel}{wxdataviewlistmodel} and associate
  15 it with this control. Then you need to add a number of
  16 \helpref{wxDataViewColumn}{wxdataviewcolumn} to this control to
  17 define what each column shall display. Each wxDataViewColumn
  18 in turn owns 1 instance of a
  19 \helpref{wxDataViewRenderer}{wxdataviewrenderer} to render its
  20 cells. A number of standard renderers for rendering text, dates,
  21 images, toggle, a progress bar etc. are provided. Additionally,
  22 the user can write custom renderes deriving from
  23 \helpref{wxDataViewCustomRenderer}{wxdataviewcustomrenderer}
  24 for displaying anything.
  25
  26 All data transfer from the control to the model and the user
  27 code is done through \helpref{wxVariant}{wxvariant} which can
  28 be extended to support more data formats as necessary.
  29 Accordingly, all type information uses the strings returned
  30 from \helpref{wxVariant::GetType}{wxvariantgettype}.
  31
  32 So far, this control has been implemented for GTK+ and there
  33 is an almost complete generic implementation including several
  34 additions for a native Windows look and feel (in particular
  35 concerning the header). It is planned to implement the control
  36 natively under OS X.
  37
  38 \wxheading{Window styles}
  39
  40 \twocolwidtha{5cm}
  41 \begin{twocollist}\itemsep=0pt
  42 \twocolitem{\windowstyle{wxDV\_SINGLE}}{Single selection mode. This is the default.}
  43 \twocolitem{\windowstyle{wxDV\_MULTIPLE}}{Multiple selection mode.}
  44 \end{twocollist}
  45
  46
  47 \wxheading{Event handling}
  48
  49 To process input from a dataview control, use the following event handler
  50 macros to direct input to member functions that take a
  51 \helpref{wxDataViewEvent}{wxdataviewevent} argument.
  52
  53 \twocolwidtha{7cm}
  54 \begin{twocollist}\itemsep=0pt
  55
  56 \twocolitem{{\bf EVT\_DATAVIEW\_ROW\_SELECTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ROW\_SELECTED event.}
  57 \twocolitem{{\bf EVT\_DATAVIEW\_ROW\_ACTIVATED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ROW\_ACTIVATED event.}
  58 \twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_CLICK(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_CLICKED event.}
  59 \twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_RIGHT\_CLICK(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_RIGHT\_CLICKED event.}
  60
  61 \end{twocollist}
  62
  63 Additionally, you can get informed about changes to the
  64 \helpref{model}{wxdataviewlistmodel}, to which a wxDataViewCtrl
  65 has been associated. These events correspond to the interface
  66 offered by \helpref{wxDataViewListModelNotifier}{wxdataviewlistmodelnotifier}.
  67
  68 \twocolwidtha{7cm}
  69 \begin{twocollist}\itemsep=0pt
  70
  71 \twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_PREPENDED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_PREPENDED event.}
  72 \twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_APPENDED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_APPENDED event.}
  73 \twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_INSERTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_INSERTED event.}
  74 \twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_DELETED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_DELETED event.}
  75 \twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROW\_CHANGED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROW\_CHANGED event.}
  76 \twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_VALUE\_CHANGED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_VALUE\_CHANGED event.}
  77 \twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_ROWS\_REORDERED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_ROWS\_REORDERED event.}
  78 \twocolitem{{\bf EVT\_DATAVIEW\_MODEL\_CLEARED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_MODEL\_CLEARED event.}
  79
  80 \end{twocollist}
  81
  82
  83 \wxheading{Derived from}
  84
  85 \helpref{wxControl}{wxcontrol}
  86
  87 \wxheading{Include files}
  88
  89 <wx/dataview.h>
  90
  91 \wxheading{Library}
  92
  93 \helpref{wxAdv}{librarieslist}
  94
  95
  96 \membersection{wxDataViewCtrl::wxDataViewCtrl}\label{wxdataviewctrlwxdataviewctrl}
  97
  98 \func{}{wxDataViewCtrl}{\void}
  99
 100 \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}}
 101
 102 Constructor. Calls \helpref{Create}{wxdataviewctrlcreate}.
 103
 104 \membersection{wxDataViewCtrl::\destruct{wxDataViewCtrl}}\label{wxdataviewctrldtor}
 105
 106 \func{}{\destruct{wxDataViewCtrl}}{\void}
 107
 108 Destructor.
 109
 110 \membersection{wxDataViewCtrl::AppendColumn}\label{wxdataviewctrlappendcolumn}
 111
 112 \func{virtual bool}{AppendColumn}{\param{wxDataViewColumn* }{col}}
 113
 114 Add a \helpref{wxDataViewColumn}{wxdataviewcolumn} to the control. Note
 115 that there is a number of short cut methods which implicitly create
 116 a \helpref{wxDataViewColumn}{wxdataviewcolumn} and a
 117 \helpref{wxDataViewRenderer}{wxdataviewrenderer} for it (see below).
 118
 119
 120 \membersection{wxDataViewCtrl::AppendBitmapColumn}\label{wxdataviewctrlappendbitmapcolumn}
 121
 122 \func{bool}{AppendBitmapColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}
 123
 124 \func{bool}{AppendBitmapColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}
 125
 126 Appends a column for rendering a bitmap.
 127
 128 \membersection{wxDataViewCtrl::AppendDateColumn}\label{wxdataviewctrlappenddatecolumn}
 129
 130 \func{bool}{AppendDateColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}}
 131
 132 \func{bool}{AppendDateColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}}
 133
 134 Appends a column for rendering a date.
 135
 136 \membersection{wxDataViewCtrl::AppendProgressColumn}\label{wxdataviewctrlappendprogresscolumn}
 137
 138 \func{bool}{AppendProgressColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}}
 139
 140 \func{bool}{AppendProgressColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}}
 141
 142 Appends a column for rendering a progress indicator.
 143
 144 \membersection{wxDataViewCtrl::AppendTextColumn}\label{wxdataviewctrlappendtextcolumn}
 145
 146 \func{bool}{AppendTextColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}
 147
 148 \func{bool}{AppendTextColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}}
 149
 150 Appends a column for rendering text.
 151
 152 \membersection{wxDataViewCtrl::AppendToggleColumn}\label{wxdataviewctrlappendtogglecolumn}
 153
 154 \func{bool}{AppendToggleColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}}
 155
 156 \func{bool}{AppendToggleColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}}
 157
 158 Appends a column for rendering a toggle.
 159
 160 \membersection{wxDataViewCtrl::AssociateModel}\label{wxdataviewctrlassociatemodel}
 161
 162 \func{virtual bool}{AssociateModel}{\param{wxDataViewListModel* }{model}}
 163
 164 Associates a \helpref{wxDataViewListModel}{wxdataviewlistmodel} with the
 165 control. In the future this should be changed to supporting any data
 166 model including a to-be-written wxDataViewTreeModel.
 167
 168 \membersection{wxDataViewCtrl::Create}\label{wxdataviewctrlcreate}
 169
 170 \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}}
 171
 172 Create the control. Useful for two step creation.
 173
 174 \membersection{wxDataViewCtrl::ClearColumns}\label{wxdataviewctrlclearcolumns}
 175
 176 \func{virtual bool}{ClearColumns}{\void}
 177
 178 Removes all columns.
 179
 180 \membersection{wxDataViewCtrl::ClearSelection}\label{wxdataviewctrlclearselection}
 181
 182 \func{void}{ClearSelection}{\void}
 183
 184 Unselects all rows.
 185
 186 \membersection{wxDataViewCtrl::DeleteColumn}\label{wxdataviewctrldeletecolumn}
 187
 188 \func{virtual bool}{DeleteColumn}{\param{unsigned int }{pos}}
 189
 190 Deletes given column.
 191
 192 \membersection{wxDataViewCtrl::GetColumn}\label{wxdataviewctrlgetcolumn}
 193
 194 \func{virtual wxDataViewColumn*}{GetColumn}{\param{unsigned int }{pos}}
 195
 196 Returns pointer to the column.
 197
 198 \membersection{wxDataViewCtrl::GetModel}\label{wxdataviewctrlgetmodel}
 199
 200 \func{virtual wxDataViewListModel*}{GetModel}{\void}
 201
 202 Returns pointer to the data model associated with the
 203 control (if any).
 204
 205 \membersection{wxDataViewCtrl::GetColumnCount}\label{wxdataviewctrlgetcolumncount}
 206
 207 \func{virtual unsigned int}{GetColumnCount}{\void}
 208
 209 Returns the number of columns.
 210
 211 \membersection{wxDataViewCtrl::GetSelection}\label{wxdataviewctrlgetselection}
 212
 213 \constfunc{virtual int}{GetSelection}{\void}
 214
 215 Returns the index of the currently selected row. It will
 216 return -1 if no row is selected and the index of the first
 217 selected row if more than one row are selected.
 218
 219 \membersection{wxDataViewCtrl::GetSelections}\label{wxdataviewctrlgetselections}
 220
 221 \constfunc{virtual int}{GetSelections}{\param{wxArrayInt\& }{aSelections}}
 222
 223 Returns the number of selected rows and fills an array of int
 224 with the indeces of the selected rows.
 225
 226 \membersection{wxDataViewCtrl::IsSelected}\label{wxdataviewctrlisselected}
 227
 228 \constfunc{virtual bool}{IsSelected}{\param{unsigned int }{row}}
 229
 230 Returns {\it true} if the row is selected, {\it false} otherwise.
 231
 232 \membersection{wxDataViewCtrl::SetSelection}\label{wxdataviewctrlsetselection}
 233
 234 \func{virtual void}{SetSelection}{\param{int }{row}}
 235
 236 Sets the selection. Use -1 to unselect all rows.
 237
 238 \membersection{wxDataViewCtrl::SetSelectionRange}\label{wxdataviewctrlsetselectionrange}
 239
 240 \func{virtual void}{SetSelectionRange}{\param{unsigned int }{from}, \param{unsigned int }{to}}
 241
 242 Set a range of selection.
 243
 244 \membersection{wxDataViewCtrl::SetSelections}\label{wxdataviewctrlsetselections}
 245
 246 \func{virtual void}{SetSelections}{\param{const wxArrayInt\& }{aSelections}}
 247
 248 Set the selection to the array of int.
 249
 250 \membersection{wxDataViewCtrl::Unselect}\label{wxdataviewctrlunselect}
 251
 252 \func{virtual void}{Unselect}{\param{unsigned int }{row}}
 253
 254 Unselect a particular row.
 255