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