many wxItemContainer-related changes:

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        clrpicker.tex
%% Purpose:     wxColourPickerCtrl and wxColourPickerEvent documentation
%% Author:      Francesco Montorsi
%% Created:     2006-04-17
%% RCS-ID:      $Id$
%% Copyright:   (c) 2006 Francesco Montorsi
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxColourPickerCtrl}}\label{wxcolourpickerctrl}

This control allows the user to select a colour. The generic implementation is
a button which brings up a \helpref{wxColourDialog}{wxcolourdialog} when clicked. Native implementation
may differ but this is usually a (small) widget which give access to the colour-chooser
dialog.
It is only available if \texttt{wxUSE\_COLOURPICKERCTRL} is set to $1$ (the default).

\wxheading{Derived from}

\helpref{wxPickerBase}{wxpickerbase}\\
\helpref{wxControl}{wxcontrol}\\
\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/clrpicker.h>

\wxheading{Window styles}

\twocolwidtha{5cm}%
\begin{twocollist}\itemsep=0pt
\twocolitem{\windowstyle{wxCLRP\_DEFAULT\_STYLE}}{The default style: 0.}
\twocolitem{\windowstyle{wxCLRP\_USE\_TEXTCTRL}}{Creates a text control to the left of the
picker button which is completely managed by the \helpref{wxColourPickerCtrl}{wxcolourpickerctrl}
and which can be used by the user to specify a colour (see \helpref{SetColour}{wxcolourpickerctrlsetcolour}).
The text control is automatically synchronized with button's value. Use functions defined in \helpref{wxPickerBase}{wxpickerbase} to modify the text control.}
\twocolitem{\windowstyle{wxCLRP\_SHOW\_LABEL}}{Shows the colour in HTML form (#AABBCC) as colour button label
(instead of no label at all).}
\end{twocollist}

\wxheading{Event handling}

To process a colour picker event, use these event handler macros to direct input to member
functions that take a \helpref{wxColourPickerEvent}{wxcolourpickerevent} argument.

\twocolwidtha{7cm}%
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_COLOURPICKER\_CHANGED(id, func)}}{The user changed the
colour selected in the control either using the button or using text control
(see wxCLRP\_USE\_TEXTCTRL; note that in this case the event is fired only if
the user's input is valid, i.e. recognizable). }
\end{twocollist}

\wxheading{See also}

\helpref{wxColourDialog}{wxcolourdialog},\\
\helpref{wxColourPickerEvent}{wxcolourpickerevent}


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

\membersection{wxColourPickerCtrl::wxColourPickerCtrl}\label{wxcolourpickerctrl}

\func{}{wxColourPickerCtrl}{\param{wxWindow *}{parent},\rtfsp
\param{wxWindowID}{ id},\rtfsp
\param{const wxColour\& }{colour = *wxBLACK},\rtfsp
\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
\param{long}{ style = wxCLRP\_DEFAULT\_STYLE},\rtfsp
\param{const wxValidator\& }{validator = wxDefaultValidator},
\param{const wxString\& }{name = ``colourpickerctrl"}}

Initializes the object and calls \helpref{Create}{wxcolourpickerctrlcreate} with
all the parameters.


\membersection{wxColourPickerCtrl::Create}\label{wxcolourpickerctrlcreate}

\func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
\param{wxWindowID}{ id},\rtfsp
\param{const wxColour\& }{colour = *wxBLACK},\rtfsp
\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
\param{long}{ style = wxCLRP\_DEFAULT\_STYLE},\rtfsp
\param{const wxValidator\& }{validator = wxDefaultValidator},
\param{const wxString\& }{name = ``colourpickerctrl"}}

\wxheading{Parameters}

\docparam{parent}{Parent window, must not be non-\texttt{NULL}.}

\docparam{id}{The identifier for the control.}

\docparam{colour}{The initial colour shown in the control.}

\docparam{pos}{Initial position.}

\docparam{size}{Initial size.}

\docparam{style}{The window style, see {\tt wxCRLP\_*} flags.}

\docparam{validator}{Validator which can be used for additional date checks.}

\docparam{name}{Control name.}

\wxheading{Return value}

\true if the control was successfully created or \false if creation failed.


\membersection{wxColourPickerCtrl::GetColour}\label{wxcolourpickerctrlgetcolour}

\constfunc{wxColour}{GetColour}{\void}

Returns the currently selected colour.


\membersection{wxColourPickerCtrl::SetColour}\label{wxcolourpickerctrlsetcolour}

\func{void}{SetColour}{\param{const wxColour \&}{col}}

\func{void}{SetColour}{\param{const wxString \&}{colname}}

Sets the currently selected colour. See \helpref{wxColour::Set}{wxcolourset}.




%% wxColourPickerEvent documentation

\section{\class{wxColourPickerEvent}}\label{wxcolourpickerevent}

This event class is used for the events generated by
\helpref{wxColourPickerCtrl}{wxcolourpickerctrl}.

\wxheading{Derived from}

\helpref{wxCommandEvent}{wxcommandevent}\\
\helpref{wxEvent}{wxevent}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/clrpicker.h>

\wxheading{Event handling}

To process input from a wxColourPickerCtrl, use one of these event handler macros to
direct input to member function that take a
\helpref{wxColourPickerEvent}{wxcolourpickerevent} argument:

\twocolwidtha{7cm}
\begin{twocollist}
\twocolitem{{\bf EVT\_COLOURPICKER\_CHANGED(id, func)}}{Generated whenever the selected colour changes.}
\end{twocollist}%


\wxheading{See also}

\helpref{wxColourPickerCtrl}{wxcolourpickerctrl}

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

\membersection{wxColourPickerEvent::wxColourPickerEvent}\label{wxcolourpickereventctor}

\func{}{wxColourPickerEvent}{\param{wxObject *}{ generator}, \param{int}{ id}, \param{const wxColour\&}{ colour}}

The constructor is not normally used by the user code.


\membersection{wxColourPickerEvent::GetColour}\label{wxcolourpickereventgetcolour}

\constfunc{wxColour}{GetColour}{\void}

Retrieve the colour the user has just selected.


\membersection{wxColourPickerEvent::SetColour}\label{wxcolourpickereventsetcolour}

\func{void}{SetColour}{\param{const wxColour \&}{pos}}

Set the colour associated with the event.