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