added null pointer check and assert

[wxWidgets.git] / docs / latex / wx / dataviewrenderer.tex

\section{\class{wxDataViewRenderer}}\label{wxdataviewrenderer}


This class is used by \helpref{wxDataViewCtrl}{wxdataviewctrl} to
render the individual cells. One instance of a renderer class is
owned by \helpref{wxDataViewColumn}{wxdataviewcolumn}. There is
a number of ready-to-use renderers provided:
\helpref{wxDataViewTextRenderer}{wxdataviewtextrenderer},
\helpref{wxDataViewIconTextRenderer}{wxdataviewicontextrenderer},
\helpref{wxDataViewToggleRenderer}{wxdataviewtogglerenderer},
\helpref{wxDataViewProgressRenderer}{wxdataviewprogressrenderer},
\helpref{wxDataViewBitmapRenderer}{wxdataviewbitmaprenderer},
\helpref{wxDataViewDateRenderer}{wxdataviewdaterenderer}.
\helpref{wxDataViewSpinRenderer}{wxdataviewspinrenderer}.

Additionally, the user can write own renderers by deriving from
\helpref{wxDataViewCustomRenderer}{wxdataviewcustomrenderer}.

The {\it wxDataViewCellMode} flag controls, what actions
the cell data allows. {\it wxDATAVIEW\_CELL\_ACTIVATABLE}
indicates that the user can double click the cell and
something will happen (e.g. a window for editing a date
will pop up). {\it wxDATAVIEW\_CELL\_EDITABLE} indicates
that the user can edit the data in-place, i.e. an control
will show up after a slow click on the cell. This behaviour
is best known from changing the filename in most file 
managers etc.



{\small
\begin{verbatim}
enum wxDataViewCellMode
{
    wxDATAVIEW_CELL_INERT,
    wxDATAVIEW_CELL_ACTIVATABLE,
    wxDATAVIEW_CELL_EDITABLE
};
\end{verbatim}
}

The {\it wxDataViewCellRenderState} flag controls how the
the renderer should display its contents in a cell:

{\small
\begin{verbatim}
enum wxDataViewCellRenderState
{
    wxDATAVIEW_CELL_SELECTED    = 1,
    wxDATAVIEW_CELL_PRELIT      = 2,
    wxDATAVIEW_CELL_INSENSITIVE = 4,
    wxDATAVIEW_CELL_FOCUSED     = 8
};
\end{verbatim}
}


\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}



\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDataViewRenderer::wxDataViewRenderer}\label{wxdataviewrendererwxdataviewrenderer}

\func{}{wxDataViewRenderer}{\param{const wxString\& }{varianttype}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{int }{alignment = wxALIGN\_LEFT|wxALIGN\_CENTRE\_VERTICAL}}

Constructor.

\membersection{wxDataViewRenderer::GetMode}\label{wxdataviewrenderergetmode}

\func{virtual wxDataViewCellMode}{GetMode}{\void}

Returns the cell mode.

\membersection{wxDataViewRenderer::GetOwner}\label{wxdataviewrenderergetowner}

\func{virtual wxDataViewColumn*}{GetOwner}{\void}

Returns pointer to the owning \helpref{wxDataViewColumn}{wxdataviewcolumn}.

\membersection{wxDataViewRenderer::GetValue}\label{wxdataviewrenderergetvalue}

\func{virtual bool}{GetValue}{\param{wxVariant\& }{value}}

This methods retrieves the value from the renderer in order to
transfer the value back to the data model. Returns {\it false}
on failure.

\membersection{wxDataViewRenderer::GetVariantType}\label{wxdataviewrenderergetvarianttype}

\func{virtual wxString}{GetVariantType}{\void}

Returns a string with the type of the \helpref{wxVariant}{wxvariant}
supported by this renderer.

\membersection{wxDataViewRenderer::SetOwner}\label{wxdataviewrenderersetowner}

\func{virtual void}{SetOwner}{\param{wxDataViewColumn* }{owner}}

