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{wxDataViewTextRendererAttr}{wxdataviewtextrendererattr},
  11 \helpref{wxDataViewIconTextRenderer}{wxdataviewicontextrenderer},
  12 \helpref{wxDataViewToggleRenderer}{wxdataviewtogglerenderer},
  13 \helpref{wxDataViewProgressRenderer}{wxdataviewprogressrenderer},
  14 \helpref{wxDataViewBitmapRenderer}{wxdataviewbitmaprenderer},
  15 \helpref{wxDataViewDateRenderer}{wxdataviewdaterenderer}.
  16 \helpref{wxDataViewSpinRenderer}{wxdataviewspinrenderer}.
  17
  18 Additionally, the user can write own renderers by deriving from
  19 \helpref{wxDataViewCustomRenderer}{wxdataviewcustomrenderer}.
  20
  21 The {\it wxDataViewCellMode} flag controls, what actions
  22 the cell data allows. {\it wxDATAVIEW\_CELL\_ACTIVATABLE}
  23 indicates that the user can double click the cell and
  24 something will happen (e.g. a window for editing a date
  25 will pop up). {\it wxDATAVIEW\_CELL\_EDITABLE} indicates
  26 that the user can edit the data in-place, i.e. an control
  27 will show up after a slow click on the cell. This behaviour
  28 is best known from changing the filename in most file
  29 managers etc.
  30
  31
  32
  33 {\small
  34 \begin{verbatim}
  35 enum wxDataViewCellMode
  36 {
  37     wxDATAVIEW_CELL_INERT,
  38     wxDATAVIEW_CELL_ACTIVATABLE,
  39     wxDATAVIEW_CELL_EDITABLE
  40 };
  41 \end{verbatim}
  42 }
  43
  44 The {\it wxDataViewCellRenderState} flag controls how the
  45 the renderer should display its contents in a cell:
  46
  47 {\small
  48 \begin{verbatim}
  49 enum wxDataViewCellRenderState
  50 {
  51     wxDATAVIEW_CELL_SELECTED    = 1,
  52     wxDATAVIEW_CELL_PRELIT      = 2,
  53     wxDATAVIEW_CELL_INSENSITIVE = 4,
  54     wxDATAVIEW_CELL_FOCUSED     = 8
  55 };
  56 \end{verbatim}
  57 }
  58
  59
  60 \wxheading{Derived from}
  61
  62 \helpref{wxObject}{wxobject}
  63
  64 \wxheading{Include files}
  65
  66 <wx/dataview.h>
  67
  68 \wxheading{Library}
  69
  70 \helpref{wxAdv}{librarieslist}
  71
  72
  73
  74 \latexignore{\rtfignore{\wxheading{Members}}}
  75
  76 \membersection{wxDataViewRenderer::wxDataViewRenderer}\label{wxdataviewrendererwxdataviewrenderer}
  77
  78 \func{}{wxDataViewRenderer}{\param{const wxString\& }{varianttype}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{alignment = wxALIGN\_LEFT|wxALIGN\_CENTRE\_VERTICAL}}
  79
  80 Constructor.
  81
  82 \membersection{wxDataViewRenderer::GetMode}\label{wxdataviewrenderergetmode}
  83
  84 \func{virtual wxDataViewCellMode}{GetMode}{\void}
  85
  86 Returns the cell mode.
  87
  88 \membersection{wxDataViewRenderer::GetOwner}\label{wxdataviewrenderergetowner}
  89
  90 \func{virtual wxDataViewColumn*}{GetOwner}{\void}
  91
  92 Returns pointer to the owning \helpref{wxDataViewColumn}{wxdataviewcolumn}.
  93
  94 \membersection{wxDataViewRenderer::GetValue}\label{wxdataviewrenderergetvalue}
  95
  96 \func{virtual bool}{GetValue}{\param{wxVariant\& }{value}}
  97
  98 This methods retrieves the value from the renderer in order to
  99 transfer the value back to the data model. Returns {\it false}
 100 on failure.
 101
 102 \membersection{wxDataViewRenderer::GetVariantType}\label{wxdataviewrenderergetvarianttype}
 103
 104 \func{virtual wxString}{GetVariantType}{\void}
 105
 106 Returns a string with the type of the \helpref{wxVariant}{wxvariant}
 107 supported by this renderer.
 108
 109 \membersection{wxDataViewRenderer::SetOwner}\label{wxdataviewrenderersetowner}
 110
 111 \func{virtual void}{SetOwner}{\param{wxDataViewColumn* }{owner}}
 112
 113 Sets the owning \helpref{wxDataViewColumn}{wxdataviewcolumn}. This
 114 is usually called from within wxDataViewColumn.
 115
 116 \membersection{wxDataViewRenderer::SetValue}\label{wxdataviewrenderersetvalue}
 117
 118 \func{virtual bool}{SetValue}{\param{const wxVariant\& }{value}}
 119
 120 Set the value of the renderer (and thus its cell) to {\it value}.
 121 The internal code will then render this cell with this data.
 122
 123
 124 \membersection{wxDataViewRenderer::Validate}\label{wxdataviewrenderervalidate}
 125
 126 \func{virtual bool}{Validate}{\param{wxVariant\& }{value}}
 127
 128 Before data is committed to the data model, it is passed to this
 129 method where it can be checked for validity. This can also be
 130 used for checking a valid range or limiting the user input in
 131 a certain aspect (e.g. max number of characters or only alphanumeric
 132 input, ASCII only etc.). Return {\it false} if the value is
 133 not valid.
 134
 135 Please note that due to implementation limitations, this validation
 136 is done after the editing control already is destroyed and the
 137 editing process finished.
 138
 139
 140 \section{\class{wxDataViewTextRenderer}}\label{wxdataviewtextrenderer}
 141
 142 wxDataViewTextRenderer is used for rendering text. It supports
 143 in-place editing if desired.
 144
 145
 146 \wxheading{Derived from}
 147
 148 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 149 \helpref{wxObject}{wxobject}
 150
 151 \wxheading{Include files}
 152
 153 <wx/dataview.h>
 154
 155 \wxheading{Library}
 156
 157 \helpref{wxAdv}{librarieslist}
 158
 159
 160 \latexignore{\rtfignore{\wxheading{Members}}}
 161
 162 \membersection{wxDataViewTextRenderer::wxDataViewTextRenderer}\label{wxdataviewtextrendererwxdataviewtextrenderer}
 163
 164 \func{}{wxDataViewTextRenderer}{\param{const wxString\& }{varianttype = "string"}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 165
 166
 167 \section{\class{wxDataViewTextRendererAttr}}\label{wxdataviewtextrendererattr}
 168
 169 The same as \helpref{wxDataViewTextRenderer}{wxdataviewtextrenderer} but with
 170 support for font attributes. Font attributes are currently only supported
 171 under GTK+ and MSW.
 172
 173 See also \helpref{wxDataViewModel::GetAttr}{wxdataviewmodelgetattr} and
 174 \helpref{wxDataViewItemAttr}{wxdataviewitemattr}.
 175
 176 \wxheading{Derived from}
 177
 178 \helpref{wxDataViewTextRenderer}{wxdataviewtextrenderer}
 179
 180 \wxheading{Include files}
 181
 182 <wx/dataview.h>
 183
 184 \wxheading{Library}
 185
 186 \helpref{wxAdv}{librarieslist}
 187
 188 \wxheading{Data structures}
 189
 190 \latexignore{\rtfignore{\wxheading{Members}}}
 191
 192
 193 \membersection{wxDataViewTextRendererAttr::wxDataViewTextRendererAttr}\label{wxdataviewtextrendererattrwxdataviewtextrendererattr}
 194
 195 \func{}{wxDataViewTextRendererAttr}{\param{const wxString\& }{varianttype = "string"}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{align = wxDVR\_DEFAULT\_ALIGNMENT}}
 196
 197
 198 \section{\class{wxDataViewProgressRenderer}}\label{wxdataviewprogressrenderer}
 199
 200 wxDataViewProgressRenderer
 201
 202
 203 \wxheading{Derived from}
 204
 205 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 206 \helpref{wxObject}{wxobject}
 207
 208 \wxheading{Include files}
 209
 210 <wx/dataview.h>
 211
 212 \wxheading{Library}
 213
 214 \helpref{wxAdv}{librarieslist}
 215
 216
 217 \latexignore{\rtfignore{\wxheading{Members}}}
 218
 219 \membersection{wxDataViewProgressRenderer::wxDataViewProgressRenderer}\label{wxdataviewprogressrendererwxdataviewprogressrenderer}
 220
 221 \func{}{wxDataViewProgressRenderer}{\param{const wxString\& }{label = wxEmptyString}, \param{const wxString\& }{varianttype = long"}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 222
 223
 224 \section{\class{wxDataViewIconText}}\label{wxdataviewicontext}
 225
 226 wxDataViewIconText is used by
 227 \helpref{wxDataViewIconTextRenderer}{wxdataviewicontextrenderer}
 228 for data transfer. This class can be converted to a from
 229 a \helpref{wxVariant}{wxvariant}.
 230
 231 \wxheading{Derived from}
 232
 233 \helpref{wxObject}{wxobject}
 234
 235 \wxheading{Include files}
 236
 237 <dataview.h>
 238
 239 \membersection{wxDataViewIconText::wxDataViewIconText}\label{wxdataviewicontextwxdataviewicontext}
 240
 241 \func{}{wxDataViewIconText}{\param{const wxString\& }{text = wxEmptyString}, \param{const wxIcon\& }{icon = wxNullIcon}}
 242
 243 \func{}{wxDataViewIconText}{\param{const wxDataViewIconText\& }{other}}
 244
 245 Constructor.
 246
 247 \membersection{wxDataViewIconText::GetIcon}\label{wxdataviewicontextgeticon}
 248
 249 \constfunc{const wxIcon\&}{GetIcon}{\void}
 250
 251 Gets the icon.
 252
 253 \membersection{wxDataViewIconText::GetText}\label{wxdataviewicontextgettext}
 254
 255 \constfunc{wxString}{GetText}{\void}
 256
 257 Gets the text.
 258
 259 \membersection{wxDataViewIconText::SetIcon}\label{wxdataviewicontextseticon}
 260
 261 \func{void}{SetIcon}{\param{const wxIcon\& }{icon}}
 262
 263 Set the icon.
 264
 265 \membersection{wxDataViewIconText::SetText}\label{wxdataviewicontextsettext}
 266
 267 \func{void}{SetText}{\param{const wxString\& }{text}}
 268
 269 Set the text.
 270
 271 \section{\class{wxDataViewIconTextRenderer}}\label{wxdataviewicontextrenderer}
 272
 273 The wxDataViewIconTextRenderer class is used to display text with
 274 a small icon next to it as it is typically done in a file manager.
 275 This classes uses the \helpref{wxDataViewIconText}{wxdataviewicontext}
 276 helper class to store its data. wxDataViewIonText can be converted
 277 to a from a \helpref{wxVariant}{wxvariant} using the left shift
 278 operator.
 279
 280 \wxheading{Derived from}
 281
 282 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 283 \helpref{wxObject}{wxobject}
 284
 285 \wxheading{Include files}
 286
 287 <wx/dataview.h>
 288
 289 \wxheading{Library}
 290
 291 \helpref{wxAdv}{librarieslist}
 292
 293
 294 \latexignore{\rtfignore{\wxheading{Members}}}
 295
 296 \membersection{wxDataViewIconTextRenderer::wxDataViewIconTextRenderer}\label{wxdataviewtogglerendererwxdataviewicontextrenderer}
 297
 298 \func{}{wxDataViewIconTextRenderer}{\param{const wxString\& }{varianttype = "wxDataViewIconText"}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 299
 300
 301 \section{\class{wxDataViewToggleRenderer}}\label{wxdataviewtogglerenderer}
 302
 303 wxDataViewToggleRenderer
 304
 305 \wxheading{Derived from}
 306
 307 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 308 \helpref{wxObject}{wxobject}
 309
 310 \wxheading{Include files}
 311
 312 <wx/dataview.h>
 313
 314 \wxheading{Library}
 315
 316 \helpref{wxAdv}{librarieslist}
 317
 318
 319 \latexignore{\rtfignore{\wxheading{Members}}}
 320
 321 \membersection{wxDataViewToggleRenderer::wxDataViewToggleRenderer}\label{wxdataviewtogglerendererwxdataviewtogglerenderer}
 322
 323 \func{}{wxDataViewToggleRenderer}{\param{const wxString\& }{varianttype = "bool"}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 324
 325
 326 \section{\class{wxDataViewBitmapRenderer}}\label{wxdataviewbitmaprenderer}
 327
 328 wxDataViewBitmapRenderer
 329
 330 \wxheading{Derived from}
 331
 332 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 333 \helpref{wxObject}{wxobject}
 334
 335 \wxheading{Include files}
 336
 337 <wx/dataview.h>
 338
 339 \wxheading{Library}
 340
 341 \helpref{wxAdv}{librarieslist}
 342
 343
 344 \latexignore{\rtfignore{\wxheading{Members}}}
 345
 346 \membersection{wxDataViewBitmapRenderer::wxDataViewBitmapRenderer}\label{wxdataviewbitmaprendererwxdataviewbitmaprenderer}
 347
 348 \func{}{wxDataViewBitmapRenderer}{\param{const wxString\& }{varianttype = "wxBitmap"}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 349
 350
 351 \section{\class{wxDataViewDateRenderer}}\label{wxdataviewdaterenderer}
 352
 353 wxDataViewDateRenderer
 354
 355
 356 \wxheading{Derived from}
 357
 358 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 359 \helpref{wxObject}{wxobject}
 360
 361 \wxheading{Include files}
 362
 363 <wx/dataview.h>
 364
 365 \wxheading{Library}
 366
 367 \helpref{wxAdv}{librarieslist}
 368
 369
 370 \latexignore{\rtfignore{\wxheading{Members}}}
 371
 372 \membersection{wxDataViewDateRenderer::wxDataViewDateRenderer}\label{wxdataviewdaterendererwxdataviewdaterenderer}
 373
 374 \func{}{wxDataViewDateRenderer}{\param{const wxString\& }{varianttype = "datetime"}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}}
 375
 376
 377 \section{\class{wxDataViewCustomRenderer}}\label{wxdataviewcustomrenderer}
 378
 379 You need to derive a new class from wxDataViewCustomRenderer in
 380 order to write a new renderer. You need to override at least
 381 \helpref{SetValue}{wxdataviewrenderersetvalue},
 382 \helpref{GetValue}{wxdataviewrenderergetvalue},
 383 \helpref{GetSize}{wxdataviewcustomrenderergetsize}
 384 and \helpref{Render}{wxdataviewcustomrendererrender}.
 385
 386 If you want your renderer to support in-place editing then you
 387 also need to override
 388 \helpref{HasEditorCtrl}{wxdataviewcustomrendererhaseditorctrl},
 389 \helpref{CreateEditorCtrl}{wxdataviewcustomrenderercreateeditorctrl}
 390 and \helpref{GetValueFromEditorCtrl}{wxdataviewcustomrenderergetvaluefromeditorctrl}.
 391 Note that a special event handler will be pushed onto that
 392 editor control which handles <ENTER> and focus out events
 393 in order to end the editing.
 394
 395 \wxheading{Derived from}
 396
 397 \helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
 398 \helpref{wxObject}{wxobject}
 399
 400 \wxheading{Include files}
 401
 402 <wx/dataview.h>
 403
 404 \wxheading{Library}
 405
 406 \helpref{wxAdv}{librarieslist}
 407
 408
 409 \latexignore{\rtfignore{\wxheading{Members}}}
 410
 411 \membersection{wxDataViewCustomRenderer::wxDataViewCustomRenderer}\label{wxdataviewcustomrendererwxdataviewcustomrenderer}
 412
 413 \func{}{wxDataViewCustomRenderer}{\param{const wxString\& }{varianttype = "string"}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{bool }{no\_init = false}}
 414
 415 Constructor.
 416
 417 \membersection{wxDataViewCustomRenderer::\destruct{wxDataViewCustomRenderer}}\label{wxdataviewcustomrendererdtor}
 418
 419 \func{}{\destruct{wxDataViewCustomRenderer}}{\void}
 420
 421 Destructor.
 422
 423
 424 \membersection{wxDataViewCustomRenderer::HasEditorCtrl}\label{wxdataviewcustomrendererhaseditorctrl}
 425
 426 \func{virtual bool}{HasEditorCtrl}{\void}
 427
 428 Override this and make it return {\it true} in order to
 429 indicate that this renderer supports in-place editing.
 430
 431 \membersection{wxDataViewCustomRenderer::CreateEditorCtrl}\label{wxdataviewcustomrenderercreateeditorctrl}
 432
 433 \func{virtual wxControl*}{CreateEditorCtrl}{\param{wxWindow *}{parent}, \param{wxRect }{labelRect}, \param{const wxVariant \& }{value}}
 434
 435 Override this to create the actual editor control once editing
 436 is about to start. {\it parent} is the parent of the editor
 437 control, {\it labelRect} indicates the position and
 438 size of the editor control and {\it value} is its initial value:
 439
 440 {\small
 441 \begin{verbatim}
 442 {
 443     long l = value;
 444     return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
 445                  labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
 446 }
 447 \end{verbatim}
 448 }
 449
 450 \membersection{wxDataViewCustomRenderer::GetValueFromEditorCtrl}\label{wxdataviewcustomrenderergetvaluefromeditorctrl}
 451
 452 \func{virtual bool}{GetValueFromEditorCtrl}{\param{wxControl* }{editor}, \param{wxVariant \& }{value}}
 453
 454 Overrride this so that the renderer can get the value
 455 from the editor control (pointed to by {\it editor}):
 456
 457 {\small
 458 \begin{verbatim}
 459 {
 460     wxSpinCtrl *sc = (wxSpinCtrl*) editor;
 461     long l = sc->GetValue();
 462     value = l;
 463     return true;
 464 }
 465 \end{verbatim}
 466 }
 467
 468 \membersection{wxDataViewCustomRenderer::Activate}\label{wxdataviewcustomrendereractivate}
 469
 470 \func{virtual bool}{Activate}{\param{wxRect }{cell}, \param{wxDataViewModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 471
 472 Override this to react to double clicks or <ENTER>.
 473
 474 \membersection{wxDataViewCustomRenderer::GetDC}\label{wxdataviewcustomrenderergetdc}
 475
 476 \func{virtual wxDC*}{GetDC}{\void}
 477
 478 Create DC on request. Internal.
 479
 480
 481 \membersection{wxDataViewCustomRenderer::GetSize}\label{wxdataviewcustomrenderergetsize}
 482
 483 \func{virtual wxSize}{GetSize}{\void}
 484
 485 Return size required to show content.
 486
 487
 488 \membersection{wxDataViewCustomRenderer::LeftClick}\label{wxdataviewcustomrendererleftclick}
 489
 490 \func{virtual bool}{LeftClick}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 491
 492 Overrride this to react to a left click.
 493
 494 \membersection{wxDataViewCustomRenderer::Render}\label{wxdataviewcustomrendererrender}
 495
 496 \func{virtual bool}{Render}{\param{wxRect }{cell}, \param{wxDC* }{dc}, \param{int }{state}}
 497
 498 Override this to render the cell. Before this is called,
 499 \helpref{SetValue}{wxdataviewrenderersetvalue} was called
 500 so that this instance knows what to render.
 501
 502 \membersection{wxDataViewCustomRenderer::RenderText}\label{wxdataviewcustomrendererrender}
 503
 504 \func{bool}{RenderText}{\param{const wxString\& }{text}, \param{int }{xoffset}, \param{wxRect }{cell}, \param{wxDC* }{dc}, \param{int }{state}}
 505
 506 This method should be called from within \helpref{Render}{wxdataviewcustomrendererrender}
 507 whenever you need to render simple text. This will ensure that the
 508 correct colour, font and vertical alignment will be chosen so the
 509 text will look the same as text drawn by native renderers.
 510
 511 \membersection{wxDataViewCustomRenderer::RightClick}\label{wxdataviewcustomrendererrightclick}
 512
 513 \func{virtual bool}{RightClick}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 514
 515 Overrride this to react to a right click.
 516
 517 \membersection{wxDataViewCustomRenderer::StartDrag}\label{wxdataviewcustomrendererstartdrag}
 518
 519 \func{virtual bool}{StartDrag}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 520
 521 Overrride this to start a drag operation.
 522
 523
 524 \section{\class{wxDataViewSpinRenderer}}\label{wxdataviewspinrenderer}
 525
 526 This is a specialized renderer for rendering integer values. It
 527 supports modifying the values in-place by using a wxSpinCtrl.
 528 The renderer only support variants of type {\it long}.
 529
 530 \wxheading{Derived from}
 531
 532 \helpref{wxDataViewCustomRenderer}{wxdataviewcustomrenderer}
 533
 534 \wxheading{Include files}
 535
 536 <dataview.h>
 537
 538 \wxheading{Data structures}
 539
 540 \latexignore{\rtfignore{\wxheading{Members}}}
 541
 542
 543 \membersection{wxDataViewSpinRenderer::wxDataViewSpinRenderer}\label{wxdataviewspinrendererwxdataviewspinrenderer}
 544
 545 \func{}{wxDataViewSpinRenderer}{\param{int }{min}, \param{int }{max}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_EDITABLE}, \param{int }{alignment = wxDVR\_DEFAULT\_ALIGNMENT}}
 546
 547 Constructor. {\it min} and {\it max} indicate the minimum und
 548 maximum values of for the wxSpinCtrl.
 549