clarified what needs to be done to get useful results with this class

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

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        datectrl.tex
%% Purpose:     wxDatePickerCtrl documentation
%% Author:      Vadim Zeitlin
%% Created:     2005-01-15
%% RCS-ID:      $Id$
%% Copyright:   (c) 2005 Vadim Zeitlin
%% License:     wxWidgets license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxDatePickerCtrl}}\label{wxdatepickerctrl}

This control allows the user to select a date. Unlike
\helpref{wxCalendarCtrl}{wxcalendarctrl}, which is a relatively big control,
it is implemented as a small window showing the currently selected date and
allowing to edit it directly using the keyboard and may also display a popup
window for more user-friendly date selection, depending on the styles used and
the platform.

\wxheading{Derived from}

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

\wxheading{Include files}

<wx/dateevt.h>

(only available if \texttt{wxUSE\_DATEPICKCTRL} is set to $1$)

\wxheading{Event handling}

\twocolwidtha{7cm}%
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_DATE\_CHANGED(id, func)}}{This event fires when the user
changes the current selection in the control.}
\end{twocollist}

\wxheading{See also}

\helpref{wxCalendarCtrl}{wxcalendarctrl},\\
\helpref{wxDateEvent}{wxdateevent}


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

\membersection{wxDatePickerCtrl::wxDatePickerCtrl}\label{wxdatepickerctrlctor}

\func{}{wxDatePickerCtrl}{\param{wxWindow *}{parent},\rtfsp
\param{wxWindowID}{ id},\rtfsp
\param{const wxDateTime\& }{dt = wxDefaultDateTime},\rtfsp
\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
\param{long}{ style = 0},\rtfsp
\param{const wxValidator\& }{validator = wxDefaultValidator},
\param{const wxString\& }{name = ``datectrl"}}

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


\membersection{wxDatePickerCtrl::Create}\label{wxdatepickerctrlcreate}

\func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
\param{wxWindowID}{ id},\rtfsp
\param{const wxDateTime\& }{dt = wxDefaultDateTime},\rtfsp
\param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
\param{const wxSize\& }{size = wxDefaultSize},\rtfsp
\param{long}{ style = 0},\rtfsp
\param{const wxValidator\& }{validator = wxDefaultValidator},
\param{const wxString\& }{name = ``datectrl"}}

\wxheading{Parameters}

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

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

\docparam{dt}{The initial value of the control, if an invalid date (such as the
default value) is used, the control is set to today.}

\docparam{pos}{Initial position.}

\docparam{size}{Initial size. If left at default value, the control chooses its
own best size by using the height approximately equal to a text control and
width large enough to show the date string fully.}

\docparam{style}{The window style, should be left at $0$ as there are no
special styles for this control in this version.}

\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{wxDatePickerCtrl::GetRange}\label{wxdatepickerctrlgetrange}

\constfunc{bool}{GetRange}{\param{wxDateTime *}{dt1}, \param{wxDateTime }{*dt2}}

If the control had been previously limited to a range of dates using 
\helpref{SetRange()}{wxdatepickerctrlsetrange}, returns the lower and upper
bounds of this range. If no range is set (or only one of the bounds is set),
the \arg{dt1} and/or \arg{dt2} are set to be invalid.

\wxheading{Parameters}

\docparam{dt1}{Pointer to the object which receives the lower range limit or
becomes invalid if it is not set. May be \texttt{NULLL} if the caller is not
interested in lower limit}

\docparam{dt2}{Same as above but for the upper limit}

\wxheading{Return value}

\false if no range limits are currently set, \true if at least one bound is
set.


\membersection{wxDatePickerCtrl::GetValue}\label{wxdatepickerctrlgetvalue}

\constfunc{wxDateTime}{GetValue}{\void}

Returns the currently selected. If there is no selection or the selection is
outside of the current range, an invalid object is returned.


\membersection{wxDatePickerCtrl::SetRange}\label{wxdatepickerctrlsetrange}

\func{void}{SetRange}{\param{const wxDateTime\&}{ dt1}, \param{const wxDateTime\&}{ dt2}}

Sets the valid range for the date selection. If \arg{dt1} is valid, it becomes
the earliest date (inclusive) accepted by the control. If \arg{dt2} is valid,
it becomes the latest possible date.

\wxheading{Remarks}

If the current value of the control is outside of the newly set range bounds,
the behaviour is undefined.


\membersection{wxDatePickerCtrl::SetValue}\label{wxdatepickerctrlsetvalue}

\func{void}{SetValue}{\param{const wxDateTime\&}{ dt}}

Changes the current value of the control. The date should be valid and included
in the currently selected range, if any.

Calling this method does not result in a date change event.