wxPython/wx/lib/maskednumctrl.py

   1 #----------------------------------------------------------------------------
   2 # Name:         wxPython.lib.maskednumctrl.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 MaskedTextCtrl), but allows Get/Set of numeric
  13 #   values, rather than text.
  14 #
  15 #   MaskedNumCtrl 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 EVT_MASKEDNUM() 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 #   MaskedNumCtrl 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 #   MaskedNumCtrl 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 -> MaskedTextCtrl
  43 # o wxMaskedNumNumberUpdatedEvent -> MaskedNumNumberUpdatedEvent
  44 # o wxMaskedNumCtrl -> MaskedNumCtrl
  45 #
  46
  47 """<html><body>
  48 <P>
  49 <B>MaskedNumCtrl:</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>MaskedNumCtrl</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 = "maskednumber",
  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>EVT_MASKEDNUM(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.maskededit import MaskedEditMixin, BaseMaskedTextCtrl, Field
 388 dbg = Logger()
 389 dbg(enable=0)
 390
 391 #----------------------------------------------------------------------------
 392
 393 wxEVT_COMMAND_MASKED_NUMBER_UPDATED = wx.NewEventType()
 394 EVT_MASKEDNUM = wx.PyEventBinder(wxEVT_COMMAND_MASKED_NUMBER_UPDATED, 1)
 395
 396 #----------------------------------------------------------------------------
 397
 398 class MaskedNumNumberUpdatedEvent(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 MaskedNumCtrlAccessorsMixin:
 413     # Define wxMaskedNumCtrl'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 MaskedNumCtrl(BaseMaskedTextCtrl, MaskedNumCtrlAccessorsMixin):
 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 = "maskednum",
 482                 **kwargs ):
 483
 484         dbg('MaskedNumCtrl::__init__', indent=1)
 485
 486         # Set defaults for control:
 487         dbg('setting defaults:')
 488         for key, param_value in MaskedNumCtrl.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(MaskedNumCtrl.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 MaskedNumCtrl.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         dbg(indent=0)
 506
 507         # Process initial fields for the control, as part of construction:
 508         if type(init_args['integerWidth']) != types.IntType:
 509             raise AttributeError('invalid integerWidth (%s) specified; expected integer' % repr(init_args['integerWidth']))
 510         elif init_args['integerWidth'] < 1:
 511             raise AttributeError('invalid integerWidth (%s) specified; must be > 0' % repr(init_args['integerWidth']))
 512
 513         fields = {}
 514
 515         if init_args.has_key('fractionWidth'):
 516             if type(init_args['fractionWidth']) != types.IntType:
 517                 raise AttributeError('invalid fractionWidth (%s) specified; expected integer' % repr(self._fractionWidth))
 518             elif init_args['fractionWidth'] < 0:
 519                 raise AttributeError('invalid fractionWidth (%s) specified; must be >= 0' % repr(init_args['fractionWidth']))
 520             self._fractionWidth = init_args['fractionWidth']
 521
 522         if self._fractionWidth:
 523             fracmask = '.' + '#{%d}' % self._fractionWidth
 524             dbg('fracmask:', fracmask)
 525             fields[1] = Field(defaultValue='0'*self._fractionWidth)
 526         else:
 527             fracmask = ''
 528
 529         self._integerWidth = init_args['integerWidth']
 530         if init_args['groupDigits']:
 531             self._groupSpace = (self._integerWidth - 1) / 3
 532         else:
 533             self._groupSpace = 0
 534         intmask = '#{%d}' % (self._integerWidth + self._groupSpace)
 535         if self._fractionWidth:
 536             emptyInvalid = False
 537         else:
 538             emptyInvalid = True
 539         fields[0] = Field(formatcodes='r<>', emptyInvalid=emptyInvalid)
 540         dbg('intmask:', intmask)
 541
 542         # don't bother to reprocess these arguments:
 543         del init_args['integerWidth']
 544         del init_args['fractionWidth']
 545
 546         self._autoSize = init_args['autoSize']
 547         if self._autoSize:
 548             formatcodes = 'FR<'
 549         else:
 550             formatcodes = 'R<'
 551
 552
 553         mask = intmask+fracmask
 554
 555         # initial value of state vars
 556         self._oldvalue = 0
 557         self._integerEnd = 0
 558         self._typedSign = False
 559
 560         # Construct the base control:
 561         BaseMaskedTextCtrl.__init__(
 562                 self, parent, id, '',
 563                 pos, size, style, validator, name,
 564                 mask = mask,
 565                 formatcodes = formatcodes,
 566                 fields = fields,
 567                 validFunc=self.IsInBounds,
 568                 setupEventHandling = False)
 569
 570         self.Bind(wx.EVT_SET_FOCUS, self._OnFocus )        ## defeat automatic full selection
 571         self.Bind(wx.EVT_KILL_FOCUS, self._OnKillFocus )   ## run internal validator
 572         self.Bind(wx.EVT_LEFT_DCLICK, self._OnDoubleClick)  ## select field under cursor on dclick
 573         self.Bind(wx.EVT_RIGHT_UP, self._OnContextMenu )    ## bring up an appropriate context menu
 574         self.Bind(wx.EVT_KEY_DOWN, self._OnKeyDown )       ## capture control events not normally seen, eg ctrl-tab.
 575         self.Bind(wx.EVT_CHAR, self._OnChar )              ## handle each keypress
 576         self.Bind(wx.EVT_TEXT, self.OnTextChange )      ## color control appropriately & keep
 577                                                            ## track of previous value for undo
 578
 579         # Establish any additional parameters, with appropriate error checking
 580         self.SetParameters(**init_args)
 581
 582         # Set the value requested (if possible)
 583 ##        wxCallAfter(self.SetValue, value)
 584         self.SetValue(value)
 585
 586         # Ensure proper coloring:
 587         self.Refresh()
 588         dbg('finished MaskedNumCtrl::__init__', indent=0)
 589
 590
 591     def SetParameters(self, **kwargs):
 592         """
 593         This routine is used to initialize and reconfigure the control:
 594         """
 595         dbg('MaskedNumCtrl::SetParameters', indent=1)
 596         maskededit_kwargs = {}
 597         reset_fraction_width = False
 598
 599
 600         if( (kwargs.has_key('integerWidth') and kwargs['integerWidth'] != self._integerWidth)
 601             or (kwargs.has_key('fractionWidth') and kwargs['fractionWidth'] != self._fractionWidth)
 602             or (kwargs.has_key('groupDigits') and kwargs['groupDigits'] != self._groupDigits)
 603             or (kwargs.has_key('autoSize') and kwargs['autoSize'] != self._autoSize) ):
 604
 605             fields = {}
 606
 607             if kwargs.has_key('fractionWidth'):
 608                 if type(kwargs['fractionWidth']) != types.IntType:
 609                     raise AttributeError('invalid fractionWidth (%s) specified; expected integer' % repr(kwargs['fractionWidth']))
 610                 elif kwargs['fractionWidth'] < 0:
 611                     raise AttributeError('invalid fractionWidth (%s) specified; must be >= 0' % repr(kwargs['fractionWidth']))
 612                 else:
 613                     if self._fractionWidth != kwargs['fractionWidth']:
 614                         self._fractionWidth = kwargs['fractionWidth']
 615
 616             if self._fractionWidth:
 617                 fracmask = '.' + '#{%d}' % self._fractionWidth
 618                 fields[1] = Field(defaultValue='0'*self._fractionWidth)
 619                 emptyInvalid = False
 620             else:
 621                 emptyInvalid = True
 622                 fracmask = ''
 623             dbg('fracmask:', fracmask)
 624
 625             if kwargs.has_key('integerWidth'):
 626                 if type(kwargs['integerWidth']) != types.IntType:
 627                     dbg(indent=0)
 628                     raise AttributeError('invalid integerWidth (%s) specified; expected integer' % repr(kwargs['integerWidth']))
 629                 elif kwargs['integerWidth'] < 0:
 630                     dbg(indent=0)
 631                     raise AttributeError('invalid integerWidth (%s) specified; must be > 0' % repr(kwargs['integerWidth']))
 632                 else:
 633                     self._integerWidth = kwargs['integerWidth']
 634
 635             if kwargs.has_key('groupDigits'):
 636                 self._groupDigits = kwargs['groupDigits']
 637
 638             if self._groupDigits:
 639                 self._groupSpace = (self._integerWidth - 1) / 3
 640             else:
 641                 self._groupSpace = 0
 642
 643             intmask = '#{%d}' % (self._integerWidth + self._groupSpace)
 644             dbg('intmask:', intmask)
 645             fields[0] = Field(formatcodes='r<>', emptyInvalid=emptyInvalid)
 646             maskededit_kwargs['fields'] = fields
 647
 648             # don't bother to reprocess these arguments:
 649             if kwargs.has_key('integerWidth'):
 650                 del kwargs['integerWidth']
 651             if kwargs.has_key('fractionWidth'):
 652                 del kwargs['fractionWidth']
 653
 654             maskededit_kwargs['mask'] = intmask+fracmask
 655
 656         if kwargs.has_key('groupChar'):
 657             old_groupchar = self._groupChar     # save so we can reformat properly
 658             dbg("old_groupchar: '%s'" % old_groupchar)
 659             maskededit_kwargs['groupChar'] = kwargs['groupChar']
 660         if kwargs.has_key('decimalChar'):
 661             old_decimalchar = self._decimalChar
 662             dbg("old_decimalchar: '%s'" % old_decimalchar)
 663             maskededit_kwargs['decimalChar'] = kwargs['decimalChar']
 664
 665         # for all other parameters, assign keyword args as appropriate:
 666         for key, param_value in kwargs.items():
 667             key = key.replace('Color', 'Colour')
 668             if key not in MaskedNumCtrl.valid_ctrl_params.keys():
 669                 raise AttributeError('invalid keyword argument "%s"' % key)
 670             elif key not in MaskedEditMixin.valid_ctrl_params.keys():
 671                 setattr(self, '_' + key, param_value)
 672             elif key in ('mask', 'autoformat'): # disallow explicit setting of mask
 673                 raise AttributeError('invalid keyword argument "%s"' % key)
 674             else:
 675                 maskededit_kwargs[key] = param_value
 676         dbg('kwargs:', kwargs)
 677
 678         # reprocess existing format codes to ensure proper resulting format:
 679         formatcodes = self.GetCtrlParameter('formatcodes')
 680         if kwargs.has_key('allowNegative'):
 681             if kwargs['allowNegative'] and '-' not in formatcodes:
 682                 formatcodes += '-'
 683                 maskededit_kwargs['formatcodes'] = formatcodes
 684             elif not kwargs['allowNegative'] and '-' in formatcodes:
 685                 formatcodes = formatcodes.replace('-','')
 686                 maskededit_kwargs['formatcodes'] = formatcodes
 687
 688         if kwargs.has_key('groupDigits'):
 689             if kwargs['groupDigits'] and ',' not in formatcodes:
 690                 formatcodes += ','
 691                 maskededit_kwargs['formatcodes'] = formatcodes
 692             elif not kwargs['groupDigits'] and ',' in formatcodes:
 693                 formatcodes = formatcodes.replace(',','')
 694                 maskededit_kwargs['formatcodes'] = formatcodes
 695
 696         if kwargs.has_key('selectOnEntry'):
 697             self._selectOnEntry = kwargs['selectOnEntry']
 698             dbg("kwargs['selectOnEntry']?", kwargs['selectOnEntry'], "'S' in formatcodes?", 'S' in formatcodes)
 699             if kwargs['selectOnEntry'] and 'S' not in formatcodes:
 700                 formatcodes += 'S'
 701                 maskededit_kwargs['formatcodes'] = formatcodes
 702             elif not kwargs['selectOnEntry'] and 'S' in formatcodes:
 703                 formatcodes = formatcodes.replace('S','')
 704                 maskededit_kwargs['formatcodes'] = formatcodes
 705
 706         if kwargs.has_key('autoSize'):
 707             self._autoSize = kwargs['autoSize']
 708             if kwargs['autoSize'] and 'F' not in formatcodes:
 709                 formatcodes += 'F'
 710                 maskededit_kwargs['formatcodes'] = formatcodes
 711             elif not kwargs['autoSize'] and 'F' in formatcodes:
 712                 formatcodes = formatcodes.replace('F', '')
 713                 maskededit_kwargs['formatcodes'] = formatcodes
 714
 715
 716         if 'r' in formatcodes and self._fractionWidth:
 717             # top-level mask should only be right insert if no fractional
 718             # part will be shown; ie. if reconfiguring control, remove
 719             # previous "global" setting.
 720             formatcodes = formatcodes.replace('r', '')
 721             maskededit_kwargs['formatcodes'] = formatcodes
 722
 723
 724         if kwargs.has_key('limited'):
 725             if kwargs['limited'] and not self._limited:
 726                 maskededit_kwargs['validRequired'] = True
 727             elif not kwargs['limited'] and self._limited:
 728                 maskededit_kwargs['validRequired'] = False
 729             self._limited = kwargs['limited']
 730
 731         dbg('maskededit_kwargs:', maskededit_kwargs)
 732         if maskededit_kwargs.keys():
 733             self.SetCtrlParameters(**maskededit_kwargs)
 734
 735         # Record end of integer and place cursor there:
 736         integerEnd = self._fields[0]._extent[1]
 737         self.SetInsertionPoint(0)
 738         self.SetInsertionPoint(integerEnd)
 739         self.SetSelection(integerEnd, integerEnd)
 740
 741         # Go ensure all the format codes necessary are present:
 742         orig_intformat = intformat = self.GetFieldParameter(0, 'formatcodes')
 743         if 'r' not in intformat:
 744             intformat += 'r'
 745         if '>' not in intformat:
 746             intformat += '>'
 747         if intformat != orig_intformat:
 748             if self._fractionWidth:
 749                 self.SetFieldParameters(0, formatcodes=intformat)
 750             else:
 751                 self.SetCtrlParameters(formatcodes=intformat)
 752
 753         # Set min and max as appropriate:
 754         if kwargs.has_key('min'):
 755             min = kwargs['min']
 756             if( self._max is None
 757                 or min is None
 758                 or (self._max is not None and self._max >= min) ):
 759                 dbg('examining min')
 760                 if min is not None:
 761                     try:
 762                         textmin = self._toGUI(min, apply_limits = False)
 763                     except ValueError:
 764                         dbg('min will not fit into control; ignoring', indent=0)
 765                         raise
 766                 dbg('accepted min')
 767                 self._min = min
 768             else:
 769                 dbg('ignoring min')
 770
 771
 772         if kwargs.has_key('max'):
 773             max = kwargs['max']
 774             if( self._min is None
 775                 or max is None
 776                 or (self._min is not None and self._min <= max) ):
 777                 dbg('examining max')
 778                 if max is not None:
 779                     try:
 780                         textmax = self._toGUI(max, apply_limits = False)
 781                     except ValueError:
 782                         dbg('max will not fit into control; ignoring', indent=0)
 783                         raise
 784                 dbg('accepted max')
 785                 self._max = max
 786             else:
 787                 dbg('ignoring max')
 788
 789         if kwargs.has_key('allowNegative'):
 790             self._allowNegative = kwargs['allowNegative']
 791
 792         # Ensure current value of control obeys any new restrictions imposed:
 793         text = self._GetValue()
 794         dbg('text value: "%s"' % text)
 795         if kwargs.has_key('groupChar') and text.find(old_groupchar) != -1:
 796             text = text.replace(old_groupchar, self._groupChar)
 797         if kwargs.has_key('decimalChar') and text.find(old_decimalchar) != -1:
 798             text = text.replace(old_decimalchar, self._decimalChar)
 799         if text != self._GetValue():
 800             wx.TextCtrl.SetValue(self, text)
 801
 802         value = self.GetValue()
 803
 804         dbg('self._allowNegative?', self._allowNegative)
 805         if not self._allowNegative and self._isNeg:
 806             value = abs(value)
 807             dbg('abs(value):', value)
 808             self._isNeg = False
 809
 810         elif not self._allowNone and BaseMaskedTextCtrl.GetValue(self) == '':
 811             if self._min > 0:
 812                 value = self._min
 813             else:
 814                 value = 0
 815
 816         sel_start, sel_to = self.GetSelection()
 817         if self.IsLimited() and self._min is not None and value < self._min:
 818             dbg('Set to min value:', self._min)
 819             self._SetValue(self._toGUI(self._min))
 820
 821         elif self.IsLimited() and self._max is not None and value > self._max:
 822             dbg('Setting to max value:', self._max)
 823             self._SetValue(self._toGUI(self._max))
 824         else:
 825             # reformat current value as appropriate to possibly new conditions
 826             dbg('Reformatting value:', value)
 827             sel_start, sel_to = self.GetSelection()
 828             self._SetValue(self._toGUI(value))
 829         self.Refresh() # recolor as appropriate
 830         dbg('finished MaskedNumCtrl::SetParameters', indent=0)
 831
 832
 833
 834     def _GetNumValue(self, value):
 835         """
 836         This function attempts to "clean up" a text value, providing a regularized
 837         convertable string, via atol() or atof(), for any well-formed numeric text value.
 838         """
 839         return value.replace(self._groupChar, '').replace(self._decimalChar, '.').replace('(', '-').replace(')','').strip()
 840
 841
 842     def GetFraction(self, candidate=None):
 843         """
 844         Returns the fractional portion of the value as a float.  If there is no
 845         fractional portion, the value returned will be 0.0.
 846         """
 847         if not self._fractionWidth:
 848             return 0.0
 849         else:
 850             fracstart, fracend = self._fields[1]._extent
 851             if candidate is None:
 852                 value = self._toGUI(BaseMaskedTextCtrl.GetValue(self))
 853             else:
 854                 value = self._toGUI(candidate)
 855             fracstring = value[fracstart:fracend].strip()
 856             if not value:
 857                 return 0.0
 858             else:
 859                 return string.atof(fracstring)
 860
 861     def _OnChangeSign(self, event):
 862         dbg('MaskedNumCtrl::_OnChangeSign', indent=1)
 863         self._typedSign = True
 864         MaskedEditMixin._OnChangeSign(self, event)
 865         dbg(indent=0)
 866
 867
 868     def _disallowValue(self):
 869         dbg('MaskedNumCtrl::_disallowValue')
 870         # limited and -1 is out of bounds
 871         if self._typedSign:
 872             self._isNeg = False
 873         if not wx.Validator_IsSilent():
 874             wx.Bell()
 875         sel_start, sel_to = self._GetSelection()
 876         dbg('queuing reselection of (%d, %d)' % (sel_start, sel_to))
 877         wx.CallAfter(self.SetInsertionPoint, sel_start)      # preserve current selection/position
 878         wx.CallAfter(self.SetSelection, sel_start, sel_to)
 879
 880     def _SetValue(self, value):
 881         """
 882         This routine supersedes the base masked control _SetValue().  It is
 883         needed to ensure that the value of the control is always representable/convertable
 884         to a numeric return value (via GetValue().)  This routine also handles
 885         automatic adjustment and grouping of the value without explicit intervention
 886         by the user.
 887         """
 888
 889         dbg('MaskedNumCtrl::_SetValue("%s")' % value, indent=1)
 890
 891         if( (self._fractionWidth and value.find(self._decimalChar) == -1) or
 892             (self._fractionWidth == 0 and value.find(self._decimalChar) != -1) ) :
 893             value = self._toGUI(value)
 894
 895         numvalue = self._GetNumValue(value)
 896         dbg('cleansed value: "%s"' % numvalue)
 897         replacement = None
 898
 899         if numvalue == "":
 900             if self._allowNone:
 901                 dbg('calling base BaseMaskedTextCtrl._SetValue(self, "%s")' % value)
 902                 BaseMaskedTextCtrl._SetValue(self, value)
 903                 self.Refresh()
 904                 return
 905             elif self._min > 0 and self.IsLimited():
 906                 replacement = self._min
 907             else:
 908                 replacement = 0
 909             dbg('empty value; setting replacement:', replacement)
 910
 911         if replacement is None:
 912             # Go get the integer portion about to be set and verify its validity
 913             intstart, intend = self._fields[0]._extent
 914             dbg('intstart, intend:', intstart, intend)
 915             dbg('raw integer:"%s"' % value[intstart:intend])
 916             int = self._GetNumValue(value[intstart:intend])
 917             numval = self._fromGUI(value)
 918
 919             dbg('integer: "%s"' % int)
 920             try:
 921                 fracval = self.GetFraction(value)
 922             except ValueError, e:
 923                 dbg('Exception:', e, 'must be out of bounds; disallow value')
 924                 self._disallowValue()
 925                 dbg(indent=0)
 926                 return
 927
 928             if fracval == 0.0:
 929                 dbg('self._isNeg?', self._isNeg)
 930                 if int == '-' and self._oldvalue < 0 and not self._typedSign:
 931                     dbg('just a negative sign; old value < 0; setting replacement of 0')
 932                     replacement = 0
 933                     self._isNeg = False
 934                 elif int[:2] == '-0' and self._fractionWidth == 0:
 935                     if self._oldvalue < 0:
 936                         dbg('-0; setting replacement of 0')
 937                         replacement = 0
 938                         self._isNeg = False
 939                     elif not self._limited or (self._min < -1 and self._max >= -1):
 940                         dbg('-0; setting replacement of -1')
 941                         replacement = -1
 942                         self._isNeg = True
 943                     else:
 944                         # limited and -1 is out of bounds
 945                         self._disallowValue()
 946                         dbg(indent=0)
 947                         return
 948
 949                 elif int == '-' and (self._oldvalue >= 0 or self._typedSign) and self._fractionWidth == 0:
 950                     if not self._limited or (self._min < -1 and self._max >= -1):
 951                         dbg('just a negative sign; setting replacement of -1')
 952                         replacement = -1
 953                     else:
 954                         # limited and -1 is out of bounds
 955                         self._disallowValue()
 956                         dbg(indent=0)
 957                         return
 958
 959                 elif( self._typedSign
 960                       and int.find('-') != -1
 961                       and self._limited
 962                       and not self._min <= numval <= self._max):
 963                     # changed sign resulting in value that's now out-of-bounds;
 964                     # disallow
 965                     self._disallowValue()
 966                     dbg(indent=0)
 967                     return
 968
 969             if replacement is None:
 970                 if int and int != '-':
 971                     try:
 972                         string.atol(int)
 973                     except ValueError:
 974                         # integer requested is not legal.  This can happen if the user
 975                         # is attempting to insert a digit in the middle of the control
 976                         # resulting in something like "   3   45". Disallow such actions:
 977                         dbg('>>>>>>>>>>>>>>>> "%s" does not convert to a long!' % int)
 978                         if not wx.Validator_IsSilent():
 979                             wx.Bell()
 980                         sel_start, sel_to = self._GetSelection()
 981                         dbg('queuing reselection of (%d, %d)' % (sel_start, sel_to))
 982                         wx.CallAfter(self.SetInsertionPoint, sel_start)      # preserve current selection/position
 983                         wx.CallAfter(self.SetSelection, sel_start, sel_to)
 984                         dbg(indent=0)
 985                         return
 986
 987                     if int[0] == '0' and len(int) > 1:
 988                         dbg('numvalue: "%s"' % numvalue.replace(' ', ''))
 989                         if self._fractionWidth:
 990                             value = self._toGUI(string.atof(numvalue))
 991                         else:
 992                             value = self._toGUI(string.atol(numvalue))
 993                         dbg('modified value: "%s"' % value)
 994
 995         self._typedSign = False     # reset state var
 996
 997         if replacement is not None:
 998             # Value presented wasn't a legal number, but control should do something
 999             # reasonable instead:
1000             dbg('setting replacement value:', replacement)
1001             self._SetValue(self._toGUI(replacement))
1002             sel_start = BaseMaskedTextCtrl.GetValue(self).find(str(abs(replacement)))   # find where it put the 1, so we can select it
1003             sel_to = sel_start + len(str(abs(replacement)))
1004             dbg('queuing selection of (%d, %d)' %(sel_start, sel_to))
1005             wx.CallAfter(self.SetInsertionPoint, sel_start)
1006             wx.CallAfter(self.SetSelection, sel_start, sel_to)
1007             dbg(indent=0)
1008             return
1009
1010         # Otherwise, apply appropriate formatting to value:
1011
1012         # Because we're intercepting the value and adjusting it
1013         # before a sign change is detected, we need to do this here:
1014         if '-' in value or '(' in value:
1015             self._isNeg = True
1016         else:
1017             self._isNeg = False
1018
1019         dbg('value:"%s"' % value, 'self._useParens:', self._useParens)
1020         if self._fractionWidth:
1021             adjvalue = self._adjustFloat(self._GetNumValue(value).replace('.',self._decimalChar))
1022         else:
1023             adjvalue = self._adjustInt(self._GetNumValue(value))
1024         dbg('adjusted value: "%s"' % adjvalue)
1025
1026
1027         sel_start, sel_to = self._GetSelection()     # record current insertion point
1028         dbg('calling BaseMaskedTextCtrl._SetValue(self, "%s")' % adjvalue)
1029         BaseMaskedTextCtrl._SetValue(self, adjvalue)
1030         # After all actions so far scheduled, check that resulting cursor
1031         # position is appropriate, and move if not:
1032         wx.CallAfter(self._CheckInsertionPoint)
1033
1034         dbg('finished MaskedNumCtrl::_SetValue', indent=0)
1035
1036     def _CheckInsertionPoint(self):
1037         # If current insertion point is before the end of the integer and
1038         # its before the 1st digit, place it just after the sign position:
1039         dbg('MaskedNumCtrl::CheckInsertionPoint', indent=1)
1040         sel_start, sel_to = self._GetSelection()
1041         text = self._GetValue()
1042         if sel_to < self._fields[0]._extent[1] and text[sel_to] in (' ', '-', '('):
1043             text, signpos, right_signpos = self._getSignedValue()
1044             dbg('setting selection(%d, %d)' % (signpos+1, signpos+1))
1045             self.SetInsertionPoint(signpos+1)
1046             self.SetSelection(signpos+1, signpos+1)
1047         dbg(indent=0)
1048
1049
1050     def _OnErase( self, event ):
1051         """
1052         This overrides the base control _OnErase, so that erasing around
1053         grouping characters auto selects the digit before or after the
1054         grouping character, so that the erasure does the right thing.
1055         """
1056         dbg('MaskedNumCtrl::_OnErase', indent=1)
1057
1058         #if grouping digits, make sure deletes next to group char always
1059         # delete next digit to appropriate side:
1060         if self._groupDigits:
1061             key = event.GetKeyCode()
1062             value = BaseMaskedTextCtrl.GetValue(self)
1063             sel_start, sel_to = self._GetSelection()
1064
1065             if key == wx.WXK_BACK:
1066                 # if 1st selected char is group char, select to previous digit
1067                 if sel_start > 0 and sel_start < len(self._mask) and value[sel_start:sel_to] == self._groupChar:
1068                     self.SetInsertionPoint(sel_start-1)
1069                     self.SetSelection(sel_start-1, sel_to)
1070
1071                 # elif previous char is group char, select to previous digit
1072                 elif sel_start > 1 and sel_start == sel_to and value[sel_start-1:sel_start] == self._groupChar:
1073                     self.SetInsertionPoint(sel_start-2)
1074                     self.SetSelection(sel_start-2, sel_to)
1075
1076             elif key == wx.WXK_DELETE:
1077                 if( sel_to < len(self._mask) - 2 + (1 *self._useParens)
1078                     and sel_start == sel_to
1079                     and value[sel_to] == self._groupChar ):
1080                     self.SetInsertionPoint(sel_start)
1081                     self.SetSelection(sel_start, sel_to+2)
1082
1083                 elif( sel_to < len(self._mask) - 2 + (1 *self._useParens)
1084                            and value[sel_start:sel_to] == self._groupChar ):
1085                     self.SetInsertionPoint(sel_start)
1086                     self.SetSelection(sel_start, sel_to+1)
1087
1088         BaseMaskedTextCtrl._OnErase(self, event)
1089         dbg(indent=0)
1090
1091
1092     def OnTextChange( self, event ):
1093         """
1094         Handles an event indicating that the text control's value
1095         has changed, and issue EVT_MaskedNum event.
1096         NOTE: using wxTextCtrl.SetValue() to change the control's
1097         contents from within a EVT_CHAR handler can cause double
1098         text events.  So we check for actual changes to the text
1099         before passing the events on.
1100         """
1101         dbg('MaskedNumCtrl::OnTextChange', indent=1)
1102         if not BaseMaskedTextCtrl._OnTextChange(self, event):
1103             dbg(indent=0)
1104             return
1105
1106         # else... legal value
1107
1108         value = self.GetValue()
1109         if value != self._oldvalue:
1110             try:
1111                 self.GetEventHandler().ProcessEvent(
1112                     MaskedNumNumberUpdatedEvent( self.GetId(), self.GetValue(), self ) )
1113             except ValueError:
1114                 dbg(indent=0)
1115                 return
1116             # let normal processing of the text continue
1117             event.Skip()
1118         self._oldvalue = value # record for next event
1119         dbg(indent=0)
1120
1121     def _GetValue(self):
1122         """
1123         Override of BaseMaskedTextCtrl to allow mixin to get the raw text value of the
1124         control with this function.
1125         """
1126         return wx.TextCtrl.GetValue(self)
1127
1128
1129     def GetValue(self):
1130         """
1131         Returns the current numeric value of the control.
1132         """
1133         return self._fromGUI( BaseMaskedTextCtrl.GetValue(self) )
1134
1135     def SetValue(self, value):
1136         """
1137         Sets the value of the control to the value specified.
1138         The resulting actual value of the control may be altered to
1139         conform with the bounds set on the control if limited,
1140         or colored if not limited but the value is out-of-bounds.
1141         A ValueError exception will be raised if an invalid value
1142         is specified.
1143         """
1144         BaseMaskedTextCtrl.SetValue( self, self._toGUI(value) )
1145
1146
1147     def SetIntegerWidth(self, value):
1148         self.SetParameters(integerWidth=value)
1149     def GetIntegerWidth(self):
1150         return self._integerWidth
1151
1152     def SetFractionWidth(self, value):
1153         self.SetParameters(fractionWidth=value)
1154     def GetFractionWidth(self):
1155         return self._fractionWidth
1156
1157
1158
1159     def SetMin(self, min=None):
1160         """
1161         Sets the minimum value of the control.  If a value of None
1162         is provided, then the control will have no explicit minimum value.
1163         If the value specified is greater than the current maximum value,
1164         then the function returns False and the minimum will not change from
1165         its current setting.  On success, the function returns True.
1166
1167         If successful and the current value is lower than the new lower
1168         bound, if the control is limited, the value will be automatically
1169         adjusted to the new minimum value; if not limited, the value in the
1170         control will be colored as invalid.
1171
1172         If min > the max value allowed by the width of the control,
1173         the function will return False, and the min will not be set.
1174         """
1175         dbg('MaskedNumCtrl::SetMin(%s)' % repr(min), indent=1)
1176         if( self._max is None
1177             or min is None
1178             or (self._max is not None and self._max >= min) ):
1179             try:
1180                 self.SetParameters(min=min)
1181                 bRet = True
1182             except ValueError:
1183                 bRet = False
1184         else:
1185             bRet = False
1186         dbg(indent=0)
1187         return bRet
1188
1189     def GetMin(self):
1190         """
1191         Gets the lower bound value of the control.  It will return
1192         None if not specified.
1193         """
1194         return self._min
1195
1196
1197     def SetMax(self, max=None):
1198         """
1199         Sets the maximum value of the control. If a value of None
1200         is provided, then the control will have no explicit maximum value.
1201         If the value specified is less than the current minimum value, then
1202         the function returns False and the maximum will not change from its
1203         current setting. On success, the function returns True.
1204
1205         If successful and the current value is greater than the new upper
1206         bound, if the control is limited the value will be automatically
1207         adjusted to this maximum value; if not limited, the value in the
1208         control will be colored as invalid.
1209
1210         If max > the max value allowed by the width of the control,
1211         the function will return False, and the max will not be set.
1212         """
1213         if( self._min is None
1214             or max is None
1215             or (self._min is not None and self._min <= max) ):
1216             try:
1217                 self.SetParameters(max=max)
1218                 bRet = True
1219             except ValueError:
1220                 bRet = False
1221         else:
1222             bRet = False
1223
1224         return bRet
1225
1226
1227     def GetMax(self):
1228         """
1229         Gets the maximum value of the control.  It will return the current
1230         maximum integer, or None if not specified.
1231         """
1232         return self._max
1233
1234
1235     def SetBounds(self, min=None, max=None):
1236         """
1237         This function is a convenience function for setting the min and max
1238         values at the same time.  The function only applies the maximum bound
1239         if setting the minimum bound is successful, and returns True
1240         only if both operations succeed.
1241         NOTE: leaving out an argument will remove the corresponding bound.
1242         """
1243         ret = self.SetMin(min)
1244         return ret and self.SetMax(max)
1245
1246
1247     def GetBounds(self):
1248         """
1249         This function returns a two-tuple (min,max), indicating the
1250         current bounds of the control.  Each value can be None if
1251         that bound is not set.
1252         """
1253         return (self._min, self._max)
1254
1255
1256     def SetLimited(self, limited):
1257         """
1258         If called with a value of True, this function will cause the control
1259         to limit the value to fall within the bounds currently specified.
1260         If the control's value currently exceeds the bounds, it will then
1261         be limited accordingly.
1262
1263         If called with a value of False, this function will disable value
1264         limiting, but coloring of out-of-bounds values will still take
1265         place if bounds have been set for the control.
1266         """
1267         self.SetParameters(limited = limited)
1268
1269
1270     def IsLimited(self):
1271         """
1272         Returns True if the control is currently limiting the
1273         value to fall within the current bounds.
1274         """
1275         return self._limited
1276
1277     def GetLimited(self):
1278         """ (For regularization of property accessors) """
1279         return self.IsLimited
1280
1281
1282     def IsInBounds(self, value=None):
1283         """
1284         Returns True if no value is specified and the current value
1285         of the control falls within the current bounds.  This function can
1286         also be called with a value to see if that value would fall within
1287         the current bounds of the given control.
1288         """
1289         dbg('IsInBounds(%s)' % repr(value), indent=1)
1290         if value is None:
1291             value = self.GetValue()
1292         else:
1293             try:
1294                 value = self._GetNumValue(self._toGUI(value))
1295             except ValueError, e:
1296                 dbg('error getting NumValue(self._toGUI(value)):', e, indent=0)
1297                 return False
1298             if value.strip() == '':
1299                 value = None
1300             elif self._fractionWidth:
1301                 value = float(value)
1302             else:
1303                 value = long(value)
1304
1305         min = self.GetMin()
1306         max = self.GetMax()
1307         if min is None: min = value
1308         if max is None: max = value
1309
1310         # if bounds set, and value is None, return False
1311         if value == None and (min is not None or max is not None):
1312             dbg('finished IsInBounds', indent=0)
1313             return 0
1314         else:
1315             dbg('finished IsInBounds', indent=0)
1316             return min <= value <= max
1317
1318
1319     def SetAllowNone(self, allow_none):
1320         """
1321         Change the behavior of the validation code, allowing control
1322         to have a value of None or not, as appropriate.  If the value
1323         of the control is currently None, and allow_none is False, the
1324         value of the control will be set to the minimum value of the
1325         control, or 0 if no lower bound is set.
1326         """
1327         self._allowNone = allow_none
1328         if not allow_none and self.GetValue() is None:
1329             min = self.GetMin()
1330             if min is not None: self.SetValue(min)
1331             else:               self.SetValue(0)
1332
1333
1334     def IsNoneAllowed(self):
1335         return self._allowNone
1336     def GetAllowNone(self):
1337         """ (For regularization of property accessors) """
1338         return self.IsNoneAllowed()
1339
1340     def SetAllowNegative(self, value):
1341         self.SetParameters(allowNegative=value)
1342     def IsNegativeAllowed(self):
1343         return self._allowNegative
1344     def GetAllowNegative(self):
1345         """ (For regularization of property accessors) """
1346         return self.IsNegativeAllowed()
1347
1348     def SetGroupDigits(self, value):
1349         self.SetParameters(groupDigits=value)
1350     def IsGroupingAllowed(self):
1351         return self._groupDigits
1352     def GetGroupDigits(self):
1353         """ (For regularization of property accessors) """
1354         return self.IsGroupingAllowed()
1355
1356     def SetGroupChar(self, value):
1357         self.SetParameters(groupChar=value)
1358     def GetGroupChar(self):
1359         return self._groupChar
1360
1361     def SetDecimalChar(self, value):
1362         self.SetParameters(decimalChar=value)
1363     def GetDecimalChar(self):
1364         return self._decimalChar
1365
1366     def SetSelectOnEntry(self, value):
1367         self.SetParameters(selectOnEntry=value)
1368     def GetSelectOnEntry(self):
1369         return self._selectOnEntry
1370
1371     def SetAutoSize(self, value):
1372         self.SetParameters(autoSize=value)
1373     def GetAutoSize(self):
1374         return self._autoSize
1375
1376
1377     # (Other parameter accessors are inherited from base class)
1378
1379
1380     def _toGUI( self, value, apply_limits = True ):
1381         """
1382         Conversion function used to set the value of the control; does
1383         type and bounds checking and raises ValueError if argument is
1384         not a valid value.
1385         """
1386         dbg('MaskedNumCtrl::_toGUI(%s)' % repr(value), indent=1)
1387         if value is None and self.IsNoneAllowed():
1388             dbg(indent=0)
1389             return self._template
1390
1391         elif type(value) in (types.StringType, types.UnicodeType):
1392             value = self._GetNumValue(value)
1393             dbg('cleansed num value: "%s"' % value)
1394             if value == "":
1395                 if self.IsNoneAllowed():
1396                     dbg(indent=0)
1397                     return self._template
1398                 else:
1399                     dbg('exception raised:', e, indent=0)
1400                     raise ValueError ('wxMaskedNumCtrl requires numeric value, passed %s'% repr(value) )
1401             # else...
1402             try:
1403                 if self._fractionWidth or value.find('.') != -1:
1404                     value = float(value)
1405                 else:
1406                     value = long(value)
1407             except Exception, e:
1408                 dbg('exception raised:', e, indent=0)
1409                 raise ValueError ('MaskedNumCtrl requires numeric value, passed %s'% repr(value) )
1410
1411         elif type(value) not in (types.IntType, types.LongType, types.FloatType):
1412             dbg(indent=0)
1413             raise ValueError (
1414                 'MaskedNumCtrl requires numeric value, passed %s'% repr(value) )
1415
1416         if not self._allowNegative and value < 0:
1417             raise ValueError (
1418                 'control configured to disallow negative values, passed %s'% repr(value) )
1419
1420         if self.IsLimited() and apply_limits:
1421             min = self.GetMin()
1422             max = self.GetMax()
1423             if not min is None and value < min:
1424                 dbg(indent=0)
1425                 raise ValueError (
1426                     'value %d is below minimum value of control'% value )
1427             if not max is None and value > max:
1428                 dbg(indent=0)
1429                 raise ValueError (
1430                     'value %d exceeds value of control'% value )
1431
1432         adjustwidth = len(self._mask) - (1 * self._useParens * self._signOk)
1433         dbg('len(%s):' % self._mask, len(self._mask))
1434         dbg('adjustwidth - groupSpace:', adjustwidth - self._groupSpace)
1435         dbg('adjustwidth:', adjustwidth)
1436         if self._fractionWidth == 0:
1437             s = str(long(value)).rjust(self._integerWidth)
1438         else:
1439             format = '%' + '%d.%df' % (self._integerWidth+self._fractionWidth+1, self._fractionWidth)
1440             s = format % float(value)
1441         dbg('s:"%s"' % s, 'len(s):', len(s))
1442         if len(s) > (adjustwidth - self._groupSpace):
1443             dbg(indent=0)
1444             raise ValueError ('value %s exceeds the integer width of the control (%d)' % (s, self._integerWidth))
1445         elif s[0] not in ('-', ' ') and self._allowNegative and len(s) == (adjustwidth - self._groupSpace):
1446             dbg(indent=0)
1447             raise ValueError ('value %s exceeds the integer width of the control (%d)' % (s, self._integerWidth))
1448
1449         s = s.rjust(adjustwidth).replace('.', self._decimalChar)
1450         if self._signOk and self._useParens:
1451             if s.find('-') != -1:
1452                 s = s.replace('-', '(') + ')'
1453             else:
1454                 s += ' '
1455         dbg('returned: "%s"' % s, indent=0)
1456         return s
1457
1458
1459     def _fromGUI( self, value ):
1460         """
1461         Conversion function used in getting the value of the control.
1462         """
1463         dbg(suspend=0)
1464         dbg('MaskedNumCtrl::_fromGUI(%s)' % value, indent=1)
1465         # One or more of the underlying text control implementations
1466         # issue an intermediate EVT_TEXT when replacing the control's
1467         # value, where the intermediate value is an empty string.
1468         # So, to ensure consistency and to prevent spurious ValueErrors,
1469         # we make the following test, and react accordingly:
1470         #
1471         if value.strip() == '':
1472             if not self.IsNoneAllowed():
1473                 dbg('empty value; not allowed,returning 0', indent = 0)
1474                 if self._fractionWidth:
1475                     return 0.0
1476                 else:
1477                     return 0
1478             else:
1479                 dbg('empty value; returning None', indent = 0)
1480                 return None
1481         else:
1482             value = self._GetNumValue(value)
1483             dbg('Num value: "%s"' % value)
1484             if self._fractionWidth:
1485                 try:
1486                     dbg(indent=0)
1487                     return float( value )
1488                 except ValueError:
1489                     dbg("couldn't convert to float; returning None")
1490                     return None
1491                 else:
1492                     raise
1493             else:
1494                 try:
1495                     dbg(indent=0)
1496                     return int( value )
1497                 except ValueError:
1498                     try:
1499                        dbg(indent=0)
1500                        return long( value )
1501                     except ValueError:
1502                        dbg("couldn't convert to long; returning None")
1503                        return None
1504
1505                     else:
1506                        raise
1507                 else:
1508                     dbg('exception occurred; returning None')
1509                     return None
1510
1511
1512     def _Paste( self, value=None, raise_on_invalid=False, just_return_value=False ):
1513         """
1514         Preprocessor for base control paste; if value needs to be right-justified
1515         to fit in control, do so prior to paste:
1516         """
1517         dbg('MaskedNumCtrl::_Paste (value = "%s")' % value)
1518         if value is None:
1519             paste_text = self._getClipboardContents()
1520         else:
1521             paste_text = value
1522
1523         # treat paste as "replace number", if appropriate:
1524         sel_start, sel_to = self._GetSelection()
1525         if sel_start == sel_to or self._selectOnEntry and (sel_start, sel_to) == self._fields[0]._extent:
1526             paste_text = self._toGUI(paste_text)
1527             self._SetSelection(0, len(self._mask))
1528
1529         return MaskedEditMixin._Paste(self,
1530                                         paste_text,
1531                                         raise_on_invalid=raise_on_invalid,
1532                                         just_return_value=just_return_value)
1533
1534
1535
1536 #===========================================================================
1537
1538 if __name__ == '__main__':
1539
1540     import traceback
1541
1542     class myDialog(wx.Dialog):
1543         def __init__(self, parent, id, title,
1544             pos = wx.DefaultPosition, size = wx.DefaultSize,
1545             style = wx.DEFAULT_DIALOG_STYLE ):
1546             wx.Dialog.__init__(self, parent, id, title, pos, size, style)
1547
1548             self.int_ctrl = MaskedNumCtrl(self, wx.NewId(), size=(55,20))
1549             self.OK = wx.Button( self, wx.ID_OK, "OK")
1550             self.Cancel = wx.Button( self, wx.ID_CANCEL, "Cancel")
1551
1552             vs = wx.BoxSizer( wx.VERTICAL )
1553             vs.Add( self.int_ctrl, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
1554             hs = wx.BoxSizer( wx.HORIZONTAL )
1555             hs.Add( self.OK, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
1556             hs.Add( self.Cancel, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
1557             vs.Add(hs, 0, wx.ALIGN_CENTRE|wx.ALL, 5 )
1558
1559             self.SetAutoLayout( True )
1560             self.SetSizer( vs )
1561             vs.Fit( self )
1562             vs.SetSizeHints( self )
1563             self.Bind(EVT_MASKEDNUM, self.OnChange, self.int_ctrl)
1564
1565         def OnChange(self, event):
1566             print 'value now', event.GetValue()
1567
1568     class TestApp(wx.App):
1569         def OnInit(self):
1570             try:
1571                 self.frame = wx.Frame(None, -1, "Test", (20,20), (120,100)  )
1572                 self.panel = wx.Panel(self.frame, -1)
1573                 button = wx.Button(self.panel, -1, "Push Me", (20, 20))
1574                 self.Bind(wx.EVT_BUTTON, self.OnClick, button)
1575             except:
1576                 traceback.print_exc()
1577                 return False
1578             return True
1579
1580         def OnClick(self, event):
1581             dlg = myDialog(self.panel, -1, "test MaskedNumCtrl")
1582             dlg.int_ctrl.SetValue(501)
1583             dlg.int_ctrl.SetInsertionPoint(1)
1584             dlg.int_ctrl.SetSelection(1,2)
1585             rc = dlg.ShowModal()
1586             print 'final value', dlg.int_ctrl.GetValue()
1587             del dlg
1588             self.frame.Destroy()
1589
1590         def Show(self):
1591             self.frame.Show(True)
1592
1593     try:
1594         app = TestApp(0)
1595         app.Show()
1596         app.MainLoop()
1597     except:
1598         traceback.print_exc()
1599
1600 i=0
1601 ## To-Do's:
1602 ## =============================##
1603 ##   1. Add support for printf-style format specification.
1604 ##   2. Add option for repositioning on 'illegal' insertion point.
1605 ##
1606 ## Version 1.1
1607 ##   1. Fixed .SetIntegerWidth() and .SetFractionWidth() functions.
1608 ##   2. Added autoSize parameter, to allow manual sizing of the control.
1609 ##   3. Changed inheritance to use wxBaseMaskedTextCtrl, to remove exposure of
1610 ##      nonsensical parameter methods from the control, so it will work
1611 ##      properly with Boa.
1612 ##   4. Fixed allowNone bug found by user sameerc1@grandecom.net
1613