wxPython/wxPython/lib/timectrl.py

   1 #----------------------------------------------------------------------------
   2 # Name:         wxTimeCtrl.py
   3 # Author:       Will Sadkin
   4 # Created:      09/19/2002
   5 # Copyright:    (c) 2002 by Will Sadkin, 2002
   6 # RCS-ID:       $Id$
   7 # License:      wxWindows license
   8 #----------------------------------------------------------------------------
   9 # NOTE:
  10 #   This was written way it is because of the lack of masked edit controls
  11 #   in wxWindows/wxPython.  I would also have preferred to derive this
  12 #   control from a wxSpinCtrl rather than wxTextCtrl, but the wxTextCtrl
  13 #   component of that control is inaccessible through the interface exposed in
  14 #   wxPython.
  15 #
  16 #   wxTimeCtrl does not use validators, because it does careful manipulation
  17 #   of the cursor in the text window on each keystroke, and validation is
  18 #   cursor-position specific, so the control intercepts the key codes before the
  19 #   validator would fire.
  20 #
  21 #   wxTimeCtrl now also supports .SetValue() with either strings or wxDateTime
  22 #   values, as well as range limits, with the option of either enforcing them
  23 #   or simply coloring the text of the control if the limits are exceeded.
  24 #
  25 #   Note: this class now makes heavy use of wxDateTime for parsing and
  26 #   regularization, but it always does so with ephemeral instances of
  27 #   wxDateTime, as the C++/Python validity of these instances seems to not
  28 #   persist.  Because "today" can be a day for which an hour can "not exist"
  29 #   or be counted twice (1 day each per year, for DST adjustments), the date
  30 #   portion of all wxDateTimes used/returned have their date portion set to
  31 #   Jan 1, 1970 (the "epoch.")
  32 #
  33
  34 """<html><body>
  35 <P>
  36 <B>wxTimeCtrl</B> provides a multi-cell control that allows manipulation of a time
  37 value.  It supports 12 or 24 hour format, and you can use wxDateTime or mxDateTime
  38 to get/set values from the control.
  39 <P>
  40 Left/right/tab keys to switch cells within a wxTimeCtrl, and the up/down arrows act
  41 like a spin control.  wxTimeCtrl also allows for an actual spin button to be attached
  42 to the control, so that it acts like the up/down arrow keys.
  43 <P>
  44 The <B>!</B> or <B>c</B> key sets the value of the control to the current time.
  45 <P>
  46 Here's the API for wxTimeCtrl:
  47 <DL><PRE>
  48     <B>wxTimeCtrl</B>(
  49          parent, id = -1,
  50          <B>value</B> = '12:00:00 AM',
  51          pos = wxDefaultPosition,
  52          size = wxDefaultSize,
  53          <B>style</B> = wxTE_PROCESS_TAB,
  54          <B>validator</B> = wxDefaultValidator,
  55          name = "time",
  56          <B>fmt24hr</B> = False,
  57          <B>spinButton</B> = None,
  58          <B>min</B> = None,
  59          <B>max</B> = None,
  60          <B>limited</B> = None,
  61          <B>oob_color</B> = "Yellow"
  62 )
  63 </PRE>
  64 <UL>
  65     <DT><B>value</B>
  66     <DD>If no initial value is set, the default will be midnight; if an illegal string
  67     is specified, a ValueError will result.  (You can always later set the initial time
  68     with SetValue() after instantiation of the control.)
  69     <DL><B>size</B>
  70     <DD>The size of the control will be automatically adjusted for 12/24 hour format
  71     if wxDefaultSize is specified.
  72     <DT><B>style</B>
  73     <DD>By default, wxTimeCtrl will process TAB events, by allowing tab to the
  74     different cells within the control.
  75     <DT><B>validator</B>
  76     <DD>By default, wxTimeCtrl just uses the default (empty) validator, as all
  77     of its validation for entry control is handled internally.  However, a validator
  78     can be supplied to provide data transfer capability to the control.
  79     <BR>
  80     <DT><B>fmt24hr</B>
  81     <DD>If True, control will display time in 24 hour time format; if False, it will
  82     use 12 hour AM/PM format.  SetValue() will adjust values accordingly for the
  83     control, based on the format specified.
  84     <BR>
  85     <DT><B>spinButton</B>
  86     <DD>If specified, this button's events will be bound to the behavior of the
  87     wxTimeCtrl, working like up/down cursor key events.  (See BindSpinButton.)
  88     <BR>
  89     <DT><B>min</B>
  90     <DD>Defines the lower bound for "valid" selections in the control.
  91     By default, wxTimeCtrl doesn't have bounds.  You must set both upper and lower
  92     bounds to make the control pay attention to them, (as only one bound makes no sense
  93     with times.) "Valid" times will fall between the min and max "pie wedge" of the
  94     clock.
  95     <DT><B>max</B>
  96     <DD>Defines the upper bound for "valid" selections in the control.
  97     "Valid" times will fall between the min and max "pie wedge" of the
  98     clock. (This can be a "big piece", ie. <b>min = 11pm, max= 10pm</b>
  99     means <I>all but the hour from 10:00pm to 11pm are valid times.</I>)
 100     <DT><B>limited</B>
 101     <DD>If True, the control will not permit entry of values that fall outside the
 102     set bounds.
 103     <BR>
 104     <DT><B>oob_color</B>
 105     <DD>Sets the background color used to indicate out-of-bounds values for the control
 106     when the control is not limited.  This is set to "Yellow" by default.
 107     </DL>
 108 </UL>
 109 <BR>
 110 <BR>
 111 <BR>
 112 <DT><B>EVT_TIMEUPDATE(win, id, func)</B>
 113 <DD>func is fired whenever the value of the control changes.
 114 <BR>
 115 <BR>
 116 <DT><B>SetValue(time_string | wxDateTime | wxTimeSpan | mx.DateTime | mx.DateTimeDelta)</B>
 117 <DD>Sets the value of the control to a particular time, given a valid
 118 value; raises ValueError on invalid value.
 119 <EM>NOTE:</EM> This will only allow mx.DateTime or mx.DateTimeDelta if mx.DateTime
 120 was successfully imported by the class module.
 121 <BR>
 122 <DT><B>GetValue(as_wxDateTime = False, as_mxDateTime = False, as_wxTimeSpan=False, as mxDateTimeDelta=False)</B>
 123 <DD>Retrieves the value of the time from the control.  By default this is
 124 returned as a string, unless one of the other arguments is set; args are
 125 searched in the order listed; only one value will be returned.
 126 <BR>
 127 <DT><B>GetWxDateTime(value=None)</B>
 128 <DD>When called without arguments, retrieves the value of the control, and applies
 129 it to the wxDateTimeFromHMS() constructor, and returns the resulting value.
 130 The date portion will always be set to Jan 1, 1970. This form is the same
 131 as GetValue(as_wxDateTime=True).  GetWxDateTime can also be called with any of the
 132 other valid time formats settable with SetValue, to regularize it to a single
 133 wxDateTime form.  The function will raise ValueError on an unconvertable argument.
 134 <BR>
 135 <DT><B>GetMxDateTime()</B>
 136 <DD>Retrieves the value of the control and applies it to the DateTime.Time()
 137 constructor,and returns the resulting value.  (The date portion will always be
 138 set to Jan 1, 1970.) (Same as GetValue(as_wxDateTime=True); provided for backward
 139 compatibility with previous release.)
 140 <BR>
 141 <BR>
 142 <DT><B>BindSpinButton(wxSpinBtton)</B>
 143 <DD>Binds an externally created spin button to the control, so that up/down spin
 144 events change the active cell or selection in the control (in addition to the
 145 up/down cursor keys.)  (This is primarily to allow you to create a "standard"
 146 interface to time controls, as seen in Windows.)
 147 <BR>
 148 <BR>
 149 <DT><B>SetMin(min=None)</B>
 150 <DD>Sets the expected minimum value, or lower bound, of the control.
 151 (The lower bound will only be enforced if the control is
 152 configured to limit its values to the set bounds.)
 153 If a value of <I>None</I> is provided, then the control will have
 154 explicit lower bound.  If the value specified is greater than
 155 the current lower bound, then the function returns False and the
 156 lower bound will not change from its current setting.  On success,
 157 the function returns True.  Even if set, if there is no corresponding
 158 upper bound, the control will behave as if it is unbounded.
 159 <DT><DD>If successful and the current value is outside the
 160 new bounds, if the control is limited the value will be
 161 automatically adjusted to the nearest bound; if not limited,
 162 the background of the control will be colored with the current
 163 out-of-bounds color.
 164 <BR>
 165 <DT><B>GetMin(as_string=False)</B>
 166 <DD>Gets the current lower bound value for the control, returning
 167 None, if not set, or a wxDateTime, unless the as_string parameter
 168 is set to True, at which point it will return the string
 169 representation of the lower bound.
 170 <BR>
 171 <BR>
 172 <DT><B>SetMax(max=None)</B>
 173 <DD>Sets the expected maximum value, or upper bound, of the control.
 174 (The upper bound will only be enforced if the control is
 175 configured to limit its values to the set bounds.)
 176 If a value of <I>None</I> is provided, then the control will
 177 have no explicit upper bound.  If the value specified is less
 178 than the current lower bound, then the function returns False and
 179 the maximum will not change from its current setting. On success,
 180 the function returns True.  Even if set, if there is no corresponding
 181 lower bound, the control will behave as if it is unbounded.
 182 <DT><DD>If successful and the current value is outside the
 183 new bounds, if the control is limited the value will be
 184 automatically adjusted to the nearest bound; if not limited,
 185 the background of the control will be colored with the current
 186 out-of-bounds color.
 187 <BR>
 188 <DT><B>GetMax(as_string = False)</B>
 189 <DD>Gets the current upper bound value for the control, returning
 190 None, if not set, or a wxDateTime, unless the as_string parameter
 191 is set to True, at which point it will return the string
 192 representation of the lower bound.
 193
 194 <BR>
 195 <BR>
 196 <DT><B>SetBounds(min=None,max=None)</B>
 197 <DD>This function is a convenience function for setting the min and max
 198 values at the same time.  The function only applies the maximum bound
 199 if setting the minimum bound is successful, and returns True
 200 only if both operations succeed.  <B><I>Note: leaving out an argument
 201 will remove the corresponding bound, and result in the behavior of
 202 an unbounded control.</I></B>
 203 <BR>
 204 <DT><B>GetBounds(as_string = False)</B>
 205 <DD>This function returns a two-tuple (min,max), indicating the
 206 current bounds of the control.  Each value can be None if
 207 that bound is not set.  The values will otherwise be wxDateTimes
 208 unless the as_string argument is set to True, at which point they
 209 will be returned as string representations of the bounds.
 210 <BR>
 211 <BR>
 212 <DT><B>IsInBounds(value=None)</B>
 213 <DD>Returns <I>True</I> if no value is specified and the current value
 214 of the control falls within the current bounds.  This function can also
 215 be called with a value to see if that value would fall within the current
 216 bounds of the given control.  It will raise ValueError if the value
 217 specified is not a wxDateTime, mxDateTime (if available) or parsable string.
 218 <BR>
 219 <BR>
 220 <DT><B>IsValid(value)</B>
 221 <DD>Returns <I>True</I>if specified value is a legal time value and
 222 falls within the current bounds of the given control.
 223 <BR>
 224 <BR>
 225 <DT><B>SetLimited(bool)</B>
 226 <DD>If called with a value of True, this function will cause the control
 227 to limit the value to fall within the bounds currently specified.
 228 (Provided both bounds have been set.)
 229 If the control's value currently exceeds the bounds, it will then
 230 be set to the nearest bound.
 231 If called with a value of False, this function will disable value
 232 limiting, but coloring of out-of-bounds values will still take
 233 place if bounds have been set for the control.
 234 <DT><B>IsLimited()</B>
 235 <DD>Returns <I>True</I> if the control is currently limiting the
 236 value to fall within the current bounds.
 237 <BR>
 238 </DL>
 239 </body></html>
 240 """
 241
 242 import string, copy
 243 from wxPython.wx import *
 244 from wxPython.tools.dbg import Logger
 245 from wxPython.lib.maskededit import wxMaskedTextCtrl, Field
 246 import wxPython.utils
 247 dbg = Logger()
 248 dbg(enable=0)
 249
 250 try:
 251     from mx import DateTime
 252     accept_mx = True
 253 except ImportError:
 254     accept_mx = False
 255
 256 # This class of event fires whenever the value of the time changes in the control:
 257 wxEVT_TIMEVAL_UPDATED = wxNewId()
 258 def EVT_TIMEUPDATE(win, id, func):
 259     """Used to trap events indicating that the current time has been changed."""
 260     win.Connect(id, -1, wxEVT_TIMEVAL_UPDATED, func)
 261
 262 class TimeUpdatedEvent(wxPyCommandEvent):
 263     def __init__(self, id, value ='12:00:00 AM'):
 264         wxPyCommandEvent.__init__(self, wxEVT_TIMEVAL_UPDATED, id)
 265         self.value = value
 266     def GetValue(self):
 267         """Retrieve the value of the time control at the time this event was generated"""
 268         return self.value
 269
 270
 271 class wxTimeCtrl(wxMaskedTextCtrl):
 272
 273     valid_ctrl_params = {
 274         'display_seconds' : True,   # by default, shows seconds
 275         'min': None,                # by default, no bounds set
 276         'max': None,
 277         'limited': False,           # by default, no limiting even if bounds set
 278         'useFixedWidthFont': True,  # by default, use a fixed-width font
 279         'oob_color': "Yellow"       # by default, the default wxMaskedTextCtrl "invalid" color
 280         }
 281
 282     def __init__ (
 283                 self, parent, id=-1, value = '12:00:00 AM',
 284                 pos = wxDefaultPosition, size = wxDefaultSize,
 285                 fmt24hr=False,
 286                 spinButton = None,
 287                 style = wxTE_PROCESS_TAB,
 288                 validator = wxDefaultValidator,
 289                 name = "time",
 290                 **kwargs ):
 291
 292         # set defaults for control:
 293         dbg('setting defaults:')
 294         for key, param_value in wxTimeCtrl.valid_ctrl_params.items():
 295             # This is done this way to make setattr behave consistently with
 296             # "private attribute" name mangling
 297             setattr(self, "_wxTimeCtrl__" + key, copy.copy(param_value))
 298
 299         # create locals from current defaults, so we can override if
 300         # specified in kwargs, and handle uniformly:
 301         min = self.__min
 302         max = self.__max
 303         limited = self.__limited
 304         self.__posCurrent = 0
 305
 306
 307         # (handle positional args (from original release) differently from rest of kwargs:)
 308         self.__fmt24hr = fmt24hr
 309
 310         maskededit_kwargs = {}
 311
 312         # assign keyword args as appropriate:
 313         for key, param_value in kwargs.items():
 314             if key not in wxTimeCtrl.valid_ctrl_params.keys():
 315                 raise AttributeError('invalid keyword argument "%s"' % key)
 316
 317             if key == "display_seconds":
 318                 self.__display_seconds = param_value
 319
 320             elif key == "min":      min = param_value
 321             elif key == "max":      max = param_value
 322             elif key == "limited":  limited = param_value
 323
 324             elif key == "useFixedWidthFont":
 325                 maskededit_kwargs[key] = param_value
 326             elif key == "oob_color":
 327                 maskededit_kwargs['invalidBackgroundColor'] = param_value
 328
 329         if self.__fmt24hr:
 330             if self.__display_seconds:  maskededit_kwargs['autoformat'] = 'MILTIMEHHMMSS'
 331             else:                       maskededit_kwargs['autoformat'] = 'MILTIMEHHMM'
 332
 333             # Set hour field to zero-pad, right-insert, require explicit field change,
 334             # select entire field on entry, and require a resultant valid entry
 335             # to allow character entry:
 336             hourfield = Field(formatcodes='0r<SV', validRegex='0\d|1\d|2[0123]', validRequired=True)
 337         else:
 338             if self.__display_seconds:  maskededit_kwargs['autoformat'] = 'TIMEHHMMSS'
 339             else:                       maskededit_kwargs['autoformat'] = 'TIMEHHMM'
 340
 341             # Set hour field to allow spaces (at start), right-insert,
 342             # require explicit field change, select entire field on entry,
 343             # and require a resultant valid entry to allow character entry:
 344             hourfield = Field(formatcodes='_0<rSV', validRegex='0[1-9]| [1-9]|1[012]', validRequired=True)
 345             ampmfield = Field(formatcodes='S')
 346
 347         # Field 1 is always a zero-padded right-insert minute field,
 348         # similarly configured as above:
 349         minutefield = Field(formatcodes='0r<SV', validRegex='[0-5]\d', validRequired=True)
 350
 351         fields = [ hourfield, minutefield ]
 352         if self.__display_seconds:
 353             fields.append(copy.copy(minutefield))    # second field has same constraints as field 1
 354
 355         if not self.__fmt24hr:
 356             fields.append(ampmfield)
 357
 358         # set fields argument:
 359         maskededit_kwargs['fields'] = fields
 360
 361         # This allows range validation if set
 362         maskededit_kwargs['validFunc'] = self.IsInBounds
 363
 364         # This allows range limits to affect insertion into control or not
 365         # dynamically without affecting individual field constraint validation
 366         maskededit_kwargs['retainFieldValidation'] = True
 367
 368         # allow control over font selection:
 369         maskededit_kwargs['useFixedWidthFont'] = self.__useFixedWidthFont
 370
 371         # allow for explicit size specification:
 372         if size != wxDefaultSize:
 373             # override (and remove) "autofit" autoformat code in standard time formats:
 374             maskededit_kwargs['formatcodes'] = 'T!'
 375
 376         # Now we can initialize the base control:
 377         wxMaskedTextCtrl.__init__(
 378                 self, parent, id=id,
 379                 pos=pos, size=size,
 380                 style = style,
 381                 validator = validator,
 382                 name = name,
 383                 setupEventHandling = False,
 384                 **maskededit_kwargs)
 385
 386
 387         # This makes ':' act like tab (after we fix each ':' key event to remove "shift")
 388         self._SetKeyHandler(':', self._OnChangeField)
 389
 390
 391         # This makes the up/down keys act like spin button controls:
 392         self._SetKeycodeHandler(WXK_UP, self.__OnSpinUp)
 393         self._SetKeycodeHandler(WXK_DOWN, self.__OnSpinDown)
 394
 395
 396         # This allows ! and c/C to set the control to the current time:
 397         self._SetKeyHandler('!', self.__OnSetToNow)
 398         self._SetKeyHandler('c', self.__OnSetToNow)
 399         self._SetKeyHandler('C', self.__OnSetToNow)
 400
 401
 402         # Set up event handling ourselves, so we can insert special
 403         # processing on the ":' key to remove the "shift" attribute
 404         # *before* the default handlers have been installed, so
 405         # that : takes you forward, not back, and so we can issue
 406         # EVT_TIMEUPDATE events on changes:
 407
 408         EVT_SET_FOCUS( self, self._OnFocus )        ## defeat automatic full selection
 409         EVT_KILL_FOCUS( self, self._OnKillFocus )   ## run internal validator
 410         EVT_LEFT_UP(self, self.__LimitSelection)    ## limit selections to single field
 411         EVT_LEFT_DCLICK(self, self._OnDoubleClick ) ## select field under cursor on dclick
 412         EVT_KEY_DOWN( self, self._OnKeyDown )       ## capture control events not normally seen, eg ctrl-tab.
 413         EVT_CHAR( self, self.__OnChar )             ## remove "shift" attribute from colon key event,
 414                                                     ## then call wxMaskedTextCtrl._OnChar with
 415                                                     ## the possibly modified event.
 416         EVT_TEXT( self, self.GetId(), self.__OnTextChange ) ## color control appropriately and EVT_TIMEUPDATE events
 417
 418
 419         # Validate initial value and set if appropriate
 420         try:
 421             self.SetBounds(min, max)
 422             self.SetLimited(limited)
 423             self.SetValue(value)
 424         except:
 425             self.SetValue('12:00:00 AM')
 426
 427         if spinButton:
 428             self.BindSpinButton(spinButton)     # bind spin button up/down events to this control
 429
 430
 431
 432     def BindSpinButton(self, sb):
 433         """
 434         This function binds an externally created spin button to the control, so that
 435         up/down events from the button automatically change the control.
 436         """
 437         dbg('wxTimeCtrl::BindSpinButton')
 438         self.__spinButton = sb
 439         if self.__spinButton:
 440             # bind event handlers to spin ctrl
 441             EVT_SPIN_UP(self.__spinButton, self.__spinButton.GetId(), self.__OnSpinUp)
 442             EVT_SPIN_DOWN(self.__spinButton, self.__spinButton.GetId(), self.__OnSpinDown)
 443
 444
 445     def __repr__(self):
 446         return "<wxTimeCtrl: %s>" % self.GetValue()
 447
 448
 449     def SetValue(self, value):
 450         """
 451         Validating SetValue function for time values:
 452         This function will do dynamic type checking on the value argument,
 453         and convert wxDateTime, mxDateTime, or 12/24 format time string
 454         into the appropriate format string for the control.
 455         """
 456         dbg('wxTimeCtrl::SetValue(%s)' % repr(value), indent=1)
 457         try:
 458             strtime = self._toGUI(self.__validateValue(value))
 459         except:
 460             dbg('validation failed', indent=0)
 461             raise
 462
 463         dbg('strtime:', strtime)
 464         self._SetValue(strtime)
 465         dbg(indent=0)
 466
 467     def GetValue(self,
 468                  as_wxDateTime = False,
 469                  as_mxDateTime = False,
 470                  as_wxTimeSpan = False,
 471                  as_mxDateTimeDelta = False):
 472
 473
 474         if as_wxDateTime or as_mxDateTime or as_wxTimeSpan or as_mxDateTimeDelta:
 475             value = self.GetWxDateTime()
 476             if as_wxDateTime:
 477                 pass
 478             elif as_mxDateTime:
 479                 value = DateTime.DateTime(1970, 1, 1, value.GetHour(), value.GetMinute(), value.GetSecond())
 480             elif as_wxTimeSpan:
 481                 value = wxTimeSpan(value.GetHour(), value.GetMinute(), value.GetSecond())
 482             elif as_mxDateTimeDelta:
 483                 value = DateTime.DateTimeDelta(0, value.GetHour(), value.GetMinute(), value.GetSecond())
 484         else:
 485             value = wxMaskedTextCtrl.GetValue(self)
 486         return value
 487
 488
 489     def SetWxDateTime(self, wxdt):
 490         """
 491         Because SetValue can take a wxDateTime, this is now just an alias.
 492         """
 493         self.SetValue(wxdt)
 494
 495
 496     def GetWxDateTime(self, value=None):
 497         """
 498         This function is the conversion engine for wxTimeCtrl; it takes
 499         one of the following types:
 500             time string
 501             wxDateTime
 502             wxTimeSpan
 503             mxDateTime
 504             mxDateTimeDelta
 505         and converts it to a wxDateTime that always has Jan 1, 1970 as its date
 506         portion, so that range comparisons around values can work using
 507         wxDateTime's built-in comparison function.  If a value is not
 508         provided to convert, the string value of the control will be used.
 509         If the value is not one of the accepted types, a ValueError will be
 510         raised.
 511         """
 512         global accept_mx
 513         dbg(suspend=1)
 514         dbg('wxTimeCtrl::GetWxDateTime(%s)' % repr(value), indent=1)
 515         if value is None:
 516             dbg('getting control value')
 517             value = self.GetValue()
 518             dbg('value = "%s"' % value)
 519
 520         valid = True    # assume true
 521         if type(value) == types.StringType:
 522
 523             # Construct constant wxDateTime, then try to parse the string:
 524             wxdt = wxDateTimeFromDMY(1, 0, 1970)
 525             dbg('attempting conversion')
 526             value = value.strip()    # (parser doesn't like leading spaces)
 527             checkTime    = wxdt.ParseTime(value)
 528             valid = checkTime == len(value)     # entire string parsed?
 529             dbg('checkTime == len(value)?', valid)
 530
 531             if not valid:
 532                 dbg(indent=0, suspend=0)
 533                 raise ValueError('cannot convert string "%s" to valid time' % value)
 534
 535         else:
 536             if isinstance(value, wxPython.utils.wxDateTimePtr):
 537                 hour, minute, second = value.GetHour(), value.GetMinute(), value.GetSecond()
 538             elif isinstance(value, wxPython.utils.wxTimeSpanPtr):
 539                 totalseconds = value.GetSeconds()
 540                 hour = totalseconds / 3600
 541                 minute = totalseconds / 60 - (hour * 60)
 542                 second = totalseconds - ((hour * 3600) + (minute * 60))
 543
 544             elif accept_mx and isinstance(value, DateTime.DateTimeType):
 545                 hour, minute, second = value.hour, value.minute, value.second
 546             elif accept_mx and isinstance(value, DateTime.DateTimeDeltaType):
 547                 hour, minute, second = value.hour, value.minute, value.second
 548             else:
 549                 # Not a valid function argument
 550                 if self.__accept_mx:
 551                     error = 'GetWxDateTime requires wxDateTime, mxDateTime or parsable time string, passed %s'% repr(value)
 552                 else:
 553                     error = 'GetWxDateTime requires wxDateTime or parsable time string, passed %s'% repr(value)
 554                 dbg(indent=0, suspend=0)
 555                 raise ValueError(error)
 556
 557             wxdt = wxDateTimeFromDMY(1, 0, 1970)
 558             wxdt.SetHour(hour)
 559             wxdt.SetMinute(minute)
 560             wxdt.SetSecond(second)
 561
 562         dbg('wxdt:', wxdt, indent=0, suspend=0)
 563         return wxdt
 564
 565
 566     def SetMxDateTime(self, mxdt):
 567         """
 568         Because SetValue can take an mxDateTime, (if DateTime is importable),
 569         this is now just an alias.
 570         """
 571         self.SetValue(value)
 572
 573
 574     def GetMxDateTime(self, value=None):
 575         if value is None:
 576             t = self.GetValue(as_mxDateTime=True)
 577         else:
 578             # Convert string 1st to wxDateTime, then use components, since
 579             # mx' DateTime.Parser.TimeFromString() doesn't handle AM/PM:
 580             wxdt = self.GetWxDateTime(value)
 581             hour, minute, second = wxdt.GetHour(), wxdt.GetMinute(), wxdt.GetSecond()
 582             t = DateTime.DateTime(1970,1,1) + DateTimeDelta(0, hour, minute, second)
 583         return t
 584
 585
 586     def SetMin(self, min=None):
 587         """
 588         Sets the minimum value of the control.  If a value of None
 589         is provided, then the control will have no explicit minimum value.
 590         If the value specified is greater than the current maximum value,
 591         then the function returns 0 and the minimum will not change from
 592         its current setting.  On success, the function returns 1.
 593
 594         If successful and the current value is lower than the new lower
 595         bound, if the control is limited, the value will be automatically
 596         adjusted to the new minimum value; if not limited, the value in the
 597         control will be colored as invalid.
 598         """
 599         dbg('wxTimeCtrl::SetMin(%s)'% repr(min), indent=1)
 600         if min is not None:
 601             try:
 602                 min = self.GetWxDateTime(min)
 603                 self.__min = self._toGUI(min)
 604             except:
 605                 dbg('exception occurred', indent=0)
 606                 return False
 607         else:
 608             self.__min = min
 609
 610         if self.IsLimited() and not self.IsInBounds():
 611             self.SetLimited(self.__limited) # force limited value:
 612         else:
 613             self._CheckValid()
 614         ret = True
 615         dbg('ret:', ret, indent=0)
 616         return ret
 617
 618
 619     def GetMin(self, as_string = False):
 620         """
 621         Gets the minimum value of the control.
 622         If None, it will return None.  Otherwise it will return
 623         the current minimum bound on the control, as a wxDateTime
 624         by default, or as a string if as_string argument is True.
 625         """
 626         dbg(suspend=1)
 627         dbg('wxTimeCtrl::GetMin, as_string?', as_string, indent=1)
 628         if self.__min is None:
 629             dbg('(min == None)')
 630             ret = self.__min
 631         elif as_string:
 632             ret = self.__min
 633             dbg('ret:', ret)
 634         else:
 635             try:
 636                 ret = self.GetWxDateTime(self.__min)
 637             except:
 638                 dbg(suspend=0)
 639                 dbg('exception occurred', indent=0)
 640             dbg('ret:', repr(ret))
 641         dbg(indent=0, suspend=0)
 642         return ret
 643
 644
 645     def SetMax(self, max=None):
 646         """
 647         Sets the maximum value of the control. If a value of None
 648         is provided, then the control will have no explicit maximum value.
 649         If the value specified is less than the current minimum value, then
 650         the function returns False and the maximum will not change from its
 651         current setting. On success, the function returns True.
 652
 653         If successful and the current value is greater than the new upper
 654         bound, if the control is limited the value will be automatically
 655         adjusted to this maximum value; if not limited, the value in the
 656         control will be colored as invalid.
 657         """
 658         dbg('wxTimeCtrl::SetMax(%s)' % repr(max), indent=1)
 659         if max is not None:
 660             try:
 661                 max = self.GetWxDateTime(max)
 662                 self.__max = self._toGUI(max)
 663             except:
 664                 dbg('exception occurred', indent=0)
 665                 return False
 666         else:
 667             self.__max = max
 668         dbg('max:', repr(self.__max))
 669         if self.IsLimited() and not self.IsInBounds():
 670             self.SetLimited(self.__limited) # force limited value:
 671         else:
 672             self._CheckValid()
 673         ret = True
 674         dbg('ret:', ret, indent=0)
 675         return ret
 676
 677
 678     def GetMax(self, as_string = False):
 679         """
 680         Gets the minimum value of the control.
 681         If None, it will return None.  Otherwise it will return
 682         the current minimum bound on the control, as a wxDateTime
 683         by default, or as a string if as_string argument is True.
 684         """
 685         dbg(suspend=1)
 686         dbg('wxTimeCtrl::GetMin, as_string?', as_string, indent=1)
 687         if self.__max is None:
 688             dbg('(max == None)')
 689             ret = self.__max
 690         elif as_string:
 691             ret = self.__max
 692             dbg('ret:', ret)
 693         else:
 694             try:
 695                 ret = self.GetWxDateTime(self.__max)
 696             except:
 697                 dbg(suspend=0)
 698                 dbg('exception occurred', indent=0)
 699                 raise
 700             dbg('ret:', repr(ret))
 701         dbg(indent=0, suspend=0)
 702         return ret
 703
 704
 705     def SetBounds(self, min=None, max=None):
 706         """
 707         This function is a convenience function for setting the min and max
 708         values at the same time.  The function only applies the maximum bound
 709         if setting the minimum bound is successful, and returns True
 710         only if both operations succeed.
 711         NOTE: leaving out an argument will remove the corresponding bound.
 712         """
 713         ret = self.SetMin(min)
 714         return ret and self.SetMax(max)
 715
 716
 717     def GetBounds(self, as_string = False):
 718         """
 719         This function returns a two-tuple (min,max), indicating the
 720         current bounds of the control.  Each value can be None if
 721         that bound is not set.
 722         """
 723         return (self.GetMin(as_string), self.GetMax(as_string))
 724
 725
 726     def SetLimited(self, limited):
 727         """
 728         If called with a value of True, this function will cause the control
 729         to limit the value to fall within the bounds currently specified.
 730         If the control's value currently exceeds the bounds, it will then
 731         be limited accordingly.
 732
 733         If called with a value of 0, this function will disable value
 734         limiting, but coloring of out-of-bounds values will still take
 735         place if bounds have been set for the control.
 736         """
 737         dbg('wxTimeCtrl::SetLimited(%d)' % limited, indent=1)
 738         self.__limited = limited
 739
 740         if not limited:
 741             self.SetMaskParameters(validRequired = False)
 742             self._CheckValid()
 743             dbg(indent=0)
 744             return
 745
 746         dbg('requiring valid value')
 747         self.SetMaskParameters(validRequired = True)
 748
 749         min = self.GetMin()
 750         max = self.GetMax()
 751         if min is None or max is None:
 752             dbg('both bounds not set; no further action taken')
 753             return  # can't limit without 2 bounds
 754
 755         elif not self.IsInBounds():
 756             # set value to the nearest bound:
 757             try:
 758                 value = self.GetWxDateTime()
 759             except:
 760                 dbg('exception occurred', indent=0)
 761                 raise
 762
 763             if min <= max:   # valid range doesn't span midnight
 764                 dbg('min <= max')
 765                 # which makes the "nearest bound" computation trickier...
 766
 767                 # determine how long the "invalid" pie wedge is, and cut
 768                 # this interval in half for comparison purposes:
 769
 770                 # Note: relies on min and max and value date portions
 771                 # always being the same.
 772                 interval = (min + wxTimeSpan(24, 0, 0, 0)) - max
 773
 774                 half_interval = wxTimeSpan(
 775                                     0,      # hours
 776                                     0,      # minutes
 777                                     interval.GetSeconds() / 2,  # seconds
 778                                     0)      # msec
 779
 780                 if value < min: # min is on next day, so use value on
 781                     # "next day" for "nearest" interval calculation:
 782                     cmp_value = value + wxTimeSpan(24, 0, 0, 0)
 783                 else:   # "before midnight; ok
 784                     cmp_value = value
 785
 786                 if (cmp_value - max) > half_interval:
 787                     dbg('forcing value to min (%s)' % min.FormatTime())
 788                     self.SetValue(min)
 789                 else:
 790                     dbg('forcing value to max (%s)' % max.FormatTime())
 791                     self.SetValue(max)
 792             else:
 793                 dbg('max < min')
 794                 # therefore  max < value < min guaranteed to be true,
 795                 # so "nearest bound" calculation is much easier:
 796                 if (value - max) >= (min - value):
 797                     # current value closer to min; pick that edge of pie wedge
 798                     dbg('forcing value to min (%s)' % min.FormatTime())
 799                     self.SetValue(min)
 800                 else:
 801                     dbg('forcing value to max (%s)' % max.FormatTime())
 802                     self.SetValue(max)
 803
 804         dbg(indent=0)
 805
 806
 807
 808     def IsLimited(self):
 809         """
 810         Returns True if the control is currently limiting the
 811         value to fall within any current bounds.  Note: can
 812         be set even if there are no current bounds.
 813         """
 814         return self.__limited
 815
 816
 817     def IsInBounds(self, value=None):
 818         """
 819         Returns True if no value is specified and the current value
 820         of the control falls within the current bounds.  As the clock
 821         is a "circle", both minimum and maximum bounds must be set for
 822         a value to ever be considered "out of bounds".  This function can
 823         also be called with a value to see if that value would fall within
 824         the current bounds of the given control.
 825         """
 826         if value is not None:
 827             try:
 828                 value = self.GetWxDateTime(value)   # try to regularize passed value
 829             except ValueError:
 830                 dbg('ValueError getting wxDateTime for %s' % repr(value), indent=0)
 831                 raise
 832
 833         dbg('wxTimeCtrl::IsInBounds(%s)' % repr(value), indent=1)
 834         if self.__min is None or self.__max is None:
 835             dbg(indent=0)
 836             return True
 837
 838         elif value is None:
 839             try:
 840                 value = self.GetWxDateTime()
 841             except:
 842                 dbg('exception occurred', indent=0)
 843
 844         dbg('value:', value.FormatTime())
 845
 846         # Get wxDateTime representations of bounds:
 847         min = self.GetMin()
 848         max = self.GetMax()
 849
 850         midnight = wxDateTimeFromDMY(1, 0, 1970)
 851         if min <= max:   # they don't span midnight
 852             ret = min <= value <= max
 853
 854         else:
 855             # have to break into 2 tests; to be in bounds
 856             # either "min" <= value (<= midnight of *next day*)
 857             # or midnight <= value <= "max"
 858             ret = min <= value or (midnight <= value <= max)
 859         dbg('in bounds?', ret, indent=0)
 860         return ret
 861
 862
 863     def IsValid( self, value ):
 864         """
 865         Can be used to determine if a given value would be a legal and
 866         in-bounds value for the control.
 867         """
 868         try:
 869             self.__validateValue(value)
 870             return True
 871         except ValueError:
 872             return False
 873
 874
 875 #-------------------------------------------------------------------------------------------------------------
 876 # these are private functions and overrides:
 877
 878
 879     def __OnTextChange(self, event=None):
 880         dbg('wxTimeCtrl::OnTextChange', indent=1)
 881
 882         # Allow wxMaskedtext base control to color as appropriate,
 883         # and Skip the EVT_TEXT event (if appropriate.)
 884         ##! WS: For some inexplicable reason, every wxTextCtrl.SetValue()
 885         ## call is generating two (2) EVT_TEXT events. (!)
 886         ## The the only mechanism I can find to mask this problem is to
 887         ## keep track of last value seen, and declare a valid EVT_TEXT
 888         ## event iff the value has actually changed.  The masked edit
 889         ## OnTextChange routine does this, and returns True on a valid event,
 890         ## False otherwise.
 891         if not wxMaskedTextCtrl._OnTextChange(self, event):
 892             return
 893
 894         dbg('firing TimeUpdatedEvent...')
 895         evt = TimeUpdatedEvent(self.GetId(), self.GetValue())
 896         evt.SetEventObject(self)
 897         self.GetEventHandler().ProcessEvent(evt)
 898         dbg(indent=0)
 899
 900
 901     def SetInsertionPoint(self, pos):
 902         """
 903         Records the specified position and associated cell before calling base class' function.
 904         This is necessary to handle the optional spin button, because the insertion
 905         point is lost when the focus shifts to the spin button.
 906         """
 907         dbg('wxTimeCtrl::SetInsertionPoint', pos, indent=1)
 908         wxMaskedTextCtrl.SetInsertionPoint(self, pos)                 # (causes EVT_TEXT event to fire)
 909         self.__posCurrent = self.GetInsertionPoint()
 910         dbg(indent=0)
 911
 912
 913     def SetSelection(self, sel_start, sel_to):
 914         dbg('wxTimeCtrl::SetSelection', sel_start, sel_to, indent=1)
 915
 916         # Adjust selection range to legal extent if not already
 917         if sel_start < 0:
 918             sel_start = 0
 919
 920         if self.__posCurrent != sel_start:                      # force selection and insertion point to match
 921             self.SetInsertionPoint(sel_start)
 922         cell_start, cell_end = self._FindField(sel_start)._extent
 923         if not cell_start <= sel_to <= cell_end:
 924             sel_to = cell_end
 925
 926         self.__bSelection = sel_start != sel_to
 927         wxMaskedTextCtrl.SetSelection(self, sel_start, sel_to)
 928         dbg(indent=0)
 929
 930
 931     def __OnSpin(self, key):
 932         """
 933         This is the function that gets called in response to up/down arrow or
 934         bound spin button events.
 935         """
 936         self.__IncrementValue(key, self.__posCurrent)   # changes the value
 937
 938         # Ensure adjusted control regains focus and has adjusted portion
 939         # selected:
 940         self.SetFocus()
 941         start, end = self._FindField(self.__posCurrent)._extent
 942         self.SetInsertionPoint(start)
 943         self.SetSelection(start, end)
 944         dbg('current position:', self.__posCurrent)
 945
 946
 947     def __OnSpinUp(self, event):
 948         """
 949         Event handler for any bound spin button on EVT_SPIN_UP;
 950         causes control to behave as if up arrow was pressed.
 951         """
 952         dbg('wxTimeCtrl::OnSpinUp', indent=1)
 953         self.__OnSpin(WXK_UP)
 954         keep_processing = False
 955         dbg(indent=0)
 956         return keep_processing
 957
 958
 959     def __OnSpinDown(self, event):
 960         """
 961         Event handler for any bound spin button on EVT_SPIN_DOWN;
 962         causes control to behave as if down arrow was pressed.
 963         """
 964         dbg('wxTimeCtrl::OnSpinDown', indent=1)
 965         self.__OnSpin(WXK_DOWN)
 966         keep_processing = False
 967         dbg(indent=0)
 968         return keep_processing
 969
 970
 971     def __OnChar(self, event):
 972         """
 973         Handler to explicitly look for ':' keyevents, and if found,
 974         clear the m_shiftDown field, so it will behave as forward tab.
 975         It then calls the base control's _OnChar routine with the modified
 976         event instance.
 977         """
 978         dbg('wxTimeCtrl::OnChar', indent=1)
 979         keycode = event.GetKeyCode()
 980         dbg('keycode:', keycode)
 981         if keycode == ord(':'):
 982             dbg('colon seen! removing shift attribute')
 983             event.m_shiftDown = False
 984         wxMaskedTextCtrl._OnChar(self, event )              ## handle each keypress
 985         dbg(indent=0)
 986
 987
 988     def __OnSetToNow(self, event):
 989         """
 990         This is the key handler for '!' and 'c'; this allows the user to
 991         quickly set the value of the control to the current time.
 992         """
 993         self.SetValue(wxDateTime_Now().FormatTime())
 994         keep_processing = False
 995         return keep_processing
 996
 997
 998     def __LimitSelection(self, event):
 999         """
1000         Event handler for motion events; this handler
1001         changes limits the selection to the new cell boundaries.
1002         """
1003         dbg('wxTimeCtrl::LimitSelection', indent=1)
1004         pos = self.GetInsertionPoint()
1005         self.__posCurrent = pos
1006         sel_start, sel_to = self.GetSelection()
1007         selection = sel_start != sel_to
1008         if selection:
1009             # only allow selection to end of current cell:
1010             start, end = self._FindField(sel_start)._extent
1011             if sel_to < pos:   sel_to = start
1012             elif sel_to > pos: sel_to = end
1013
1014         dbg('new pos =', self.__posCurrent, 'select to ', sel_to)
1015         self.SetInsertionPoint(self.__posCurrent)
1016         self.SetSelection(self.__posCurrent, sel_to)
1017         if event: event.Skip()
1018         dbg(indent=0)
1019
1020
1021     def __IncrementValue(self, key, pos):
1022         dbg('wxTimeCtrl::IncrementValue', key, pos, indent=1)
1023         text = self.GetValue()
1024         field = self._FindField(pos)
1025         dbg('field: ', field._index)
1026         start, end = field._extent
1027         slice = text[start:end]
1028         if key == WXK_UP: increment = 1
1029         else:             increment = -1
1030
1031         if slice in ('A', 'P'):
1032             if slice == 'A': newslice = 'P'
1033             elif slice == 'P': newslice = 'A'
1034             newvalue = text[:start] + newslice + text[end:]
1035
1036         elif field._index == 0:
1037             # adjusting this field is trickier, as its value can affect the
1038             # am/pm setting.  So, we use wxDateTime to generate a new value for us:
1039             # (Use a fixed date not subject to DST variations:)
1040             converter = wxDateTimeFromDMY(1, 0, 1970)
1041             dbg('text: "%s"' % text)
1042             converter.ParseTime(text.strip())
1043             currenthour = converter.GetHour()
1044             dbg('current hour:', currenthour)
1045             newhour = (currenthour + increment) % 24
1046             dbg('newhour:', newhour)
1047             converter.SetHour(newhour)
1048             dbg('converter.GetHour():', converter.GetHour())
1049             newvalue = converter     # take advantage of auto-conversion for am/pm in .SetValue()
1050
1051         else:   # minute or second field; handled the same way:
1052             newslice = "%02d" % ((int(slice) + increment) % 60)
1053             newvalue = text[:start] + newslice + text[end:]
1054
1055         try:
1056             self.SetValue(newvalue)
1057
1058         except ValueError:  # must not be in bounds:
1059             if not wxValidator_IsSilent():
1060                 wxBell()
1061         dbg(indent=0)
1062
1063
1064     def _toGUI( self, wxdt ):
1065         """
1066         This function takes a wxdt as an unambiguous representation of a time, and
1067         converts it to a string appropriate for the format of the control.
1068         """
1069         if self.__fmt24hr:
1070             if self.__display_seconds: strval = wxdt.Format('%H:%M:%S')
1071             else:                      strval = wxdt.Format('%H:%M')
1072         else:
1073             if self.__display_seconds: strval = wxdt.Format('%I:%M:%S %p')
1074             else:                      strval = wxdt.Format('%I:%M %p')
1075
1076         return strval
1077
1078
1079     def __validateValue( self, value ):
1080         """
1081         This function converts the value to a wxDateTime if not already one,
1082         does bounds checking and raises ValueError if argument is
1083         not a valid value for the control as currently specified.
1084         It is used by both the SetValue() and the IsValid() methods.
1085         """
1086         dbg('wxTimeCtrl::__validateValue(%s)' % repr(value), indent=1)
1087         if not value:
1088             dbg(indent=0)
1089             raise ValueError('%s not a valid time value' % repr(value))
1090
1091         valid = True    # assume true
1092         try:
1093             value = self.GetWxDateTime(value)   # regularize form; can generate ValueError if problem doing so
1094         except:
1095             dbg('exception occurred', indent=0)
1096             raise
1097
1098         if self.IsLimited() and not self.IsInBounds(value):
1099             dbg(indent=0)
1100             raise ValueError (
1101                 'value %s is not within the bounds of the control' % str(value) )
1102         dbg(indent=0)
1103         return value
1104
1105 #----------------------------------------------------------------------------
1106 # Test jig for wxTimeCtrl:
1107
1108 if __name__ == '__main__':
1109     import traceback
1110
1111     class TestPanel(wxPanel):
1112         def __init__(self, parent, id,
1113                      pos = wxPyDefaultPosition, size = wxPyDefaultSize,
1114                      fmt24hr = 0, test_mx = 0,
1115                      style = wxTAB_TRAVERSAL ):
1116
1117             wxPanel.__init__(self, parent, id, pos, size, style)
1118
1119             self.test_mx = test_mx
1120
1121             self.tc = wxTimeCtrl(self, 10, fmt24hr = fmt24hr)
1122             sb = wxSpinButton( self, 20, wxDefaultPosition, wxSize(-1,20), 0 )
1123             self.tc.BindSpinButton(sb)
1124
1125             sizer = wxBoxSizer( wxHORIZONTAL )
1126             sizer.AddWindow( self.tc, 0, wxALIGN_CENTRE|wxLEFT|wxTOP|wxBOTTOM, 5 )
1127             sizer.AddWindow( sb, 0, wxALIGN_CENTRE|wxRIGHT|wxTOP|wxBOTTOM, 5 )
1128
1129             self.SetAutoLayout( True )
1130             self.SetSizer( sizer )
1131             sizer.Fit( self )
1132             sizer.SetSizeHints( self )
1133
1134             EVT_TIMEUPDATE(self, self.tc.GetId(), self.OnTimeChange)
1135
1136         def OnTimeChange(self, event):
1137             dbg('OnTimeChange: value = ', event.GetValue())
1138             wxdt = self.tc.GetWxDateTime()
1139             dbg('wxdt =', wxdt.GetHour(), wxdt.GetMinute(), wxdt.GetSecond())
1140             if self.test_mx:
1141                 mxdt = self.tc.GetMxDateTime()
1142                 dbg('mxdt =', mxdt.hour, mxdt.minute, mxdt.second)
1143
1144
1145     class MyApp(wxApp):
1146         def OnInit(self):
1147             import sys
1148             fmt24hr = '24' in sys.argv
1149             test_mx = 'mx' in sys.argv
1150             try:
1151                 frame = wxFrame(NULL, -1, "wxTimeCtrl Test", wxPoint(20,20), wxSize(100,100) )
1152                 panel = TestPanel(frame, -1, wxPoint(-1,-1), fmt24hr=fmt24hr, test_mx = test_mx)
1153                 frame.Show(True)
1154             except:
1155                 traceback.print_exc()
1156                 return False
1157             return True
1158
1159     try:
1160         app = MyApp(0)
1161         app.MainLoop()
1162     except:
1163         traceback.print_exc()