maskededit.py

Wxpython Implemented on Windows CE, Source code

#----------------------------------------------------------------------------
# Name:         maskededit.py
# Authors:      Jeff Childers, Will Sadkin
# Email:        [e-mail], [e-mail]
# Created:      02/11/2003
# Copyright:    (c) 2003 by Jeff Childers, Will Sadkin, 2003
# Portions:     (c) 2002 by Will Sadkin, 2002-2003
# RCS-ID:       $Id: maskededit.py,v 1.18 2006/06/10 22:13:21 RD Exp $
# License:      wxWindows license
#----------------------------------------------------------------------------
# NOTE:
#   MaskedEdit controls are based on a suggestion made on [wxPython-Users] by
#   Jason Hihn, and borrows liberally from Will Sadkin's original masked edit
#   control for time entry, TimeCtrl (which is now rewritten using this
#   control!).
#
#   MaskedEdit controls do not normally use validators, because they do
#   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.  However, validators can be
#   provided to do data transfer to the controls.
#
#----------------------------------------------------------------------------
#
# This file now contains the bulk of the logic behind all masked controls,
# the MaskedEditMixin class, the Field class, and the autoformat codes.
#
#----------------------------------------------------------------------------
#
# 03/30/2004 - Will Sadkin ([e-mail])
#
# o Split out TextCtrl, ComboBox and IpAddrCtrl into their own files,
# o Reorganized code into masked package
#
# 12/09/2003 - Jeff Grimmett ([e-mail])
#
# o Updated for wx namespace. No guarantees. This is one huge file.
#
# 12/13/2003 - Jeff Grimmett ([e-mail])
#
# o Missed wx.DateTime stuff earlier.
#
# 12/20/2003 - Jeff Grimmett ([e-mail])
#
# o MaskedEditMixin -> MaskedEditMixin
# o wxMaskedTextCtrl -> maskedTextCtrl
# o wxMaskedComboBoxSelectEvent -> MaskedComboBoxSelectEvent
# o wxMaskedComboBox -> MaskedComboBox
# o wxIpAddrCtrl -> IpAddrCtrl
# o wxTimeCtrl -> TimeCtrl
#

