docs/latex/wx/datectrl.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        datectrl.tex
   3 %% Purpose:     wxDatePickerCtrl documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Created:     2005-01-15
   6 %% RCS-ID:      $Id$
   7 %% Copyright:   (c) 2005 Vadim Zeitlin
   8 %% License:     wxWindows license
   9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  10
  11 \section{\class{wxDatePickerCtrl}}\label{wxdatepickerctrl}
  12
  13 This control allows the user to select a date. Unlike
  14 \helpref{wxCalendarCtrl}{wxcalendarctrl}, which is a relatively big control,
  15 wxDatePickerCtrl is implemented as a small window showing the currently selected date.
  16 The control can be edited using the keyboard, and can also display a popup
  17 window for more user-friendly date selection, depending on the styles used and
  18 the platform, except PalmOS where date is selected using native dialog.
  19
  20 It is only available if \texttt{wxUSE\_DATEPICKCTRL} is set to $1$.
  21
  22 \wxheading{Derived from}
  23
  24 \helpref{wxControl}{wxcontrol}\\
  25 \helpref{wxWindow}{wxwindow}\\
  26 \helpref{wxEvtHandler}{wxevthandler}\\
  27 \helpref{wxObject}{wxobject}
  28
  29 \wxheading{Include files}
  30
  31 <wx/datectrl.h>
  32
  33 (only available if \texttt{wxUSE\_DATEPICKCTRL} is set to $1$)
  34
  35 \wxheading{Window styles}
  36
  37 \twocolwidtha{5cm}%
  38 \begin{twocollist}\itemsep=0pt
  39 \twocolitem{\windowstyle{wxDP\_SPIN}}{Creates a control without a month calendar
  40 drop down but with spin-control-like arrows to change individual date
  41 components. This style is not supported by the generic version.}
  42 \twocolitem{\windowstyle{wxDP\_DROPDOWN}}{Creates a control with a month
  43 calendar drop-down part from which the user can select a date.}
  44 \twocolitem{\windowstyle{wxDP\_DEFAULT}}{Creates a control with the style
  45 that is best supported for the current platform (currently wxDP\_SPIN
  46 under Windows and wxDP\_DROPDOWN elsewhere).}
  47 \twocolitem{\windowstyle{wxDP\_ALLOWNONE}}{With this style, the control allows
  48 the user to not enter any valid date at all. Without it - the default - the control always has some valid date.}
  49 \twocolitem{\windowstyle{wxDP\_SHOWCENTURY}}{Forces display of the century in
  50 the default date format. Without this style the century could be displayed, or
  51 not, depending on the default date representation in the system.}
  52 \end{twocollist}
  53
  54 \wxheading{Event handling}
  55
  56 \twocolwidtha{7cm}%
  57 \begin{twocollist}\itemsep=0pt
  58 \twocolitem{{\bf EVT\_DATE\_CHANGED(id, func)}}{This event fires when the user
  59 changes the current selection in the control.}
  60 \end{twocollist}
  61
  62 \wxheading{See also}
  63
  64 \helpref{wxCalendarCtrl}{wxcalendarctrl},\\
  65 \helpref{wxDateEvent}{wxdateevent}
  66
  67
  68 \latexignore{\rtfignore{\wxheading{Members}}}
  69
  70 \membersection{wxDatePickerCtrl::wxDatePickerCtrl}\label{wxdatepickerctrlctor}
  71
  72 \func{}{wxDatePickerCtrl}{\param{wxWindow *}{parent},\rtfsp
  73 \param{wxWindowID}{ id},\rtfsp
  74 \param{const wxDateTime\& }{dt = wxDefaultDateTime},\rtfsp
  75 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  76 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  77 \param{long}{ style = wxDP\_DEFAULT | wxDP\_SHOWCENTURY},\rtfsp
  78 \param{const wxValidator\& }{validator = wxDefaultValidator},
  79 \param{const wxString\& }{name = ``datectrl"}}
  80
  81 Initializes the object and calls \helpref{Create}{wxdatepickerctrlcreate} with
  82 all the parameters.
  83
  84
  85 \membersection{wxDatePickerCtrl::Create}\label{wxdatepickerctrlcreate}
  86
  87 \func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
  88 \param{wxWindowID}{ id},\rtfsp
  89 \param{const wxDateTime\& }{dt = wxDefaultDateTime},\rtfsp
  90 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  91 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  92 \param{long}{ style = wxDP\_DEFAULT | wxDP\_SHOWCENTURY},\rtfsp
  93 \param{const wxValidator\& }{validator = wxDefaultValidator},
  94 \param{const wxString\& }{name = ``datectrl"}}
  95
  96 \wxheading{Parameters}
  97
  98 \docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
  99
 100 \docparam{id}{The identifier for the control.}
 101
 102 \docparam{dt}{The initial value of the control, if an invalid date (such as the
 103 default value) is used, the control is set to today.}
 104
 105 \docparam{pos}{Initial position.}
 106
 107 \docparam{size}{Initial size. If left at default value, the control chooses its
 108 own best size by using the height approximately equal to a text control and
 109 width large enough to show the date string fully.}
 110
 111 \docparam{style}{The window style, should be left at $0$ as there are no
 112 special styles for this control in this version.}
 113
 114 \docparam{validator}{Validator which can be used for additional date checks.}
 115
 116 \docparam{name}{Control name.}
 117
 118 \wxheading{Return value}
 119
 120 \true if the control was successfully created or \false if creation failed.
 121
 122
 123 \membersection{wxDatePickerCtrl::GetRange}\label{wxdatepickerctrlgetrange}
 124
 125 \constfunc{bool}{GetRange}{\param{wxDateTime *}{dt1}, \param{wxDateTime }{*dt2}}
 126
 127 If the control had been previously limited to a range of dates using
 128 \helpref{SetRange()}{wxdatepickerctrlsetrange}, returns the lower and upper
 129 bounds of this range. If no range is set (or only one of the bounds is set),
 130  \arg{dt1} and/or \arg{dt2} are set to be invalid.
 131
 132 \wxheading{Parameters}
 133
 134 \docparam{dt1}{Pointer to the object which receives the lower range limit or
 135 becomes invalid if it is not set. May be \texttt{NULL} if the caller is not
 136 interested in lower limit}
 137
 138 \docparam{dt2}{Same as above but for the upper limit}
 139
 140 \wxheading{Return value}
 141
 142 \false if no range limits are currently set, \true if at least one bound is
 143 set.
 144
 145
 146 \membersection{wxDatePickerCtrl::GetValue}\label{wxdatepickerctrlgetvalue}
 147
 148 \constfunc{wxDateTime}{GetValue}{\void}
 149
 150 Returns the currently selected. If there is no selection or the selection is
 151 outside of the current range, an invalid object is returned.
 152
 153 \membersection{wxDatePickerCtrl::SetFormat}\label{wxdatepickerctrlsetformat}
 154
 155 \func{void}{SetFormat}{\param{const wxChar*}{ format}}
 156
 157 Please note that this function is only available in the generic version of this
 158 control. The native version always uses the current system locale.
 159
 160 Sets the display format for the date in the control. See wxDateTime for the
 161 meaning of format strings.
 162
 163 \wxheading{Remarks}
 164
 165 If the format parameter is invalid,
 166 the behaviour is undefined.
 167
 168
 169 \membersection{wxDatePickerCtrl::SetRange}\label{wxdatepickerctrlsetrange}
 170
 171 \func{void}{SetRange}{\param{const wxDateTime\&}{ dt1}, \param{const wxDateTime\&}{ dt2}}
 172
 173 Sets the valid range for the date selection. If \arg{dt1} is valid, it becomes
 174 the earliest date (inclusive) accepted by the control. If \arg{dt2} is valid,
 175 it becomes the latest possible date.
 176
 177 \wxheading{Remarks}
 178
 179 If the current value of the control is outside of the newly set range bounds,
 180 the behaviour is undefined.
 181
 182
 183 \membersection{wxDatePickerCtrl::SetValue}\label{wxdatepickerctrlsetvalue}
 184
 185 \func{void}{SetValue}{\param{const wxDateTime\&}{ dt}}
 186
 187 Changes the current value of the control. The date should be valid and included
 188 in the currently selected range, if any.
 189
 190 Calling this method does not result in a date change event.
 191