X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/339983ff62d8d8e2cd4137dd61c46553d459cedc..eb3efe0d4b8a0964cd0504a69c0e9540c18e390c:/wxPython/wx/lib/masked/timectrl.py?ds=sidebyside diff --git a/wxPython/wx/lib/masked/timectrl.py b/wxPython/wx/lib/masked/timectrl.py index ababfc9185..06e36e2d80 100644 --- a/wxPython/wx/lib/masked/timectrl.py +++ b/wxPython/wx/lib/masked/timectrl.py @@ -43,229 +43,233 @@ # o wxTimeCtrl -> masked.TimeCtrl # -""" -

-TimeCtrl provides a multi-cell control that allows manipulation of a time +""" +*TimeCtrl* provides a multi-cell control that allows manipulation of a time value. It supports 12 or 24 hour format, and you can use wxDateTime or mxDateTime to get/set values from the control. -

+ Left/right/tab keys to switch cells within a TimeCtrl, and the up/down arrows act like a spin control. TimeCtrl also allows for an actual spin button to be attached to the control, so that it acts like the up/down arrow keys. -

-The ! or c key sets the value of the control to the current time. -

-Here's the API for TimeCtrl: -

-    TimeCtrl(
+
+The ! or c key sets the value of the control to the current time.
+
+  Here's the API for TimeCtrl::
+
+    from wx.lib.masked import TimeCtrl
+
+    TimeCtrl(
          parent, id = -1,
-         value = '00:00:00',
+         value = '00:00:00',
          pos = wx.DefaultPosition,
          size = wx.DefaultSize,
-         style = wxTE_PROCESS_TAB,
-         validator = wx.DefaultValidator,
+         style = wxTE_PROCESS_TAB,
+         validator = wx.DefaultValidator,
          name = "time",
-         format = 'HHMMSS',
-         fmt24hr = False,
-         displaySeconds = True,
-         spinButton = None,
-         min = None,
-         max = None,
-         limited = None,
-         oob_color = "Yellow"
-)
-
- -
-
-
-
EVT_TIMEUPDATE(win, id, func) -
func is fired whenever the value of the control changes. -
-
-
SetValue(time_string | wxDateTime | wxTimeSpan | mx.DateTime | mx.DateTimeDelta) -
Sets the value of the control to a particular time, given a valid -value; raises ValueError on invalid value. -NOTE: This will only allow mx.DateTime or mx.DateTimeDelta if mx.DateTime -was successfully imported by the class module. -
-
GetValue(as_wxDateTime = False, as_mxDateTime = False, as_wxTimeSpan=False, as mxDateTimeDelta=False) -
Retrieves the value of the time from the control. By default this is -returned as a string, unless one of the other arguments is set; args are -searched in the order listed; only one value will be returned. -
-
GetWxDateTime(value=None) -
When called without arguments, retrieves the value of the control, and applies -it to the wxDateTimeFromHMS() constructor, and returns the resulting value. -The date portion will always be set to Jan 1, 1970. This form is the same -as GetValue(as_wxDateTime=True). GetWxDateTime can also be called with any of the -other valid time formats settable with SetValue, to regularize it to a single -wxDateTime form. The function will raise ValueError on an unconvertable argument. -
-
GetMxDateTime() -
Retrieves the value of the control and applies it to the DateTime.Time() -constructor,and returns the resulting value. (The date portion will always be -set to Jan 1, 1970.) (Same as GetValue(as_wxDateTime=True); provided for backward -compatibility with previous release.) -
-
-
BindSpinButton(SpinBtton) -
Binds an externally created spin button to the control, so that up/down spin -events change the active cell or selection in the control (in addition to the -up/down cursor keys.) (This is primarily to allow you to create a "standard" -interface to time controls, as seen in Windows.) -
-
-
SetMin(min=None) -
Sets the expected minimum value, or lower bound, of the control. -(The lower bound will only be enforced if the control is -configured to limit its values to the set bounds.) -If a value of None is provided, then the control will have -explicit lower bound. If the value specified is greater than -the current lower bound, then the function returns False and the -lower bound will not change from its current setting. On success, -the function returns True. Even if set, if there is no corresponding -upper bound, the control will behave as if it is unbounded. -
If successful and the current value is outside the -new bounds, if the control is limited the value will be -automatically adjusted to the nearest bound; if not limited, -the background of the control will be colored with the current -out-of-bounds color. -
-
GetMin(as_string=False) -
Gets the current lower bound value for the control, returning -None, if not set, or a wxDateTime, unless the as_string parameter -is set to True, at which point it will return the string -representation of the lower bound. -
-
-
SetMax(max=None) -
Sets the expected maximum value, or upper bound, of the control. -(The upper bound will only be enforced if the control is -configured to limit its values to the set bounds.) -If a value of None is provided, then the control will -have no explicit upper bound. If the value specified is less -than the current lower bound, then the function returns False and -the maximum will not change from its current setting. On success, -the function returns True. Even if set, if there is no corresponding -lower bound, the control will behave as if it is unbounded. -
If successful and the current value is outside the -new bounds, if the control is limited the value will be -automatically adjusted to the nearest bound; if not limited, -the background of the control will be colored with the current -out-of-bounds color. -
-
GetMax(as_string = False) -
Gets the current upper bound value for the control, returning -None, if not set, or a wxDateTime, unless the as_string parameter -is set to True, at which point it will return the string -representation of the lower bound. - -
-
-
SetBounds(min=None,max=None) -
This function is a convenience function for setting the min and max -values at the same time. The function only applies the maximum bound -if setting the minimum bound is successful, and returns True -only if both operations succeed. Note: leaving out an argument -will remove the corresponding bound, and result in the behavior of -an unbounded control. -
-
GetBounds(as_string = False) -
This function returns a two-tuple (min,max), indicating the -current bounds of the control. Each value can be None if -that bound is not set. The values will otherwise be wxDateTimes -unless the as_string argument is set to True, at which point they -will be returned as string representations of the bounds. -
-
-
IsInBounds(value=None) -
Returns True if no value is specified and the current value -of the control falls within the current bounds. This function can also -be called with a value to see if that value would fall within the current -bounds of the given control. It will raise ValueError if the value -specified is not a wxDateTime, mxDateTime (if available) or parsable string. -
-
-
IsValid(value) -
Returns Trueif specified value is a legal time value and -falls within the current bounds of the given control. -
-
-
SetLimited(bool) -
If called with a value of True, this function will cause the control -to limit the value to fall within the bounds currently specified. -(Provided both bounds have been set.) -If the control's value currently exceeds the bounds, it will then -be set to the nearest bound. -If called with a value of False, this function will disable value -limiting, but coloring of out-of-bounds values will still take -place if bounds have been set for the control. -
IsLimited() -
Returns True if the control is currently limiting the -value to fall within the current bounds. -
-
- + +-------------------- + +EVT_TIMEUPDATE(win, id, func) + func is fired whenever the value of the control changes. + + +SetValue(time_string | wxDateTime | wxTimeSpan | mx.DateTime | mx.DateTimeDelta) + Sets the value of the control to a particular time, given a valid + value; raises ValueError on invalid value. + +*NOTE:* This will only allow mx.DateTime or mx.DateTimeDelta if mx.DateTime + was successfully imported by the class module. + +GetValue(as_wxDateTime = False, as_mxDateTime = False, as_wxTimeSpan=False, as mxDateTimeDelta=False) + Retrieves the value of the time from the control. By default this is + returned as a string, unless one of the other arguments is set; args are + searched in the order listed; only one value will be returned. + +GetWxDateTime(value=None) + When called without arguments, retrieves the value of the control, and applies + it to the wxDateTimeFromHMS() constructor, and returns the resulting value. + The date portion will always be set to Jan 1, 1970. This form is the same + as GetValue(as_wxDateTime=True). GetWxDateTime can also be called with any of the + other valid time formats settable with SetValue, to regularize it to a single + wxDateTime form. The function will raise ValueError on an unconvertable argument. + +GetMxDateTime() + Retrieves the value of the control and applies it to the DateTime.Time() + constructor,and returns the resulting value. (The date portion will always be + set to Jan 1, 1970.) (Same as GetValue(as_wxDateTime=True); provided for backward + compatibility with previous release.) + + +BindSpinButton(SpinBtton) + Binds an externally created spin button to the control, so that up/down spin + events change the active cell or selection in the control (in addition to the + up/down cursor keys.) (This is primarily to allow you to create a "standard" + interface to time controls, as seen in Windows.) + + +SetMin(min=None) + Sets the expected minimum value, or lower bound, of the control. + (The lower bound will only be enforced if the control is + configured to limit its values to the set bounds.) + If a value of *None* is provided, then the control will have + explicit lower bound. If the value specified is greater than + the current lower bound, then the function returns False and the + lower bound will not change from its current setting. On success, + the function returns True. Even if set, if there is no corresponding + upper bound, the control will behave as if it is unbounded. + + If successful and the current value is outside the + new bounds, if the control is limited the value will be + automatically adjusted to the nearest bound; if not limited, + the background of the control will be colored with the current + out-of-bounds color. + +GetMin(as_string=False) + Gets the current lower bound value for the control, returning + None, if not set, or a wxDateTime, unless the as_string parameter + is set to True, at which point it will return the string + representation of the lower bound. + + +SetMax(max=None) + Sets the expected maximum value, or upper bound, of the control. + (The upper bound will only be enforced if the control is + configured to limit its values to the set bounds.) + If a value of *None* is provided, then the control will + have no explicit upper bound. If the value specified is less + than the current lower bound, then the function returns False and + the maximum will not change from its current setting. On success, + the function returns True. Even if set, if there is no corresponding + lower bound, the control will behave as if it is unbounded. + + If successful and the current value is outside the + new bounds, if the control is limited the value will be + automatically adjusted to the nearest bound; if not limited, + the background of the control will be colored with the current + out-of-bounds color. + +GetMax(as_string = False) + Gets the current upper bound value for the control, returning + None, if not set, or a wxDateTime, unless the as_string parameter + is set to True, at which point it will return the string + representation of the lower bound. + + + +SetBounds(min=None,max=None) + This function is a convenience function for setting the min and max + values at the same time. The function only applies the maximum bound + if setting the minimum bound is successful, and returns True + only if both operations succeed. *Note: leaving out an argument + will remove the corresponding bound, and result in the behavior of + an unbounded control.* + +GetBounds(as_string = False) + This function returns a two-tuple (min,max), indicating the + current bounds of the control. Each value can be None if + that bound is not set. The values will otherwise be wxDateTimes + unless the as_string argument is set to True, at which point they + will be returned as string representations of the bounds. + + +IsInBounds(value=None) + Returns *True* if no value is specified and the current value + of the control falls within the current bounds. This function can also + be called with a value to see if that value would fall within the current + bounds of the given control. It will raise ValueError if the value + specified is not a wxDateTime, mxDateTime (if available) or parsable string. + + +IsValid(value) + Returns *True* if specified value is a legal time value and + falls within the current bounds of the given control. + + +SetLimited(bool) + If called with a value of True, this function will cause the control + to limit the value to fall within the bounds currently specified. + (Provided both bounds have been set.) + If the control's value currently exceeds the bounds, it will then + be set to the nearest bound. + If called with a value of False, this function will disable value + limiting, but coloring of out-of-bounds values will still take + place if bounds have been set for the control. +IsLimited() + Returns *True* if the control is currently limiting the + value to fall within the current bounds. + + """ import copy @@ -291,6 +295,9 @@ wxEVT_TIMEVAL_UPDATED = wx.NewEventType() EVT_TIMEUPDATE = wx.PyEventBinder(wxEVT_TIMEVAL_UPDATED, 1) class TimeUpdatedEvent(wx.PyCommandEvent): + """ + Used to fire an EVT_TIMEUPDATE event whenever the value in a TimeCtrl changes. + """ def __init__(self, id, value ='12:00:00 AM'): wx.PyCommandEvent.__init__(self, wxEVT_TIMEVAL_UPDATED, id) self.value = value @@ -299,9 +306,10 @@ class TimeUpdatedEvent(wx.PyCommandEvent): return self.value class TimeCtrlAccessorsMixin: - # Define TimeCtrl's list of attributes having their own - # Get/Set functions, ignoring those that make no sense for - # an numeric control. + """ + Defines TimeCtrl's list of attributes having their own Get/Set functions, + ignoring those in the base class that make no sense for a time control. + """ exposed_basectrl_params = ( 'defaultValue', 'description', @@ -328,6 +336,9 @@ class TimeCtrlAccessorsMixin: class TimeCtrl(BaseMaskedTextCtrl): + """ + Masked control providing several time formats and manipulation of time values. + """ valid_ctrl_params = { 'format' : 'HHMMSS', # default format code @@ -354,7 +365,13 @@ class TimeCtrl(BaseMaskedTextCtrl): self.__fmt24hr = False wxdt = wx.DateTimeFromDMY(1, 0, 1970) - if wxdt.Format('%p') != 'AM': + try: + if wxdt.Format('%p') != 'AM': + TimeCtrl.valid_ctrl_params['format'] = '24HHMMSS' + self.__fmt24hr = True + fmt24hr = True # force/change default positional argument + # (will countermand explicit set to False too.) + except: TimeCtrl.valid_ctrl_params['format'] = '24HHMMSS' self.__fmt24hr = True fmt24hr = True # force/change default positional argument @@ -467,6 +484,9 @@ class TimeCtrl(BaseMaskedTextCtrl): def SetParameters(self, **kwargs): + """ + Function providing access to the parameters governing TimeCtrl display and bounds. + """ ## dbg('TimeCtrl::SetParameters(%s)' % repr(kwargs), indent=1) maskededit_kwargs = {} reset_format = False @@ -484,10 +504,13 @@ class TimeCtrl(BaseMaskedTextCtrl): if key == 'format': wxdt = wx.DateTimeFromDMY(1, 0, 1970) - if wxdt.Format('%p') != 'AM': + try: + if wxdt.Format('%p') != 'AM': + require24hr = True + else: + require24hr = False + except: require24hr = True - else: - require24hr = False # handle both local or generic 'maskededit' autoformat codes: if param_value == 'HHMMSS' or param_value == 'TIMEHHMMSS': @@ -621,6 +644,11 @@ class TimeCtrl(BaseMaskedTextCtrl): as_mxDateTime = False, as_wxTimeSpan = False, as_mxDateTimeDelta = False): + """ + This function returns the value of the display as a string by default, but + supports return as a wx.DateTime, mx.DateTime, wx.TimeSpan, or mx.DateTimeDelta, + if requested. (Evaluated in the order above-- first one wins!) + """ if as_wxDateTime or as_mxDateTime or as_wxTimeSpan or as_mxDateTimeDelta: @@ -640,7 +668,7 @@ class TimeCtrl(BaseMaskedTextCtrl): def SetWxDateTime(self, wxdt): """ - Because SetValue can take a wxDateTime, this is now just an alias. + Because SetValue can take a wx.DateTime, this is now just an alias. """ self.SetValue(wxdt) @@ -654,9 +682,9 @@ class TimeCtrl(BaseMaskedTextCtrl): wxTimeSpan mxDateTime mxDateTimeDelta - and converts it to a wxDateTime that always has Jan 1, 1970 as its date + and converts it to a wx.DateTime that always has Jan 1, 1970 as its date portion, so that range comparisons around values can work using - wxDateTime's built-in comparison function. If a value is not + wx.DateTime's built-in comparison function. If a value is not provided to convert, the string value of the control will be used. If the value is not one of the accepted types, a ValueError will be raised. @@ -685,12 +713,15 @@ class TimeCtrl(BaseMaskedTextCtrl): if not valid: # deal with bug/deficiency in wx.DateTime: - if wxdt.Format('%p') not in ('AM', 'PM') and checkTime in (5,8): - # couldn't parse the AM/PM field + try: + if wxdt.Format('%p') not in ('AM', 'PM') and checkTime in (5,8): + # couldn't parse the AM/PM field + raise ValueError('cannot convert string "%s" to valid time for the current locale; please use 24hr time instead' % value) + else: + ## dbg(indent=0, suspend=0) + raise ValueError('cannot convert string "%s" to valid time' % value) + except: raise ValueError('cannot convert string "%s" to valid time for the current locale; please use 24hr time instead' % value) - else: -## dbg(indent=0, suspend=0) - raise ValueError('cannot convert string "%s" to valid time' % value) else: if isinstance(value, wx.DateTime): @@ -725,13 +756,17 @@ class TimeCtrl(BaseMaskedTextCtrl): def SetMxDateTime(self, mxdt): """ - Because SetValue can take an mxDateTime, (if DateTime is importable), + Because SetValue can take an mx.DateTime, (if DateTime is importable), this is now just an alias. """ self.SetValue(value) def GetMxDateTime(self, value=None): + """ + Returns the value of the control as an mx.DateTime, with the date + portion set to January 1, 1970. + """ if value is None: t = self.GetValue(as_mxDateTime=True) else: @@ -869,7 +904,7 @@ class TimeCtrl(BaseMaskedTextCtrl): values at the same time. The function only applies the maximum bound if setting the minimum bound is successful, and returns True only if both operations succeed. - NOTE: leaving out an argument will remove the corresponding bound. + **NOTE:** leaving out an argument will remove the corresponding bound. """ ret = self.SetMin(min) return ret and self.SetMax(max) @@ -969,7 +1004,7 @@ class TimeCtrl(BaseMaskedTextCtrl): def IsLimited(self): """ Returns True if the control is currently limiting the - value to fall within any current bounds. Note: can + value to fall within any current bounds. *Note:* can be set even if there are no current bounds. """ return self.__limited @@ -1072,9 +1107,10 @@ class TimeCtrl(BaseMaskedTextCtrl): def SetInsertionPoint(self, pos): """ - Records the specified position and associated cell before calling base class' function. - This is necessary to handle the optional spin button, because the insertion - point is lost when the focus shifts to the spin button. + This override records the specified position and associated cell before + calling base class' function. This is necessary to handle the optional + spin button, because the insertion point is lost when the focus shifts + to the spin button. """ ## dbg('TimeCtrl::SetInsertionPoint', pos, indent=1) BaseMaskedTextCtrl.SetInsertionPoint(self, pos) # (causes EVT_TEXT event to fire) @@ -1333,7 +1369,15 @@ if __name__ == '__main__': app.MainLoop() except: traceback.print_exc() -i=0 +__i=0 + +## CHANGELOG: +## ==================== +## Version 1.3 +## 1. Converted docstrings to reST format, added doc for ePyDoc. +## 2. Renamed helper functions, vars etc. not intended to be visible in public +## interface to code. +## ## Version 1.2 ## 1. Changed parameter name display_seconds to displaySeconds, to follow ## other masked edit conventions.