numctrl.py

Wxpython Implemented on Windows CE, Source code

#----------------------------------------------------------------------------
# Name:         wxPython.lib.masked.numctrl.py
# Author:       Will Sadkin
# Created:      09/06/2003
# Copyright:   (c) 2003 by Will Sadkin
# RCS-ID:      $Id: numctrl.py,v 1.6 2006/06/10 22:13:21 RD Exp $
# License:     wxWidgets license
#----------------------------------------------------------------------------
# NOTE:
#   This was written to provide a numeric edit control for wxPython that
#   does things like right-insert (like a calculator), and does grouping, etc.
#   (ie. the features of masked.TextCtrl), but allows Get/Set of numeric
#   values, rather than text.
#
#   Masked.NumCtrl permits integer, and floating point values to be set
#   retrieved or set via .GetValue() and .SetValue() (type chosen based on
#   fraction width, and provides an masked.EVT_NUM() event function for trapping
#   changes to the control.
#
#   It supports negative numbers as well as the naturals, and has the option
#   of not permitting leading zeros or an empty control; if an empty value is
#   not allowed, attempting to delete the contents of the control will result
#   in a (selected) value of zero, thus preserving a legitimate numeric value.
#   Similarly, replacing the contents of the control with '-' will result in
#   a selected (absolute) value of -1.
#
#   masked.NumCtrl also supports range limits, with the option of either
#   enforcing them or simply coloring the text of the control if the limits
#   are exceeded.
#
#   masked.NumCtrl is intended to support fixed-point numeric entry, and
#   is derived from BaseMaskedTextCtrl.  As such, it supports a limited range
#   of values to comply with a fixed-width entry mask.
#----------------------------------------------------------------------------
# 12/09/2003 - Jeff Grimmett ([e-mail])
#
# o Updated for wx namespace
#
# 12/20/2003 - Jeff Grimmett ([e-mail])
#
# o wxMaskedEditMixin -> MaskedEditMixin
# o wxMaskedTextCtrl -> masked.TextCtrl
# o wxMaskedNumNumberUpdatedEvent -> masked.NumberUpdatedEvent
# o wxMaskedNumCtrl -> masked.NumCtrl
#

