.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2020 by Total Control Software
License: wxWindows License
.. include:: headings.inc
.. module:: wx.lib.masked.timectrl
.. currentmodule:: wx.lib.masked.timectrl
.. highlight:: python
.. _wx.lib.masked.timectrl:
==========================================================================================================================================
|phoenix_title| **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.
|class_summary| Classes Summary
===============================
================================================================================ ================================================================================
`~wx.lib.masked.timectrl.TimeCtrl` Masked control providing several time formats and manipulation of time values.
`~wx.lib.masked.timectrl.TimeCtrlAccessorsMixin` Defines TimeCtrl's list of attributes having their own Get/Set functions,
`~wx.lib.masked.timectrl.TimeUpdatedEvent` Used to fire an EVT_TIMEUPDATE event whenever the value in a TimeCtrl changes.
================================================================================ ================================================================================
|
.. toctree::
:maxdepth: 1
:hidden:
wx.lib.masked.timectrl.TimeCtrl
wx.lib.masked.timectrl.TimeCtrlAccessorsMixin
wx.lib.masked.timectrl.TimeUpdatedEvent