wxPython/wx/lib/masked/numctrl.py

   1 #----------------------------------------------------------------------------
   2 # Name:         wxPython.lib.masked.numctrl.py
   3 # Author:       Will Sadkin
   4 # Created:      09/06/2003
   5 # Copyright:   (c) 2003 by Will Sadkin
   6 # RCS-ID:      $Id$
   7 # License:     wxWidgets license
   8 #----------------------------------------------------------------------------
   9 # NOTE:
  10 #   This was written to provide a numeric edit control for wxPython that
  11 #   does things like right-insert (like a calculator), and does grouping, etc.
  12 #   (ie. the features of masked.TextCtrl), but allows Get/Set of numeric
  13 #   values, rather than text.
  14 #
  15 #   Masked.NumCtrl permits integer, and floating point values to be set
  16 #   retrieved or set via .GetValue() and .SetValue() (type chosen based on
  17 #   fraction width, and provides an masked.EVT_NUM() event function for trapping
  18 #   changes to the control.
  19 #
  20 #   It supports negative numbers as well as the naturals, and has the option
  21 #   of not permitting leading zeros or an empty control; if an empty value is
  22 #   not allowed, attempting to delete the contents of the control will result
  23 #   in a (selected) value of zero, thus preserving a legitimate numeric value.
  24 #   Similarly, replacing the contents of the control with '-' will result in
  25 #   a selected (absolute) value of -1.
  26 #
  27 #   masked.NumCtrl also supports range limits, with the option of either
  28 #   enforcing them or simply coloring the text of the control if the limits
  29 #   are exceeded.
  30 #
  31 #   masked.NumCtrl is intended to support fixed-point numeric entry, and
  32 #   is derived from BaseMaskedTextCtrl.  As such, it supports a limited range
  33 #   of values to comply with a fixed-width entry mask.
  34 #----------------------------------------------------------------------------
  35 # 12/09/2003 - Jeff Grimmett (grimmtooth@softhome.net)
  36 #
  37 # o Updated for wx namespace
  38 #
  39 # 12/20/2003 - Jeff Grimmett (grimmtooth@softhome.net)
  40 #
  41 # o wxMaskedEditMixin -> MaskedEditMixin
  42 # o wxMaskedTextCtrl -> masked.TextCtrl
  43 # o wxMaskedNumNumberUpdatedEvent -> masked.NumberUpdatedEvent
  44 # o wxMaskedNumCtrl -> masked.NumCtrl
  45 #
  46
  47 """<html><body>
  48 <P>
  49 <B>masked.NumCtrl:</B>
  50 <UL>
  51 <LI>allows you to get and set integer or floating point numbers as value,</LI>
  52 <LI>provides bounds support and optional value limiting,</LI>
  53 <LI>has the right-insert input style that MaskedTextCtrl supports,</LI>
  54 <LI>provides optional automatic grouping, sign control and format, grouping and decimal
  55 character selection, etc. etc.</LI>
  56 </UL>
  57 <P>
  58 Being derived from MaskedTextCtrl, the control only allows
  59 fixed-point  notation.  That is, it has a fixed (though reconfigurable)
  60 maximum width for the integer portion and optional fixed width
  61 fractional portion.
  62 <P>
  63 Here's the API:
  64 <DL><PRE>
  65     <B>masked.NumCtrl</B>(
  66          parent, id = -1,
  67          <B>value</B> = 0,
  68          pos = wx.DefaultPosition,
  69          size = wx.DefaultSize,
  70          style = 0,
  71          validator = wx.DefaultValidator,
  72          name = "masked.number",
  73          <B>integerWidth</B> = 10,
  74          <B>fractionWidth</B> = 0,
  75          <B>allowNone</B> = False,
  76          <B>allowNegative</B> = True,
  77          <B>useParensForNegatives</B> = False,
  78          <B>groupDigits</B> = False,
  79          <B>groupChar</B> = ',',
  80          <B>decimalChar</B> = '.',
  81          <B>min</B> = None,
  82          <B>max</B> = None,
  83          <B>limited</B> = False,
  84          <B>selectOnEntry</b> = True,
  85          <B>foregroundColour</B> = "Black",
  86          <B>signedForegroundColour</B> = "Red",
  87          <B>emptyBackgroundColour</B> = "White",
  88          <B>validBackgroundColour</B> = "White",
  89          <B>invalidBackgroundColour</B> = "Yellow",
  90          <B>autoSize</B> = True
  91          )
  92 </PRE>
  93 <UL>
  94     <DT><B>value</B>
  95     <DD>If no initial value is set, the default will be zero, or
  96         the minimum value, if specified.  If an illegal string is specified,
  97         a ValueError will result. (You can always later set the initial
  98         value with SetValue() after instantiation of the control.)
  99     <BR>
 100     <DL><B>integerWidth</B>
 101     <DD>Indicates how many places to the right of any decimal point
 102         should be allowed in the control.  This will, perforce, limit
 103         the size of the values that can be entered. This number need
 104         not include space for grouping characters or the sign, if either
 105         of these options are enabled, as the resulting underlying
 106         mask is automatically by the control.  The default of 10
 107         will allow any 32 bit integer value.  The minimum value
 108         for integerWidth is 1.
 109     <BR>
 110     <DL><B>fractionWidth</B>
 111     <DD>Indicates how many decimal places to show for numeric value.
 112         If default (0), then the control will display and return only
 113         integer or long values.
 114     <BR>
 115     <DT><B>allowNone</B>
 116     <DD>Boolean indicating whether or not the control is allowed to be
 117         empty, representing a value of None for the control.
 118     <BR>
 119     <DT><B>allowNegative</B>
 120     <DD>Boolean indicating whether or not control is allowed to hold
 121         negative numbers.
 122     <BR>
 123     <DT><B>useParensForNegatives</B>
 124     <DD>If true, this will cause negative numbers to be displayed with ()s
 125         rather than -, (although '-' will still trigger a negative number.)
 126     <BR>
 127     <DT><B>groupDigits</B>
 128     <DD>Indicates whether or not grouping characters should be allowed and/or
 129         inserted when leaving the control or the decimal character is entered.
 130     <BR>
 131     <DT><B>groupChar</B>
 132     <DD>What grouping character will be used if allowed. (By default ',')
 133     <BR>
 134     <DT><B>decimalChar</B>
 135     <DD>If fractionWidth is > 0, what character will be used to represent
 136         the decimal point.  (By default '.')
 137     <BR>
 138     <DL><B>min</B>
 139     <DD>The minimum value that the control should allow.  This can be also be
 140         adjusted with SetMin().  If the control is not limited, any value
 141         below this bound will result in a background colored with the current
 142         invalidBackgroundColour.  If the min specified will not fit into the
 143         control, the min setting will be ignored.
 144     <BR>
 145     <DT><B>max</B>
 146     <DD>The maximum value that the control should allow.  This can be
 147         adjusted with SetMax().  If the control is not limited, any value
 148         above this bound will result in a background colored with the current
 149         invalidBackgroundColour.  If the max specified will not fit into the
 150         control, the max setting will be ignored.
 151     <BR>
 152     <DT><B>limited</B>
 153     <DD>Boolean indicating whether the control prevents values from
 154         exceeding the currently set minimum and maximum values (bounds).
 155         If False and bounds are set, out-of-bounds values will
 156         result in a background colored with the current invalidBackgroundColour.
 157     <BR>
 158     <DT><B>selectOnEntry</B>
 159     <DD>Boolean indicating whether or not the value in each field of the
 160         control should be automatically selected (for replacement) when
 161         that field is entered, either by cursor movement or tabbing.
 162         This can be desirable when using these controls for rapid data entry.
 163     <BR>
 164     <DT><B>foregroundColour</B>
 165     <DD>Color value used for positive values of the control.
 166     <BR>
 167     <DT><B>signedForegroundColour</B>
 168     <DD>Color value used for negative values of the control.
 169     <BR>
 170     <DT><B>emptyBackgroundColour</B>
 171     <DD>What background color to use when the control is considered
 172         "empty." (allow_none must be set to trigger this behavior.)
 173     <BR>
 174     <DT><B>validBackgroundColour</B>
 175     <DD>What background color to use when the control value is
 176         considered valid.
 177     <BR>
 178     <DT><B>invalidBackgroundColour</B>
 179     <DD>Color value used for illegal values or values out-of-bounds of the
 180         control when the bounds are set but the control is not limited.
 181     <BR>
 182     <DT><B>autoSize</B>
 183     <DD>Boolean indicating whether or not the control should set its own
 184         width based on the integer and fraction widths.  True by default.
 185         <B><I>Note:</I></B> Setting this to False will produce seemingly odd
 186         behavior unless the control is large enough to hold the maximum
 187         specified value given the widths and the sign positions; if not,
 188         the control will appear to "jump around" as the contents scroll.
 189         (ie. autoSize is highly recommended.)
 190 </UL>
 191 <BR>
 192 <BR>
 193 <DT><B>masked.EVT_NUM(win, id, func)</B>
 194 <DD>Respond to a EVT_COMMAND_MASKED_NUMBER_UPDATED event, generated when
 195 the value changes. Notice that this event will always be sent when the
 196 control's contents changes - whether this is due to user input or
 197 comes from the program itself (for example, if SetValue() is called.)
 198 <BR>
 199 <BR>
 200 <DT><B>SetValue(int|long|float|string)</B>
 201 <DD>Sets the value of the control to the value specified, if
 202 possible.  The resulting actual value of the control may be
 203 altered to conform to the format of the control, changed
 204 to conform with the bounds set on the control if limited,
 205 or colored if not limited but the value is out-of-bounds.
 206 A ValueError exception will be raised if an invalid value
 207 is specified.
 208 <BR>
 209 <DT><B>GetValue()</B>
 210 <DD>Retrieves the numeric value from the control.  The value
 211 retrieved will be either be returned as a long if the
 212 fractionWidth is 0, or a float otherwise.
 213 <BR>
 214 <BR>
 215 <DT><B>SetParameters(**kwargs)</B>
 216 <DD>Allows simultaneous setting of various attributes
 217 of the control after construction.  Keyword arguments
 218 allowed are the same parameters as supported in the constructor.
 219 <BR>
 220 <BR>
 221 <DT><B>SetIntegerWidth(value)</B>
 222 <DD>Resets the width of the integer portion of the control.  The
 223 value must be >= 1, or an AttributeError exception will result.
 224 This value should account for any grouping characters that might
 225 be inserted (if grouping is enabled), but does not need to account
 226 for the sign, as that is handled separately by the control.
 227 <DT><B>GetIntegerWidth()</B>
 228 <DD>Returns the current width of the integer portion of the control,
 229 not including any reserved sign position.
 230 <BR>
 231 <BR>
 232 <DT><B>SetFractionWidth(value)</B>
 233 <DD>Resets the width of the fractional portion of the control.  The
 234 value must be >= 0, or an AttributeError exception will result.  If
 235 0, the current value of the control will be truncated to an integer
 236 value.
 237 <DT><B>GetFractionWidth()</B>
 238 <DD>Returns the current width of the fractional portion of the control.
 239 <BR>
 240 <BR>
 241 <DT><B>SetMin(min=None)</B>
 242 <DD>Resets the minimum value of the control.  If a value of <I>None</I>
 243 is provided, then the control will have no explicit minimum value.
 244 If the value specified is greater than the current maximum value,
 245 then the function returns False and the minimum will not change from
 246 its current setting.  On success, the function returns True.
 247 <DT><DD>
 248 If successful and the current value is lower than the new lower
 249 bound, if the control is limited, the value will be automatically
 250 adjusted to the new minimum value; if not limited, the value in the
 251 control will be colored as invalid.
 252 <DT><DD>
 253 If min > the max value allowed by the width of the control,
 254 the function will return False, and the min will not be set.
 255 <BR>
 256 <DT><B>GetMin()</B>
 257 <DD>Gets the current lower bound value for the control.
 258 It will return None if no lower bound is currently specified.
 259 <BR>
 260 <BR>
 261 <DT><B>SetMax(max=None)</B>
 262 <DD>Resets the maximum value of the control. If a value of <I>None</I>
 263 is provided, then the control will have no explicit maximum value.
 264 If the value specified is less than the current minimum value, then
 265 the function returns False and the maximum will not change from its
 266 current setting. On success, the function returns True.
 267 <DT><DD>
 268 If successful and the current value is greater than the new upper
 269 bound, if the control is limited the value will be automatically
 270 adjusted to this maximum value; if not limited, the value in the
 271 control will be colored as invalid.
 272 <DT><DD>
 273 If max > the max value allowed by the width of the control,
 274 the function will return False, and the max will not be set.
 275 <BR>
 276 <DT><B>GetMax()</B>
 277 <DD>Gets the current upper bound value for the control.
 278 It will return None if no upper bound is currently specified.
 279 <BR>
 280 <BR>
 281 <DT><B>SetBounds(min=None,max=None)</B>
 282 <DD>This function is a convenience function for setting the min and max
 283 values at the same time.  The function only applies the maximum bound
 284 if setting the minimum bound is successful, and returns True
 285 only if both operations succeed.  <B><I>Note:</I></B> leaving out an argument
 286 will remove the corresponding bound.
 287 <DT><B>GetBounds()</B>
 288 <DD>This function returns a two-tuple (min,max), indicating the
 289 current bounds of the control.  Each value can be None if
 290 that bound is not set.
 291 <BR>
 292 <BR>
 293 <DT><B>IsInBounds(value=None)</B>
 294 <DD>Returns <I>True</I> if no value is specified and the current value
 295 of the control falls within the current bounds.  This function can also
 296 be called with a value to see if that value would fall within the current
 297 bounds of the given control.
 298 <BR>
 299 <BR>
 300 <DT><B>SetLimited(bool)</B>
 301 <DD>If called with a value of True, this function will cause the control
 302 to limit the value to fall within the bounds currently specified.
 303 If the control's value currently exceeds the bounds, it will then
 304 be limited accordingly.
 305 If called with a value of False, this function will disable value
 306 limiting, but coloring of out-of-bounds values will still take
 307 place if bounds have been set for the control.
 308 <DT><B>GetLimited()</B>
 309 <DT><B>IsLimited()</B>
 310 <DD>Returns <I>True</I> if the control is currently limiting the
 311 value to fall within the current bounds.
 312 <BR>
 313 <BR>
 314 <DT><B>SetAllowNone(bool)</B>
 315 <DD>If called with a value of True, this function will cause the control
 316 to allow the value to be empty, representing a value of None.
 317 If called with a value of False, this function will prevent the value
 318 from being None.  If the value of the control is currently None,
 319 ie. the control is empty, then the value will be changed to that
 320 of the lower bound of the control, or 0 if no lower bound is set.
 321 <DT><B>GetAllowNone()</B>
 322 <DT><B>IsNoneAllowed()</B>
 323 <DD>Returns <I>True</I> if the control currently allows its
 324 value to be None.
 325 <BR>
 326 <BR>
 327 <DT><B>SetAllowNegative(bool)</B>
 328 <DD>If called with a value of True, this function will cause the
 329 control to allow the value to be negative (and reserve space for
 330 displaying the sign. If called with a value of False, and the
 331 value of the control is currently negative, the value of the
 332 control will be converted to the absolute value, and then
 333 limited appropriately based on the existing bounds of the control
 334 (if any).
 335 <DT><B>GetAllowNegative()</B>
 336 <DT><B>IsNegativeAllowed()</B>
 337 <DD>Returns <I>True</I> if the control currently permits values
 338 to be negative.
 339 <BR>
 340 <BR>
 341 <DT><B>SetGroupDigits(bool)</B>
 342 <DD>If called with a value of True, this will make the control
 343 automatically add and manage grouping characters to the presented
 344 value in integer portion of the control.
 345 <DT><B>GetGroupDigits()</B>
 346 <DT><B>IsGroupingAllowed()</B>
 347 <DD>Returns <I>True</I> if the control is currently set to group digits.
 348 <BR>
 349 <BR>
 350 <DT><B>SetGroupChar()</B>
 351 <DD>Sets the grouping character for the integer portion of the
 352 control.  (The default grouping character this is ','.
 353 <DT><B>GetGroupChar()</B>
 354 <DD>Returns the current grouping character for the control.
 355 <BR>
 356 <BR>
 357 <DT><B>SetSelectOnEntry()</B>
 358 <DD>If called with a value of <I>True</I>, this will make the control
 359 automatically select the contents of each field as it is entered
 360 within the control.  (The default is True.)
 361 <DT><B>GetSelectOnEntry()</B>
 362 <DD>Returns <I>True</I> if the control currently auto selects
 363 the field values on entry.
 364 <BR>
 365 <BR>
 366 <DT><B>SetAutoSize(bool)</B>
 367 <DD>Resets the autoSize attribute of the control.
 368 <DT><B>GetAutoSize()</B>
 369 <DD>Returns the current state of the autoSize attribute for the control.
 370 <BR>
 371 <BR>
 372 </DL>
 373 </body></html>
 374 """
 375
 376 import  copy
 377 import  string
 378 import  types
 379
 380 import  wx
 381
 382 from sys import maxint
 383 MAXINT = maxint     # (constants should be in upper case)
 384 MININT = -maxint-1
 385
 386 from wx.tools.dbg import Logger
 387 from wx.lib.masked import MaskedEditMixin, Field, BaseMaskedTextCtrl
 388 dbg = Logger()
 389 ##dbg(enable=0)
 390
 391 #----------------------------------------------------------------------------
 392
 393 wxEVT_COMMAND_MASKED_NUMBER_UPDATED = wx.NewEventType()
 394 EVT_NUM = wx.PyEventBinder(wxEVT_COMMAND_MASKED_NUMBER_UPDATED, 1)
 395
 396 #----------------------------------------------------------------------------
 397
 398 class NumberUpdatedEvent(wx.PyCommandEvent):
 399     def __init__(self, id, value = 0, object=None):
 400         wx.PyCommandEvent.__init__(self, wxEVT_COMMAND_MASKED_NUMBER_UPDATED, id)
 401
 402         self.__value = value
 403         self.SetEventObject(object)
 404
 405     def GetValue(self):
 406         """Retrieve the value of the control at the time
 407         this event was generated."""
 408         return self.__value
 409
 410
 411 #----------------------------------------------------------------------------
 412 class NumCtrlAccessorsMixin:
 413     # Define masked.NumCtrl's list of attributes having their own
 414     # Get/Set functions, ignoring those that make no sense for
 415     # an numeric control.
 416     exposed_basectrl_params = (
 417          'decimalChar',
 418          'shiftDecimalChar',
 419          'groupChar',
 420          'useParensForNegatives',
 421          'defaultValue',
 422          'description',
 423
 424          'useFixedWidthFont',
 425          'autoSize',
 426          'signedForegroundColour',
 427          'emptyBackgroundColour',
 428          'validBackgroundColour',
 429          'invalidBackgroundColour',
 430
 431          'emptyInvalid',
 432          'validFunc',
 433          'validRequired',
 434         )
 435     for param in exposed_basectrl_params:
 436         propname = param[0].upper() + param[1:]
 437         exec('def Set%s(self, value): self.SetCtrlParameters(%s=value)' % (propname, param))
 438         exec('def Get%s(self): return self.GetCtrlParameter("%s")''' % (propname, param))
 439
 440         if param.find('Colour') != -1:
 441             # add non-british spellings, for backward-compatibility
 442             propname.replace('Colour', 'Color')
 443
 444             exec('def Set%s(self, value): self.SetCtrlParameters(%s=value)' % (propname, param))
 445             exec('def Get%s(self): return self.GetCtrlParameter("%s")''' % (propname, param))
 446
 447
 448
 449 #----------------------------------------------------------------------------
 450
 451 class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin):
 452
 453
 454     valid_ctrl_params = {
 455         'integerWidth': 10,                 # by default allow all 32-bit integers
 456         'fractionWidth': 0,                 # by default, use integers
 457         'decimalChar': '.',                 # by default, use '.' for decimal point
 458         'allowNegative': True,              # by default, allow negative numbers
 459         'useParensForNegatives': False,     # by default, use '-' to indicate negatives
 460         'groupDigits': True,                # by default, don't insert grouping
 461         'groupChar': ',',                   # by default, use ',' for grouping
 462         'min': None,                        # by default, no bounds set
 463         'max': None,
 464         'limited': False,                   # by default, no limiting even if bounds set
 465         'allowNone': False,                 # by default, don't allow empty value
 466         'selectOnEntry': True,              # by default, select the value of each field on entry
 467         'foregroundColour': "Black",
 468         'signedForegroundColour': "Red",
 469         'emptyBackgroundColour': "White",
 470         'validBackgroundColour': "White",
 471         'invalidBackgroundColour': "Yellow",
 472         'useFixedWidthFont': True,          # by default, use a fixed-width font
 473         'autoSize': True,                   # by default, set the width of the control based on the mask
 474         }
 475
 476
 477     def __init__ (
 478                 self, parent, id=-1, value = 0,
 479                 pos = wx.DefaultPosition, size = wx.DefaultSize,
 480                 style = wx.TE_PROCESS_TAB, validator = wx.DefaultValidator,
 481                 name = "masked.num",
 482                 **kwargs ):
 483
 484 ##        dbg('masked.NumCtrl::__init__', indent=1)
 485
 486         # Set defaults for control:
 487 ##        dbg('setting defaults:')
 488         for key, param_value in NumCtrl.valid_ctrl_params.items():
 489             # This is done this way to make setattr behave consistently with
 490             # "private attribute" name mangling
 491             setattr(self, '_' + key, copy.copy(param_value))
 492
 493         # Assign defaults for all attributes:
 494         init_args = copy.deepcopy(NumCtrl.valid_ctrl_params)
 495 ##        dbg('kwargs:', kwargs)
 496         for key, param_value in kwargs.items():
 497             key = key.replace('Color', 'Colour')
 498             if key not in NumCtrl.valid_ctrl_params.keys():
 499                 raise AttributeError('invalid keyword argument "%s"' % key)
 500             else:
 501                 init_args[key] = param_value
 502 ##        dbg('init_args:', indent=1)
 503         for key, param_value in init_args.items():
 504 ##            dbg('%s:' % key, param_value)
 505             pass
 506 ##        dbg(indent=0)
 507
 508         # Process initial fields for the control, as part of construction:
 509         if type(init_args['integerWidth']) != types.IntType:
 510             raise AttributeError('invalid integerWidth (%s) specified; expected integer' % repr(init_args['integerWidth']))
 511         elif init_args['integerWidth'] < 1:
 512             raise AttributeError('invalid integerWidth (%s) specified; must be > 0' % repr(init_args['integerWidth']))
 513
 514         fields = {}
 515
 516         if init_args.has_key('fractionWidth'):
 517             if type(init_args['fractionWidth']) != types.IntType:
 518                 raise AttributeError('invalid fractionWidth (%s) specified; expected integer' % repr(self._fractionWidth))
 519             elif init_args['fractionWidth'] < 0:
 520                 raise AttributeError('invalid fractionWidth (%s) specified; must be >= 0' % repr(init_args['fractionWidth']))
 521             self._fractionWidth = init_args['fractionWidth']
 522
 523         if self._fractionWidth:
 524             fracmask = '.' + '#{%d}' % self._fractionWidth
 525 ##            dbg('fracmask:', fracmask)
 526             fields[1] = Field(defaultValue='0'*self._fractionWidth)
 527         else:
 528             fracmask = ''
 529
 530         self._integerWidth = init_args['integerWidth']
 531         if init_args['groupDigits']:
 532             self._groupSpace = (self._integerWidth - 1) / 3
 533         else:
 534             self._groupSpace = 0
 535         intmask = '#{%d}' % (self._integerWidth + self._groupSpace)
 536         if self._fractionWidth:
 537             emptyInvalid = False
 538         else:
 539             emptyInvalid = True
 540         fields[0] = Field(formatcodes='r<>', emptyInvalid=emptyInvalid)
 541 ##        dbg('intmask:', intmask)
 542
 543         # don't bother to reprocess these arguments:
 544         del init_args['integerWidth']
 545         del init_args['fractionWidth']
 546
 547         self._autoSize = init_args['autoSize']
 548         if self._autoSize:
 549             formatcodes = 'FR<'
 550         else:
 551             formatcodes = 'R<'
 552
 553
 554         mask = intmask+fracmask
 555
 556         # initial value of state vars
 557         self._oldvalue = 0
 558         self._integerEnd = 0
 559         self._typedSign = False
 560
 561         # Construct the base control:
 562         BaseMaskedTextCtrl.__init__(
 563                 self, parent, id, '',
 564                 pos, size, style, validator, name,
 565                 mask = mask,
 566                 formatcodes = formatcodes,
 567                 fields = fields,
 568                 validFunc=self.IsInBounds,
 569                 setupEventHandling = False)
 570
 571         self.Bind(wx.EVT_SET_FOCUS, self._OnFocus )        ## defeat automatic full selection
 572         self.Bind(wx.EVT_KILL_FOCUS, self._OnKillFocus )   ## run internal validator
 573         self.Bind(wx.EVT_LEFT_DCLICK, self._OnDoubleClick)  ## select field under cursor on dclick
 574         self.Bind(wx.EVT_RIGHT_UP, self._OnContextMenu )    ## bring up an appropriate context menu
 575         self.Bind(wx.EVT_KEY_DOWN, self._OnKeyDown )       ## capture control events not normally seen, eg ctrl-tab.
 576         self.Bind(wx.EVT_CHAR, self._OnChar )              ## handle each keypress
 577         self.Bind(wx.EVT_TEXT, self.OnTextChange )      ## color control appropriately & keep
 578                                                            ## track of previous value for undo
 579
 580         # Establish any additional parameters, with appropriate error checking
 581         self.SetParameters(**init_args)
 582
 583         # Set the value requested (if possible)
 584 ##        wxCallAfter(self.SetValue, value)
 585         self.SetValue(value)
 586
 587         # Ensure proper coloring:
 588         self.Refresh()
 589 ##        dbg('finished NumCtrl::__init__', indent=0)
 590
 591
 592     def SetParameters(self, **kwargs):
 593         """
 594         This routine is used to initialize and reconfigure the control:
 595         """
 596 ##        dbg('NumCtrl::SetParameters', indent=1)
 597         maskededit_kwargs = {}
 598         reset_fraction_width = False
 599
 600
 601         if( (kwargs.has_key('integerWidth') and kwargs['integerWidth'] != self._integerWidth)
 602             or (kwargs.has_key('fractionWidth') and kwargs['fractionWidth'] != self._fractionWidth)
 603             or (kwargs.has_key('groupDigits') and kwargs['groupDigits'] != self._groupDigits)
 604             or (kwargs.has_key('autoSize') and kwargs['autoSize'] != self._autoSize) ):
 605
 606             fields = {}
 607
 608             if kwargs.has_key('fractionWidth'):
 609                 if type(kwargs['fractionWidth']) != types.IntType:
 610                     raise AttributeError('invalid fractionWidth (%s) specified; expected integer' % repr(kwargs['fractionWidth']))
 611                 elif kwargs['fractionWidth'] < 0:
 612                     raise AttributeError('invalid fractionWidth (%s) specified; must be >= 0' % repr(kwargs['fractionWidth']))
 613                 else:
 614                     if self._fractionWidth != kwargs['fractionWidth']:
 615                         self._fractionWidth = kwargs['fractionWidth']
 616
 617             if self._fractionWidth:
 618                 fracmask = '.' + '#{%d}' % self._fractionWidth
 619                 fields[1] = Field(defaultValue='0'*self._fractionWidth)
 620                 emptyInvalid = False
 621             else:
 622                 emptyInvalid = True
 623                 fracmask = ''
 624 ##            dbg('fracmask:', fracmask)
 625
 626             if kwargs.has_key('integerWidth'):
 627                 if type(kwargs['integerWidth']) != types.IntType:
 628 ##                    dbg(indent=0)
 629                     raise AttributeError('invalid integerWidth (%s) specified; expected integer' % repr(kwargs['integerWidth']))
 630                 elif kwargs['integerWidth'] < 0:
 631 ##                    dbg(indent=0)
 632                     raise AttributeError('invalid integerWidth (%s) specified; must be > 0' % repr(kwargs['integerWidth']))
 633                 else:
 634                     self._integerWidth = kwargs['integerWidth']
 635
 636             if kwargs.has_key('groupDigits'):
 637                 self._groupDigits = kwargs['groupDigits']
 638
 639             if self._groupDigits:
 640                 self._groupSpace = (self._integerWidth - 1) / 3
 641             else:
 642                 self._groupSpace = 0
 643
 644             intmask = '#{%d}' % (self._integerWidth + self._groupSpace)
 645 ##            dbg('intmask:', intmask)
 646             fields[0] = Field(formatcodes='r<>', emptyInvalid=emptyInvalid)
 647             maskededit_kwargs['fields'] = fields
 648
 649             # don't bother to reprocess these arguments:
 650             if kwargs.has_key('integerWidth'):
 651                 del kwargs['integerWidth']
 652             if kwargs.has_key('fractionWidth'):
 653                 del kwargs['fractionWidth']
 654
 655             maskededit_kwargs['mask'] = intmask+fracmask
 656
 657         if kwargs.has_key('groupChar'):
 658             old_groupchar = self._groupChar     # save so we can reformat properly
 659 ##            dbg("old_groupchar: '%s'" % old_groupchar)
 660             maskededit_kwargs['groupChar'] = kwargs['groupChar']
 661         if kwargs.has_key('decimalChar'):
 662             old_decimalchar = self._decimalChar
 663 ##            dbg("old_decimalchar: '%s'" % old_decimalchar)
 664             maskededit_kwargs['decimalChar'] = kwargs['decimalChar']
 665
 666         # for all other parameters, assign keyword args as appropriate:
 667         for key, param_value in kwargs.items():
 668             key = key.replace('Color', 'Colour')
 669             if key not in NumCtrl.valid_ctrl_params.keys():
 670                 raise AttributeError('invalid keyword argument "%s"' % key)
 671             elif key not in MaskedEditMixin.valid_ctrl_params.keys():
 672                 setattr(self, '_' + key, param_value)
 673             elif key in ('mask', 'autoformat'): # disallow explicit setting of mask
 674                 raise AttributeError('invalid keyword argument "%s"' % key)
 675             else:
 676                 maskededit_kwargs[key] = param_value
 677 ##        dbg('kwargs:', kwargs)
 678
 679         # reprocess existing format codes to ensure proper resulting format:
 680         formatcodes = self.GetCtrlParameter('formatcodes')
 681         if kwargs.has_key('allowNegative'):
 682             if kwargs['allowNegative'] and '-' not in formatcodes:
 683                 formatcodes += '-'
 684                 maskededit_kwargs['formatcodes'] = formatcodes
 685             elif not kwargs['allowNegative'] and '-' in formatcodes:
 686                 formatcodes = formatcodes.replace('-','')
 687                 maskededit_kwargs['formatcodes'] = formatcodes
 688
 689         if kwargs.has_key('groupDigits'):
 690             if kwargs['groupDigits'] and ',' not in formatcodes:
 691                 formatcodes += ','
 692                 maskededit_kwargs['formatcodes'] = formatcodes
 693             elif not kwargs['groupDigits'] and ',' in formatcodes:
 694                 formatcodes = formatcodes.replace(',','')
 695                 maskededit_kwargs['formatcodes'] = formatcodes
 696
 697         if kwargs.has_key('selectOnEntry'):
 698             self._selectOnEntry = kwargs['selectOnEntry']
 699 ##            dbg("kwargs['selectOnEntry']?", kwargs['selectOnEntry'], "'S' in formatcodes?", 'S' in formatcodes)
 700             if kwargs['selectOnEntry'] and 'S' not in formatcodes:
 701                 formatcodes += 'S'
 702                 maskededit_kwargs['formatcodes'] = formatcodes
 703             elif not kwargs['selectOnEntry'] and 'S' in formatcodes:
 704                 formatcodes = formatcodes.replace('S','')
 705                 maskededit_kwargs['formatcodes'] = formatcodes
 706
 707         if kwargs.has_key('autoSize'):
 708             self._autoSize = kwargs['autoSize']
 709             if kwargs['autoSize'] and 'F' not in formatcodes:
 710                 formatcodes += 'F'
 711                 maskededit_kwargs['formatcodes'] = formatcodes
 712             elif not kwargs['autoSize'] and 'F' in formatcodes:
 713                 formatcodes = formatcodes.replace('F', '')
 714                 maskededit_kwargs['formatcodes'] = formatcodes
 715
 716
 717         if 'r' in formatcodes and self._fractionWidth:
 718             # top-level mask should only be right insert if no fractional
 719             # part will be shown; ie. if reconfiguring control, remove
 720             # previous "global" setting.
 721             formatcodes = formatcodes.replace('r', '')
 722             maskededit_kwargs['formatcodes'] = formatcodes
 723
 724
 725         if kwargs.has_key('limited'):
 726             if kwargs['limited'] and not self._limited:
 727                 maskededit_kwargs['validRequired'] = True
 728             elif not kwargs['limited'] and self._limited:
 729                 maskededit_kwargs['validRequired'] = False
 730             self._limited = kwargs['limited']
 731
 732 ##        dbg('maskededit_kwargs:', maskededit_kwargs)
 733         if maskededit_kwargs.keys():
 734             self.SetCtrlParameters(**maskededit_kwargs)
 735
 736         # Record end of integer and place cursor there:
 737         integerEnd = self._fields[0]._extent[1]
 738         self.SetInsertionPoint(0)
 739         self.SetInsertionPoint(integerEnd)
 740         self.SetSelection(integerEnd, integerEnd)
 741
 742         # Go ensure all the format codes necessary are present:
 743         orig_intformat = intformat = self.GetFieldParameter(0, 'formatcodes')
 744         if 'r' not in intformat:
 745             intformat += 'r'
 746         if '>' not in intformat:
 747             intformat += '>'
 748         if intformat != orig_intformat:
 749             if self._fractionWidth:
 750                 self.SetFieldParameters(0, formatcodes=intformat)
 751             else:
 752                 self.SetCtrlParameters(formatcodes=intformat)
 753
 754         # Set min and max as appropriate:
 755         if kwargs.has_key('min'):
 756             min = kwargs['min']
 757             if( self._max is None
 758                 or min is None
 759                 or (self._max is not None and self._max >= min) ):
 760 ##                dbg('examining min')
 761                 if min is not None:
 762                     try:
 763                         textmin = self._toGUI(min, apply_limits = False)
 764                     except ValueError:
 765 ##                        dbg('min will not fit into control; ignoring', indent=0)
 766                         raise
 767 ##                dbg('accepted min')
 768                 self._min = min
 769             else:
 770 ##                dbg('ignoring min')
 771                 pass
 772
 773
 774         if kwargs.has_key('max'):
 775             max = kwargs['max']
 776             if( self._min is None
 777                 or max is None
 778                 or (self._min is not None and self._min <= max) ):
 779 ##                dbg('examining max')
 780                 if max is not None:
 781                     try:
 782                         textmax = self._toGUI(max, apply_limits = False)
 783                     except ValueError:
 784 ##                        dbg('max will not fit into control; ignoring', indent=0)
 785                         raise
 786 ##                dbg('accepted max')
 787                 self._max = max
 788             else:
 789 ##                dbg('ignoring max')
 790                 pass
 791
 792         if kwargs.has_key('allowNegative'):
 793             self._allowNegative = kwargs['allowNegative']
 794
 795         # Ensure current value of control obeys any new restrictions imposed:
 796         text = self._GetValue()
 797 ##        dbg('text value: "%s"' % text)
 798         if kwargs.has_key('groupChar') and text.find(old_groupchar) != -1:
 799             text = text.replace(old_groupchar, self._groupChar)
 800         if kwargs.has_key('decimalChar') and text.find(old_decimalchar) != -1:
 801             text = text.replace(old_decimalchar, self._decimalChar)
 802         if text != self._GetValue():
 803             wx.TextCtrl.SetValue(self, text)
 804
 805         value = self.GetValue()
 806
 807 ##        dbg('self._allowNegative?', self._allowNegative)
 808         if not self._allowNegative and self._isNeg:
 809             value = abs(value)
 810 ##            dbg('abs(value):', value)
 811             self._isNeg = False
 812
 813         elif not self._allowNone and BaseMaskedTextCtrl.GetValue(self) == '':
 814             if self._min > 0:
 815                 value = self._min
 816             else:
 817                 value = 0
 818
 819         sel_start, sel_to = self.GetSelection()
 820         if self.IsLimited() and self._min is not None and value < self._min:
 821 ##            dbg('Set to min value:', self._min)
 822             self._SetValue(self._toGUI(self._min))
 823
 824         elif self.IsLimited() and self._max is not None and value > self._max:
 825 ##            dbg('Setting to max value:', self._max)
 826             self._SetValue(self._toGUI(self._max))
 827         else:
 828             # reformat current value as appropriate to possibly new conditions
 829 ##            dbg('Reformatting value:', value)
 830             sel_start, sel_to = self.GetSelection()
 831             self._SetValue(self._toGUI(value))
 832         self.Refresh() # recolor as appropriate
 833 ##        dbg('finished NumCtrl::SetParameters', indent=0)
 834
 835
 836
 837     def _GetNumValue(self, value):
 838         """
 839         This function attempts to "clean up" a text value, providing a regularized
 840         convertable string, via atol() or atof(), for any well-formed numeric text value.
 841         """
 842         return value.replace(self._groupChar, '').replace(self._decimalChar, '.').replace('(', '-').replace(')','').strip()
 843
 844
 845     def GetFraction(self, candidate=None):
 846         """
 847         Returns the fractional portion of the value as a float.  If there is no
 848         fractional portion, the value returned will be 0.0.
 849         """
 850         if not self._fractionWidth:
 851             return 0.0
 852         else:
 853             fracstart, fracend = self._fields[1]._extent
 854             if candidate is None:
 855                 value = self._toGUI(BaseMaskedTextCtrl.GetValue(self))
 856             else:
 857                 value = self._toGUI(candidate)
 858             fracstring = value[fracstart:fracend].strip()
 859             if not value:
 860                 return 0.0
 861             else:
 862                 return string.atof(fracstring)
 863
 864     def _OnChangeSign(self, event):
 865 ##        dbg('NumCtrl::_OnChangeSign', indent=1)
 866         self._typedSign = True
 867         MaskedEditMixin._OnChangeSign(self, event)
 868 ##        dbg(indent=0)
 869
 870
 871     def _disallowValue(self):
 872 ##        dbg('NumCtrl::_disallowValue')
 873         # limited and -1 is out of bounds
 874         if self._typedSign:
 875             self._isNeg = False
 876         if not wx.Validator_IsSilent():
 877             wx.Bell()
 878         sel_start, sel_to = self._GetSelection()
 879 ##        dbg('queuing reselection of (%d, %d)' % (sel_start, sel_to))
 880         wx.CallAfter(self.SetInsertionPoint, sel_start)      # preserve current selection/position
 881         wx.CallAfter(self.SetSelection, sel_start, sel_to)
 882
 883     def _SetValue(self, value):
 884         """
 885         This routine supersedes the base masked control _SetValue().  It is
 886         needed to ensure that the value of the control is always representable/convertable
 887         to a numeric return value (via GetValue().)  This routine also handles
 888         automatic adjustment and grouping of the value without explicit intervention
 889         by the user.
 890         """
 891
 892 ##        dbg('NumCtrl::_SetValue("%s")' % value, indent=1)
 893
 894         if( (self._fractionWidth and value.find(self._decimalChar) == -1) or
 895             (self._fractionWidth == 0 and value.find(self._decimalChar) != -1) ) :
 896             value = self._toGUI(value)
 897
 898         numvalue = self._GetNumValue(value)
 899 ##        dbg('cleansed value: "%s"' % numvalue)
 900         replacement = None
 901
 902         if numvalue == "":
 903             if self._allowNone:
 904 ##                dbg('calling base BaseMaskedTextCtrl._SetValue(self, "%s")' % value)
 905                 BaseMaskedTextCtrl._SetValue(self, value)
 906                 self.Refresh()
 907                 return
 908             elif self._min > 0 and self.IsLimited():
 909                 replacement = self._min
 910             else:
 911                 replacement = 0
 912 ##            dbg('empty value; setting replacement:', replacement)
 913
 914         if replacement is None:
 915             # Go get the integer portion about to be set and verify its validity
 916             intstart, intend = self._fields[0]._extent
 917 ##            dbg('intstart, intend:', intstart, intend)
 918 ##            dbg('raw integer:"%s"' % value[intstart:intend])
 919             int = self._GetNumValue(value[intstart:intend])
 920             numval = self._fromGUI(value)
 921
 922 ##            dbg('integer: "%s"' % int)
 923             try:
 924                 fracval = self.GetFraction(value)
 925             except ValueError, e:
 926 ##                dbg('Exception:', e, 'must be out of bounds; disallow value')
 927                 self._disallowValue()
 928 ##                dbg(indent=0)
 929                 return
 930
 931             if fracval == 0.0:
 932 ##                dbg('self._isNeg?', self._isNeg)
 933                 if int == '-' and self._oldvalue < 0 and not self._typedSign:
 934 ##                    dbg('just a negative sign; old value < 0; setting replacement of 0')
 935                     replacement = 0
 936                     self._isNeg = False
 937                 elif int[:2] == '-0' and self._fractionWidth == 0:
 938                     if self._oldvalue < 0:
 939 ##                        dbg('-0; setting replacement of 0')
 940                         replacement = 0
 941                         self._isNeg = False
 942                     elif not self._limited or (self._min < -1 and self._max >= -1):
 943 ##                        dbg('-0; setting replacement of -1')
 944                         replacement = -1
 945                         self._isNeg = True
 946                     else:
 947                         # limited and -1 is out of bounds
 948                         self._disallowValue()
 949 ##                        dbg(indent=0)
 950                         return
 951
 952                 elif int == '-' and (self._oldvalue >= 0 or self._typedSign) and self._fractionWidth == 0:
 953                     if not self._limited or (self._min < -1 and self._max >= -1):
 954 ##                        dbg('just a negative sign; setting replacement of -1')
 955                         replacement = -1
 956                     else:
 957                         # limited and -1 is out of bounds
 958                         self._disallowValue()
 959 ##                        dbg(indent=0)
 960                         return
 961
 962                 elif( self._typedSign
 963                       and int.find('-') != -1
 964                       and self._limited
 965                       and not self._min <= numval <= self._max):
 966                     # changed sign resulting in value that's now out-of-bounds;
 967                     # disallow
 968                     self._disallowValue()
 969 ##                    dbg(indent=0)
 970                     return
 971
 972             if replacement is None:
 973                 if int and int != '-':
 974                     try:
 975                         string.atol(int)
 976                     except ValueError:
 977                         # integer requested is not legal.  This can happen if the user
 978                         # is attempting to insert a digit in the middle of the control
 979                         # resulting in something like "   3   45". Disallow such actions:
 980 ##                        dbg('>>>>>>>>>>>>>>>> "%s" does not convert to a long!' % int)
 981                         if not wx.Validator_IsSilent():
 982                             wx.Bell()
 983                         sel_start, sel_to = self._GetSelection()
 984 ##                        dbg('queuing reselection of (%d, %d)' % (sel_start, sel_to))
 985                         wx.CallAfter(self.SetInsertionPoint, sel_start)      # preserve current selection/position
 986                         wx.CallAfter(self.SetSelection, sel_start, sel_to)
 987 ##                        dbg(indent=0)
 988                         return
 989
 990                     if int[0] == '0' and len(int) > 1:
 991 ##                        dbg('numvalue: "%s"' % numvalue.replace(' ', ''))
 992                         if self._fractionWidth:
 993                             value = self._toGUI(string.atof(numvalue))
 994                         else:
 995                             value = self._toGUI(string.atol(numvalue))
 996 ##                        dbg('modified value: "%s"' % value)
 997
 998         self._typedSign = False     # reset state var
 999
