wxPython/wx/lib/masked/textctrl.py

   1 #----------------------------------------------------------------------------
   2 # Name:         masked.textctrl.py
   3 # Authors:      Jeff Childers, Will Sadkin
   4 # Email:        jchilders_98@yahoo.com, wsadkin@nameconnector.com
   5 # Created:      02/11/2003
   6 # Copyright:    (c) 2003 by Jeff Childers, Will Sadkin, 2003
   7 # Portions:     (c) 2002 by Will Sadkin, 2002-2003
   8 # RCS-ID:       $Id$
   9 # License:      wxWidgets license
  10 #----------------------------------------------------------------------------
  11 #
  12 # This file contains the most typically used generic masked control,
  13 # masked.TextCtrl.  It also defines the BaseMaskedTextCtrl, which can
  14 # be used to derive other "semantics-specific" classes, like masked.NumCtrl,
  15 # masked.TimeCtrl, and masked.IpAddrCtrl.
  16 #
  17 #----------------------------------------------------------------------------
  18 """
  19 Provides a generic, fully configurable masked edit text control, as well as
  20 a base class from which you can derive masked controls tailored to a specific
  21 function.  See maskededit module overview for how to configure the control.
  22 """
  23
  24 import  wx
  25 from wx.lib.masked import *
  26
  27 # jmg 12/9/03 - when we cut ties with Py 2.2 and earlier, this would
  28 # be a good place to implement the 2.3 logger class
  29 from wx.tools.dbg import Logger
  30 ##dbg = Logger()
  31 ##dbg(enable=1)
  32
  33
  34 class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ):
  35     """
  36     This is the primary derivation from MaskedEditMixin.  It provides
  37     a general masked text control that can be configured with different
  38     masks.
  39
  40     However, this is done with an extra level of inheritance, so that
  41     "general" classes like masked.TextCtrl can have all possible attributes,
  42     while derived classes, like masked.TimeCtrl and masked.NumCtrl
  43     can prevent exposure of those optional attributes of their base
  44     class that do not make sense for their derivation.  Therefore,
  45     we define::
  46
  47         BaseMaskedTextCtrl(TextCtrl, MaskedEditMixin)
  48
  49     and::
  50
  51         masked.TextCtrl(BaseMaskedTextCtrl, MaskedEditAccessorsMixin).
  52
  53     This allows us to then derive::
  54
  55         masked.NumCtrl( BaseMaskedTextCtrl )
  56
  57     and not have to expose all the same accessor functions for the
  58     derived control when they don't all make sense for it.
  59
  60     In practice, BaseMaskedTextCtrl should never be instantiated directly,
  61     but should only be used in derived classes.
  62     """
  63
  64     def __init__( self, parent, id=-1, value = '',
  65                   pos = wx.DefaultPosition,
  66                   size = wx.DefaultSize,
  67                   style = wx.TE_PROCESS_TAB,
  68                   validator=wx.DefaultValidator,     ## placeholder provided for data-transfer logic
  69                   name = 'maskedTextCtrl',
  70                   setupEventHandling = True,        ## setup event handling by default
  71                   **kwargs):
  72
  73         wx.TextCtrl.__init__(self, parent, id, value='',
  74                             pos=pos, size = size,
  75                             style=style, validator=validator,
  76                             name=name)
  77
  78         self._PostInit(setupEventHandling = setupEventHandling,
  79                       name=name, value=value,**kwargs )
  80
  81
  82     def _PostInit(self,setupEventHandling=True,
  83                  name='maskedTextCtrl' , value='', **kwargs):
  84
  85         self.controlInitialized = True
  86         MaskedEditMixin.__init__( self, name, **kwargs )
  87
  88         self._SetInitialValue(value)
  89
  90         if setupEventHandling:
  91             ## Setup event handlers
  92             self.Bind(wx.EVT_SET_FOCUS, self._OnFocus )         ## defeat automatic full selection
  93             self.Bind(wx.EVT_KILL_FOCUS, self._OnKillFocus )    ## run internal validator
  94             self.Bind(wx.EVT_LEFT_DCLICK, self._OnDoubleClick)  ## select field under cursor on dclick
  95             self.Bind(wx.EVT_RIGHT_UP, self._OnContextMenu )    ## bring up an appropriate context menu
  96             self.Bind(wx.EVT_KEY_DOWN, self._OnKeyDown )        ## capture control events not normally seen, eg ctrl-tab.
  97             self.Bind(wx.EVT_CHAR, self._OnChar )               ## handle each keypress
  98             self.Bind(wx.EVT_TEXT, self._OnTextChange )         ## color control appropriately & keep
  99                                                                 ## track of previous value for undo
 100
 101
 102     def __repr__(self):
 103         return "<BaseMaskedTextCtrl: %s>" % self.GetValue()
 104
 105
 106     def _GetSelection(self):
 107         """
 108         Allow mixin to get the text selection of this control.
 109         REQUIRED by any class derived from MaskedEditMixin.
 110         """
 111         return self.GetSelection()
 112
 113     def _SetSelection(self, sel_start, sel_to):
 114         """
 115         Allow mixin to set the text selection of this control.
 116         REQUIRED by any class derived from MaskedEditMixin.
 117         """
 118 ####        dbg("MaskedTextCtrl::_SetSelection(%(sel_start)d, %(sel_to)d)" % locals())
 119         return self.SetSelection( sel_start, sel_to )
 120
 121 ##    def SetSelection(self, sel_start, sel_to):
 122 ##        """
 123 ##        This is just for debugging...
 124 ##        """
 125 ##        dbg("MaskedTextCtrl::SetSelection(%(sel_start)d, %(sel_to)d)" % locals())
 126 ##        wx.TextCtrl.SetSelection(self, sel_start, sel_to)
 127
 128
 129     def _GetInsertionPoint(self):
 130         return self.GetInsertionPoint()
 131
 132     def _SetInsertionPoint(self, pos):
 133 ####        dbg("MaskedTextCtrl::_SetInsertionPoint(%(pos)d)" % locals())
 134         self.SetInsertionPoint(pos)
 135
 136 ##    def SetInsertionPoint(self, pos):
 137 ##        """
 138 ##        This is just for debugging...
 139 ##        """
 140 ##        dbg("MaskedTextCtrl::SetInsertionPoint(%(pos)d)" % locals())
 141 ##        wx.TextCtrl.SetInsertionPoint(self, pos)
 142
 143
 144     def IsEmpty(*args, **kw):
 145         return MaskedEditMixin.IsEmpty(*args, **kw)
 146
 147     def _GetValue(self):
 148         """
 149         Allow mixin to get the raw value of the control with this function.
 150         REQUIRED by any class derived from MaskedEditMixin.
 151         """
 152         return self.GetValue()
 153
 154
 155     def _SetValue(self, value):
 156         """
 157         Allow mixin to set the raw value of the control with this function.
 158         REQUIRED by any class derived from MaskedEditMixin.
 159         """
 160 ##        dbg('MaskedTextCtrl::_SetValue("%(value)s", use_change_value=%(use_change_value)d)' % locals(), indent=1)
 161         # Record current selection and insertion point, for undo
 162         self._prevSelection = self._GetSelection()
 163         self._prevInsertionPoint = self._GetInsertionPoint()
 164         wx.TextCtrl.SetValue(self, value)
 165 ##        dbg(indent=0)
 166
 167     def _ChangeValue(self, value):
 168         """
 169         Allow mixin to set the raw value of the control with this function without
 170         generating an event as a result. (New for masked.TextCtrl as of 2.8.4)
 171         """
 172 ##        dbg('MaskedTextCtrl::_ChangeValue("%(value)s", use_change_value=%(use_change_value)d)' % locals(), indent=1)
 173         # Record current selection and insertion point, for undo
 174         self._prevSelection = self._GetSelection()
 175         self._prevInsertionPoint = self._GetInsertionPoint()
 176         wx.TextCtrl.ChangeValue(self, value)
 177 ##        dbg(indent=0)
 178
 179     def SetValue(self, value):
 180         """
 181         This function redefines the externally accessible .SetValue() to be
 182         a smart "paste" of the text in question, so as not to corrupt the
 183         masked control.  NOTE: this must be done in the class derived
 184         from the base wx control.
 185         """
 186         self.ModifyValue(value, use_change_value=False)
 187
 188     def ChangeValue(self, value):
 189         """
 190         Provided to accomodate similar functionality added to base control in wxPython 2.7.1.1.
 191         """
 192         self.ModifyValue(value, use_change_value=True)
 193
 194
 195     def ModifyValue(self, value, use_change_value=False):
 196         """
 197         This factored function of common code does the bulk of the work for SetValue
 198         and ChangeValue.
 199         """
 200 ##        dbg('MaskedTextCtrl::ModifyValue("%(value)s", use_change_value=%(use_change_value)d)' % locals(), indent=1)
 201
 202         if not self._mask:
 203             if use_change_value:
 204                 wx.TextCtrl.ChangeValue(self, value)    # revert to base control behavior
 205             else:
 206                 wx.TextCtrl.SetValue(self, value)    # revert to base control behavior
 207             return
 208
 209         # empty previous contents, replacing entire value:
 210         self._SetInsertionPoint(0)
 211         self._SetSelection(0, self._masklength)
 212         if self._signOk and self._useParens:
 213             signpos = value.find('-')
 214             if signpos != -1:
 215                 value = value[:signpos] + '(' + value[signpos+1:].strip() + ')'
 216             elif value.find(')') == -1 and len(value) < self._masklength:
 217                 value += ' '    # add place holder for reserved space for right paren
 218
 219         if( len(value) < self._masklength                # value shorter than control
 220             and (self._isFloat or self._isInt)            # and it's a numeric control
 221             and self._ctrl_constraints._alignRight ):   # and it's a right-aligned control
 222
 223 ##            dbg('len(value)', len(value), ' < self._masklength', self._masklength)
 224             # try to intelligently "pad out" the value to the right size:
 225             value = self._template[0:self._masklength - len(value)] + value
 226             if self._isFloat and value.find('.') == -1:
 227                 value = value[1:]
 228 ##            dbg('padded value = "%s"' % value)
 229
 230         # make Set/ChangeValue behave the same as if you had typed the value in:
 231         try:
 232             value, replace_to = self._Paste(value, raise_on_invalid=True, just_return_value=True)
 233             if self._isFloat:
 234                 self._isNeg = False     # (clear current assumptions)
 235                 value = self._adjustFloat(value)
 236             elif self._isInt:
 237                 self._isNeg = False     # (clear current assumptions)
 238                 value = self._adjustInt(value)
 239             elif self._isDate and not self.IsValid(value) and self._4digityear:
 240                 value = self._adjustDate(value, fixcentury=True)
 241         except ValueError:
 242             # If date, year might be 2 digits vs. 4; try adjusting it:
 243             if self._isDate and self._4digityear:
 244                 dateparts = value.split(' ')
 245                 dateparts[0] = self._adjustDate(dateparts[0], fixcentury=True)
 246                 value = string.join(dateparts, ' ')
 247 ##                dbg('adjusted value: "%s"' % value)
 248                 value, replace_to = self._Paste(value, raise_on_invalid=True, just_return_value=True)
 249             else:
 250 ##                dbg('exception thrown', indent=0)
 251                 raise
 252         if use_change_value:
 253             self._ChangeValue(value)
 254         else:
 255             self._SetValue(value)       # note: to preserve similar capability, .SetValue()
 256                                         # does not change IsModified()
 257 ####        dbg('queuing insertion after ._Set/ChangeValue', replace_to)
 258         # set selection to last char replaced by paste
 259         wx.CallAfter(self._SetInsertionPoint, replace_to)
 260         wx.CallAfter(self._SetSelection, replace_to, replace_to)
 261 ##        dbg(indent=0)
 262
 263
 264     def SetFont(self, *args, **kwargs):
 265         """ Set the font, then recalculate control size, if appropriate. """
 266         wx.TextCtrl.SetFont(self, *args, **kwargs)
 267         if self._autofit:
 268 ##            dbg('calculated size:', self._CalcSize())
 269             self.SetClientSize(self._CalcSize())
 270             width = self.GetSize().width
 271             height = self.GetBestSize().height
 272 ##            dbg('setting client size to:', (width, height))
 273             self.SetInitialSize((width, height))
 274
 275
 276     def Clear(self):
 277         """ Blanks the current control value by replacing it with the default value."""
 278 ##        dbg("MaskedTextCtrl::Clear - value reset to default value (template)")
 279         if self._mask:
 280             self.ClearValue()
 281         else:
 282             wx.TextCtrl.Clear(self)    # else revert to base control behavior
 283
 284
 285     def _Refresh(self):
 286         """
 287         Allow mixin to refresh the base control with this function.
 288         REQUIRED by any class derived from MaskedEditMixin.
 289         """
 290 ##        dbg('MaskedTextCtrl::_Refresh', indent=1)
 291         wx.TextCtrl.Refresh(self)
 292 ##        dbg(indent=0)
 293
 294
 295     def Refresh(self):
 296         """
 297         This function redefines the externally accessible .Refresh() to
 298         validate the contents of the masked control as it refreshes.
 299         NOTE: this must be done in the class derived from the base wx control.
 300         """
 301 ##        dbg('MaskedTextCtrl::Refresh', indent=1)
 302         self._CheckValid()
 303         self._Refresh()
 304 ##        dbg(indent=0)
 305
 306
 307     def _IsEditable(self):
 308         """
 309         Allow mixin to determine if the base control is editable with this function.
 310         REQUIRED by any class derived from MaskedEditMixin.
 311         """
 312         return wx.TextCtrl.IsEditable(self)
 313
 314
 315     def Cut(self):
 316         """
 317         This function redefines the externally accessible .Cut to be
 318         a smart "erase" of the text in question, so as not to corrupt the
 319         masked control.  NOTE: this must be done in the class derived
 320         from the base wx control.
 321         """
 322         if self._mask:
 323             self._Cut()             # call the mixin's Cut method
 324         else:
 325             wx.TextCtrl.Cut(self)    # else revert to base control behavior
 326
 327
 328     def Paste(self):
 329         """
 330         This function redefines the externally accessible .Paste to be
 331         a smart "paste" of the text in question, so as not to corrupt the
 332         masked control.  NOTE: this must be done in the class derived
 333         from the base wx control.
 334         """
 335         if self._mask:
 336             self._Paste()                   # call the mixin's Paste method
 337         else:
 338             wx.TextCtrl.Paste(self, value)   # else revert to base control behavior
 339
 340
 341     def Undo(self):
 342         """
 343         This function defines the undo operation for the control. (The default
 344         undo is 1-deep.)
 345         """
 346         if self._mask:
 347             self._Undo()
 348         else:
 349             wx.TextCtrl.Undo(self)   # else revert to base control behavior
 350
 351
 352     def IsModified(self):
 353         """
 354         This function overrides the raw wx.TextCtrl method, because the
 355         masked edit mixin uses SetValue to change the value, which doesn't
 356         modify the state of this attribute.  So, the derived control keeps track
 357         on each keystroke to see if the value changes, and if so, it's been
 358         modified.
 359         """
 360         return wx.TextCtrl.IsModified(self) or self.modified
 361
 362
 363     def _CalcSize(self, size=None):
 364         """
 365         Calculate automatic size if allowed; use base mixin function.
 366         """
 367         return self._calcSize(size)
 368
 369
 370 class TextCtrl( BaseMaskedTextCtrl, MaskedEditAccessorsMixin ):
 371     """
 372     The "user-visible" masked text control; it is identical to the
 373     BaseMaskedTextCtrl class it's derived from.
 374     (This extra level of inheritance allows us to add the generic
 375     set of masked edit parameters only to this class while allowing
 376     other classes to derive from the "base" masked text control,
 377     and provide a smaller set of valid accessor functions.)
 378     See BaseMaskedTextCtrl for available methods.
 379     """
 380     pass
 381
 382
 383 class PreMaskedTextCtrl( BaseMaskedTextCtrl, MaskedEditAccessorsMixin ):
 384     """
 385     This class exists to support the use of XRC subclassing.
 386     """
 387     # This should really be wx.EVT_WINDOW_CREATE but it is not
 388     # currently delivered for native controls on all platforms, so
 389     # we'll use EVT_SIZE instead.  It should happen shortly after the
 390     # control is created as the control is set to its "best" size.
 391     _firstEventType = wx.EVT_SIZE
 392
 393     def __init__(self):
 394         pre = wx.PreTextCtrl()
 395         self.PostCreate(pre)
 396         self.Bind(self._firstEventType, self.OnCreate)
 397
 398
 399     def OnCreate(self, evt):
 400         self.Unbind(self._firstEventType)
 401         self._PostInit()
 402
 403 __i=0
 404 ## CHANGELOG:
 405 ## ====================
 406 ##  Version 1.3
 407 ##  - Added support for ChangeValue() function, similar to that of the base
 408 ##    control, added in wxPython 2.7.1.1.
 409 ##
 410 ##  Version 1.2
 411 ##  - Converted docstrings to reST format, added doc for ePyDoc.
 412 ##    removed debugging override functions.
 413 ##
 414 ##  Version 1.1
 415 ##  1. Added .SetFont() method that properly resizes control
 416 ##  2. Modified control to support construction via XRC mechanism.