interface/wx/timectrl.h

   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 };