1 /////////////////////////////////////////////////////////////////////////////
2 // Name:        wx/timectrl.h
3 // Purpose:     interface of wxTimePickerCtrl
4 // Author:      Vadim Zeitlin
5 // Created:     2011-09-22
6 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
7 // Licence:     wxWindows licence
8 /////////////////////////////////////////////////////////////////////////////
9 
10 /**
11     Styles used with wxTimePickerCtrl.
12 
13     Currently no special styles are defined for this object.
14 
15     @library{wxadv}
16     @category{pickers}
17 
18     @since 2.9.3
19  */
20 enum
21 {
22     wxTP_DEFAULT = 0
23 };
24 
25 /**
26     @class wxTimePickerCtrl
27 
28     This control allows the user to enter time.
29 
30     It is similar to wxDatePickerCtrl but is used for time, and not date,
31     selection. While GetValue() and SetValue() still work with values of type
32     wxDateTime (because wxWidgets doesn't provide a time-only class), their
33     date part is ignored by this control.
34 
35     It is only available if @c wxUSE_TIMEPICKCTRL is set to 1.
36 
37     This control currently doesn't have any specific flags.
38 
39     @beginEventEmissionTable{wxDateEvent}
40     @event{EVT_TIME_CHANGED(id, func)}
41            This event fires when the user changes the current selection in the
42            control.
43     @endEventTable
44 
45     @library{wxadv}
46     @category{pickers}
47     @appearance{timepickerctrl}
48 
49     @see wxDatePickerCtrl, wxDateEvent
50 
51     @since 2.9.3
52 */
53 class wxTimePickerCtrl : public wxControl
54 {
55 public:
56     /**
57        Default constructor.
58     */
59     wxTimePickerCtrl();
60 
61     /**
62         Initializes the object and calls Create() with all the parameters.
63     */
64     wxTimePickerCtrl(wxWindow* parent, wxWindowID id,
65                      const wxDateTime& dt = wxDefaultDateTime,
66                      const wxPoint& pos = wxDefaultPosition,
67                      const wxSize& size = wxDefaultSize,
68                      long style = wxTP_DEFAULT,
69                      const wxValidator& validator = wxDefaultValidator,
70                      const wxString& name = "timectrl");
71 
72     /**
73         Create the control window.
74 
75         This method should only be used for objects created using default
76         constructor.
77 
78         @param parent
79             Parent window, must not be non-@NULL.
80         @param id
81             The identifier for the control.
82         @param dt
83             The initial value of the control, if an invalid date (such as the
84             default value) is used, the control is set to current time.
85         @param pos
86             Initial position.
87         @param size
88             Initial size. If left at default value, the control chooses its own
89             best size by using the height approximately equal to a text control
90             and width large enough to show the time fully.
91         @param style
92             The window style, should be left at 0 as there are no special
93             styles for this control in this version.
94         @param validator
95             Validator which can be used for additional checks.
96         @param name
97             Control name.
98 
99         @return @true if the control was successfully created or @false if
100                  creation failed.
101     */
102     bool Create(wxWindow* parent, wxWindowID id,
103                 const wxDateTime& dt = wxDefaultDateTime,
104                 const wxPoint& pos = wxDefaultPosition,
105                 const wxSize& size = wxDefaultSize,
106                 long style = wxDP_DEFAULT | wxDP_SHOWCENTURY,
107                 const wxValidator& validator = wxDefaultValidator,
108                 const wxString& name = "timectrl");
109 
110     /**
111         Returns the currently entered time as hours, minutes and seconds.
112 
113         All the arguments must be non-@NULL, @false is returned otherwise and
114         none of them is modified.
115 
116         @see SetTime()
117 
118         @since 2.9.4
119      */
120     bool GetTime(int* hour, int* min, int* sec) const;
121 
122     /**
123         Returns the currently entered time.
124 
125         The date part of the returned wxDateTime object is always set to today
126         and should be ignored, only the time part is relevant.
127     */
128     virtual wxDateTime GetValue() const;
129 
130     /**
131         Changes the current time of the control.
132 
133         Calling this method does not result in a time change event.
134 
135         @param hour The new hour value in 0..23 interval.
136         @param min The new minute value in 0..59 interval.
137         @param sec The new second value in 0..59 interval.
138         @return @true if the time was changed or @false on failure, e.g. if the
139             time components were invalid.
140 
141         @see GetTime()
142 
143         @since 2.9.4
144      */
145     bool SetTime(int hour, int min, int sec);
146 
147     /**
148         Changes the current value of the control.
149 
150         The date part of @a dt is ignored, only the time part is displayed in
151         the control. The @a dt object must however be valid.
152 
153         In particular notice that it is a bad idea to use default wxDateTime
154         constructor from hour, minute and second values as it uses the today
155         date for the date part which means that some times can be invalid if
156         today happens to be the day of DST change. For example, when switching
157         to summer time the time 2:00 typically doesn't exist as the clocks jump
158         directly to 3:00. To avoid this problem, use a fixed date on which DST
159         is known not to change (e.g. Jan 1, 2012) for the date part of the
160         argument or use SetTime().
161 
162         Calling this method does not result in a time change event.
163     */
164     virtual void SetValue(const wxDateTime& dt);
165 };
166