Sets the owning \helpref{wxDataViewColumn}{wxdataviewcolumn}. This
is usually called from within wxDataViewColumn.

\membersection{wxDataViewRenderer::SetValue}\label{wxdataviewrenderersetvalue}

\func{virtual bool}{SetValue}{\param{const wxVariant\& }{value}}

Set the value of the renderer (and thus its cell) to {\it value}.
The internal code will then render this cell with this data.


\membersection{wxDataViewRenderer::Validate}\label{wxdataviewrenderervalidate}

\func{virtual bool}{Validate}{\param{wxVariant\& }{value}}

Before data is committed to the data model, it is passed to this
method where it can be checked for validity. This can also be
used for checking a valid range or limiting the user input in
a certain aspect (e.g. max number of characters or only alphanumeric
input, ASCII only etc.). Return {\it false} if the value is
not valid.

Please note that due to implementation limitations, this validation
is done after the editing control already is destroyed and the
editing process finished.


\section{\class{wxDataViewTextRenderer}}\label{wxdataviewtextrenderer}

wxDataViewTextRenderer is used for rendering text. It supports
in-place editing if desired.


\wxheading{Derived from}

\helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDataViewTextRenderer::wxDataViewTextRenderer}\label{wxdataviewtextrendererwxdataviewtextrenderer}

\func{}{wxDataViewTextRenderer}{\param{const wxString\& }{varianttype = wxT("string")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}



\section{\class{wxDataViewProgressRenderer}}\label{wxdataviewprogressrenderer}

wxDataViewProgressRenderer


\wxheading{Derived from}

\helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDataViewProgressRenderer::wxDataViewProgressRenderer}\label{wxdataviewprogressrendererwxdataviewprogressrenderer}

\func{}{wxDataViewProgressRenderer}{\param{const wxString\& }{label = wxEmptyString}, \param{const wxString\& }{varianttype = wxT("long")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}


\section{\class{wxDataViewIconText}}\label{wxdataviewicontext}

wxDataViewIconText is used by 
\helpref{wxDataViewIconTextRenderer}{wxdataviewicontextrenderer}
for data transfer. This class can be converted to a from
a \helpref{wxVariant}{wxvariant}.

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<dataview.h>

\membersection{wxDataViewIconText::wxDataViewIconText}\label{wxdataviewicontextwxdataviewicontext}

\func{}{wxDataViewIconText}{\param{const wxString\& }{text = wxEmptyString}, \param{const wxIcon\& }{icon = wxNullIcon}}

\func{}{wxDataViewIconText}{\param{const wxDataViewIconText\& }{other}}

Constructor.

\membersection{wxDataViewIconText::GetIcon}\label{wxdataviewicontextgeticon}

\constfunc{const wxIcon\&}{GetIcon}{\void}

Gets the icon.

\membersection{wxDataViewIconText::GetText}\label{wxdataviewicontextgettext}

\constfunc{wxString}{GetText}{\void}

Gets the text.

\membersection{wxDataViewIconText::SetIcon}\label{wxdataviewicontextseticon}

\func{void}{SetIcon}{\param{const wxIcon\& }{icon}}

Set the icon.

\membersection{wxDataViewIconText::SetText}\label{wxdataviewicontextsettext}

\func{void}{SetText}{\param{const wxString\& }{text}}

Set the text.

\section{\class{wxDataViewIconTextRenderer}}\label{wxdataviewicontextrenderer}

The wxDataViewIconTextRenderer class is used to display text with
a small icon next to it as it is typically done in a file manager.
This classes uses the \helpref{wxDataViewIconText}{wxdataviewicontext}
helper class to store its data. wxDataViewIonText can be converted
to a from a \helpref{wxVariant}{wxvariant} using the left shift
operator.

\wxheading{Derived from}

\helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDataViewIconTextRenderer::wxDataViewIconTextRenderer}\label{wxdataviewtogglerendererwxdataviewicontextrenderer}

