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