"""
masked.NumCtrl:
  - allows you to get and set integer or floating point numbers as value,</LI>
  - provides bounds support and optional value limiting,</LI>
  - has the right-insert input style that MaskedTextCtrl supports,</LI>
  - provides optional automatic grouping, sign control and format, grouping and decimal
    character selection, etc. etc.</LI>


  Being derived from masked.TextCtrl, the control only allows
  fixed-point  notation.  That is, it has a fixed (though reconfigurable)
  maximum width for the integer portion and optional fixed width
  fractional portion.

  Here's the API::

        from wx.lib.masked import NumCtrl

        NumCtrl(
             parent, id = -1,
             value = 0,
             pos = wx.DefaultPosition,
             size = wx.DefaultSize,
             style = 0,
             validator = wx.DefaultValidator,
             name = "masked.number",
             integerWidth = 10,
             fractionWidth = 0,
             allowNone = False,
             allowNegative = True,
             useParensForNegatives = False,
             groupDigits = False,
             groupChar = ',',
             decimalChar = '.',
             min = None,
             max = None,
             limited = False,
             selectOnEntry = True,
             foregroundColour = "Black",
             signedForegroundColour = "Red",
             emptyBackgroundColour = "White",
             validBackgroundColour = "White",
             invalidBackgroundColour = "Yellow",
             autoSize = True
             )


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

  integerWidth
        Indicates how many places to the right of any decimal point
        should be allowed in the control.  This will, perforce, limit
        the size of the values that can be entered. This number need
        not include space for grouping characters or the sign, if either
        of these options are enabled, as the resulting underlying
        mask is automatically by the control.  The default of 10
        will allow any 32 bit integer value.  The minimum value
        for integerWidth is 1.

  fractionWidth
        Indicates how many decimal places to show for numeric value.
        If default (0), then the control will display and return only
        integer or long values.

  allowNone
        Boolean indicating whether or not the control is allowed to be
        empty, representing a value of None for the control.
        
  allowNegative
        Boolean indicating whether or not control is allowed to hold
        negative numbers.

  useParensForNegatives
        If true, this will cause negative numbers to be displayed with ()s
        rather than -, (although '-' will still trigger a negative number.)

  groupDigits
        Indicates whether or not grouping characters should be allowed and/or
        inserted when leaving the control or the decimal character is entered.

  groupChar
        What grouping character will be used if allowed. (By default ',')

  decimalChar
        If fractionWidth is > 0, what character will be used to represent
        the decimal point.  (By default '.')

  min
        The minimum value that the control should allow.  This can be also be
        adjusted with SetMin().  If the control is not limited, any value
        below this bound will result in a background colored with the current
        invalidBackgroundColour.  If the min specified will not fit into the
        control, the min setting will be ignored.

  max
        The maximum value that the control should allow.  This can be
        adjusted with SetMax().  If the control is not limited, any value
        above this bound will result in a background colored with the current
        invalidBackgroundColour.  If the max specified will not fit into the
        control, the max setting will be ignored.

  limited
        Boolean indicating whether the control prevents values from
        exceeding the currently set minimum and maximum values (bounds).
        If False and bounds are set, out-of-bounds values will
        result in a background colored with the current invalidBackgroundColour.

  selectOnEntry
        Boolean indicating whether or not the value in each field of the
        control should be automatically selected (for replacement) when
        that field is entered, either by cursor movement or tabbing.
        This can be desirable when using these controls for rapid data entry.

  foregroundColour
        Color value used for positive values of the control.

  signedForegroundColour
        Color value used for negative values of the control.

  emptyBackgroundColour
        What background color to use when the control is considered
        "empty." (allow_none must be set to trigger this behavior.)

  validBackgroundColour
        What background color to use when the control value is
        considered valid.

  invalidBackgroundColour
        Color value used for illegal values or values out-of-bounds of the
        control when the bounds are set but the control is not limited.

  autoSize
        Boolean indicating whether or not the control should set its own
        width based on the integer and fraction widths.  True by default.
        <I>Note:</I> Setting this to False will produce seemingly odd
        behavior unless the control is large enough to hold the maximum
        specified value given the widths and the sign positions; if not,
        the control will appear to "jump around" as the contents scroll.
        (ie. autoSize is highly recommended.)

--------------------------

masked.EVT_NUM(win, id, func)
    Respond to a EVT_COMMAND_MASKED_NUMBER_UPDATED event, generated when
    the value changes. Notice that this event will always be sent when the
    control's contents changes - whether this is due to user input or
    comes from the program itself (for example, if SetValue() is called.)


SetValue(int|long|float|string)
    Sets the value of the control to the value specified, if
    possible.  The resulting actual value of the control may be
    altered to conform to the format of the control, changed
    to conform with the bounds set on the control if limited,
    or colored if not limited but the value is out-of-bounds.
    A ValueError exception will be raised if an invalid value
    is specified.

GetValue()
    Retrieves the numeric value from the control.  The value
    retrieved will be either be returned as a long if the
    fractionWidth is 0, or a float otherwise.


SetParameters(\*\*kwargs)
    Allows simultaneous setting of various attributes
    of the control after construction.  Keyword arguments
    allowed are the same parameters as supported in the constructor.


SetIntegerWidth(value)
    Resets the width of the integer portion of the control.  The
    value must be >= 1, or an AttributeError exception will result.
    This value should account for any grouping characters that might
    be inserted (if grouping is enabled), but does not need to account
    for the sign, as that is handled separately by the control.
GetIntegerWidth()
    Returns the current width of the integer portion of the control,
    not including any reserved sign position.


SetFractionWidth(value)
    Resets the width of the fractional portion of the control.  The
    value must be >= 0, or an AttributeError exception will result.  If
    0, the current value of the control will be truncated to an integer
    value.
GetFractionWidth()
    Returns the current width of the fractional portion of the control.


SetMin(min=None)
    Resets the minimum value of the control.  If a value of <I>None</I>
    is provided, then the control will have no explicit minimum value.
    If the value specified is greater than the current maximum value,
    then the function returns False and the minimum will not change from
    its current setting.  On success, the function returns True.

    If successful and the current value is lower than the new lower
    bound, if the control is limited, the value will be automatically
    adjusted to the new minimum value; if not limited, the value in the
    control will be colored as invalid.

    If min > the max value allowed by the width of the control,
    the function will return False, and the min will not be set.

GetMin()
    Gets the current lower bound value for the control.
    It will return None if no lower bound is currently specified.


SetMax(max=None)
    Resets the maximum value of the control. If a value of <I>None</I>
    is provided, then the control will have no explicit maximum value.
    If the value specified is less than the current minimum value, then
    the function returns False and the maximum will not change from its
    current setting. On success, the function returns True.

    If successful and the current value is greater than the new upper
    bound, if the control is limited the value will be automatically
    adjusted to this maximum value; if not limited, the value in the
    control will be colored as invalid.

    If max > the max value allowed by the width of the control,
    the function will return False, and the max will not be set.

GetMax()
    Gets the current upper bound value for the control.
    It will return None if no upper bound is currently specified.


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.  <B><I>Note:</I> leaving out an argument
    will remove the corresponding bound.
GetBounds()
    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.


IsInBounds(value=None)
    Returns <I>True</I> 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.


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.
    If the control's value currently exceeds the bounds, it will then
    be limited accordingly.
    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.

GetLimited()

IsLimited()
    Returns <I>True</I> if the control is currently limiting the
    value to fall within the current bounds.