maskededit.py

Wxpython Implemented on Windows CE, Source code

autoCompleteKeycodes=[]
  By default, DownArrow, PageUp and PageDown will auto-complete a
  partially entered field.  Shift-DownArrow, Shift-UpArrow, PageUp
  and PageDown will also auto-complete, but if the field already
  contains a matched value, these keys will cycle through the list
  of choices forward or backward as appropriate.  Shift-Up and
  Shift-Down also take you to the next/previous field after any
  auto-complete action.

  Additional auto-complete keys can be specified via this parameter.
  Any keys so specified will act like PageDown.
  (This is a control-level parameter.)



Validating User Input
=====================
There are a variety of initialization parameters that are used to validate
user input.  These parameters can apply to the control as a whole, and/or
to individual fields:

        =====================  ==================================================================
        excludeChars           A string of characters to exclude even if otherwise allowed
        includeChars           A string of characters to allow even if otherwise disallowed
        validRegex             Use a regular expression to validate the contents of the text box
        validRange             Pass a rangeas list (low,high) to limit numeric fields/values
        choices                A list of strings that are allowed choices for the control.
        choiceRequired         value must be member of choices list
        compareNoCase          Perform case-insensitive matching when validating against list
                               *Note: for masked.ComboBox, this defaults to True.*
        emptyInvalid           Boolean indicating whether an empty value should be considered 
                               invalid

        validFunc              A function to call of the form: bool = func(candidate_value)
                               which will return True if the candidate_value satisfies some
                               external criteria for the control in addition to the the
                               other validation, or False if not.  (This validation is
                               applied last in the chain of validations.)

        validRequired          Boolean indicating whether or not keys that are allowed by the
                               mask, but result in an invalid value are allowed to be entered
                               into the control.  Setting this to True implies that a valid
                               default value is set for the control.

        retainFieldValidation  False by default; if True, this allows individual fields to
                               retain their own validation constraints independently of any
                               subsequent changes to the control's overall parameters.
                               (This is a control-level parameter.)

        validator              Validators are not normally needed for masked controls, because
                               of the nature of the validation and control of input.  However,
                               you can supply one to provide data transfer routines for the
                               controls.
        =====================  ==================================================================


Coloring Behavior
=================
  The following parameters have been provided to allow you to change the default
  coloring behavior of the control.   These can be set at construction, or via
  the .SetCtrlParameters() function.  Pass a color as string e.g. 'Yellow':

        ========================  =======================================================================
        emptyBackgroundColour      Control Background color when identified as empty. Default=White
        invalidBackgroundColour    Control Background color when identified as Not valid. Default=Yellow
        validBackgroundColour      Control Background color when identified as Valid. Default=white
        ========================  =======================================================================


  The following parameters control the default foreground color coloring behavior of the
  control. Pass a color as string e.g. 'Yellow':

        ========================  ======================================================================
        foregroundColour           Control foreground color when value is not negative.  Default=Black
        signedForegroundColour     Control foreground color when value is negative. Default=Red
        ========================  ======================================================================


Fields
======
  Each part of the mask that allows user input is considered a field.  The fields
  are represented by their own class instances.  You can specify field-specific
  constraints by constructing or accessing the field instances for the control
  and then specifying those constraints via parameters.

