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