1000         if replacement is not None:
1001             # Value presented wasn't a legal number, but control should do something
1002             # reasonable instead:
1003 ##            dbg('setting replacement value:', replacement)
1004             self._SetValue(self._toGUI(replacement))
1005             sel_start = BaseMaskedTextCtrl.GetValue(self).find(str(abs(replacement)))   # find where it put the 1, so we can select it
1006             sel_to = sel_start + len(str(abs(replacement)))
1007 ##            dbg('queuing selection of (%d, %d)' %(sel_start, sel_to))
1008             wx.CallAfter(self.SetInsertionPoint, sel_start)
1009             wx.CallAfter(self.SetSelection, sel_start, sel_to)
1010 ##            dbg(indent=0)
1011             return
1012
1013         # Otherwise, apply appropriate formatting to value:
1014
1015         # Because we're intercepting the value and adjusting it
1016         # before a sign change is detected, we need to do this here:
1017         if '-' in value or '(' in value:
1018             self._isNeg = True
1019         else:
1020             self._isNeg = False
1021
1022 ##        dbg('value:"%s"' % value, 'self._useParens:', self._useParens)
1023         if self._fractionWidth:
1024             adjvalue = self._adjustFloat(self._GetNumValue(value).replace('.',self._decimalChar))
1025         else:
1026             adjvalue = self._adjustInt(self._GetNumValue(value))
1027 ##        dbg('adjusted value: "%s"' % adjvalue)
1028
1029
1030         sel_start, sel_to = self._GetSelection()     # record current insertion point
1031 ##        dbg('calling BaseMaskedTextCtrl._SetValue(self, "%s")' % adjvalue)
1032         BaseMaskedTextCtrl._SetValue(self, adjvalue)
1033         # After all actions so far scheduled, check that resulting cursor
1034         # position is appropriate, and move if not:
1035         wx.CallAfter(self._CheckInsertionPoint)
1036
1037 ##        dbg('finished NumCtrl::_SetValue', indent=0)
1038
1039     def _CheckInsertionPoint(self):
1040         # If current insertion point is before the end of the integer and
1041         # its before the 1st digit, place it just after the sign position:
1042 ##        dbg('NumCtrl::CheckInsertionPoint', indent=1)
1043         sel_start, sel_to = self._GetSelection()
1044         text = self._GetValue()
1045         if sel_to < self._fields[0]._extent[1] and text[sel_to] in (' ', '-', '('):
1046             text, signpos, right_signpos = self._getSignedValue()
1047 ##            dbg('setting selection(%d, %d)' % (signpos+1, signpos+1))
1048             self.SetInsertionPoint(signpos+1)
1049             self.SetSelection(signpos+1, signpos+1)
1050 ##        dbg(indent=0)
1051
1052
1053     def _OnErase( self, event=None, just_return_value=False ):
1054         """
1055         This overrides the base control _OnErase, so that erasing around
1056         grouping characters auto selects the digit before or after the
1057         grouping character, so that the erasure does the right thing.
1058         """
1059 ##        dbg('NumCtrl::_OnErase', indent=1)
1060         if event is None:   # called as action routine from Cut() operation.
1061             key = wx.WXK_DELETE
1062         else:
1063             key = event.GetKeyCode()
1064         #if grouping digits, make sure deletes next to group char always
1065         # delete next digit to appropriate side:
1066         if self._groupDigits:
1067             value = BaseMaskedTextCtrl.GetValue(self)
1068             sel_start, sel_to = self._GetSelection()
1069
1070             if key == wx.WXK_BACK:
1071                 # if 1st selected char is group char, select to previous digit
1072                 if sel_start > 0 and sel_start < len(self._mask) and value[sel_start:sel_to] == self._groupChar:
1073                     self.SetInsertionPoint(sel_start-1)
1074                     self.SetSelection(sel_start-1, sel_to)
1075
1076                 # elif previous char is group char, select to previous digit
1077                 elif sel_start > 1 and sel_start == sel_to and value[sel_start-1:sel_start] == self._groupChar:
1078                     self.SetInsertionPoint(sel_start-2)
1079                     self.SetSelection(sel_start-2, sel_to)
1080
1081             elif key == wx.WXK_DELETE:
1082                 if( sel_to < len(self._mask) - 2 + (1 *self._useParens)
1083                     and sel_start == sel_to
1084                     and value[sel_to] == self._groupChar ):
1085                     self.SetInsertionPoint(sel_start)
1086                     self.SetSelection(sel_start, sel_to+2)
1087
1088                 elif( sel_to < len(self._mask) - 2 + (1 *self._useParens)
1089                            and value[sel_start:sel_to] == self._groupChar ):
1090                     self.SetInsertionPoint(sel_start)
1091                     self.SetSelection(sel_start, sel_to+1)
1092
1093         return BaseMaskedTextCtrl._OnErase(self, event, just_return_value)
1094 ##        dbg(indent=0)
1095
1096
1097     def OnTextChange( self, event ):
1098         """
1099         Handles an event indicating that the text control's value
1100         has changed, and issue EVT_NUM event.
1101         NOTE: using wxTextCtrl.SetValue() to change the control's
1102         contents from within a EVT_CHAR handler can cause double
1103         text events.  So we check for actual changes to the text
1104         before passing the events on.
1105         """
1106 ##        dbg('NumCtrl::OnTextChange', indent=1)
1107         if not BaseMaskedTextCtrl._OnTextChange(self, event):
1108 ##            dbg(indent=0)
1109             return
1110
1111         # else... legal value
1112
1113         value = self.GetValue()
1114         if value != self._oldvalue:
1115             try:
1116                 self.GetEventHandler().ProcessEvent(
1117                     NumberUpdatedEvent( self.GetId(), self.GetValue(), self ) )
1118             except ValueError:
1119 ##                dbg(indent=0)
1120                 return
1121             # let normal processing of the text continue
1122             event.Skip()
1123         self._oldvalue = value # record for next event
1124 ##        dbg(indent=0)
1125
1126     def _GetValue(self):
1127         """
1128         Override of BaseMaskedTextCtrl to allow mixin to get the raw text value of the
1129         control with this function.
1130         """
1131         return wx.TextCtrl.GetValue(self)
1132
1133
1134     def GetValue(self):
1135         """
1136         Returns the current numeric value of the control.
1137         """
1138         return self._fromGUI( BaseMaskedTextCtrl.GetValue(self) )
1139
1140     def SetValue(self, value):
1141         """
1142         Sets the value of the control to the value specified.
1143         The resulting actual value of the control may be altered to
1144         conform with the bounds set on the control if limited,
1145         or colored if not limited but the value is out-of-bounds.
1146         A ValueError exception will be raised if an invalid value
1147         is specified.
1148         """
1149         BaseMaskedTextCtrl.SetValue( self, self._toGUI(value) )
1150
1151
1152     def SetIntegerWidth(self, value):
1153         self.SetParameters(integerWidth=value)
1154     def GetIntegerWidth(self):
1155         return self._integerWidth
1156
1157     def SetFractionWidth(self, value):
1158         self.SetParameters(fractionWidth=value)
1159     def GetFractionWidth(self):
1160         return self._fractionWidth
1161
1162
1163
1164     def SetMin(self, min=None):
1165         """
1166         Sets the minimum value of the control.  If a value of None
1167         is provided, then the control will have no explicit minimum value.
1168         If the value specified is greater than the current maximum value,
1169         then the function returns False and the minimum will not change from
1170         its current setting.  On success, the function returns True.
1171
1172         If successful and the current value is lower than the new lower
1173         bound, if the control is limited, the value will be automatically
1174         adjusted to the new minimum value; if not limited, the value in the
1175         control will be colored as invalid.
1176
1177         If min > the max value allowed by the width of the control,
1178         the function will return False, and the min will not be set.
1179         """
1180 ##        dbg('NumCtrl::SetMin(%s)' % repr(min), indent=1)
1181         if( self._max is None
1182             or min is None
1183             or (self._max is not None and self._max >= min) ):
1184             try:
1185                 self.SetParameters(min=min)
1186                 bRet = True
1187             except ValueError:
1188                 bRet = False
1189         else:
1190             bRet = False
1191 ##        dbg(indent=0)
1192         return bRet
1193
1194     def GetMin(self):
1195         """
1196         Gets the lower bound value of the control.  It will return
1197         None if not specified.
1198         """
1199         return self._min
1200
1201
1202     def SetMax(self, max=None):
1203         """
1204         Sets the maximum value of the control. If a value of None
1205         is provided, then the control will have no explicit maximum value.
1206         If the value specified is less than the current minimum value, then
1207         the function returns False and the maximum will not change from its
1208         current setting. On success, the function returns True.
1209
1210         If successful and the current value is greater than the new upper
1211         bound, if the control is limited the value will be automatically
1212         adjusted to this maximum value; if not limited, the value in the
1213         control will be colored as invalid.
1214
1215         If max > the max value allowed by the width of the control,
1216         the function will return False, and the max will not be set.
1217         """
1218         if( self._min is None
1219             or max is None
1220             or (self._min is not None and self._min <= max) ):
1221             try:
1222                 self.SetParameters(max=max)
1223                 bRet = True
1224             except ValueError:
1225                 bRet = False
1226         else:
1227             bRet = False
1228
1229         return bRet
1230
1231
1232     def GetMax(self):
1233         """
1234         Gets the maximum value of the control.  It will return the current
1235         maximum integer, or None if not specified.
1236         """
1237         return self._max
1238
1239
1240     def SetBounds(self, min=None, max=None):
1241         """
1242         This function is a convenience function for setting the min and max
1243         values at the same time.  The function only applies the maximum bound
1244         if setting the minimum bound is successful, and returns True
1245         only if both operations succeed.
1246         NOTE: leaving out an argument will remove the corresponding bound.
1247         """
1248         ret = self.SetMin(min)
1249         return ret and self.SetMax(max)
1250
1251
1252     def GetBounds(self):
1253         """
1254         This function returns a two-tuple (min,max), indicating the
1255         current bounds of the control.  Each value can be None if
1256         that bound is not set.
1257         """
1258         return (self._min, self._max)
1259
1260
1261     def SetLimited(self, limited):
1262         """
1263         If called with a value of True, this function will cause the control
1264         to limit the value to fall within the bounds currently specified.
1265         If the control's value currently exceeds the bounds, it will then
1266         be limited accordingly.
1267
1268         If called with a value of False, this function will disable value
1269         limiting, but coloring of out-of-bounds values will still take
1270         place if bounds have been set for the control.
1271         """
1272         self.SetParameters(limited = limited)
1273
1274
1275     def IsLimited(self):
1276         """
1277         Returns True if the control is currently limiting the
1278         value to fall within the current bounds.
1279         """
1280         return self._limited
1281
1282     def GetLimited(self):
1283         """ (For regularization of property accessors) """
1284         return self.IsLimited
1285
1286
1287     def IsInBounds(self, value=None):
1288         """
1289         Returns True if no value is specified and the current value
1290         of the control falls within the current bounds.  This function can
1291         also be called with a value to see if that value would fall within
1292         the current bounds of the given control.
1293         """
1294 ##        dbg('IsInBounds(%s)' % repr(value), indent=1)
1295         if value is None:
1296             value = self.GetValue()
1297         else:
1298             try:
1299                 value = self._GetNumValue(self._toGUI(value))
1300             except ValueError, e:
1301 ##                dbg('error getting NumValue(self._toGUI(value)):', e, indent=0)
1302                 return False
1303             if value.strip() == '':
1304                 value = None
1305             elif self._fractionWidth:
1306                 value = float(value)
1307             else:
1308                 value = long(value)
1309
1310         min = self.GetMin()
1311         max = self.GetMax()
1312         if min is None: min = value
1313         if max is None: max = value
1314
1315         # if bounds set, and value is None, return False
1316         if value == None and (min is not None or max is not None):
1317 ##            dbg('finished IsInBounds', indent=0)
1318             return 0
1319         else:
1320 ##            dbg('finished IsInBounds', indent=0)
1321             return min <= value <= max
1322
1323
1324     def SetAllowNone(self, allow_none):
1325         """
1326         Change the behavior of the validation code, allowing control
1327         to have a value of None or not, as appropriate.  If the value
1328         of the control is currently None, and allow_none is False, the
1329         value of the control will be set to the minimum value of the
1330         control, or 0 if no lower bound is set.
1331         """
1332         self._allowNone = allow_none
1333         if not allow_none and self.GetValue() is None:
1334             min = self.GetMin()
1335             if min is not None: self.SetValue(min)
1336             else:               self.SetValue(0)
1337
1338
1339     def IsNoneAllowed(self):
1340         return self._allowNone
1341     def GetAllowNone(self):
1342         """ (For regularization of property accessors) """
1343         return self.IsNoneAllowed()
1344
1345     def SetAllowNegative(self, value):
1346         self.SetParameters(allowNegative=value)
1347     def IsNegativeAllowed(self):
1348         return self._allowNegative
1349     def GetAllowNegative(self):
1350         """ (For regularization of property accessors) """
1351         return self.IsNegativeAllowed()
1352
1353     def SetGroupDigits(self, value):
1354         self.SetParameters(groupDigits=value)
1355     def IsGroupingAllowed(self):
1356         return self._groupDigits
1357     def GetGroupDigits(self):
1358         """ (For regularization of property accessors) """
1359         return self.IsGroupingAllowed()
1360
1361     def SetGroupChar(self, value):
1362         self.SetParameters(groupChar=value)
1363     def GetGroupChar(self):
1364         return self._groupChar
1365
1366     def SetDecimalChar(self, value):
1367         self.SetParameters(decimalChar=value)
1368     def GetDecimalChar(self):
1369         return self._decimalChar
1370
1371     def SetSelectOnEntry(self, value):
1372         self.SetParameters(selectOnEntry=value)
1373     def GetSelectOnEntry(self):
1374         return self._selectOnEntry
1375
1376     def SetAutoSize(self, value):
1377         self.SetParameters(autoSize=value)
1378     def GetAutoSize(self):
1379         return self._autoSize
1380
1381
1382     # (Other parameter accessors are inherited from base class)
1383
1384
1385     def _toGUI( self, value, apply_limits = True ):
1386         """
1387         Conversion function used to set the value of the control; does
1388         type and bounds checking and raises ValueError if argument is
1389         not a valid value.
1390         """
1391 ##        dbg('NumCtrl::_toGUI(%s)' % repr(value), indent=1)
1392         if value is None and self.IsNoneAllowed():
1393 ##            dbg(indent=0)
1394             return self._template
1395
1396         elif type(value) in (types.StringType, types.UnicodeType):
1397             value = self._GetNumValue(value)
1398 ##            dbg('cleansed num value: "%s"' % value)
1399             if value == "":
1400                 if self.IsNoneAllowed():
1401 ##                    dbg(indent=0)
1402                     return self._template
1403                 else:
1404 ##                    dbg('exception raised:', e, indent=0)
1405                     raise ValueError ('NumCtrl requires numeric value, passed %s'% repr(value) )
1406             # else...
1407             try:
1408                 if self._fractionWidth or value.find('.') != -1:
1409                     value = float(value)
1410                 else:
1411                     value = long(value)
1412             except Exception, e:
1413 ##                dbg('exception raised:', e, indent=0)
1414                 raise ValueError ('NumCtrl requires numeric value, passed %s'% repr(value) )
1415
1416         elif type(value) not in (types.IntType, types.LongType, types.FloatType):
1417 ##            dbg(indent=0)
1418             raise ValueError (
1419                 'NumCtrl requires numeric value, passed %s'% repr(value) )
1420
1421         if not self._allowNegative and value < 0:
1422             raise ValueError (
1423                 'control configured to disallow negative values, passed %s'% repr(value) )
1424
1425         if self.IsLimited() and apply_limits:
1426             min = self.GetMin()
1427             max = self.GetMax()
1428             if not min is None and value < min:
1429 ##                dbg(indent=0)
1430                 raise ValueError (
1431                     'value %d is below minimum value of control'% value )
1432             if not max is None and value > max:
1433 ##                dbg(indent=0)
1434                 raise ValueError (
1435                     'value %d exceeds value of control'% value )
1436
1437         adjustwidth = len(self._mask) - (1 * self._useParens * self._signOk)
1438 ##        dbg('len(%s):' % self._mask, len(self._mask))
1439 ##        dbg('adjustwidth - groupSpace:', adjustwidth - self._groupSpace)
1440 ##        dbg('adjustwidth:', adjustwidth)
1441         if self._fractionWidth == 0:
1442             s = str(long(value)).rjust(self._integerWidth)
1443         else:
1444             format = '%' + '%d.%df' % (self._integerWidth+self._fractionWidth+1, self._fractionWidth)
1445             s = format % float(value)
1446 ##        dbg('s:"%s"' % s, 'len(s):', len(s))
1447         if len(s) > (adjustwidth - self._groupSpace):
1448 ##            dbg(indent=0)
1449             raise ValueError ('value %s exceeds the integer width of the control (%d)' % (s, self._integerWidth))
1450         elif s[0] not in ('-', ' ') and self._allowNegative and len(s) == (adjustwidth - self._groupSpace):
1451 ##            dbg(indent=0)
1452             raise ValueError ('value %s exceeds the integer width of the control (%d)' % (s, self._integerWidth))
1453
1454         s = s.rjust(adjustwidth).replace('.', self._decimalChar)
1455         if self._signOk and self._useParens:
1456             if s.find('-') != -1:
1457                 s = s.replace('-', '(') + ')'
1458             else:
1459                 s += ' '
1460 ##        dbg('returned: "%s"' % s, indent=0)
1461         return s
1462
1463
1464     def _fromGUI( self, value ):
1465         """
1466         Conversion function used in getting the value of the control.
1467         """
1468 ##        dbg(suspend=0)
1469 ##        dbg('NumCtrl::_fromGUI(%s)' % value, indent=1)
1470         # One or more of the underlying text control implementations
1471         # issue an intermediate EVT_TEXT when replacing the control's
1472         # value, where the intermediate value is an empty string.
1473         # So, to ensure consistency and to prevent spurious ValueErrors,
1474         # we make the following test, and react accordingly:
1475         #
1476         if value.strip() == '':
1477             if not self.IsNoneAllowed():
1478 ##                dbg('empty value; not allowed,returning 0', indent = 0)
1479                 if self._fractionWidth:
1480                     return 0.0
1481                 else:
1482                     return 0
1483             else:
1484 ##                dbg('empty value; returning None', indent = 0)
1485                 return None
1486         else:
1487             value = self._GetNumValue(value)
1488 ##            dbg('Num value: "%s"' % value)
1489             if self._fractionWidth:
1490                 try:
1491 ##                    dbg(indent=0)
1492                     return float( value )
1493                 except ValueError:
1494 ##                    dbg("couldn't convert to float; returning None")
1495                     return None
1496                 else:
1497                     raise
1498             else:
1499                 try:
1500 ##                    dbg(indent=0)
1501                     return int( value )
1502                 except ValueError:
1503                     try:
1504 ##                       dbg(indent=0)
1505                        return long( value )
1506                     except ValueError:
1507 ##                       dbg("couldn't convert to long; returning None")
1508                        return None
1509
1510                     else:
1511                        raise
1512                 else:
1513 ##                    dbg('exception occurred; returning None')
1514                     return None
1515
1516
1517     def _Paste( self, value=None, raise_on_invalid=False, just_return_value=False ):
1518         """
1519         Preprocessor for base control paste; if value needs to be right-justified
1520         to fit in control, do so prior to paste:
1521         """
1522 ##        dbg('NumCtrl::_Paste (value = "%s")' % value)
1523         if value is None:
1524             paste_text = self._getClipboardContents()
1525         else:
1526             paste_text = value
1527         sel_start, sel_to = self._GetSelection()
1528         orig_sel_start = sel_start
1529         orig_sel_to = sel_to
1530 ##        dbg('selection:', (sel_start, sel_to))
1531         old_value = self._GetValue()
1532
1533         #
1534         field = self._FindField(sel_start)
1535         edit_start, edit_end = field._extent
1536         paste_text = paste_text.replace(self._groupChar, '').replace(self._decimalChar, '.').replace('(', '-').replace(')','')
1537         if field._insertRight and self._groupDigits:
1538             # want to paste to the left; see if it will fit:
1539             left_text = old_value[edit_start:sel_start].lstrip()
1540 ##            dbg('len(left_text):', len(left_text))
1541 ##            dbg('len(paste_text):', len(paste_text))
1542 ##            dbg('sel_start - (len(left_text) + len(paste_text)) >= edit_start?', sel_start - (len(left_text) + len(paste_text)) >= edit_start)
1543             if sel_start - (len(left_text) + len(paste_text)) >= edit_start:
1544                 # will fit! create effective paste text, and move cursor back to do so:
1545                 paste_text = left_text + paste_text
1546                 sel_start -= len(paste_text)
1547                 sel_start += sel_to - orig_sel_start    # decrease by amount selected
1548             else:
1549 ##                dbg("won't fit left;", 'paste text remains: "%s"' % paste_text)
1550 ##            dbg('adjusted start before accounting for grouping:', sel_start)
1551 ##            dbg('adjusted paste_text before accounting for grouping: "%s"' % paste_text)
1552                 pass
1553             if self._groupDigits and sel_start != orig_sel_start:
1554                 left_len = len(old_value[:sel_to].lstrip())
1555                 # remove group chars from adjusted paste string, and left pad to wipe out
1556                 # old characters, so that selection will remove the right chars, and
1557                 # readjust will do the right thing:
1558                 paste_text = paste_text.replace(self._groupChar,'')
1559                 adjcount = left_len - len(paste_text)
1560                 paste_text = ' ' * adjcount + paste_text
1561                 sel_start = sel_to - len(paste_text)
1562 ##                dbg('adjusted start after accounting for grouping:', sel_start)
1563 ##                dbg('adjusted paste_text after accounting for grouping: "%s"' % paste_text)
1564             self.SetInsertionPoint(sel_to)
1565             self.SetSelection(sel_start, sel_to)
1566
1567 ##        # treat paste as "replace number", if appropriate:
1568 ##        sel_start, sel_to = self._GetSelection()
1569 ##        if sel_start == sel_to or self._selectOnEntry and (sel_start, sel_to) == self._fields[0]._extent:
1570 ##            paste_text = self._toGUI(paste_text)
1571 ##            self._SetSelection(0, len(self._mask))
1572
1573         new_text, replace_to = MaskedEditMixin._Paste(self,
1574                                         paste_text,
1575                                         raise_on_invalid=raise_on_invalid,
1576                                         just_return_value=True)
1577         self._SetInsertionPoint(orig_sel_to)
1578         self._SetSelection(orig_sel_start, orig_sel_to)
1579         if not just_return_value and new_text is not None:
1580             if new_text != self._GetValue():
1581                     self.modified = True
1582             if new_text == '':
1583                 self.ClearValue()
1584             else:
1585                 wx.CallAfter(self._SetValue, new_text)
1586                 wx.CallAfter(self._SetInsertionPoint, replace_to)
1587 ##            dbg(indent=0)
1588         else:
1589 ##            dbg(indent=0)
1590             return new_text, replace_to
1591
1592     def _Undo(self, value=None, prev=None):
1593         '''numctrl's undo is more complicated than the base control's, due to
1594         grouping characters; we don't want to consider them when calculating
1595         the undone portion.'''
1596 ##        dbg('NumCtrl::_Undo', indent=1)
1597         if value is None: value = self._GetValue()
1598         if prev is None: prev = self._prevValue
1599         if not self._groupDigits:
1600             ignore, (new_sel_start, new_sel_to) = BaseMaskedTextCtrl._Undo(self, value, prev, just_return_results = True)
1601             self._SetValue(prev)
1602             self._SetInsertionPoint(new_sel_start)
1603             self._SetSelection(new_sel_start, new_sel_to)
1604             self._prevSelection = (new_sel_start, new_sel_to)
1605 ##            dbg('resetting "prev selection" to', self._prevSelection)
1606 ##            dbg(indent=0)
1607             return
1608         # else...
1609         sel_start, sel_to = self._prevSelection
1610         edit_start, edit_end = self._FindFieldExtent(0)
1611
1612         adjvalue = self._GetNumValue(value).rjust(self._masklength)
1613         adjprev  = self._GetNumValue(prev ).rjust(self._masklength)
1614
1615         # move selection to account for "ungrouped" value:
1616         left_text = value[sel_start:].lstrip()
1617         numleftgroups = len(left_text) - len(left_text.replace(self._groupChar, ''))
1618         adjsel_start = sel_start + numleftgroups
1619         right_text = value[sel_to:].lstrip()
1620         numrightgroups = len(right_text) - len(right_text.replace(self._groupChar, ''))
1621         adjsel_to = sel_to + numrightgroups
1622 ##        dbg('adjusting "previous" selection from', (sel_start, sel_to), 'to:', (adjsel_start, adjsel_to))
1623         self._prevSelection = (adjsel_start, adjsel_to)
1624
1625         # determine appropriate selection for ungrouped undo
1626         ignore, (new_sel_start, new_sel_to) = BaseMaskedTextCtrl._Undo(self, adjvalue, adjprev, just_return_results = True)
1627
1628         # adjust new selection based on grouping:
1629         left_len = edit_end - new_sel_start
1630         numleftgroups = left_len / 3
1631         new_sel_start -= numleftgroups
1632         if numleftgroups and left_len % 3 == 0:
1633             new_sel_start += 1
1634
1635         if new_sel_start < self._masklength and prev[new_sel_start] == self._groupChar:
1636             new_sel_start += 1
1637
1638         right_len = edit_end - new_sel_to
1639         numrightgroups = right_len / 3
1640         new_sel_to -= numrightgroups
1641
1642         if new_sel_to and prev[new_sel_to-1] == self._groupChar:
1643             new_sel_to -= 1
1644
1645         if new_sel_start > new_sel_to:
1646             new_sel_to = new_sel_start
1647
1648         # for numbers, we don't care about leading whitespace; adjust selection if
1649         # it includes leading space.
1650         prev_stripped = prev.lstrip()
1651         prev_start = self._masklength - len(prev_stripped)
1652         if new_sel_start < prev_start:
1653             new_sel_start = prev_start
1654
1655 ##        dbg('adjusted selection accounting for grouping:', (new_sel_start, new_sel_to))
1656         self._SetValue(prev)
1657         self._SetInsertionPoint(new_sel_start)
1658         self._SetSelection(new_sel_start, new_sel_to)
1659         self._prevSelection = (new_sel_start, new_sel_to)
1660 ##        dbg('resetting "prev selection" to', self._prevSelection)
1661 ##        dbg(indent=0)
1662
1663 #===========================================================================
1664
1665 if __name__ == '__main__':
1666
1667     import traceback
1668
1669     class myDialog(wx.Dialog):
1670         def __init__(self, parent, id, title,
1671             pos = wx.DefaultPosition, size = wx.DefaultSize,
1672             style = wx.DEFAULT_DIALOG_STYLE ):
1673             wx.Dialog.__init__(self, parent, id, title, pos, size, style)
1674
1675             self.int_ctrl = NumCtrl(self, wx.NewId(), size=(55,20))
1676             self.OK = wx.Button( self, wx.ID_OK, "OK")
1677             self.Cancel = wx.Button( self, wx.ID_CANCEL, "Cancel")
1678
1679             vs = wx.BoxSizer( wx.VERTICAL )
1680             vs.Add( self.int_ctrl, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
1681             hs = wx.BoxSizer( wx.HORIZONTAL )
1682             hs.Add( self.OK, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
1683             hs.Add( self.Cancel, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
1684             vs.Add(hs, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
1685
1686             self.SetAutoLayout( True )
1687             self.SetSizer( vs )
1688             vs.Fit( self )
1689             vs.SetSizeHints( self )
1690             self.Bind(EVT_NUM, self.OnChange, self.int_ctrl)
1691
1692         def OnChange(self, event):
1693             print 'value now', event.GetValue()
1694
1695     class TestApp(wx.App):
1696         def OnInit(self):
1697             try:
1698                 self.frame = wx.Frame(None, -1, "Test", (20,20), (120,100)  )
1699                 self.panel = wx.Panel(self.frame, -1)
1700                 button = wx.Button(self.panel, -1, "Push Me", (20, 20))
1701                 self.Bind(wx.EVT_BUTTON, self.OnClick, button)
1702             except:
1703                 traceback.print_exc()
1704                 return False
1705             return True
1706
1707         def OnClick(self, event):
1708             dlg = myDialog(self.panel, -1, "test NumCtrl")
1709             dlg.int_ctrl.SetValue(501)
1710             dlg.int_ctrl.SetInsertionPoint(1)
1711             dlg.int_ctrl.SetSelection(1,2)
1712             rc = dlg.ShowModal()
1713             print 'final value', dlg.int_ctrl.GetValue()
1714             del dlg
1715             self.frame.Destroy()
1716
1717         def Show(self):
1718             self.frame.Show(True)
1719
1720     try:
1721         app = TestApp(0)
1722         app.Show()
1723         app.MainLoop()
1724     except:
1725         traceback.print_exc()
1726
1727 i=0
1728 ## To-Do's:
1729 ## =============================##
1730 ##   1. Add support for printf-style format specification.
1731 ##   2. Add option for repositioning on 'illegal' insertion point.
1732 ##
1733 ## Version 1.2
1734 ##   1. Allowed select/replace digits.
1735 ##   2. Fixed undo to ignore grouping chars.
1736 ##
1737 ## Version 1.1
1738 ##   1. Fixed .SetIntegerWidth() and .SetFractionWidth() functions.
1739 ##   2. Added autoSize parameter, to allow manual sizing of the control.
1740 ##   3. Changed inheritance to use wxBaseMaskedTextCtrl, to remove exposure of
1741 ##      nonsensical parameter methods from the control, so it will work
1742 ##      properly with Boa.
1743 ##   4. Fixed allowNone bug found by user sameerc1@grandecom.net
1744 ##