fields
  This parameter allows you to specify Field instances containing
  constraints for the individual fields of a control, eg: local
  choice lists, validation rules, functions, regexps, etc.
  It can be either an ordered list or a dictionary.  If a list,
  the fields will be applied as fields 0, 1, 2, etc.
  If a dictionary, it should be keyed by field index.
  the values should be a instances of maskededit.Field.

  Any field not represented by the list or dictionary will be
  implicitly created by the control.

  Eg::

    fields = [ Field(formatcodes='_r'), Field('choices=['a', 'b', 'c']) ]
    
  Or::

    fields = {
               1: ( Field(formatcodes='_R', choices=['a', 'b', 'c']),
               3: ( Field(choices=['01', '02', '03'], choiceRequired=True)
             }

  The following parameters are available for individual fields, with the
  same semantics as for the whole control but applied to the field in question:

    ==============  =============================================================================
    fillChar        if set for a field, it will override the control's fillChar for that field
    groupChar       if set for a field, it will override the control's default
    defaultValue    sets field-specific default value; overrides any default from control
    compareNoCase   overrides control's settings
    emptyInvalid    determines whether field is required to be filled at all times
    validRequired   if set, requires field to contain valid value
    ==============  =============================================================================

  If any of the above parameters are subsequently specified for the control as a
  whole, that new value will be propagated to each field, unless the
  retainFieldValidation control-level parameter is set.

    ==============  ==============================
    formatcodes      Augments control's settings
    excludeChars         '       '        '
    includeChars         '       '        '
    validRegex           '       '        '
    validRange           '       '        '
    choices              '       '        '
    choiceRequired       '       '        '
    validFunc            '       '        '
    ==============  ==============================



Control Class Functions
=======================
.GetPlainValue(value=None)
                    Returns the value specified (or the control's text value
                    not specified) without the formatting text.
                    In the example above, might return phone no='3522640075',
                    whereas control.GetValue() would return '[phone]'
.ClearValue()
                    Returns the control's value to its default, and places the
                    cursor at the beginning of the control.
.SetValue()
                    Does "smart replacement" of passed value into the control, as does
                    the .Paste() method.  As with other text entry controls, the
                    .SetValue() text replacement begins at left-edge of the control,
                    with missing mask characters inserted as appropriate.
                    .SetValue will also adjust integer, float or date mask entry values,
                    adding commas, auto-completing years, etc. as appropriate.
                    For "right-aligned" numeric controls, it will also now automatically
                    right-adjust any value whose length is less than the width of the
                    control before attempting to set the value.
                    If a value does not follow the format of the control's mask, or will
                    not fit into the control, a ValueError exception will be raised.

                    Eg::

                      mask = '(###) ###-####'
                          .SetValue('1234567890')           => '[phone]'
                          .SetValue('(123)4567890')         => '[phone]'
                          .SetValue('[phone]')        => '[phone]'
                          .SetValue('123/4567-890')         => illegal paste; ValueError

                      mask = '#{6}.#{2}', formatcodes = '_,-',
                          .SetValue('111')                  => ' 111   .  '
                          .SetValue(' %9.2f' % -111.12345 ) => '   -111.12'
                          .SetValue(' %9.2f' % 1234.00 )    => '  1,234.00'
                          .SetValue(' %9.2f' % -1234567.12345 ) => insufficient room; ValueError

                      mask = '#{6}.#{2}', formatcodes = '_,-R'  # will right-adjust value for right-aligned control
                          .SetValue('111')                  => padded value misalignment ValueError: "       111" will not fit
                          .SetValue('%.2f' % 111 )          => '    111.00'
                          .SetValue('%.2f' % -111.12345 )   => '   -111.12'


.IsValid(value=None)
                    Returns True if the value specified (or the value of the control
                    if not specified) passes validation tests
.IsEmpty(value=None)
                    Returns True if the value specified (or the value of the control
                    if not specified) is equal to an "empty value," ie. all
                    editable characters == the fillChar for their respective fields.
.IsDefault(value=None)
                    Returns True if the value specified (or the value of the control
                    if not specified) is equal to the initial value of the control.

.Refresh()
                    Recolors the control as appropriate to its current settings.

.SetCtrlParameters(\*\*kwargs)
                    This function allows you to set up and/or change the control parameters
                    after construction; it takes a list of key/value pairs as arguments,
                    where the keys can be any of the mask-specific parameters in the constructor.

                    Eg::

                        ctl = masked.TextCtrl( self, -1 )
                        ctl.SetCtrlParameters( mask='###-####',
                                               defaultValue='555-1212',
                                               formatcodes='F')

.GetCtrlParameter(parametername)
                    This function allows you to retrieve the current value of a parameter
                    from the control.

  *Note:* Each of the control parameters can also be set using its
      own Set and Get function.  These functions follow a regular form:
      All of the parameter names start with lower case; for their
      corresponding Set/Get function, the parameter name is capitalized.

    Eg::

          ctl.SetMask('###-####')
          ctl.SetDefaultValue('555-1212')
          ctl.GetChoiceRequired()
          ctl.GetFormatcodes()

  *Note:* After any change in parameters, the choices for the
      control are reevaluated to ensure that they are still legal.  If you
      have large choice lists, it is therefore more efficient to set parameters
      before setting the choices available.

.SetFieldParameters(field_index, \*\*kwargs)
                    This function allows you to specify change individual field
                    parameters after construction. (Indices are 0-based.)

.GetFieldParameter(field_index, parametername)
                    Allows the retrieval of field parameters after construction


The control detects certain common constructions. In order to use the signed feature
(negative numbers and coloring), the mask has to be all numbers with optionally one
decimal point. Without a decimal (e.g. '######', the control will treat it as an integer
value. With a decimal (e.g. '###.##'), the control will act as a floating point control
(i.e. press decimal to 'tab' to the decimal position). Pressing decimal in the
integer control truncates the value.  However, for a true numeric control,
masked.NumCtrl provides all this, and true numeric input/output support as well.


Check your controls by calling each control's .IsValid() function and the
.IsEmpty() function to determine which controls have been a) filled in and
b) filled in properly.


Regular expression validations can be used flexibly and creatively.
Take a look at the demo; the zip-code validation succeeds as long as the
first five numerals are entered. the last four are optional, but if
any are entered, there must be 4 to be valid.

masked.Ctrl Configuration
=========================
masked.Ctrl works by looking for a special *controlType*
parameter in the variable arguments of the control, to determine
what kind of instance to return.
controlType can be one of::

    controlTypes.TEXT
    controlTypes.COMBO
    controlTypes.IPADDR
    controlTypes.TIME
    controlTypes.NUMBER

These constants are also available individually, ie, you can
use either of the following::

    from wxPython.wx.lib.masked import MaskedCtrl, controlTypes
    from wxPython.wx.lib.masked import MaskedCtrl, COMBO, TEXT, NUMBER, IPADDR