diff --git a/unittests/test_lib_masked.py b/unittests/test_lib_masked.py new file mode 100644 index 00000000..81f31480 --- /dev/null +++ b/unittests/test_lib_masked.py @@ -0,0 +1,143 @@ +import imp_unittest, unittest +import wtc +import wx +import wx.lib.masked as m + +#--------------------------------------------------------------------------- + +class MaskedComboBoxTests(wtc.WidgetTestCase): + + def test_ComboBoxCtors(self): + c = m.ComboBox(self.frame, value='value', choices="one two three four".split()) + c = m.ComboBox(self.frame, -1, 'value', wx.Point(10,10), wx.Size(80,-1), + "one two three four".split(), 0) + c = m.ComboBox(self.frame, -1, "", (10,10), (80,-1), "one two three four".split(), 0) + + self.assertTrue(c.GetCount() == 4) + + #def test_ComboBoxDefaultCtor(self): + #c = m.PreMaskedComboBox(self.frame) + #c.Create(self.frame, value="value", choices="one two three four".split()) + + +#--------------------------------------------------------------------------- + +class MaskedTextCtrlTests(wtc.WidgetTestCase): + + def test_textctrlCtor(self): + t = m.TextCtrl(self.frame) + t = m.TextCtrl(self.frame, -1, "Hello") + t = m.TextCtrl(self.frame, style=wx.TE_READONLY) + t = m.TextCtrl(self.frame, style=wx.TE_PASSWORD) + t = m.TextCtrl(self.frame, style=wx.TE_MULTILINE) + + + #def test_textctrlDefaultCtor(self): + #t = m.TextCtrl() + #t.Create(self.frame) + + + def test_textctrlProperties(self): + t = m.TextCtrl(self.frame) + + t.DefaultStyle + t.NumberOfLines + t.Hint + t.InsertionPoint + t.LastPosition + t.Margins + t.StringSelection + t.Value + + +#--------------------------------------------------------------------------- + + +class MaskedNumCtrlTests(wtc.WidgetTestCase): + + def test_numctrlCtor(self): + t = m.NumCtrl(self.frame) + t = m.NumCtrl(self.frame, -1, "10") + t = m.NumCtrl(self.frame, style=wx.TE_READONLY) + + + #def test_numctrlDefaultCtor(self): + #t = m.TextCtrl() + #t.Create(self.frame) + + + def test_numctrlProperties(self): + t = m.NumCtrl(self.frame) + + t.DefaultStyle + t.NumberOfLines + t.Hint + t.InsertionPoint + t.LastPosition + t.Margins + t.StringSelection + t.Value + + +#--------------------------------------------------------------------------- + + +class MaskedTimeCtrlTests(wtc.WidgetTestCase): + + def test_timectrlCtor(self): + t = m.TimeCtrl(self.frame) + t = m.TimeCtrl(self.frame, -1, "18:00:00") + t = m.TimeCtrl(self.frame, style=wx.TE_READONLY) + + + #def test_numctrlDefaultCtor(self): + #t = m.TextCtrl() + #t.Create(self.frame) + + + def test_timectrlProperties(self): + t = m.TimeCtrl(self.frame) + + t.DefaultStyle + t.NumberOfLines + t.Hint + t.InsertionPoint + t.LastPosition + t.Margins + t.StringSelection + t.Value + + +#--------------------------------------------------------------------------- + +class MaskedIpAddrCtrlTests(wtc.WidgetTestCase): + + def test_ipaddrctrlCtor(self): + t = m.IpAddrCtrl(self.frame) + t = m.IpAddrCtrl(self.frame, -1, "128.000.000.000") + t = m.IpAddrCtrl(self.frame, style=wx.TE_READONLY) + + + #def test_ipaddrctrlDefaultCtor(self): + #t = m.IpAddrCtrl() + #t.Create(self.frame) + + + def test_ipaddrctrlProperties(self): + t = m.IpAddrCtrl(self.frame) + + t.DefaultStyle + t.NumberOfLines + t.Hint + t.InsertionPoint + t.LastPosition + t.Margins + t.StringSelection + t.Value + + +#--------------------------------------------------------------------------- + + +if __name__ == '__main__': + unittest.main() diff --git a/wx/lib/masked/combobox.py b/wx/lib/masked/combobox.py index 76da8461..e1338636 100644 --- a/wx/lib/masked/combobox.py +++ b/wx/lib/masked/combobox.py @@ -6,6 +6,9 @@ # Copyright: (c) 2003 by Will Sadkin, 2003 # RCS-ID: $Id$ # License: wxWidgets license +# +# Tags: phoenix-port, unittest, documented +# #---------------------------------------------------------------------------- # # This masked edit class allows for the semantics of masked controls @@ -85,9 +88,27 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): style = wx.CB_DROPDOWN, validator = wx.DefaultValidator, name = "maskedComboBox", - setupEventHandling = True, ## setup event handling by default): + setupEventHandling = True, **kwargs): + """ + Default class constructor. + :param Window `parent`: the window parent. Must not be ``None``; + :param integer `id`: window identifier. A value of -1 indicates a default value; + :param string `value`: value to be shown; + :param `pos`: the control position. A value of (-1, -1) indicates a default position, + chosen by either the windowing system or wxPython, depending on platform; + :type `pos`: tuple or :class:`Point` + :param `size`: the control size. A value of (-1, -1) indicates a default size, + chosen by either the windowing system or wxPython, depending on platform; + :param list `choices`: a list of valid choices; + :param integer `style`: the window style; + :param Validator `validator`: this is mainly provided for data-transfer, as control does + its own validation; + :param string `name`: the window name; + :param boolean `setupEventHandling`: setup event handling by default. + + """ kwargs['choices'] = choices ## set up maskededit to work with choice list too @@ -211,7 +232,12 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def SetFont(self, *args, **kwargs): - """ Set the font, then recalculate control size, if appropriate. """ + """ + Set the font, then recalculate control size, if appropriate. + + see :meth:`ComboBox.SetFont` for valid arguments + + """ wx.ComboBox.SetFont(self, *args, **kwargs) if self._autofit: ## dbg('calculated size:', self._CalcSize()) @@ -293,10 +319,14 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def SetValue(self, value): """ - This function redefines the externally accessible .SetValue to be - a smart "paste" of the text in question, so as not to corrupt the - masked control. NOTE: this must be done in the class derived - from the base wx control. + This function redefines the externally accessible :meth:`ComboBox.SetValue` + to be a smart "paste" of the text in question, so as not to corrupt the + masked control. + + .. note:: + + This must be done in the class derived from the base wx control. + """ ## dbg('MaskedComboBox::SetValue(%s)' % value, indent=1) if not self._mask: @@ -374,9 +404,13 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def Refresh(self): """ - This function redefines the externally accessible .Refresh() to - validate the contents of the masked control as it refreshes. - NOTE: this must be done in the class derived from the base wx control. + This function redefines the externally accessible :meth:`ComboBox.Refresh` + to validate the contents of the masked control as it refreshes. + + .. note:: + + This must be done in the class derived from the base wx control. + """ self._CheckValid() self._Refresh() @@ -392,10 +426,14 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def Cut(self): """ - This function redefines the externally accessible .Cut to be - a smart "erase" of the text in question, so as not to corrupt the - masked control. NOTE: this must be done in the class derived - from the base wx control. + This function redefines the externally accessible :meth:`ComboBox.Cut` + to be a smart "erase" of the text in question, so as not to corrupt the + masked control. + + .. note:: + + This must be done in the class derived from the base wx control. + """ if self._mask: self._Cut() # call the mixin's Cut method @@ -405,10 +443,14 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def Paste(self): """ - This function redefines the externally accessible .Paste to be - a smart "paste" of the text in question, so as not to corrupt the - masked control. NOTE: this must be done in the class derived - from the base wx control. + This function redefines the externally accessible :meth:`ComboBox.Paste` + to be a smart "paste" of the text in question, so as not to corrupt the + masked control. + + .. note:: + + This must be done in the class derived from the base wx control. + """ if self._mask: self._Paste() # call the mixin's Paste method @@ -418,8 +460,8 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def Undo(self): """ - This function defines the undo operation for the control. (The default - undo is 1-deep.) + This function defines the undo operation for the control. + (The default undo is 1-deep.) """ if not self.__readonly: if self._mask: @@ -429,11 +471,12 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def Append( self, choice, clientData=None ): """ - This base control function override is necessary so the control can keep track - of any additions to the list of choices, because wx.ComboBox doesn't have an - accessor for the choice list. The code here is the same as in the - SetParameters() mixin function, but is done for the individual value - as appended, so the list can be built incrementally without speed penalty. + This base control function override is necessary so the control can keep + track of any additions to the list of choices, because :class:`ComboBox` + doesn't have an accessor for the choice list. The code here is the same + as in the SetParameters() mixin function, but is done for the individual + value as appended, so the list can be built incrementally without speed + penalty. """ if self._mask: if type(choice) not in (types.StringType, types.UnicodeType): @@ -474,7 +517,8 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def AppendItems( self, choices ): """ - AppendItems() is handled in terms of Append, to avoid code replication. + :meth:`~lib.masked.combobox.ComboBox.AppendItems` is handled in terms + of :meth:`lib.masked.combobox.ComboBox.Append`, to avoid code replication. """ for choice in choices: self.Append(choice) @@ -482,9 +526,9 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def Clear( self ): """ - This base control function override is necessary so the derived control can - keep track of any additions to the list of choices, because wx.ComboBox - doesn't have an accessor for the choice list. + This base control function override is necessary so the derived control + can keep track of any additions to the list of choices, because + :class:`ComboBox` doesn't have an accessor for the choice list. """ if self._mask: self._choices = [] @@ -512,7 +556,7 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): if not hasattr(wx.ComboBox, 'GetMark'): def GetMark(self): """ - This function is a hack to make up for the fact that wx.ComboBox has no + This function is a hack to make up for the fact that :class:`ComboBox` has no method for returning the selected portion of its edit control. It works, but has the nasty side effect of generating lots of intermediate events. @@ -555,8 +599,11 @@ class BaseMaskedComboBox( wx.ComboBox, MaskedEditMixin ): def SetSelection(self, index): """ - Necessary override for bookkeeping on choice selection, to keep current value - current. + Necessary override for bookkeeping on choice selection, to keep current + value current. + + :param integer `index`: index to choice item to be set + """ ## dbg('MaskedComboBox::SetSelection(%d)' % index, indent=1) if self._mask: diff --git a/wx/lib/masked/ipaddrctrl.py b/wx/lib/masked/ipaddrctrl.py index 7402061e..84ed7f79 100644 --- a/wx/lib/masked/ipaddrctrl.py +++ b/wx/lib/masked/ipaddrctrl.py @@ -6,7 +6,9 @@ # Copyright: (c) 2003 by Will Sadkin, 2003 # RCS-ID: $Id$ # License: wxWidgets license -# Tags: phoenix-port, py3-port +# +# Tags: phoenix-port, py3-port, unittest, documented +# #---------------------------------------------------------------------------- # NOTE: # Masked.IpAddrCtrl is a minor modification to masked.TextCtrl, that is @@ -77,19 +79,36 @@ class IpAddrCtrl( BaseMaskedTextCtrl, IpAddrCtrlAccessorsMixin ): character, so that typing an IP address can be done naturally. """ - - def __init__( self, parent, id=-1, value = '', pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.TE_PROCESS_TAB, validator = wx.DefaultValidator, name = 'IpAddrCtrl', - setupEventHandling = True, ## setup event handling by default + setupEventHandling = True, **kwargs): + """ + Default class constructor. + + :param Window `parent`: the window parent. Must not be ``None``; + :param integer `id`: window identifier. A value of -1 indicates a default value; + :param string `value`: value to be shown; + :param `pos`: the control position. A value of (-1, -1) indicates a default position, + chosen by either the windowing system or wxPython, depending on platform; + :type `pos`: tuple or :class:`Point` + :param `size`: the control size. A value of (-1, -1) indicates a default size, + chosen by either the windowing system or wxPython, depending on platform; + :param integer `style`: the window style; + :param Validator `validator`: this is mainly provided for data-transfer, as control does + its own validation; + :param string `name`: the window name; + :param boolean `setupEventHandling`: setup event handling by default. + + """ + if not kwargs.has_key('mask'): - kwargs['mask'] = mask = "###.###.###.###" + kwargs['mask'] = mask = "###.###.###.###" if not kwargs.has_key('formatcodes'): kwargs['formatcodes'] = 'F_Sr<>' if not kwargs.has_key('validRegex'): @@ -144,7 +163,6 @@ class IpAddrCtrl( BaseMaskedTextCtrl, IpAddrCtrlAccessorsMixin ): return self._OnChangeField(event) - def GetAddress(self): """ Returns the control value, with any spaces removed. @@ -165,6 +183,9 @@ class IpAddrCtrl( BaseMaskedTextCtrl, IpAddrCtrlAccessorsMixin ): splits it into an array of 4 fields, justifies it appropriately, and inserts it into the control. Invalid values will raise a ValueError exception. + + :param string `value`: the IP address in the form '000.000.000.000' + """ ## dbg('IpAddrCtrl::SetValue(%s)' % str(value), indent=1) if type(value) not in (types.StringType, types.UnicodeType): diff --git a/wx/lib/masked/maskededit.py b/wx/lib/masked/maskededit.py index db3caf8a..5d9f565b 100644 --- a/wx/lib/masked/maskededit.py +++ b/wx/lib/masked/maskededit.py @@ -2913,7 +2913,7 @@ class MaskedEditMixin: """ Set the control's font typeface -- pass the font name as str.""" #### dbg('MaskedEditMixin::_setFont', indent=1) if not self._useFixedWidthFont: - self._font = wx.SystemSettings_GetFont(wx.SYS_DEFAULT_GUI_FONT) + self._font = wx.SystemSettings.GetFont(wx.SYS_DEFAULT_GUI_FONT) else: font = self.GetFont() # get size, weight, etc from current font points = font.GetPointSize() diff --git a/wx/lib/masked/numctrl.py b/wx/lib/masked/numctrl.py index c5c7f38a..56b1cda1 100644 --- a/wx/lib/masked/numctrl.py +++ b/wx/lib/masked/numctrl.py @@ -5,7 +5,9 @@ # Copyright: (c) 2003-2007 by Will Sadkin # RCS-ID: $Id$ # License: wxWidgets license -# Tags: phoenix-port, py3-port +# +# Tags: phoenix-port, py3-port, unittest, documented +# #---------------------------------------------------------------------------- # NOTE: # This was written to provide a numeric edit control for wxPython that @@ -518,7 +520,24 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): style = wx.TE_PROCESS_TAB, validator = wx.DefaultValidator, name = "masked.num", **kwargs ): + """ + Default class constructor. + :param Window `parent`: the window parent. Must not be ``None``; + :param integer `id`: window identifier. A value of -1 indicates a default value; + :param integer `value`: value to be shown; + :param `pos`: the control position. A value of (-1, -1) indicates a default position, + chosen by either the windowing system or wxPython, depending on platform; + :type `pos`: tuple or :class:`Point` + :param `size`: the control size. A value of (-1, -1) indicates a default size, + chosen by either the windowing system or wxPython, depending on platform; + :param integer `style`: the window style; + :param Validator `validator`: this is mainly provided for data-transfer, as control does + its own validation; + :param string `name`: the window name; + + """ + ## dbg('masked.NumCtrl::__init__', indent=1) # Set defaults for control: @@ -634,7 +653,8 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): def SetParameters(self, **kwargs): """ This function is used to initialize and reconfigure the control. - See TimeCtrl module overview for available parameters. + See :class:`~lib.masked.timectrl.TimeCtrl` module overview for available + parameters. """ ## dbg('NumCtrl::SetParameters', indent=1) maskededit_kwargs = {} @@ -919,7 +939,7 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): def GetFraction(self, candidate=None): """ - Returns the fractional portion of the value as a float. If there is no + Returns the fractional portion of the value as a float. If there is no fractional portion, the value returned will be 0.0. """ if not self._fractionWidth: @@ -1230,10 +1250,12 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): """ Handles an event indicating that the text control's value has changed, and issue EVT_NUM event. - NOTE: using wxTextCtrl.SetValue() to change the control's - contents from within a EVT_CHAR handler can cause double - text events. So we check for actual changes to the text - before passing the events on. + + .. note:: + + Using :meth:`TextCtrl.SetValue` to change the control's contents from + within a EVT_CHAR handler can cause double text events. So we check + for actual changes to the text before passing the events on. """ ## dbg('NumCtrl::OnTextChange', indent=1) if not BaseMaskedTextCtrl._OnTextChange(self, event): @@ -1277,6 +1299,9 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): or colored if not limited but the value is out-of-bounds. A ValueError exception will be raised if an invalid value is specified. + + :param integer `value`: new value + """ ## dbg('NumCtrl::SetValue(%s)' % value, indent=1) BaseMaskedTextCtrl.SetValue( self, self._toGUI(value) ) @@ -1290,26 +1315,47 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): or colored if not limited but the value is out-of-bounds. A ValueError exception will be raised if an invalid value is specified. + + This method does not fire a change event. + + :param integer `value`: new value + """ ## dbg('NumCtrl::ChangeValue(%s)' % value, indent=1) BaseMaskedTextCtrl.ChangeValue( self, self._toGUI(value) ) ## dbg(indent=0) - - def SetIntegerWidth(self, value): + """ + Set the integer width of the control + + :param integer `value`: the width value + + """ self.SetParameters(integerWidth=value) + def GetIntegerWidth(self): + """ + Get the integer width. + """ return self._integerWidth def SetFractionWidth(self, value): + """ + Set the fraction width of the control + + :param integer `value`: the width value + + """ self.SetParameters(fractionWidth=value) + def GetFractionWidth(self): + """ + Get the fraction width. + """ return self._fractionWidth - - def SetMin(self, min=None): """ Sets the minimum value of the control. If a value of None @@ -1325,6 +1371,10 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): If min > the max value allowed by the width of the control, the function will return False, and the min will not be set. + + :param `min`: Minium value for the control + :type `min`: integer or None + """ ## dbg('NumCtrl::SetMin(%s)' % repr(min), indent=1) if( self._max is None @@ -1347,7 +1397,6 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): """ return self._min - def SetMax(self, max=None): """ Sets the maximum value of the control. If a value of None @@ -1363,6 +1412,10 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): If max > the max value allowed by the width of the control, the function will return False, and the max will not be set. + + :param `max`: Minium value for the control + :type `max`: integer or None + """ if( self._min is None or max is None @@ -1377,7 +1430,6 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): return bRet - def GetMax(self): """ Gets the maximum value of the control. It will return the current @@ -1385,14 +1437,20 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): """ return self._max - def SetBounds(self, min=None, max=None): """ This function is a convenience function for setting the min and max values at the same time. The function only applies the maximum bound if setting the minimum bound is successful, and returns True only if both operations succeed. - NOTE: leaving out an argument will remove the corresponding bound. + + .. note:: leaving out an argument will remove the corresponding bound. + + :param `min`: Minium value for the control + :type `min`: integer or None + :param `max`: Minium value for the control + :type `max`: integer or None + """ ret = self.SetMin(min) return ret and self.SetMax(max) @@ -1417,6 +1475,9 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): If called with a value of False, this function will disable value limiting, but coloring of out-of-bounds values will still take place if bounds have been set for the control. + + :param boolean `limited`: define value limiting + """ self.SetParameters(limited = limited) @@ -1442,6 +1503,9 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): If called with a value of False, this function will disable value limiting, but coloring of out-of-bounds values will still take place if bounds have been set for the control. + + :param boolean `limit`: define value limiting + """ self.SetParameters(limitOnFieldChange = limit) @@ -1464,6 +1528,9 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): of the control falls within the current bounds. This function can also be called with a value to see if that value would fall within the current bounds of the given control. + + :param `value`: value to check + """ ## dbg('IsInBounds(%s)' % repr(value), indent=1) if value is None: @@ -1502,6 +1569,9 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): of the control is currently None, and allow_none is False, the value of the control will be set to the minimum value of the control, or 0 if no lower bound is set. + + :param boolean `allow_none`: True if None is allowed + """ self._allowNone = allow_none if not allow_none and self.GetValue() is None: @@ -1512,50 +1582,57 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): def IsNoneAllowed(self): return self._allowNone + def GetAllowNone(self): """ (For regularization of property accessors) """ return self.IsNoneAllowed() def SetAllowNegative(self, value): self.SetParameters(allowNegative=value) + def IsNegativeAllowed(self): return self._allowNegative + def GetAllowNegative(self): """ (For regularization of property accessors) """ return self.IsNegativeAllowed() def SetGroupDigits(self, value): self.SetParameters(groupDigits=value) + def IsGroupingAllowed(self): return self._groupDigits + def GetGroupDigits(self): """ (For regularization of property accessors) """ return self.IsGroupingAllowed() def SetGroupChar(self, value): self.SetParameters(groupChar=value) + def GetGroupChar(self): return self._groupChar def SetDecimalChar(self, value): self.SetParameters(decimalChar=value) + def GetDecimalChar(self): return self._decimalChar def SetSelectOnEntry(self, value): self.SetParameters(selectOnEntry=value) + def GetSelectOnEntry(self): return self._selectOnEntry def SetAutoSize(self, value): self.SetParameters(autoSize=value) + def GetAutoSize(self): return self._autoSize - # (Other parameter accessors are inherited from base class) - def _toGUI( self, value, apply_limits = True ): """ Conversion function used to set the value of the control; does @@ -1676,13 +1753,13 @@ class NumCtrl(BaseMaskedTextCtrl, NumCtrlAccessorsMixin): except ValueError: try: ## dbg(indent=0) - return long( value ) + return long( value ) except ValueError: ## dbg("couldn't convert to long; returning None") - return None + return None else: - raise + raise else: ## dbg('exception occurred; returning None') return None diff --git a/wx/lib/masked/textctrl.py b/wx/lib/masked/textctrl.py index 727f4484..bbda29f5 100644 --- a/wx/lib/masked/textctrl.py +++ b/wx/lib/masked/textctrl.py @@ -14,6 +14,8 @@ # be used to derive other "semantics-specific" classes, like masked.NumCtrl, # masked.TimeCtrl, and masked.IpAddrCtrl. # +# Tags: phoenix-port, unittest, documented +# #---------------------------------------------------------------------------- """ Provides a generic, fully configurable masked edit text control, as well as @@ -65,10 +67,28 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): pos = wx.DefaultPosition, size = wx.DefaultSize, style = wx.TE_PROCESS_TAB, - validator=wx.DefaultValidator, ## placeholder provided for data-transfer logic + validator=wx.DefaultValidator, name = 'maskedTextCtrl', - setupEventHandling = True, ## setup event handling by default + setupEventHandling = True, **kwargs): + """ + Default class constructor. + + :param Window `parent`: the window parent. Must not be ``None``; + :param integer `id`: window identifier. A value of -1 indicates a default value; + :param string `value`: value to be shown; + :param `pos`: the control position. A value of (-1, -1) indicates a default position, + chosen by either the windowing system or wxPython, depending on platform; + :type `pos`: tuple or :class:`Point` + :param `size`: the control size. A value of (-1, -1) indicates a default size, + chosen by either the windowing system or wxPython, depending on platform; + :param integer `style`: the window style; + :param Validator `validator`: this is mainly provided for data-transfer, as control does + its own validation; + :param string `name`: the window name; + :param boolean `setupEventHandling`: setup event handling by default. + + """ if not hasattr(self, 'this'): wx.TextCtrl.__init__(self, parent, id, value='', @@ -181,24 +201,36 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): def SetValue(self, value): """ - This function redefines the externally accessible .SetValue() to be - a smart "paste" of the text in question, so as not to corrupt the - masked control. NOTE: this must be done in the class derived - from the base wx control. + This function redefines the externally accessible :meth:`TextCtrl.SetValue` + to be a smart "paste" of the text in question, so as not to corrupt the + masked control. + + .. note:: + + This must be done in the class derived from the base wx control. """ self.ModifyValue(value, use_change_value=False) def ChangeValue(self, value): """ - Provided to accomodate similar functionality added to base control in wxPython 2.7.1.1. + Provided to accomodate similar functionality added to base + control in wxPython 2.7.1.1. + + :param string `value`: new value for control, this will not fire an event + """ self.ModifyValue(value, use_change_value=True) def ModifyValue(self, value, use_change_value=False): """ - This factored function of common code does the bulk of the work for SetValue - and ChangeValue. + This factored function of common code does the bulk of the work for + SetValue and ChangeValue. + + :param string `value`: new value for control + :param boolean `use_change_value`: if True uses + :meth:`~lib.masked.textctrl.TextCtrl.ChangeValue` + """ ## dbg('MaskedTextCtrl::ModifyValue("%(value)s", use_change_value=%(use_change_value)d)' % locals(), indent=1) @@ -265,7 +297,11 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): def SetFont(self, *args, **kwargs): - """ Set the font, then recalculate control size, if appropriate. """ + """ + Set the font, then recalculate control size, if appropriate. + + see :meth:`TextCtrl.SetFont` for valid arguements + """ wx.TextCtrl.SetFont(self, *args, **kwargs) if self._autofit: ## dbg('calculated size:', self._CalcSize()) @@ -277,7 +313,9 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): def Clear(self): - """ Blanks the current control value by replacing it with the default value.""" + """ + Blanks the current control value by replacing it with the default value. + """ ## dbg("MaskedTextCtrl::Clear - value reset to default value (template)") if self._mask: self.ClearValue() @@ -297,9 +335,12 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): def Refresh(self): """ - This function redefines the externally accessible .Refresh() to - validate the contents of the masked control as it refreshes. - NOTE: this must be done in the class derived from the base wx control. + This function redefines the externally accessible :meth:`TextCtrl.Refresh` + to validate the contents of the masked control as it refreshes. + + .. note:: + + This must be done in the class derived from the base wx control. """ ## dbg('MaskedTextCtrl::Refresh', indent=1) self._CheckValid() @@ -317,10 +358,14 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): def Cut(self): """ - This function redefines the externally accessible .Cut to be - a smart "erase" of the text in question, so as not to corrupt the - masked control. NOTE: this must be done in the class derived - from the base wx control. + This function redefines the externally accessible :meth:`TextCtrl.Cut` + to be a smart "erase" of the text in question, so as not to corrupt the + masked control. + + .. note:: + + This must be done in the class derived from the base wx control. + """ if self._mask: self._Cut() # call the mixin's Cut method @@ -330,10 +375,14 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): def Paste(self): """ - This function redefines the externally accessible .Paste to be - a smart "paste" of the text in question, so as not to corrupt the - masked control. NOTE: this must be done in the class derived - from the base wx control. + This function redefines the externally accessible :meth:`TextCtrl.Paste` + to be a smart "paste" of the text in question, so as not to corrupt the + masked control. + + .. note:: + + This must be done in the class derived from the base wx control. + """ if self._mask: self._Paste() # call the mixin's Paste method @@ -343,8 +392,8 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): def Undo(self): """ - This function defines the undo operation for the control. (The default - undo is 1-deep.) + This function defines the undo operation for the control. + (The default undo is 1-deep.) """ if self._mask: self._Undo() @@ -354,11 +403,11 @@ class BaseMaskedTextCtrl( wx.TextCtrl, MaskedEditMixin ): def IsModified(self): """ - This function overrides the raw wx.TextCtrl method, because the - masked edit mixin uses SetValue to change the value, which doesn't - modify the state of this attribute. So, the derived control keeps track - on each keystroke to see if the value changes, and if so, it's been - modified. + This function overrides the raw :meth:`TextCtrl.IsModified` method, + because the masked edit mixin uses SetValue to change the value, which + doesn't modify the state of this attribute. So, the derived control + keeps track on each keystroke to see if the value changes, and if so, + it's been modified. """ return wx.TextCtrl.IsModified(self) or self.modified diff --git a/wx/lib/masked/timectrl.py b/wx/lib/masked/timectrl.py index 0a350186..cb396786 100644 --- a/wx/lib/masked/timectrl.py +++ b/wx/lib/masked/timectrl.py @@ -5,6 +5,9 @@ # Copyright: (c) 2002 by Will Sadkin, 2002 # RCS-ID: $Id$ # License: wxWindows license +# +# Tags: phoenix-port, unittest, documented +# #---------------------------------------------------------------------------- # NOTE: # This was written way it is because of the lack of masked edit controls @@ -360,6 +363,27 @@ class TimeCtrl(BaseMaskedTextCtrl): name = "time", **kwargs ): + """ + Default class constructor. + + :param Window `parent`: the window parent. Must not be ``None``; + :param integer `id`: window identifier. A value of -1 indicates a default value; + :param string `value`: value to be shown; + :param `pos`: the control position. A value of (-1, -1) indicates a default position, + chosen by either the windowing system or wxPython, depending on platform; + :type `pos`: tuple or :class:`Point` + :param `size`: the control size. A value of (-1, -1) indicates a default size, + chosen by either the windowing system or wxPython, depending on platform; + :param boolean `fmt24hr`: True to use 24 hour format (sometimes called military format; + :param SpinButton `spinButton`: an instance of :class:`SpinButton` or + None; + :param integer `style`: the window style; + :param Validator `validator`: this is mainly provided for data-transfer, as control does + its own validation; + :param string `name`: the window name; + + """ + # set defaults for control: ## dbg('setting defaults:') @@ -485,7 +509,8 @@ class TimeCtrl(BaseMaskedTextCtrl): def SetParameters(self, **kwargs): """ - Function providing access to the parameters governing TimeCtrl display and bounds. + Function providing access to the parameters governing TimeCtrl display + and bounds. """ ## dbg('TimeCtrl::SetParameters(%s)' % repr(kwargs), indent=1) maskededit_kwargs = {} @@ -606,8 +631,11 @@ class TimeCtrl(BaseMaskedTextCtrl): def BindSpinButton(self, sb): """ - This function binds an externally created spin button to the control, so that - up/down events from the button automatically change the control. + This function binds an externally created spin button to the control, + so that up/down events from the button automatically change the control. + + :param SpinButton `sb`: an instance of :class:`SpinButton` + """ ## dbg('TimeCtrl::BindSpinButton') self.__spinButton = sb @@ -625,8 +653,11 @@ class TimeCtrl(BaseMaskedTextCtrl): """ Validating SetValue function for time values: This function will do dynamic type checking on the value argument, - and convert wxDateTime, mxDateTime, or 12/24 format time string + and convert :class:`DateTime`, mxDateTime, or 12/24 format time string into the appropriate format string for the control. + + :param `value`: the time value + """ ## dbg('TimeCtrl::SetValue(%s)' % repr(value), indent=1) try: @@ -643,8 +674,13 @@ class TimeCtrl(BaseMaskedTextCtrl): """ Validating ChangeValue function for time values: This function will do dynamic type checking on the value argument, - and convert wxDateTime, mxDateTime, or 12/24 format time string + and convert :class:`DateTime`, mxDateTime, or 12/24 format time string into the appropriate format string for the control. + + No change event is fired by this method. + + :param `value`: the time value + """ ## dbg('TimeCtrl::ChangeValue(%s)' % repr(value), indent=1) try: @@ -663,12 +699,18 @@ class TimeCtrl(BaseMaskedTextCtrl): as_wxTimeSpan = False, as_mxDateTimeDelta = False): """ - This function returns the value of the display as a string by default, but - supports return as a wx.DateTime, mx.DateTime, wx.TimeSpan, or mx.DateTimeDelta, - if requested. (Evaluated in the order above-- first one wins!) + This function returns the value of the display as a string by default, + but supports return as a :class:`DateTime`, mx.DateTime, :class:`TimeSpan`, + or mx.DateTimeDelta, if requested. + (Evaluated in the order above-- first one wins!) + + :param boolean `as_wxDateTime`: return value as :class:`DateTime`; + :param boolean `as_mxDateTime`: return value as mxDateTime; + :param boolean `as_wxTimeSpan`: return value as :class:`TimeSpan`; + :param boolean `as_mxDateTimeDelta`: return value as mxDateTimeDelta; + """ - if as_wxDateTime or as_mxDateTime or as_wxTimeSpan or as_mxDateTimeDelta: value = self.GetWxDateTime() if as_wxDateTime: @@ -686,7 +728,7 @@ class TimeCtrl(BaseMaskedTextCtrl): def SetWxDateTime(self, wxdt): """ - Because SetValue can take a wx.DateTime, this is now just an alias. + Because SetValue can take a :class:`DateTime`, this is now just an alias. """ self.SetValue(wxdt) @@ -697,14 +739,14 @@ class TimeCtrl(BaseMaskedTextCtrl): one of the following types: * time string - * wx.DateTime - * wx.TimeSpan + * :class:`DateTime` + * :class:`TimeSpan` * mxDateTime * mxDateTimeDelta - and converts it to a wx.DateTime that always has Jan 1, 1970 as its date - portion, so that range comparisons around values can work using - wx.DateTime's built-in comparison function. If a value is not + and converts it to a :class:`DateTime` that always has Jan 1, 1970 as + its date portion, so that range comparisons around values can work using + :class:`DateTime` built-in comparison function. If a value is not provided to convert, the string value of the control will be used. If the value is not one of the accepted types, a ValueError will be raised. @@ -808,6 +850,10 @@ class TimeCtrl(BaseMaskedTextCtrl): bound, if the control is limited, the value will be automatically adjusted to the new minimum value; if not limited, the value in the control will be colored as invalid. + + :param `min`: Minium value for the control + :type `min`: integer or None + """ ## dbg('TimeCtrl::SetMin(%s)'% repr(min), indent=1) if min is not None: @@ -833,7 +879,7 @@ class TimeCtrl(BaseMaskedTextCtrl): """ Gets the minimum value of the control. If None, it will return None. Otherwise it will return - the current minimum bound on the control, as a wxDateTime + the current minimum bound on the control, as a :class:`DateTime` by default, or as a string if as_string argument is True. """ ## dbg(suspend=1) @@ -868,6 +914,10 @@ class TimeCtrl(BaseMaskedTextCtrl): bound, if the control is limited the value will be automatically adjusted to this maximum value; if not limited, the value in the control will be colored as invalid. + + :param `max`: Minium value for the control + :type `max`: integer or None + """ ## dbg('TimeCtrl::SetMax(%s)' % repr(max), indent=1) if max is not None: @@ -893,7 +943,7 @@ class TimeCtrl(BaseMaskedTextCtrl): """ Gets the minimum value of the control. If None, it will return None. Otherwise it will return - the current minimum bound on the control, as a wxDateTime + the current minimum bound on the control, as a :class:`DateTime` by default, or as a string if as_string argument is True. """ ## dbg(suspend=1) @@ -922,7 +972,14 @@ class TimeCtrl(BaseMaskedTextCtrl): values at the same time. The function only applies the maximum bound if setting the minimum bound is successful, and returns True only if both operations succeed. - **NOTE:** leaving out an argument will remove the corresponding bound. + + .. note:: Leaving out an argument will remove the corresponding bound. + + :param `min`: Minium value for the control + :type `min`: integer or None + :param `max`: Minium value for the control + :type `max`: integer or None + """ ret = self.SetMin(min) return ret and self.SetMax(max) @@ -947,6 +1004,9 @@ class TimeCtrl(BaseMaskedTextCtrl): If called with a value of 0, this function will disable value limiting, but coloring of out-of-bounds values will still take place if bounds have been set for the control. + + :param boolean `limited`: define value limiting + """ ## dbg('TimeCtrl::SetLimited(%d)' % limited, indent=1) self.__limited = limited @@ -1018,7 +1078,6 @@ class TimeCtrl(BaseMaskedTextCtrl): ## dbg(indent=0) - def IsLimited(self): """ Returns True if the control is currently limiting the @@ -1075,10 +1134,12 @@ class TimeCtrl(BaseMaskedTextCtrl): return ret - def IsValid( self, value ): + def IsValid(self, value): """ Can be used to determine if a given value would be a legal and in-bounds value for the control. + + :param `value`: value to check """ try: self.__validateValue(value)