\func{}{wxDataViewIconTextRenderer}{\param{const wxString\& }{varianttype = wxT("wxDataViewIconText")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}


\section{\class{wxDataViewToggleRenderer}}\label{wxdataviewtogglerenderer}

wxDataViewToggleRenderer

\wxheading{Derived from}

\helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDataViewToggleRenderer::wxDataViewToggleRenderer}\label{wxdataviewtogglerendererwxdataviewtogglerenderer}

\func{}{wxDataViewToggleRenderer}{\param{const wxString\& }{varianttype = wxT("bool")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}


\section{\class{wxDataViewBitmapRenderer}}\label{wxdataviewbitmaprenderer}

wxDataViewBitmapRenderer

\wxheading{Derived from}

\helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDataViewBitmapRenderer::wxDataViewBitmapRenderer}\label{wxdataviewbitmaprendererwxdataviewbitmaprenderer}

\func{}{wxDataViewBitmapRenderer}{\param{const wxString\& }{varianttype = wxT("wxBitmap")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}}


\section{\class{wxDataViewDateRenderer}}\label{wxdataviewdaterenderer}

wxDataViewDateRenderer


\wxheading{Derived from}

\helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDataViewDateRenderer::wxDataViewDateRenderer}\label{wxdataviewdaterendererwxdataviewdaterenderer}

\func{}{wxDataViewDateRenderer}{\param{const wxString\& }{varianttype = wxT("datetime")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_ACTIVATABLE}}


\section{\class{wxDataViewCustomRenderer}}\label{wxdataviewcustomrenderer}

You need to derive a new class from wxDataViewCustomRenderer in
order to write a new renderer. You need to override at least 
\helpref{SetValue}{wxdataviewrenderersetvalue},
\helpref{GetValue}{wxdataviewrenderergetvalue}, 
\helpref{GetSize}{wxdataviewcustomrenderergetsize}
and \helpref{Render}{wxdataviewcustomrendererrender}.

If you want your renderer to support in-place editing then you
also need to override 
\helpref{HasEditorCtrl}{wxdataviewcustomrendererhaseditorctrl},
\helpref{CreateEditorCtrl}{wxdataviewcustomrenderercreateeditorctrl}
and \helpref{GetValueFromEditorCtrl}{wxdataviewcustomrenderergetvaluefromeditorctrl}.
Note that a special event handler will be pushed onto that
editor control which handles <ENTER> and focus out events
in order to end the editing.

\wxheading{Derived from}

\helpref{wxDataViewRenderer}{wxdataviewrenderer}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/dataview.h>

\wxheading{Library}

\helpref{wxAdv}{librarieslist}


\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxDataViewCustomRenderer::wxDataViewCustomRenderer}\label{wxdataviewcustomrendererwxdataviewcustomrenderer}

\func{}{wxDataViewCustomRenderer}{\param{const wxString\& }{varianttype = wxT("string")}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_INERT}, \param{bool }{no\_init = false}}

Constructor.

\membersection{wxDataViewCustomRenderer::\destruct{wxDataViewCustomRenderer}}\label{wxdataviewcustomrendererdtor}

\func{}{\destruct{wxDataViewCustomRenderer}}{\void}

Destructor.


\membersection{wxDataViewCustomRenderer::HasEditorCtrl}\label{wxdataviewcustomrendererhaseditorctrl}

\func{virtual bool}{HasEditorCtrl}{\void}

Override this and make it return {\it true} in order to
indicate that this renderer supports in-place editing.

\membersection{wxDataViewCustomRenderer::CreateEditorCtrl}\label{wxdataviewcustomrenderercreateeditorctrl}

\func{virtual wxControl*}{CreateEditorCtrl}{\param{wxWindow *}{parent}, \param{wxRect }{labelRect}, \param{const wxVariant \& }{value}}

Override this to create the actual editor control once editing
is about to start. {\it parent} is the parent of the editor
control, {\it labelRect} indicates the position and
size of the editor control and {\it value} is its initial value:

{\small
\begin{verbatim}
{ 
    long l = value;
    return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString, 
                 labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
}
\end{verbatim}
}

