docs/latex/wx/dataviewctrl.tex

   1 \section{\class{wxDataViewCtrl}}\label{wxdataviewctrl}
   2
   3 wxDataViewCtrl is a control to display data either
   4 in a tree like fashion or in a tabular form or both.
   5 If you only need to display a simple tree structure
   6 with an API more like the older wxTreeCtrl class,
   7 then the specialized \helpref{wxDataViewTreeCtrl}{wxdataviewtreectrl}
   8 can be used.
   9
  10 A \helpref{wxDataViewItem}{wxdataviewitem} is used
  11 to represent a (visible) item in the control.
  12
  13 Unlike \helpref{wxListCtrl}{wxlistctrl} wxDataViewCtrl doesn't
  14 get its data from the user through virtual functions or by
  15 setting it directly. Instead you need to write your own
  16 \helpref{wxDataViewModel}{wxdataviewmodel} and associate
  17 it with this control. Then you need to add a number of
  18 \helpref{wxDataViewColumn}{wxdataviewcolumn} to this control to
  19 define what each column shall display. Each wxDataViewColumn
  20 in turn owns 1 instance of a
  21 \helpref{wxDataViewRenderer}{wxdataviewrenderer} to render its
  22 cells. A number of standard renderers for rendering text, dates,
  23 images, toggle, a progress bar etc. are provided. Additionally,
  24 the user can write custom renderes deriving from
  25 \helpref{wxDataViewCustomRenderer}{wxdataviewcustomrenderer}
  26 for displaying anything.
  27
  28 All data transfer from the control to the model and the user
  29 code is done through \helpref{wxVariant}{wxvariant} which can
  30 be extended to support more data formats as necessary.
  31 Accordingly, all type information uses the strings returned
  32 from \helpref{wxVariant::GetType}{wxvariantgettype}.
  33
  34 \wxheading{Window styles}
  35
  36 \twocolwidtha{5cm}
  37 \begin{twocollist}\itemsep=0pt
  38 \twocolitem{\windowstyle{wxDV\_SINGLE}}{Single selection mode. This is the default.}
  39 \twocolitem{\windowstyle{wxDV\_MULTIPLE}}{Multiple selection mode.}
  40 \twocolitem{\windowstyle{wxDV\_ROW\_LINES}}{Use alternating colours for rows if supported by platform and theme.}
  41 \twocolitem{\windowstyle{wxDV\_HORIZ\_RULES}}{Display fine rules between row if supported.}
  42 \twocolitem{\windowstyle{wxDV\_VERT\_RULES}}{Display fine rules between columns is supported.}
  43 \end{twocollist}
  44
  45
  46 \wxheading{Event handling}
  47
  48 To process input from a dataview control, use the following event handler
  49 macros to direct input to member functions that take a
  50 \helpref{wxDataViewEvent}{wxdataviewevent} argument.
  51
  52 \twocolwidtha{7cm}
  53 \begin{twocollist}\itemsep=0pt
  54
  55 \twocolitem{{\bf EVT\_DATAVIEW\_SELECTION\_CHANGED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_SELECTION\_CHANGED event.}
  56 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_ACTIVATED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_ACTIVATED event.}
  57 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_EDITING\_STARTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_EDITING\_STARTED event.}
  58 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_EDITING\_DONE(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_EDITING\_DONE event.}
  59 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_COLLAPSING(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_COLLAPSING event.}
  60 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_COLLAPSED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_COLLAPSED event.}
  61 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_EXPANDING(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_EXPANDING event.}
  62 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_EXPANDED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_EXPANDED event.}
  63 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_VALUE\_CHANGED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_VALUE\_CHANGED event.}
  64 \twocolitem{{\bf EVT\_DATAVIEW\_ITEM\_CONTEXT\_MENU(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_ITEM\_CONTEXT\_MENU event.}
  65 \twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_CLICK(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_CLICKED event.}
  66 \twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_RIGHT\_CLICK(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_RIGHT\_CLICKED event.}
  67 \twocolitem{{\bf EVT\_DATAVIEW\_COLUMN\_HEADER\_SORTED(id, func)}}{Processes a wxEVT\_COMMAND\_DATAVIEW\_COLUMN\_HEADER\_SORTED event.}
  68
  69 \end{twocollist}
  70
  71
  72 \wxheading{Derived from}
  73
  74 \helpref{wxControl}{wxcontrol}\\
  75 \helpref{wxWindow}{wxwindow}\\
  76 \helpref{wxEvtHandler}{wxevthandler}\\
  77 \helpref{wxObject}{wxobject}
  78
  79 \wxheading{Include files}
  80
  81 <wx/dataview.h>
  82
  83 \wxheading{Library}
  84
  85 \helpref{wxAdv}{librarieslist}
  86
  87
  88 \latexignore{\rtfignore{\wxheading{Members}}}
  89
  90 \membersection{wxDataViewCtrl::wxDataViewCtrl}\label{wxdataviewctrlwxdataviewctrl}
  91
  92 \func{}{wxDataViewCtrl}{\void}
  93
  94 \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}}
  95
  96 Constructor. Calls \helpref{Create}{wxdataviewctrlcreate}.
  97
  98 \membersection{wxDataViewCtrl::\destruct{wxDataViewCtrl}}\label{wxdataviewctrldtor}
  99
 100 \func{}{\destruct{wxDataViewCtrl}}{\void}
 101
 102 Destructor.
 103
 104 \membersection{wxDataViewCtrl::AppendColumn}\label{wxdataviewctrlappendcolumn}
 105
 106 \func{virtual bool}{AppendColumn}{\param{wxDataViewColumn* }{col}}
 107
 108 Add a \helpref{wxDataViewColumn}{wxdataviewcolumn} to the control. Returns
 109 {\it true} on success.
 110
 111 Note that there is a number of short cut methods which implicitly create
 112 a \helpref{wxDataViewColumn}{wxdataviewcolumn} and a
 113 \helpref{wxDataViewRenderer}{wxdataviewrenderer} for it (see below).
 114
 115 \membersection{wxDataViewCtrl::AppendBitmapColumn}\label{wxdataviewctrlappendbitmapcolumn}
 116
 117 \func{wxDataViewColumn*}{AppendBitmapColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 118
 119 \func{wxDataViewColumn*}{AppendBitmapColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 120
 121 Appends a column for rendering a bitmap. Returns the wxDataViewColumn
 122 created in the function or NULL on failure.
 123
 124 \membersection{wxDataViewCtrl::AppendDateColumn}\label{wxdataviewctrlappenddatecolumn}
 125
 126 \func{wxDataViewColumn*}{AppendDateColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 127
 128 \func{wxDataViewColumn*}{AppendDateColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 129
 130 Appends a column for rendering a date. Returns the wxDataViewColumn
 131 created in the function or NULL on failure.
 132
 133 \membersection{wxDataViewCtrl::AppendProgressColumn}\label{wxdataviewctrlappendprogresscolumn}
 134
 135 \func{wxDataViewColumn*}{AppendProgressColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 136
 137 \func{wxDataViewColumn*}{AppendProgressColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 80}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 138
 139 Appends a column for rendering a progress indicator. Returns the wxDataViewColumn
 140 created in the function or NULL on failure.
 141
 142 \membersection{wxDataViewCtrl::AppendIconTextColumn}\label{wxdataviewctrlappendicontextcolumn}
 143
 144 \func{wxDataViewColumn*}{AppendIconTextColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_LEFT}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 145
 146 \func{wxDataViewColumn*}{AppendIconTextColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_LEFT}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 147
 148 Appends a column for rendering text with an icon. Returns the wxDataViewColumn
 149 created in the function or NULL on failure. This uses the
 150 \helpref{wxDataViewIconTextRenderer}{wxdataviewicontextrenderer}.
 151
 152 \membersection{wxDataViewCtrl::AppendTextColumn}\label{wxdataviewctrlappendtextcolumn}
 153
 154 \func{wxDataViewColumn*}{AppendTextColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_LEFT}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 155
 156 \func{wxDataViewColumn*}{AppendTextColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = -1}, \param{wxAlignment }{align = wxALIGN\_LEFT}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 157
 158 Appends a column for rendering text. Returns the wxDataViewColumn
 159 created in the function or NULL on failure.
 160
 161 \membersection{wxDataViewCtrl::AppendToggleColumn}\label{wxdataviewctrlappendtogglecolumn}
 162
 163 \func{wxDataViewColumn*}{AppendToggleColumn}{\param{const wxString\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 164
 165 \func{wxDataViewColumn*}{AppendToggleColumn}{\param{const wxBitmap\& }{label}, \param{unsigned int }{model\_column}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{width = 30}, \param{wxAlignment }{align = wxALIGN\_CENTER}, \param{int }{flags = wxDATAVIEW\_COL\_RESIZABLE}}
 166
 167 Appends a column for rendering a toggle. Returns the wxDataViewColumn
 168 created in the function or NULL on failure.
 169
 170 \membersection{wxDataViewCtrl::AssociateModel}\label{wxdataviewctrlassociatemodel}
 171
 172 \func{virtual bool}{AssociateModel}{\param{wxDataViewModel* }{model}}
 173
 174 Associates a \helpref{wxDataViewModel}{wxdataviewmodel} with the
 175 control. This increases the reference count of the model by 1.
 176
 177 \membersection{wxDataViewCtrl::Create}\label{wxdataviewctrlcreate}
 178
 179 \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}}
 180
 181 Create the control. Useful for two step creation.
 182
 183 \membersection{wxDataViewCtrl::ClearColumns}\label{wxdataviewctrlclearcolumns}
 184
 185 \func{virtual bool}{ClearColumns}{\void}
 186
 187 Removes all columns.
 188
 189 \membersection{wxDataViewCtrl::ClearSelection}\label{wxdataviewctrlclearselection}
 190
 191 \func{void}{ClearSelection}{\void}
 192
 193 Unselects all rows.
 194
 195 \membersection{wxDataViewCtrl::Collapse}\label{wxdataviewctrlcollapse}
 196
 197 \func{void}{Collapse}{\param{const wxDataViewItem \& }{item}}
 198
 199 Collapses the item.
 200
 201 \membersection{wxDataViewCtrl::DeleteColumn}\label{wxdataviewctrldeletecolumn}
 202
 203 \func{virtual bool}{DeleteColumn}{\param{const wxDataViewColumn* }{column}}
 204
 205 Deletes given column.
 206
 207 \membersection{wxDataViewCtrl::Expand}\label{wxdataviewctrlexpand}
 208
 209 \func{void}{Expand}{\param{const wxDataViewItem \& }{item}}
 210
 211 Expands the item.
 212
 213 \membersection{wxDataViewCtrl::GetColumn}\label{wxdataviewctrlgetcolumn}
 214
 215 \constfunc{virtual wxDataViewColumn*}{GetColumn}{\param{unsigned int }{pos}}
 216
 217 Returns pointer to the column. {\it pos} refers to the
 218 position in the control which may change after reordering
 219 columns by the user.
 220
 221 \membersection{wxDataViewCtrl::GetColumnCount}\label{wxdataviewctrlgetcolumncount}
 222
 223 \constfunc{virtual unsigned int}{GetColumnCount}{\void}
 224
 225 Returns the number of columns.
 226
 227 \membersection{wxDataViewCtrl::GetColumnPosition}\label{wxdataviewctrlgetcolumnposition}
 228
 229 \constfunc{virtual int}{GetColumnPosition}{\param{const wxDataViewColumn* }{column}}
 230
 231 Returns the position of the column or -1 if not found in the control.
 232
 233 \membersection{wxDataViewCtrl::EnsureVisible}\label{wxdataviewctrlensurevisible}
 234
 235 \func{void}{EnsureVisible}{\param{const wxDataViewItem \& }{item}, \param{const wxDataViewColumn* }{column = NULL}}
 236
 237 Call this to ensure that the given item is visible.
 238
 239 \membersection{wxDataViewCtrl::GetExpanderColumn}\label{wxdataviewctrlgetexpandercolumn}
 240
 241 \constfunc{wxDataViewColumn *}{GetExpanderColumn}{\void}
 242
 243 Returns column containing the expanders.
 244
 245 \membersection{wxDataViewCtrl::GetIndent}\label{wxdataviewctrlgetindent}
 246
 247 \constfunc{int}{GetIndent}{\void}
 248
 249 Returns indentation.
 250
 251 \membersection{wxDataViewCtrl::GetItemRect}\label{wxdataviewctrlgetitemrect}
 252
 253 \constfunc{wxRect}{GetItemRect}{\param{const wxDataViewItem\& }{item}, \param{const wxDataViewColumn *}{col = NULL}}
 254
 255 Returns item rect.
 256
 257 \membersection{wxDataViewCtrl::GetModel}\label{wxdataviewctrlgetmodel}
 258
 259 \constfunc{virtual wxDataViewModel*}{GetModel}{\void}
 260
 261 Returns pointer to the data model associated with the
 262 control (if any).
 263
 264 \membersection{wxDataViewCtrl::GetSelection}\label{wxdataviewctrlgetselection}
 265
 266 \constfunc{wxDataViewItem}{GetSelection}{\void}
 267
 268 Returns first selected item or an invalid item if none is selected.
 269
 270 \membersection{wxDataViewCtrl::GetSelections}\label{wxdataviewctrlgetselections}
 271
 272 \constfunc{int}{GetSelections}{\param{wxDataViewItemArray \& }{sel}}
 273
 274 Fills {\it sel} with currently selected items and returns
 275 their number.
 276
 277 \membersection{wxDataViewCtrl::GetSortingColumn}\label{wxdataviewctrlgetsortingcolumn}
 278
 279 \constfunc{virtual wxDataViewColumn*}{GetSortingColumn}{\void}
 280
 281 Returns the wxDataViewColumn currently responsible for sorting
 282 or NULL if none has been selected.
 283
 284 \membersection{wxDataViewCtrl::HitTest}\label{wxdataviewctrlhittest}
 285
 286 \constfunc{void}{HitTest}{\param{const wxPoint\& }{point}, \param{wxDataViewItem\& }{item}, \param{wxDataViewColumn *\&}{col}}
 287
 288 Hittest.
 289
 290 \membersection{wxDataViewCtrl::IsSelected}\label{wxdataviewctrlisselected}
 291
 292 \constfunc{bool}{IsSelected}{\param{const wxDataViewItem \& }{item}}
 293
 294 Return true if the item is selected.
 295
 296 \membersection{wxDataViewCtrl::Select}\label{wxdataviewctrlselect}
 297
 298 \func{void}{Select}{\param{const wxDataViewItem \& }{item}}
 299
 300 Select the given item.
 301
 302 \membersection{wxDataViewCtrl::SelectAll}\label{wxdataviewctrlselectall}
 303
 304 \func{void}{SelectAll}{\void}
 305
 306 Select all items.
 307
 308 \membersection{wxDataViewCtrl::SetExpanderColumn}\label{wxdataviewctrlsetexpandercolumn}
 309
 310 \func{void}{SetExpanderColumn}{\param{wxDataViewColumn *}{col}}
 311
 312 Set which column shall contain the tree-like expanders.
 313
 314 \membersection{wxDataViewCtrl::SetIndent}\label{wxdataviewctrlsetindent}
 315
 316 \func{void}{SetIndent}{\param{int }{indent}}
 317
 318 Sets the indendation.
 319
 320 \membersection{wxDataViewCtrl::SetSelections}\label{wxdataviewctrlsetselections}
 321
 322 \func{void}{SetSelections}{\param{const wxDataViewItemArray \& }{sel}}
 323
 324 Sets the selection to the array of wxDataViewItems.
 325
 326 \membersection{wxDataViewCtrl::Unselect}\label{wxdataviewctrlunselect}
 327
 328 \func{void}{Unselect}{\param{const wxDataViewItem \& }{item}}
 329
 330 Unselect the given item.
 331
 332 \membersection{wxDataViewCtrl::UnselectAll}\label{wxdataviewctrlunselectall}
 333
 334 \func{void}{UnselectAll}{\void}
 335
 336 Unselect all item. This method only has effect if multiple
 337 selections are allowed.
 338