wx.lib.masked.timectrl

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:

from wx.lib.masked import TimeCtrl

TimeCtrl(
     parent, id = -1,
     value = '00:00:00',
     pos = wx.DefaultPosition,
     size = wx.DefaultSize,
     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"
    )

value

If no initial value is set, the default will be midnight; if an illegal string is specified, a ValueError will result. (You can always later set the initial time with SetValue() after instantiation of the control.)

size

The size of the control will be automatically adjusted for 12/24 hour format if wx.DefaultSize is specified. NOTE: due to a problem with wx.DateTime, if the locale does not use ‘AM/PM’ for its values, the default format will automatically change to 24 hour format, and an AttributeError will be thrown if a non-24 format is specified.

style

By default, TimeCtrl will process TAB events, by allowing tab to the different cells within the control.

validator

By default, TimeCtrl just uses the default (empty) validator, as all of its validation for entry control is handled internally. However, a validator can be supplied to provide data transfer capability to the control.

format

This parameter can be used instead of the fmt24hr and displaySeconds parameters, respectively; it provides a shorthand way to specify the time format you want. Accepted values are ‘HHMMSS’, ‘HHMM’, ‘24HHMMSS’, and ‘24HHMM’. If the format is specified, the other two arguments will be ignored.

fmt24hr

If True, control will display time in 24 hour time format; if False, it will use 12 hour AM/PM format. SetValue() will adjust values accordingly for the control, based on the format specified. (This value is ignored if the format parameter is specified.)

displaySeconds

If True, control will include a seconds field; if False, it will just show hours and minutes. (This value is ignored if the format parameter is specified.)

spinButton

If specified, this button’s events will be bound to the behavior of the TimeCtrl, working like up/down cursor key events. (See BindSpinButton.)

min

Defines the lower bound for “valid” selections in the control. By default, TimeCtrl doesn’t have bounds. You must set both upper and lower bounds to make the control pay attention to them, (as only one bound makes no sense with times.) “Valid” times will fall between the min and max “pie wedge” of the clock.

max

Defines the upper bound for “valid” selections in the control. “Valid” times will fall between the min and max “pie wedge” of the clock. (This can be a “big piece”, ie. min = 11pm, max= 10pm means all but the hour from 10:00pm to 11pm are valid times.)

limited

If True, the control will not permit entry of values that fall outside the set bounds.

oob_color

Sets the background color used to indicate out-of-bounds values for the control when the control is not limited. This is set to “Yellow” by default.

---

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.

Classes Summary

TimeCtrl	Masked control providing several time formats and manipulation of time values.
TimeCtrlAccessorsMixin	Defines TimeCtrl’s list of attributes having their own Get/Set functions,
TimeUpdatedEvent	Used to fire an EVT_TIMEUPDATE event whenever the value in a TimeCtrl changes.