\membersection{wxDataViewCustomRenderer::GetValueFromEditorCtrl}\label{wxdataviewcustomrenderergetvaluefromeditorctrl}

\func{virtual bool}{GetValueFromEditorCtrl}{\param{wxControl* }{editor}, \param{wxVariant \& }{value}}

Overrride this so that the renderer can get the value 
from the editor control (pointed to by {\it editor}):

{\small
\begin{verbatim}
{ 
    wxSpinCtrl *sc = (wxSpinCtrl*) editor;
    long l = sc->GetValue();
    value = l;
    return true;
}
\end{verbatim}
}

\membersection{wxDataViewCustomRenderer::Activate}\label{wxdataviewcustomrendereractivate}

\func{virtual bool}{Activate}{\param{wxRect }{cell}, \param{wxDataViewModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}

Override this to react to double clicks or <ENTER>.

\membersection{wxDataViewCustomRenderer::GetDC}\label{wxdataviewcustomrenderergetdc}

\func{virtual wxDC*}{GetDC}{\void}

Create DC on request. Internal.


\membersection{wxDataViewCustomRenderer::GetSize}\label{wxdataviewcustomrenderergetsize}

\func{virtual wxSize}{GetSize}{\void}

Return size required to show content.


\membersection{wxDataViewCustomRenderer::LeftClick}\label{wxdataviewcustomrendererleftclick}

\func{virtual bool}{LeftClick}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}

Overrride this to react to a left click.

\membersection{wxDataViewCustomRenderer::Render}\label{wxdataviewcustomrendererrender}

\func{virtual bool}{Render}{\param{wxRect }{cell}, \param{wxDC* }{dc}, \param{int }{state}}

Override this to render the cell. Before this is called,
\helpref{SetValue}{wxdataviewrenderersetvalue} was called
so that this instance knows what to render.

\membersection{wxDataViewCustomRenderer::RenderText}\label{wxdataviewcustomrendererrender}

\func{bool}{RenderText}{\param{const wxString\& }{text}, \param{int }{xoffset}, \param{wxRect }{cell}, \param{wxDC* }{dc}, \param{int }{state}}

This method should be called from within \helpref{Render}{wxdataviewcustomrendererrender}
whenever you need to render simple text. This will ensure that the
correct colour, font and vertical alignment will be chosen so the
text will look the same as text drawn by native renderers.

\membersection{wxDataViewCustomRenderer::RightClick}\label{wxdataviewcustomrendererrightclick}

\func{virtual bool}{RightClick}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}

Overrride this to react to a right click.

\membersection{wxDataViewCustomRenderer::StartDrag}\label{wxdataviewcustomrendererstartdrag}

\func{virtual bool}{StartDrag}{\param{wxPoint }{cursor}, \param{wxRect }{cell}, \param{wxDataViewModel* }{model}, \param{unsigned int }{col}, \param{unsigned int }{row}}

Overrride this to start a drag operation.


\section{\class{wxDataViewSpinRenderer}}\label{wxdataviewspinrenderer}

This is a specialized renderer for rendering integer values. It
supports modifying the values in-place by using a wxSpinCtrl.
The renderer only support variants of type {\it long}.

\wxheading{Derived from}

\helpref{wxDataViewCustomRenderer}{wxdataviewcustomrenderer}

\wxheading{Include files}

<dataview.h>

\wxheading{Data structures}

\latexignore{\rtfignore{\wxheading{Members}}}


\membersection{wxDataViewSpinRenderer::wxDataViewSpinRenderer}\label{wxdataviewspinrendererwxdataviewspinrenderer}

\func{}{wxDataViewSpinRenderer}{\param{int }{min}, \param{int }{max}, \param{wxDataViewCellMode }{mode = wxDATAVIEW\_CELL\_EDITABLE}, \param{int }{alignment = wxDVR\_DEFAULT\_ALIGNMENT}}

Constructor. {\it min} and {\it max} indicate the minimum und
maximum values of for the wxSpinCtrl.