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