Working on commenting gui package.

fsl/gui/elistbox.py

@@ -7,7 +7,7 @@
 
 """An alternative to ``wx.gizmos.EditableListBox``.
 
-A wx ``EditableListBox`` implementation. The ``wx.gizmos.EditableListBox``
+A wx :class:`EditableListBox` implementation. The ``wx.gizmos.EditableListBox``
 is buggy under OS X Mavericks, and getting tooltips working with the
 ``wx.ListBox`` is an absolute pain in the behind. So I felt the need to
 replicate its functionality. This implementation supports single selection
@@ -160,7 +160,7 @@ class EditableListBox(wx.Panel):
             clientData=None,
             tooltips=None,
             style=0):
-        """Create an ``EditableListBox`` object.
+        """Create an :class:`EditableListBox` object.
 
         :param parent:     Wx parent object
         

fsl/gui/floatslider.py

 #!/usr/bin/env python
 #
-# floatslider.py - Provides two classes, FloatSlider and SliderSpinPanel.
-
-# The FloatSlider class is an alternative to wx.Slider which supports
-# floating point numbers.
-#
-# The SliderSpinPanel class is a panel containing a FloatSlider and a
-# wx.SpinCtrlDouble, linked such that changes in one are reflected in the
-# other.
+# floatslider.py - Floating point slider widgets.
 #
 # Author: Paul McCarthy <pauldmccarthy@gmail.com>
 #
+"""Floating point slider widgets.
+
+Provides two classes, :class:`FloatSlider` and :class:`SliderSpinPanel`.
+
+The :class:FloatSlider` class is an alternative to ``wx.Slider`` which
+supports floating point numbers.
+
+The :class:`SliderSpinPanel` class is a panel containing a :class:`FloatSlider`
+and a ``wx.SpinCtrlDouble``, linked such that changes in one are reflected in
+the other. The :class:`SliderSpinPanel` class also allows the user to change the
+slider limits, via the :class:`~fsl.gui.numberdialog.NumberDialog` class.
+"""
 
 import wx
 import wx.lib.newevent as wxevent
@@ -18,10 +23,11 @@ import wx.lib.newevent as wxevent
 import numberdialog
 
 class FloatSlider(wx.Slider):
-    """
-    A cheap and nasty subclass of wx.Slider which supports floating point
-    numbers of any range. The desired range is transformed into the range
-    [-2**31, 2**31-1].
+    """Floating point slider widget.
+    
+    A cheap and nasty subclass of ``wx.Slider`` which supports floating point
+    numbers of any range. The desired range is transformed into the internal
+    range :math:`[-2^{31}, 2^{31-1}]`.
     """
 
     def __init__(self,
@@ -30,13 +36,18 @@ class FloatSlider(wx.Slider):
                  minValue=None,
                  maxValue=None,
                  **kwargs):
-        """
-        Initialises a FloatSlider. Parameters:
-          - parent:   The wx parent.
-          - value:    Initial slider value
-          - minValue: Minimum slider value
-          - maxValue: Maximum slider value
-          - kwargs:   Passed through to the wx.Slider constructor
+        """Initialise a FloatSlider.
+
+        :param parent:         The wx parent.
+        
+        :param float value:    Initial slider value.
+        
+        :param float minValue: Minimum slider value.
+        
+        :param float maxValue: Maximum slider value.
+        
+        :param kwargs:         Passed through to the ``wx.Slider``
+                               constructor.
         """
 
         if value    is None: value    = 0
@@ -58,19 +69,19 @@ class FloatSlider(wx.Slider):
         
 
     def GetRange(self):
-        """
-        Return a tuple containing the (minimum, maximum) slider values.
-        """
+        """Return a tuple containing the (minimum, maximum) slider values."""
         return (self.__realMin, self.__realMax)
 
 
     def __SetRange(self, minValue, maxValue):
-        """
-        Set the minimum/maximum slider values.  This logic is not in
-        the public FloatSlider.SetRange method so we can overcome
-        a chicken-and-egg problem in __init__ - SetValue needs __realMin
-        and __realMax to be set, but SetRange needs to retrieve the
-        value before setting __realMin and __realMax.
+        """Set the minimum/maximum slider values.
+
+        This logic is not in the public :meth:`SetRange` method so
+        we can overcome a chicken-and-egg problem in :meth:`__init__` -
+        :meth:`SetValue` needs :attribute:`__realMin` and
+        :attribute:`__realMax` to be set, but :meth:`SetRange` needs to
+        retrieve the value before setting :attribute:`__realMin` and
+        :attribute:`__realMax`.
         """ 
 
         self.__realMin   = float(minValue)
@@ -81,9 +92,7 @@ class FloatSlider(wx.Slider):
 
         
     def SetRange(self, minValue, maxValue):
-        """
-        Set the minimum/maximum slider values.
-        """
+        """Set the minimum/maximum slider values."""
 
         # wx.Slider values change when their bounds
         # are changed. It does this to keep the
@@ -96,55 +105,41 @@ class FloatSlider(wx.Slider):
 
         
     def GetMin(self):
-        """
-        Return the minimum slider value.
-        """
+        """Return the minimum slider value."""
         return self.GetRange()[0]
 
     
     def GetMax(self):
-        """
-        Return the maximum slider value.
-        """
+        """Return the maximum slider value."""
         return self.GetRange()[1]
 
         
     def SetMin(self, minValue):
-        """
-        Set the minimum slider value.
-        """
+        """Set the minimum slider value."""
         self.SetRange(minValue, self.GetMax())
 
         
     def SetMax(self, maxValue):
-        """
-        Set the maximum slider value.
-        """
+        """Set the maximum slider value."""
         self.SetRange(self.GetMin(), maxValue)
 
         
     def __sliderToReal(self, value):
-        """
-        Converts the given value from slider space to real space.
-        """
+        """Converts the given value from slider space to real space."""
         value = self.__realMin + (value - self.__sliderMin) * \
             (self.__realRange / self.__sliderRange)
         return value
 
         
     def __realToSlider(self, value):
-        """
-        Converts the given value from real space to slider space.
-        """ 
+        """Converts the given value from real space to slider space.""" 
         value = self.__sliderMin + (value - self.__realMin) * \
             (self.__sliderRange / self.__realRange)
         return int(round(value))
 
         
     def SetValue(self, value):
-        """
-        Set the slider value.
-        """
+        """Set the slider value."""
         value = self.__realToSlider(value)
 
         if value < self.__sliderMin: value = self.__sliderMin
@@ -154,35 +149,52 @@ class FloatSlider(wx.Slider):
 
         
     def GetValue(self):
-        """
-        Returns the slider value.
-        """
+        """Returns the slider value."""
         value = wx.Slider.GetValue(self)
         return self.__sliderToReal(value)
 
 
-# Event emitted when the SliderSpinPanel value changes.
-# Contains a single parameter, 'value', which contains
-# the new value.
-SliderSpinValueEvent, EVT_SSP_VALUE = wxevent.NewEvent()
+_SliderSpinValueEvent, _EVT_SSP_VALUE = wxevent.NewEvent()
+_SliderSpinLimitEvent, _EVT_SSP_LIMIT = wxevent.NewEvent()
+
+
+EVT_SSP_VALUE        = _EVT_SSP_VALUE
+"""Identifier for the :data:`SliderSpinValueEvent`."""
+
+
+EVT_SSP_LIMIT        = _EVT_SSP_LIMIT
+"""Identifier for the :data:`SliderSpinLimitEvent`."""
+
+
+SliderSpinValueEvent = _SliderSpinValueEvent
+"""Event emitted when the :class:`SliderSpinPanel` value
+changes. Contains a single attribute, ``value``, which
+contains the new value.
+"""
+
+
+SliderSpinLimitEvent = _SliderSpinLimitEvent
+"""Event emitted when the :class:`SliderSpinPanel` limits
+change. Contains two attributes, ``min`` and ``max``, which
+contain the new limit values.
+"""
 
-# Event emitted when the SliderSpinPanel limits change.
-# Contains two parameters, 'min' and 'max', which contain
-# the new limit values.
-SliderSpinLimitEvent, EVT_SSP_LIMIT = wxevent.NewEvent() 
 
 class SliderSpinPanel(wx.Panel):
-    """
-    A panel which contains a FloatSlider and a wx.SpinCtrlDouble, linked
-    such that changes to one are reflected in the other.  The class also
-    provides the option to have the minimum/maximum limits displayed on
-    either side of the slider/spinbox, and to have those limits editable
-    via a button push.
-
-    Users of the SliderSpinPanel may wish to bind listeners to the
-    following events:
-      - EVT_SSP_VALUE: Emitted when the slider value changes.
-      - EVT_SSP_LIMIT: Emitted when the slider limits change.
+    """A panel containing a :class:`FloatSlider` and a ``wx.SpinCtrlDouble``.
+
+    The slider and spinbox are linked such that changes to one are
+    reflected in the other.  The :class:`SliderSpinPanel` class also
+    provides the option to have the minimum/maximum limits displayed
+    on either side of the slider/spinbox, and to have those limits
+    editable via a button push.
+
+    Users of the :class:`SliderSpinPanel` may wish to bind listeners to
+    the following events:
+    
+      - :data:`EVT_SSP_VALUE`: Emitted when the slider value changes.
+    
+      - :data:`EVT_SSP_LIMIT`: Emitted when the slider limits change.
     """
 
     def __init__(self,
@@ -195,30 +207,33 @@ class SliderSpinPanel(wx.Panel):
                  showLimits=True,
                  editLimits=False):
         """
-        Initialises a SliderSpinPanel object. Parameters:
-        
-          - parent:     wx parent object.
+        Initialise a :class:`SliderSpinPanel` object.
+
+        :param parent:          Wx parent object.
 
-          - real:       If False, a wx.Slider and wx.SpinCtrl are used,
-                        instead of a FloatSlider and wx.SpinCtrlDouble.
+        :param bool real:       If ``False``, a ``wx.Slider`` and
+                                ``wx.SpinCtrl`` are used, instead of a
+                                :class:`FloatSlider` and
+                                ``wx.SpinCtrlDouble``.
         
-          - value:      Initial slider/spin value.
+        :param number value:    Initial slider/spin value.
         
-          - minValue:   Minimum slider/spin value.
+        :param number minValue: Minimum slider/spin value.
         
-          - maxValue:   Maximum slider/spin value.
+        :param number maxValue: Maximum slider/spin value.
 
-          - label:      If not None, a wx.StaticText widget is added to
-                        the left of the slider, containing the given label.
-                        
+        :param str label:       If not ``None``, a ``wx.StaticText`` widget
+                                is added to the left of the slider, containing
+                                the given label.
         
-          - showLimits: If True, buttons placed on the left and right,
-                        displaying the minimum/maximum limits.
+        :param bool showLimits: If ``True``, buttons placed on the left and
+                                right, displaying the minimum/maximum limits.
         
-          - editLimits: If True, when said buttons are clicked, a dialog
-                        window pops up allowing the user to edit the limits
-                        values (see numberdialog.py). Has no effect if
-                        showLimits is False.
+        :param bool editLimits: If ``True``, when said buttons are clicked, a
+                                :class:`~fsl.gui.numberdialog.NumberDialog`
+                                window pops up allowing the user to edit the
+                                limit values. Has no effect if ``showLimits``
+                                is ``False``.
         """
 
         wx.Panel.__init__(self, parent)
@@ -287,11 +302,10 @@ class SliderSpinPanel(wx.Panel):
 
         
     def _onLimitButton(self, ev):
-        """
-        Called when either of the minimum/maximum limit buttons are
-        clicked. Pops up a numberdialog.NumberDialog window and, if
-        the user changes the value, updates the slider/spin limits,
-        and emits an EVT_SSP_LIMIT event.
+        """Called when either of the minimum/maximum limit buttons
+        are clicked. Pops up a :class:`~fsl.gui.numberdialog.NumberDialog`
+        window and, if the user changes the value, updates the slider/spin
+        limits, and emits an :data:`EVT_SSP_LIMIT` event.
         """
 
         source = ev.GetEventObject()
@@ -330,9 +344,8 @@ class SliderSpinPanel(wx.Panel):
 
         
     def _onSlider(self, ev):
-        """
-        Called when the user changes the slider value. Updates the
-        spinbox value and emits an EVT_SSP_VALUE event.
+        """Called when the user changes the slider value. Updates the
+        spinbox value and emits an :data:`EVT_SSP_VALUE` event.
         """
         val = self._slider.GetValue()
         self._spinbox.SetValue(val)
@@ -340,9 +353,8 @@ class SliderSpinPanel(wx.Panel):
 
         
     def _onSpin(self, ev):
-        """
-        Called when the user changes the spinbox value. Updates the
-        slider value and emits an EVT_SSP_VALUE event.
+        """Called when the user changes the spinbox value. Updates the
+        slider value and emits an :data:`EVT_SSP_VALUE` event.
         """
         val = self._spinbox.GetValue()
         self._slider.SetValue(val)
@@ -350,46 +362,35 @@ class SliderSpinPanel(wx.Panel):
 
         
     def GetRange(self):
-        """
-        Return a tuple containing the (minimum, maximum) slider/spinbox
+        """Return a tuple containing the (minimum, maximum) slider/spinbox
         values.
         """
         return self._slider.GetRange()
 
         
     def GetMin(self):
-        """
-        Returns the minimum slider/spinbox value.
-        """
+        """Returns the minimum slider/spinbox value."""
         return self._slider.GetMin()
 
         
     def GetMax(self):
-        """
-        Returns the maximum slider/spinbox value.
-        """
+        """Returns the maximum slider/spinbox value."""
         return self._slider.GetMax()
 
         
     def GetValue(self):
-        """
-        Returns the current slider/spinbox value.
-        """
+        """Returns the current slider/spinbox value. """
         return self._slider.GetValue()
 
         
     def SetRange(self, minValue, maxValue):
-        """
-        Sets the minimum/maximum slider/spinbox values.
-        """ 
+        """Sets the minimum/maximum slider/spinbox values.""" 
         self.SetMin(minValue)
         self.SetMax(maxValue)
 
         
     def SetMin(self, minValue):
-        """
-        Sets the minimum slider/spinbox value.
-        """ 
+        """Sets the minimum slider/spinbox value.""" 
         self._slider .SetMin(minValue)
         self._spinbox.SetMin(minValue)
 
@@ -398,9 +399,7 @@ class SliderSpinPanel(wx.Panel):
 
             
     def SetMax(self, maxValue):
-        """
-        Sets the maximum slider/spinbox value.
-        """ 
+        """Sets the maximum slider/spinbox value.""" 
         self._slider .SetMax(maxValue)
         self._spinbox.SetMax(maxValue)
 
@@ -409,8 +408,6 @@ class SliderSpinPanel(wx.Panel):
 
             
     def SetValue(self, value):
-        """
-        Sets the current slider/spinbox value.
-        """ 
+        """Sets the current slider/spinbox value.""" 
         self._slider .SetValue(value)
         self._spinbox.SetValue(value)

fsl/gui/numberdialog.py

@@ -29,7 +29,7 @@ class NumberDialog(wx.Dialog):
                  initial=None,
                  minValue=None,
                  maxValue=None):
-        """Create and lay out a NumberDialog.
+        """Create and lay out a :class:`NumberDialog`.
 
         :param parent:          Wx parent object.