docs/latex/wx/dataviewctrl.tex

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