"""\
====================
Masked Edit Overview
====================

masked.TextCtrl:
    is a sublassed text control that can carefully control the user's input
    based on a mask string you provide.

    General usage example::

        control = masked.TextCtrl( win, -1, '', mask = '(###) ###-####')

    The example above will create a text control that allows only numbers to be
    entered and then only in the positions indicated in the mask by the # sign.

masked.ComboBox:
    is a similar subclass of wxComboBox that allows the same sort of masking,
    but also can do auto-complete of values, and can require the value typed
    to be in the list of choices to be colored appropriately.

masked.Ctrl:
    is actually a factory function for several types of masked edit controls:

    =================   ==================================================
    masked.TextCtrl     standard masked edit text box
    masked.ComboBox     adds combobox capabilities
    masked.IpAddrCtrl   adds special semantics for IP address entry
    masked.TimeCtrl     special subclass handling lots of types as values
    masked.NumCtrl      special subclass handling numeric values
    =================   ==================================================

    It works by looking for a *controlType* parameter in the keyword
    arguments of the control, to determine what kind of instance to return.
    If not specified as a keyword argument, the default control type returned
    will be masked.TextCtrl.

    Each of the above classes has its own set of arguments, but masked.Ctrl
    provides a single "unified" interface for masked controls.  Those for
    masked.TextCtrl, masked.ComboBox and masked.IpAddrCtrl are all documented
    below; the others have their own demo pages and interface descriptions.
    (See end of following discussion for how to configure the wx.MaskedCtrl()
    to select the above control types.)

=========================

Initialization Parameters
-------------------------
mask
    Allowed mask characters and function:

    =========  ==========================================================
    Character   Function
    =========  ==========================================================
        #       Allow numeric only (0-9)
        N       Allow letters and numbers (0-9)
        A       Allow uppercase letters only
        a       Allow lowercase letters only
        C       Allow any letter, upper or lower
        X       Allow string.letters, string.punctuation, string.digits
        &       Allow string.punctuation only
        \*       Allow any ansi character
    =========  ==========================================================


    These controls define these sets of characters using string.letters,
    string.uppercase, etc.  These sets are affected by the system locale
    setting, so in order to have the masked controls accept characters
    that are specific to your users' language, your application should
    set the locale.
    For example, to allow international characters to be used in the
    above masks, you can place the following in your code as part of
    your application's initialization code::

      import locale
      locale.setlocale(locale.LC_ALL, '')

    The controls now also support (by popular demand) all "ansi" chars,
    that is, all ascii codes between 32 and 255, by use of the * mask character.

  Using these mask characters, a variety of template masks can be built. See
  the demo for some other common examples include date+time, social security
  number, etc.  If any of these characters are needed as template rather
  than mask characters, they can be escaped with \, ie. \N means "literal N".
  (use \\ for literal backslash, as in: r'CCC\\NNN'.)


  *Note:*
      Masks containing only # characters and one optional decimal point
      character are handled specially, as "numeric" controls.  Such
      controls have special handling for typing the '-' key, handling
      the "decimal point" character as truncating the integer portion,
      optionally allowing grouping characters and so forth.
      There are several parameters and format codes that only make sense
      when combined with such masks, eg. groupChar, decimalChar, and so
      forth (see below).  These allow you to construct reasonable
      numeric entry controls.

  *Note:*
      Changing the mask for a control deletes any previous field classes
      (and any associated validation or formatting constraints) for them.

useFixedWidthFont
  By default, masked edit controls use a fixed width font, so that
  the mask characters are fixed within the control, regardless of
  subsequent modifications to the value.  Set to False if having
  the control font be the same as other controls is required. (This is
  a control-level parameter.)

defaultEncoding
  (Applies to unicode systems only) By default, the default unicode encoding
  used is latin1, or iso-8859-1.  If necessary, you can set this control-level
  parameter to govern the codec used to decode your keyboard inputs.
  (This is a control-level parameter.)

formatcodes
  These other properties can be passed to the class when instantiating it:
    Formatcodes are specified as a string of single character formatting
    codes that modify  behavior of the control::
    
            _  Allow spaces
            !  Force upper
            ^  Force lower
            R  Right-align field(s)
            r  Right-insert in field(s) (implies R)
            <  Stay in field until explicit navigation out of it

            >  Allow insert/delete within partially filled fields (as
               opposed to the default "overwrite" mode for fixed-width
               masked edit controls.)  This allows single-field controls
               or each field within a multi-field control to optionally
               behave more like standard text controls.
               (See EMAIL or phone number autoformat examples.)

               *Note: This also governs whether backspace/delete operations
               shift contents of field to right of cursor, or just blank the
               erased section.

               Also, when combined with 'r', this indicates that the field
               or control allows right insert anywhere within the current
               non-empty value in the field.  (Otherwise right-insert behavior
               is only performed to when the entire right-insertable field is
               selected or the cursor is at the right edge of the field.*


            ,  Allow grouping character in integer fields of numeric controls
               and auto-group/regroup digits (if the result fits) when leaving
               such a field.  (If specified, .SetValue() will attempt to
               auto-group as well.)
               ',' is also the default grouping character.  To change the
               grouping character and/or decimal character, use the groupChar
               and decimalChar parameters, respectively.
               Note: typing the "decimal point" character in such fields will
               clip the value to that left of the cursor for integer
               fields of controls with "integer" or "floating point" masks.
               If the ',' format code is specified, this will also cause the
               resulting digits to be regrouped properly, using the current
               grouping character.
            -  Prepend and reserve leading space for sign to mask and allow
               signed values (negative #s shown in red by default.) Can be
               used with argument useParensForNegatives (see below.)
            0  integer fields get leading zeros
            D  Date[/time] field
            T  Time field
            F  Auto-Fit: the control calulates its size from
               the length of the template mask
            V  validate entered chars against validRegex before allowing them
               to be entered vs. being allowed by basic mask and then having
               the resulting value just colored as invalid.
               (See USSTATE autoformat demo for how this can be used.)
            S  select entire field when navigating to new field

fillChar

defaultValue
  These controls have two options for the initial state of the control.
  If a blank control with just the non-editable characters showing
  is desired, simply leave the constructor variable fillChar as its
  default (' ').  If you want some other character there, simply
  change the fillChar to that value.  Note: changing the control's fillChar
  will implicitly reset all of the fields' fillChars to this value.

  If you need different default characters in each mask position,
  you can specify a defaultValue parameter in the constructor, or
  set them for each field individually.
  This value must satisfy the non-editable characters of the mask,
  but need not conform to the replaceable characters.

groupChar

decimalChar
  These parameters govern what character is used to group numbers
  and is used to indicate the decimal point for numeric format controls.
  The default groupChar is ',', the default decimalChar is '.'
  By changing these, you can customize the presentation of numbers
  for your location.

  Eg::

        formatcodes = ',', groupChar='\''                  allows  12'345.34
        formatcodes = ',', groupChar='.', decimalChar=','  allows  12.345,34

  (These are control-level parameters.)

shiftDecimalChar
  The default "shiftDecimalChar" (used for "backwards-tabbing" until
  shift-tab is fixed in wxPython) is '>' (for QUERTY keyboards.) for
  other keyboards, you may want to customize this, eg '?' for shift ',' on
  AZERTY keyboards, ':' or ';' for other European keyboards, etc.
  (This is a control-level parameter.)

useParensForNegatives=False
  This option can be used with signed numeric format controls to
  indicate signs via () rather than '-'.
  (This is a control-level parameter.)

autoSelect=False
  This option can be used to have a field or the control try to
  auto-complete on each keystroke if choices have been specified.