1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%% Name:        datectrl.tex
3%% Purpose:     wxDatePickerCtrl documentation
4%% Author:      Vadim Zeitlin
5%% Created:     2005-01-15
6%% RCS-ID:      $Id: datectrl.tex 43742 2006-12-02 12:50:24Z VZ $
7%% Copyright:   (c) 2005 Vadim Zeitlin
8%% License:     wxWindows license
9%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10
11\section{\class{wxDatePickerCtrl}}\label{wxdatepickerctrl}
12
13This control allows the user to select a date. Unlike 
14\helpref{wxCalendarCtrl}{wxcalendarctrl}, which is a relatively big control,
15wxDatePickerCtrl is implemented as a small window showing the currently selected date.
16The control can be edited using the keyboard, and can also display a popup
17window for more user-friendly date selection, depending on the styles used and
18the platform, except PalmOS where date is selected using native dialog.
19
20It 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
40drop down but with spin-control-like arrows to change individual date
41components. This style is not supported by the generic version.}
42\twocolitem{\windowstyle{wxDP\_DROPDOWN}}{Creates a control with a month
43calendar drop-down part from which the user can select a date.}
44\twocolitem{\windowstyle{wxDP\_DEFAULT}}{Creates a control with the style
45that is best supported for the current platform (currently wxDP\_SPIN
46under Windows and wxDP\_DROPDOWN elsewhere).}
47\twocolitem{\windowstyle{wxDP\_ALLOWNONE}}{With this style, the control allows
48the 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
50the default date format. Without this style the century could be displayed, or
51not, 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
59changes 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
81Initializes the object and calls \helpref{Create}{wxdatepickerctrlcreate} with
82all 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
103default 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
108own best size by using the height approximately equal to a text control and
109width large enough to show the date string fully.}
110
111\docparam{style}{The window style, should be left at $0$ as there are no
112special 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
127If the control had been previously limited to a range of dates using 
128\helpref{SetRange()}{wxdatepickerctrlsetrange}, returns the lower and upper
129bounds 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
135becomes invalid if it is not set. May be \texttt{NULL} if the caller is not
136interested 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
143set.
144
145
146\membersection{wxDatePickerCtrl::GetValue}\label{wxdatepickerctrlgetvalue}
147
148\constfunc{wxDateTime}{GetValue}{\void}
149
150Returns the currently selected. If there is no selection or the selection is
151outside 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
157Please note that this function is only available in the generic version of this
158control. The native version always uses the current system locale.
159
160Sets the display format for the date in the control. See wxDateTime for the
161meaning of format strings.
162
163\wxheading{Remarks}
164
165If the format parameter is invalid,
166the 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
173Sets the valid range for the date selection. If \arg{dt1} is valid, it becomes
174the earliest date (inclusive) accepted by the control. If \arg{dt2} is valid,
175it becomes the latest possible date.
176
177\wxheading{Remarks}
178
179If the current value of the control is outside of the newly set range bounds,
180the behaviour is undefined.
181
182
183\membersection{wxDatePickerCtrl::SetValue}\label{wxdatepickerctrlsetvalue}
184
185\func{void}{SetValue}{\param{const wxDateTime\&}{ dt}}
186
187Changes the current value of the control. The date should be valid and included
188in the currently selected range, if any.
189
190Calling this method does not result in a date change event.
191
192