docs/latex/wx/dataviewrenderer.tex

   1
   2 \section{\class{wxDataViewRenderer}}\label{wxdataviewrenderer}
   3
   4
   5 This class is used by \helpref{wxDataViewCtrl}{wxdataviewctrl} to
   6 render the individual cells. One instance of a renderer class is
   7 owned by \helpref{wxDataViewColumn}{wxdataviewcolumn}. There is
   8 a number of ready-to-use renderers provided:
   9 \helpref{wxDataViewTextRenderer}{wxdataviewtextrenderer},
  10 \helpref{wxDataViewToggleRenderer}{wxdataviewtogglerenderer},
  11 \helpref{wxDataViewProgressRenderer}{wxdataviewprogressrenderer},
  12 \helpref{wxDataViewBitmapRenderer}{wxdataviewbitmaprenderer},
  13 \helpref{wxDataViewDateRenderer}{wxdataviewdaterenderer}.
  14
  15 Additionally, the user can write own renderers by deriving from
  16 \helpref{wxDataViewCustomRenderer}{wxdataviewcustomrenderer}.
  17
  18 The {\it wxDataViewCellMode} flag controls, what actions
  19 the cell data allows. {\it wxDATAVIEW\_CELL\_ACTIVATABLE}
  20 indicates that the user can double click the cell and
  21 something will happen (e.g. a window for editing a date
  22 will pop up). {\it wxDATAVIEW\_CELL\_EDITABLE} indicates
  23 that the user can edit the data in-place, i.e. an control
  24 will show up after a slow click on the cell. This behaviour
  25 is best known from changing the filename in most file
  26 managers etc.
  27
  28
  29
  30 {\small
  31 \begin{verbatim}
  32 enum wxDataViewCellMode
  33 {
  34     wxDATAVIEW_CELL_INERT,
  35     wxDATAVIEW_CELL_ACTIVATABLE,
  36     wxDATAVIEW_CELL_EDITABLE
  37 };
  38 \end{verbatim}
  39 }
  40
  41 The {\it wxDataViewCellRenderState} flag controls how the
  42 the renderer should display its contents in a cell:
  43
  44 {\small
  45 \begin{verbatim}
  46 enum wxDataViewCellRenderState
  47 {
  48     wxDATAVIEW_CELL_SELECTED    = 1,
  49     wxDATAVIEW_CELL_PRELIT      = 2,
  50     wxDATAVIEW_CELL_INSENSITIVE = 4,
  51     wxDATAVIEW_CELL_FOCUSED     = 8
  52 };
  53 \end{verbatim}
  54 }
  55
  56
  57 \wxheading{Derived from}
  58
  59 \helpref{wxObject}{wxobject}
  60
  61 \wxheading{Include files}
  62
  63 <wx/dataview.h>
  64
  65 \wxheading{Library}
  66
  67 \helpref{wxAdv}{librarieslist}
  68
  69
  70 \membersection{wxDataViewRenderer::wxDataViewRenderer}\label{wxdataviewrendererwxdataviewrenderer}
  71
  72 \func{}{wxDataViewRenderer}{\param{const wxString\& }{varianttype}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
  73
  74 Constructor.
  75
  76 \membersection{wxDataViewRenderer::GetMode}\label{wxdataviewrenderergetmode}
  77
  78 \func{virtual wxDataViewCellMode}{GetMode}{\void}
  79
  80 Returns the cell mode.
  81
  82 \membersection{wxDataViewRenderer::GetOwner}\label{wxdataviewrenderergetowner}
  83
  84 \func{virtual wxDataViewColumn*}{GetOwner}{\void}
  85
  86 Returns pointer to the owning \helpref{wxDataViewColumn}{wxdataviewcolumn}.
  87
  88 \membersection{wxDataViewRenderer::GetValue}\label{wxdataviewrenderergetvalue}
  89
  90 \func{virtual bool}{GetValue}{\param{wxVariant\& }{value}}
  91
  92 This methods retrieves the value from the renderer in order to
  93 transfer the value back to the data model. Returns {\it false}
  94 on failure.
  95
  96 \membersection{wxDataViewRenderer::GetVariantType}\label{wxdataviewrenderergetvarianttype}
  97
  98 \func{virtual wxString}{GetVariantType}{\void}
  99
 100 Returns a string with the type of the \helpref{wxVariant}{wxvariant}
 101 supported by this renderer.
 102
 103 \membersection{wxDataViewRenderer::SetOwner}\label{wxdataviewrenderersetowner}
 104
 105 \func{virtual void}{SetOwner}{\param{wxDataViewColumn* }{owner}}
 106
 107 Sets the owning \helpref{wxDataViewColumn}{wxdataviewcolumn}. This
 108 is usually called from within wxDataViewColumn.
 109
 110 \membersection{wxDataViewRenderer::SetValue}\label{wxdataviewrenderersetvalue}
 111
 112 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{value}}
 113
 114 Set the value of the renderer (and thus its cell) to {\it value}.
 115 The internal code will then render this cell with this data.
 116
 117
 118 \membersection{wxDataViewRenderer::Validate}\label{wxdataviewrenderervalidate}
 119
 120 \func{virtual bool}{Validate}{\param{wxVariant\& }{value}}
 121
 122 Before data is committed to the data model, it is passed to this
 123 method where it can be checked for validity. This can also be
 124 used for checking a valid range or limiting the user input in
 125 a certain aspect (e.g. max number of characters or only alphanumeric
 126 input, ASCII only etc.). Return {\it false} if the value is
 127 not valid.
 128
 129 Please note that due to implementation limitations, this validation
 130 is done after the editing control already is destroyed and the
 131 editing process finished.
 132
 133
 134 \section{\class{wxDataViewTextRenderer}}\label{wxdataviewtextrenderer}
 135
 136 wxDataViewTextRenderer is used for rendering text. It supports
 137 in-place editing if desired.
 138
 139
 140 \wxheading{Derived from}
 141
 142 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 143 \helpref{wxObject}{wxobject}
 144
 145 \wxheading{Include files}
 146
 147 <wx/dataview.h>
 148
 149 \wxheading{Library}
 150
 151 \helpref{wxAdv}{librarieslist}
 152
 153
 154 \membersection{wxDataViewTextRenderer::wxDataViewTextRenderer}\label{wxdataviewtextrendererwxdataviewtextrenderer}
 155
 156 \func{}{wxDataViewTextRenderer}{\param{const wxString\& }{varianttype = wxT("string")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 157
 158
 159
 160 \section{\class{wxDataViewProgressRenderer}}\label{wxdataviewprogressrenderer}
 161
 162 wxDataViewProgressRenderer
 163
 164
 165 \wxheading{Derived from}
 166
 167 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 168 \helpref{wxObject}{wxobject}
 169
 170 \wxheading{Include files}
 171
 172 <wx/dataview.h>
 173
 174 \wxheading{Library}
 175
 176 \helpref{wxAdv}{librarieslist}
 177
 178
 179 \membersection{wxDataViewProgressRenderer::wxDataViewProgressRenderer}\label{wxdataviewprogressrendererwxdataviewprogressrenderer}
 180
 181 \func{}{wxDataViewProgressRenderer}{\param{const wxString\& }{label = wxEmptyString}, \param{const wxString\& }{varianttype = wxT("long")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 182
 183
 184
 185 \section{\class{wxDataViewToggleRenderer}}\label{wxdataviewtogglerenderer}
 186
 187 wxDataViewToggleRenderer
 188
 189 \wxheading{Derived from}
 190
 191 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 192 \helpref{wxObject}{wxobject}
 193
 194 \wxheading{Include files}
 195
 196 <wx/dataview.h>
 197
 198 \wxheading{Library}
 199
 200 \helpref{wxAdv}{librarieslist}
 201
 202
 203 \membersection{wxDataViewToggleRenderer::wxDataViewToggleRenderer}\label{wxdataviewtogglerendererwxdataviewtogglerenderer}
 204
 205 \func{}{wxDataViewToggleRenderer}{\param{const wxString\& }{varianttype = wxT("bool")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 206
 207
 208 \section{\class{wxDataViewBitmapRenderer}}\label{wxdataviewbitmaprenderer}
 209
 210 wxDataViewBitmapRenderer
 211
 212 \wxheading{Derived from}
 213
 214 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 215 \helpref{wxObject}{wxobject}
 216
 217 \wxheading{Include files}
 218
 219 <wx/dataview.h>
 220
 221 \wxheading{Library}
 222
 223 \helpref{wxAdv}{librarieslist}
 224
 225
 226 \membersection{wxDataViewBitmapRenderer::wxDataViewBitmapRenderer}\label{wxdataviewbitmaprendererwxdataviewbitmaprenderer}
 227
 228 \func{}{wxDataViewBitmapRenderer}{\param{const wxString\& }{varianttype = wxT("wxBitmap")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 229
 230
 231 \section{\class{wxDataViewDateRenderer}}\label{wxdataviewdaterenderer}
 232
 233 wxDataViewDateRenderer
 234
 235
 236 \wxheading{Derived from}
 237
 238 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 239 \helpref{wxObject}{wxobject}
 240
 241 \wxheading{Include files}
 242
 243 <wx/dataview.h>
 244
 245 \wxheading{Library}
 246
 247 \helpref{wxAdv}{librarieslist}
 248
 249 \membersection{wxDataViewDateRenderer::wxDataViewDateRenderer}\label{wxdataviewdaterendererwxdataviewdaterenderer}
 250
 251 \func{}{wxDataViewDateRenderer}{\param{const wxString\& }{varianttype = wxT("datetime")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}}
 252
 253
 254 \section{\class{wxDataViewCustomRenderer}}\label{wxdataviewcustomrenderer}
 255
 256 You need to derive a new class from wxDataViewCustomRenderer in
 257 order to write a new renderer. You need to override at least
 258 \helpref{SetValue}{wxdataviewrenderersetvalue},
 259 \helpref{GetValue}{wxdataviewrenderergetvalue},
 260 \helpref{GetSize}{wxdataviewcustomrenderergetsize}
 261 and \helpref{Render}{wxdataviewcustomrendererrender}.
 262
 263 If you want your renderer to support in-place editing then you
 264 also need to override
 265 \helpref{HasEditorCtrl}{wxdataviewcustomrendererhaseditorctrl},
 266 \helpref{CreateEditorCtrl}{wxdataviewcustomrenderercreateeditorctrl}
 267 and \helpref{GetValueFromEditorCtrl}{wxdataviewcustomrenderergetvaluefromeditorctrl}.
 268 Note that a special event handler will be pushed onto that
 269 editor control which handles <ENTER> and focus out events
 270 in order to end the editing.
 271
 272 \wxheading{Derived from}
 273
 274 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 275 \helpref{wxObject}{wxobject}
 276
 277 \wxheading{Include files}
 278
 279 <wx/dataview.h>
 280
 281 \wxheading{Library}
 282
 283 \helpref{wxAdv}{librarieslist}
 284
 285 \membersection{wxDataViewCustomRenderer::wxDataViewCustomRenderer}\label{wxdataviewcustomrendererwxdataviewcustomrenderer}
 286
 287 \func{}{wxDataViewCustomRenderer}{\param{const wxString\& }{varianttype = wxT("string")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{bool }{no\_init = false}}
 288
 289 Constructor.
 290
 291 \membersection{wxDataViewCustomRenderer::\destruct{wxDataViewCustomRenderer}}\label{wxdataviewcustomrendererdtor}
 292
 293 \func{}{\destruct{wxDataViewCustomRenderer}}{\void}
 294
 295 Destructor.
 296
 297
 298 \membersection{wxDataViewCustomRenderer::HasEditorCtrl}\label{wxdataviewcustomrendererhaseditorctrl}
 299
 300 \func{virtual bool}{HasEditorCtrl}{\void}
 301
 302 Override this and make it return {\it true} in order to
 303 indicate that this renderer supports in-place editing.
 304
 305 \membersection{wxDataViewCustomRenderer::CreateEditorCtrl}\label{wxdataviewcustomrenderercreateeditorctrl}
 306
 307 \func{virtual wxControl*}{CreateEditorCtrl}{\param{wxWindow *}{parent}, \param{wxRect }{labelRect}, \param{const wxVariant \& }{value}}
 308
 309 Override this to create the actual editor control once editing
 310 is about to start. {\it parent} is the parent of the editor
 311 control, {\it labelRect} indicates the position and
 312 size of the editor control and {\it value} is its initial value:
 313
 314 {\small
 315 \begin{verbatim}
 316 {
 317     long l = value;
 318     return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
 319                  labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
 320 }
 321 \end{verbatim}
 322 }
 323
 324 \membersection{wxDataViewCustomRenderer::GetValueFromEditorCtrl}\label{wxdataviewcustomrenderergetvaluefromeditorctrl}
 325
 326 \func{virtual bool}{GetValueFromEditorCtrl}{\param{wxControl* }{editor}, \param{wxVariant \& }{value}}
 327
 328 Overrride this so that the renderer can get the value
 329 from the editor control (pointed to by {\it editor}):
 330
 331 {\small
 332 \begin{verbatim}
 333 {
 334     wxSpinCtrl *sc = (wxSpinCtrl*) editor;
 335     long l = sc->GetValue();
 336     value = l;
 337     return true;
 338 }
 339 \end{verbatim}
 340 }
 341
 342 \membersection{wxDataViewCustomRenderer::Activate}\label{wxdataviewcustomrendereractivate}
 343
 344 \func{virtual bool}{Activate}{\param{wxRect }{cell}, \param{wxDataViewListModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 345
 346 Override this to react to double clicks or <ENTER>.
 347
 348 \membersection{wxDataViewCustomRenderer::GetDC}\label{wxdataviewcustomrenderergetdc}
 349
 350 \func{virtual wxDC*}{GetDC}{\void}
 351
 352 Create DC on request. Internal.
 353
 354
 355 \membersection{wxDataViewCustomRenderer::GetSize}\label{wxdataviewcustomrenderergetsize}
 356
 357 \func{virtual wxSize}{GetSize}{\void}
 358
 359 Return size required to show content.
 360
 361
 362 \membersection{wxDataViewCustomRenderer::LeftClick}\label{wxdataviewcustomrendererleftclick}
 363
 364 \func{virtual bool}{LeftClick}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewListModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 365
 366 Overrride this to react to a left click.
 367
 368 \membersection{wxDataViewCustomRenderer::Render}\label{wxdataviewcustomrendererrender}
 369
 370 \func{virtual bool}{Render}{\param{wxRect }{cell}, \param{wxDC* }{dc}, \param{int }{state}}
 371
 372 Override this to render the cell. Before this is called,
 373 \helpref{SetValue}{wxdataviewrenderersetvalue} was called
 374 so that this instance knows what to render.
 375
 376 \membersection{wxDataViewCustomRenderer::RightClick}\label{wxdataviewcustomrendererrightclick}
 377
 378 \func{virtual bool}{RightClick}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewListModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 379
 380 Overrride this to react to a right click.
 381
 382 \membersection{wxDataViewCustomRenderer::StartDrag}\label{wxdataviewcustomrendererstartdrag}
 383
 384 \func{virtual bool}{StartDrag}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewListModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 385
 386 Overrride this to start a drag operation.
 387
 388
 389