timectrl.py

Wxpython Implemented on Windows CE, Source code

#----------------------------------------------------------------------------
# Name:         timectrl.py
# Author:       Will Sadkin
# Created:      09/19/2002
# Copyright:    (c) 2002 by Will Sadkin, 2002
# RCS-ID:       $Id: timectrl.py,v 1.4 2005/02/28 18:45:13 RD Exp $
# License:      wxWindows license
#----------------------------------------------------------------------------
# NOTE:
#   This was written way it is because of the lack of masked edit controls
#   in wxWindows/wxPython.  I would also have preferred to derive this
#   control from a wxSpinCtrl rather than wxTextCtrl, but the wxTextCtrl
#   component of that control is inaccessible through the interface exposed in
#   wxPython.
#
#   TimeCtrl does not use validators, because it does careful manipulation
#   of the cursor in the text window on each keystroke, and validation is
#   cursor-position specific, so the control intercepts the key codes before the
#   validator would fire.
#
#   TimeCtrl now also supports .SetValue() with either strings or wxDateTime
#   values, as well as range limits, with the option of either enforcing them
#   or simply coloring the text of the control if the limits are exceeded.
#
#   Note: this class now makes heavy use of wxDateTime for parsing and
#   regularization, but it always does so with ephemeral instances of
#   wxDateTime, as the C++/Python validity of these instances seems to not
#   persist.  Because "today" can be a day for which an hour can "not exist"
#   or be counted twice (1 day each per year, for DST adjustments), the date
#   portion of all wxDateTimes used/returned have their date portion set to
#   Jan 1, 1970 (the "epoch.")
#----------------------------------------------------------------------------
# 12/13/2003 - Jeff Grimmett ([e-mail])
#
# o Updated for V2.5 compatability
# o wx.SpinCtl has some issues that cause the control to
#   lock up. Noted in other places using it too, it's not this module
#   that's at fault.
#
# 12/20/2003 - Jeff Grimmett ([e-mail])
#
# o wxMaskedTextCtrl -> masked.TextCtrl
# o wxTimeCtrl -> 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.


"""

import  copy
import  string
import  types

import  wx

from wx.tools.dbg import Logger
from wx.lib.masked import Field, BaseMaskedTextCtrl

dbg = Logger()
##dbg(enable=0)

try:
    from mx import DateTime
    accept_mx = True
except ImportError:
    accept_mx = False

# This class of event fires whenever the value of the time changes in the control:
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
    def GetValue(self):
        """Retrieve the value of the time control at the time this event was generated"""
        return self.value

class TimeCtrlAccessorsMixin:
    """
    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',

         'useFixedWidthFont',
         'emptyBackgroundColour',
         'validBackgroundColour',
         'invalidBackgroundColour',

         'validFunc',
         'validRequired',
        )
    for param in exposed_basectrl_params:
        propname = param[0].upper() + param[1:]
        exec('def Set%s(self, value): self.SetCtrlParameters(%s=value)' % (propname, param))
        exec('def Get%s(self): return self.GetCtrlParameter("%s")''' % (propname, param))

        if param.find('Colour') != -1:
            # add non-british spellings, for backward-compatibility
            propname.replace('Colour', 'Color')

            exec('def Set%s(self, value): self.SetCtrlParameters(%s=value)' % (propname, param))
            exec('def Get%s(self): return self.GetCtrlParameter("%s")''' % (propname, param))


class TimeCtrl(BaseMaskedTextCtrl):
    """
    Masked control providing several time formats and manipulation of time values.
    """

    valid_ctrl_params = {
        'format' :  'HHMMSS',       # default format code
        'displaySeconds' : True,    # by default, shows seconds
        'min': None,                # by default, no bounds set
        'max': None,