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
 144 \wxheading{Include files}
 145
 146 <wx/dataview.h>
 147
 148 \wxheading{Library}
 149
 150 \helpref{wxAdv}{librarieslist}
 151
 152
 153 \membersection{wxDataViewTextRenderer::wxDataViewTextRenderer}\label{wxdataviewtextrendererwxdataviewtextrenderer}
 154
 155 \func{}{wxDataViewTextRenderer}{\param{const wxString\& }{varianttype = wxT("string")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 156
 157
 158
 159 \section{\class{wxDataViewProgressRenderer}}\label{wxdataviewprogressrenderer}
 160
 161 wxDataViewProgressRenderer
 162
 163
 164 \wxheading{Derived from}
 165
 166 \helpref{wxDataViewRenderer}{wxdataviewrenderer}
 167
 168 \wxheading{Include files}
 169
 170 <wx/dataview.h>
 171
 172 \wxheading{Library}
 173
 174 \helpref{wxAdv}{librarieslist}
 175
 176
 177 \membersection{wxDataViewProgressRenderer::wxDataViewProgressRenderer}\label{wxdataviewprogressrendererwxdataviewprogressrenderer}
 178
 179 \func{}{wxDataViewProgressRenderer}{\param{const wxString\& }{label = wxEmptyString}, \param{const wxString\& }{varianttype = wxT("long")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 180
 181
 182
 183 \section{\class{wxDataViewToggleRenderer}}\label{wxdataviewtogglerenderer}
 184
 185 wxDataViewToggleRenderer
 186
 187 \wxheading{Derived from}
 188
 189 \helpref{wxDataViewRenderer}{wxdataviewrenderer}
 190
 191 \wxheading{Include files}
 192
 193 <wx/dataview.h>
 194
 195 \wxheading{Library}
 196
 197 \helpref{wxAdv}{librarieslist}
 198
 199
 200 \membersection{wxDataViewToggleRenderer::wxDataViewToggleRenderer}\label{wxdataviewtogglerendererwxdataviewtogglerenderer}
 201
 202 \func{}{wxDataViewToggleRenderer}{\param{const wxString\& }{varianttype = wxT("bool")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 203
 204
 205 \section{\class{wxDataViewBitmapRenderer}}\label{wxdataviewbitmaprenderer}
 206
 207 wxDataViewBitmapRenderer
 208
 209 \wxheading{Derived from}
 210
 211 \helpref{wxDataViewRenderer}{wxdataviewrenderer}
 212
 213 \wxheading{Include files}
 214
 215 <wx/dataview.h>
 216
 217 \wxheading{Library}
 218
 219 \helpref{wxAdv}{librarieslist}
 220
 221
 222 \membersection{wxDataViewBitmapRenderer::wxDataViewBitmapRenderer}\label{wxdataviewbitmaprendererwxdataviewbitmaprenderer}
 223
 224 \func{}{wxDataViewBitmapRenderer}{\param{const wxString\& }{varianttype = wxT("wxBitmap")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}
 225
 226
 227 \section{\class{wxDataViewDateRenderer}}\label{wxdataviewdaterenderer}
 228
 229 wxDataViewDateRenderer
 230
 231
 232 \wxheading{Derived from}
 233
 234 \helpref{wxDataViewRenderer}{wxdataviewrenderer}
 235
 236 \wxheading{Include files}
 237
 238 <wx/dataview.h>
 239
 240 \wxheading{Library}
 241
 242 \helpref{wxAdv}{librarieslist}
 243
 244 \membersection{wxDataViewDateRenderer::wxDataViewDateRenderer}\label{wxdataviewdaterendererwxdataviewdaterenderer}
 245
 246 \func{}{wxDataViewDateRenderer}{\param{const wxString\& }{varianttype = wxT("datetime")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}}
 247
 248
 249 \section{\class{wxDataViewCustomRenderer}}\label{wxdataviewcustomrenderer}
 250
 251 You need to derive a new class from wxDataViewCustomRenderer in
 252 order to write a new renderer. You need to override at least
 253 \helpref{SetValue}{wxdataviewrenderersetvalue},
 254 \helpref{GetValue}{wxdataviewrenderergetvalue},
 255 \helpref{GetSize}{wxdataviewcustomrenderergetsize}
 256 and \helpref{Render}{wxdataviewcustomrendererrender}.
 257
 258 If you want your renderer to support in-place editing then you
 259 also need to override
 260 \helpref{HasEditorCtrl}{wxdataviewcustomrendererhaseditorctrl},
 261 \helpref{CreateEditorCtrl}{wxdataviewcustomrenderercreateeditorctrl}
 262 and \helpref{GetValueFromEditorCtrl}{wxdataviewcustomrenderergetvaluefromeditorctrl}.
 263 Note that a special event handler will be pushed onto that
 264 editor control which handles <ENTER> and focus out events
 265 in order to end the editing.
 266
 267 \wxheading{Derived from}
 268
 269 \helpref{wxDataViewRenderer}{wxdataviewrenderer}
 270
 271 \wxheading{Include files}
 272
 273 <wx/dataview.h>
 274
 275 \wxheading{Library}
 276
 277 \helpref{wxAdv}{librarieslist}
 278
 279 \membersection{wxDataViewCustomRenderer::wxDataViewCustomRenderer}\label{wxdataviewcustomrendererwxdataviewcustomrenderer}
 280
 281 \func{}{wxDataViewCustomRenderer}{\param{const wxString\& }{varianttype = wxT("string")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{bool }{no\_init = false}}
 282
 283 Constructor.
 284
 285 \membersection{wxDataViewCustomRenderer::\destruct{wxDataViewCustomRenderer}}\label{wxdataviewcustomrendererdtor}
 286
 287 \func{}{\destruct{wxDataViewCustomRenderer}}{\void}
 288
 289 Destructor.
 290
 291
 292 \membersection{wxDataViewCustomRenderer::HasEditorCtrl}\label{wxdataviewcustomrendererhaseditorctrl}
 293
 294 \func{virtual bool}{HasEditorCtrl}{\void}
 295
 296 Override this and make it return {\it true} in order to
 297 indicate that this renderer supports in-place editing.
 298
 299 \membersection{wxDataViewCustomRenderer::CreateEditorCtrl}\label{wxdataviewcustomrenderercreateeditorctrl}
 300
 301 \func{virtual wxControl*}{CreateEditorCtrl}{\param{wxWindow *}{parent}, \param{wxRect }{labelRect}, \param{const wxVariant \& }{value}}
 302
 303 Override this to create the actual editor control once editing
 304 is about to start. {\it parent} is the parent of the editor
 305 control, {\it labelRect} indicates the position and
 306 size of the editor control and {\it value} is its initial value:
 307
 308 {\small
 309 \begin{verbatim}
 310 {
 311     long l = value;
 312     return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
 313                  labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
 314 }
 315 \end{verbatim}
 316 }
 317
 318 \membersection{wxDataViewCustomRenderer::GetValueFromEditorCtrl}\label{wxdataviewcustomrenderergetvaluefromeditorctrl}
 319
 320 \func{virtual bool}{GetValueFromEditorCtrl}{\param{wxControl* }{editor}, \param{wxVariant \& }{value}}
 321
 322 Overrride this so that the renderer can get the value
 323 from the editor control (pointed to by {\it editor}):
 324
 325 {\small
 326 \begin{verbatim}
 327 {
 328     wxSpinCtrl *sc = (wxSpinCtrl*) editor;
 329     long l = sc->GetValue();
 330     value = l;
 331     return true;
 332 }
 333 \end{verbatim}
 334 }
 335
 336 \membersection{wxDataViewCustomRenderer::Activate}\label{wxdataviewcustomrendereractivate}
 337
 338 \func{virtual bool}{Activate}{\param{wxRect }{cell}, \param{wxDataViewListModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 339
 340 Override this to react to double clicks or <ENTER>.
 341
 342 \membersection{wxDataViewCustomRenderer::GetDC}\label{wxdataviewcustomrenderergetdc}
 343
 344 \func{virtual wxDC*}{GetDC}{\void}
 345
 346 Create DC on request. Internal.
 347
 348
 349 \membersection{wxDataViewCustomRenderer::GetSize}\label{wxdataviewcustomrenderergetsize}
 350
 351 \func{virtual wxSize}{GetSize}{\void}
 352
 353 Return size required to show content.
 354
 355
 356 \membersection{wxDataViewCustomRenderer::LeftClick}\label{wxdataviewcustomrendererleftclick}
 357
 358 \func{virtual bool}{LeftClick}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewListModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 359
 360 Overrride this to react to a left click.
 361
 362 \membersection{wxDataViewCustomRenderer::Render}\label{wxdataviewcustomrendererrender}
 363
 364 \func{virtual bool}{Render}{\param{wxRect }{cell}, \param{wxDC* }{dc}, \param{int }{state}}
 365
 366 Override this to render the cell. Before this is called,
 367 \helpref{SetValue}{wxdataviewrenderersetvalue} was called
 368 so that this instance knows what to render.
 369
 370 \membersection{wxDataViewCustomRenderer::RightClick}\label{wxdataviewcustomrendererrightclick}
 371
 372 \func{virtual bool}{RightClick}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewListModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 373
 374 Overrride this to react to a right click.
 375
 376 \membersection{wxDataViewCustomRenderer::StartDrag}\label{wxdataviewcustomrendererstartdrag}
 377
 378 \func{virtual bool}{StartDrag}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewListModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}
 379
 380 Overrride this to start a drag operation.
 381
 382
 383