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