Refactor fields (#1234)

This is a refactor of the Field class to split it into display and
editable variants: base `Fields` may not be editable, `EditaleFields`
add editability (ie. the value can be changed by the user). Includes
tests and documentation, including fixes to make the documentation
actually compile.

Adds a LabelField and ImageField to demonstrate the non-editable Fields.

---------

Co-authored-by: Mark Dickinson <mdickinson@enthought.com>

Author: corranwebster

docs/source/conf.py

@@ -11,9 +11,7 @@
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
-import os
-import runpy
-import sys
+import importlib.metadata
 
 # General configuration
 # ---------------------
@@ -45,10 +43,7 @@
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
-version_py = os.path.join('..', '..', 'pyface', '_version.py')
-version_content = runpy.run_path(version_py)
-version = ".".join(version_content["version"].split(".", 2)[:2])
-release = version
+version = release = importlib.metadata.version("pyface")
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

docs/source/fields.rst

@@ -9,16 +9,81 @@ to a Traits interface, so that you can use them in a cross-toolkit manner.
 
 Where possible, these classes share a common API for the same functionality.
 In particular, all classes have a
-:py:attr:`~pyface.fields.i_field.IField.value` trait which holds the (usually
-user-editable) value displayed in the field.  Code using the field can listen
-to changes in this trait to react to the user entering a new value for the
-field without needing to know anything about the underlying toolkit event
-signalling mechanisms.
+:py:attr:`~pyface.fields.i_field.IField.value` trait which holds the value
+displayed in the field.
 
-All fields also provide a trait for setting the
-:py:attr:`~pyface.fields.i_field.IField.context_menu` of the field. Context
-menus should be :py:class:`~pyface.action.menu_manager.MenuManager`
-instances.
+Fields where the value is user-editable rather than simply displayed implement
+the :py:attr:`~pyface.fields.i_editable_field.IEditableField` interface.  Code
+using the field can listen to changes in the value trait to react to the user
+entering a new value for the field without needing to know anything about the
+underlying toolkit event signalling mechanisms.
+
+Fields inherit from :py:class:`~pyface.i_widget.IWidget` and
+:py:class:`~pyface.i_layout_item.ILayoutItem` which have a number of
+additional traits with useful features:
+
+:py:attr:`~pyface.i_widget.IWidget.tooltip`
+    A tooltip for the widget, which should hold string.
+
+:py:attr:`~pyface.i_widget.IWidget.context_menu`
+    A context menu for the widget, which should hold an
+    :py:class:`~pyface.action.i_menu_manager.IMenuManager` instance.
+
+:py:attr:`~pyface.i_layout_item.ILayoutItem.minimum_size`
+    A tuple holding the minimum size of a layout widget.
+
+:py:attr:`~pyface.i_layout_item.ILayoutItem.maximum_size`
+    A tuple holding the minimum size of a layout widget.
+
+:py:attr:`~pyface.i_layout_item.ILayoutItem.stretch`
+    A tuple holding information about the distribution of addtional space into
+    the widget when growing in a layout.  Higher numbers mean proportinally
+    more space.
+
+:py:attr:`~pyface.i_layout_item.ILayoutItem.size_policy`
+    A tuple holding information about how the widget can grow and shrink.
+
+:py:attr:`~pyface.fields.i_field.IField.alignment`
+    A value holding the horizontal alignment of the contents of the field.
+
+ComboField
+==========
+
+The :py:class:`~pyface.fields.i_combo_field.IComboField` interface has an arbitrary
+:py:attr:`~pyface.fields.i_combo_field.IComboField.value` that must come from a list
+of valid :py:attr:`~pyface.fields.i_combo_field.IComboField.values`.  For non-text
+values, a :py:attr:`~pyface.fields.i_combo_field.IComboField.formatter` function
+should be provided, defaulting to :py:func:`str`.
+
+LabelField
+==========
+
+The :py:class:`~pyface.fields.i_label_field.ILabelField` interface has a string
+for the :py:attr:`~pyface.fields.i_label_field.ILabelField.value` which is not
+user-editable.
+
+In the Qt backend they can have an image for an
+:py:attr:`~pyface.fields.i_label_field.ILabelField.icon`.
+
+ImageField
+==========
+
+The :py:class:`~pyface.fields.i_image_field.IImageField` interface has an
+:py:class:`~pyface.i_image.IImage` for its
+:py:attr:`~pyface.fields.i_image_field.IImageField.value` which is not
+user-editable.
+
+SpinField
+=========
+
+The :py:class:`~pyface.fields.i_spin_field.ISpinField` interface has an integer
+for the :py:attr:`~pyface.fields.i_spin_field.ISpinField.value`, and also
+requires a range to be set, either via setting the min/max values as a tuple to
+the :py:attr:`~pyface.fields.i_spin_field.ISpinField.bounds` trait, or by setting
+values individually to :py:attr:`~pyface.fields.i_spin_field.ISpinField.minimum`
+and :py:attr:`~pyface.fields.i_spin_field.ISpinField.maximum`.  The
+:py:attr:`~pyface.fields.i_spin_field.ISpinField.wrap` trait determines whether
+the spinner wraps around at the extreme values.
 
 TextField
 =========
@@ -41,26 +106,6 @@ the Qt backend has a number of other options as well).  The text field can be
 set to read-only mode via the
 :py:attr:`~pyface.fields.i_text_field.ITextField.read_only` trait.
 
-SpinField
-=========
-
-The :py:class:`~pyface.fields.i_spin_field.ISpinField` interface has an integer
-for the :py:attr:`~pyface.fields.i_spin_field.ISpinField.value`, and also
-requires a range to be set, either via setting the min/max values as a tuple to
-the :py:attr:`~pyface.fields.i_spin_field.ISpinField.range` trait, or by setting
-values individually to :py:attr:`~pyface.fields.i_spin_field.ISpinField.minimum`
-and :py:attr:`~pyface.fields.i_spin_field.ISpinField.maximum`.
-
-ComboField
-==========
-
-The :py:class:`~pyface.fields.i_combo_field.IComboField` interface has an arbitrary
-:py:attr:`~pyface.fields.i_combo_field.IComboField.value` that must come from a list
-of valid :py:attr:`~pyface.fields.i_combo_field.IComboField.values`.  For non-text
-values, a :py:attr:`~pyface.fields.i_combo_field.IComboField.formatter` function
-should be provided - this defaults to either :py:func:`str` (Python 3+) or
-:py:func:`unicode` (Python 2).
-
 TimeField
 ==========
 

pyface/fields/api.py

@@ -14,6 +14,10 @@
 
 - :class:`~.CheckBoxField`
 - :class:`~.ComboField`
+- :class:`~.EditableField`
+- :class:`~.Field`
+- :class:`~.ImageField`
+- :class:`~.LabelField`
 - :class:`~.RadioButtonField`
 - :class:`~.SpinField`
 - :class:`~.TextField`
@@ -23,7 +27,10 @@
 Interfaces
 ----------
 - :class:`~.IComboField`
+- :class:`~.IEditableField`
 - :class:`~.IField`
+- :class:`~.IImageField`
+- :class:`~.ILabelField`
 - :class:`~.ISpinField`
 - :class:`~.ITextField`
 - :class:`~.ITimeField`
@@ -32,7 +39,10 @@
 """
 
 from .i_combo_field import IComboField
+from .i_editable_field import IEditableField
 from .i_field import IField
+from .i_image_field import IImageField
+from .i_label_field import ILabelField
 from .i_spin_field import ISpinField
 from .i_text_field import ITextField
 from .i_time_field import ITimeField
@@ -48,6 +58,10 @@
 _toolkit_imports = {
     'CheckBoxField': 'toggle_field',
     'ComboField': 'combo_field',
+    'EditableField': 'editable_field',
+    'Field': 'field',
+    'ImageField': 'image_field',
+    'LabelField': 'label_field',
     'RadioButtonField': 'toggle_field',
     'SpinField': 'spin_field',
     'TextField': 'text_field',

pyface/fields/i_combo_field.py

@@ -13,10 +13,10 @@
 
 from traits.api import Callable, HasTraits, Enum, List
 
-from pyface.fields.i_field import IField
+from pyface.fields.i_editable_field import IEditableField
 
 
-class IComboField(IField):
+class IComboField(IEditableField):
     """ The combo field interface.
 
     This is for comboboxes holding a list of values.
@@ -64,21 +64,16 @@ def __init__(self, values, **traits):
     def _initialize_control(self):
         super()._initialize_control()
         self._set_control_values(self.values)
-        self._set_control_value(self.value)
 
     def _add_event_listeners(self):
         """ Set up toolkit-specific bindings for events """
         super()._add_event_listeners()
         self.observe(
             self._values_updated, "values.items,formatter", dispatch="ui"
         )
-        if self.control is not None:
-            self._observe_control_value()
 
     def _remove_event_listeners(self):
         """ Remove toolkit-specific bindings for events """
-        if self.control is not None:
-            self._observe_control_value(remove=True)
         self.observe(
             self._values_updated,
             "values.items,formatter",

pyface/fields/i_editable_field.py

@@ -0,0 +1,62 @@
+# (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
+# All rights reserved.
+#
+# This software is provided without warranty under the terms of the BSD
+# license included in LICENSE.txt and may be redistributed only under
+# the conditions described in the aforementioned license. The license
+# is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+# Thanks for using Enthought open source!
+
+""" The editable field interface. """
+
+
+from traits.api import HasTraits
+
+from .i_field import IField
+
+
+class IEditableField(IField):
+    """ The editable field interface.
+
+    A editable field is a widget that displays a user-editable value.
+    """
+
+
+class MEditableField(HasTraits):
+    """The editable field mix-in.
+
+    Classes which use this mixin should implement _observe_control_value to
+    connect a toolkit handler that calls _update_value.
+    """
+
+    # ------------------------------------------------------------------------
+    # IWidget interface
+    # ------------------------------------------------------------------------
+
+    def _add_event_listeners(self):
+        """ Set up toolkit-specific bindings for events """
+        super()._add_event_listeners()
+        self._observe_control_value()
+
+    def _remove_event_listeners(self):
+        """ Remove toolkit-specific bindings for events """
+        self._observe_control_value(remove=True)
+        super()._remove_event_listeners()
+
+    # ------------------------------------------------------------------------
+    # Private interface
+    # ------------------------------------------------------------------------
+
+    def _update_value(self, value):
+        """ Handle a change to the value from user interaction
+
+        This is a method suitable for calling from a toolkit event handler.
+        """
+        self.value = self._get_control_value()
+
+    # Toolkit control interface ---------------------------------------------
+
+    def _observe_control_value(self, remove=False):
+        """ Toolkit specific method to change the control value observer. """
+        raise NotImplementedError()

pyface/fields/i_field.py

@@ -14,6 +14,7 @@
 from traits.api import Any, HasTraits
 
 from pyface.i_layout_widget import ILayoutWidget
+from pyface.ui_traits import Alignment
 
 
 class IField(ILayoutWidget):
@@ -26,51 +27,62 @@ class IField(ILayoutWidget):
     #: The value held by the field.
     value = Any()
 
+    #: The alignment of the field's content.
+    alignment = Alignment()
+
 
 class MField(HasTraits):
     """ The field mix-in. """
 
     #: The value held by the field.
     value = Any()
 
+    #: The alignment of the text in the field.
+    alignment = Alignment()
+
     # ------------------------------------------------------------------------
     # IWidget interface
     # ------------------------------------------------------------------------
 
+    def create(self, parent=None):
+        """ Creates the toolkit specific control.
+
+        This method should create the control and assign it to the
+        :py:attr:``control`` trait.
+        """
+        super().create(parent=parent)
+
+        self.show(self.visible)
+        self.enable(self.enabled)
+
+    def _initialize_control(self):
+        """ Perform any post-creation initialization for the control.
+        """
+        super()._initialize_control()
+        self._set_control_value(self.value)
+        if self.alignment != 'default':
+            self._set_control_alignment(self.alignment)
+
     def _add_event_listeners(self):
         """ Set up toolkit-specific bindings for events """
         super()._add_event_listeners()
         self.observe(self._value_updated, "value", dispatch="ui")
+        self.observe(self._alignment_updated, "alignment", dispatch="ui")
 
     def _remove_event_listeners(self):
         """ Remove toolkit-specific bindings for events """
         self.observe(
             self._value_updated, "value", dispatch="ui", remove=True
         )
+        self.observe(
+            self._alignment_updated, "alignment", dispatch="ui", remove=True
+        )
         super()._remove_event_listeners()
 
     # ------------------------------------------------------------------------
     # Private interface
     # ------------------------------------------------------------------------
 
-    def create(self, parent=None):
-        """ Creates the toolkit specific control.
-
-        This method should create the control and assign it to the
-        :py:attr:``control`` trait.
-        """
-        super().create(parent=parent)
-
-        self.show(self.visible)
-        self.enable(self.enabled)
-
-    def _update_value(self, value):
-        """ Handle a change to the value from user interaction
-
-        This is a method suitable for calling from a toolkit event handler.
-        """
-        self.value = self._get_control_value()
-
     def _get_control(self):
         """ If control is not passed directly, get it from the trait. """
         control = self.control
@@ -88,8 +100,12 @@ def _set_control_value(self, value):
         """ Toolkit specific method to set the control's value. """
         raise NotImplementedError()
 
-    def _observe_control_value(self, remove=False):
-        """ Toolkit specific method to change the control value observer. """
+    def _get_control_alignment(self):
+        """ Toolkit specific method to get the control's read_only state. """
+        raise NotImplementedError()
+
+    def _set_control_alignment(self, alignment):
+        """ Toolkit specific method to set the control's alignment. """
         raise NotImplementedError()
 
     # Trait change handlers -------------------------------------------------
@@ -98,3 +114,8 @@ def _value_updated(self, event):
         value = event.new
         if self.control is not None:
             self._set_control_value(value)
+
+    def _alignment_updated(self, event):
+        alignment = event.new
+        if self.control is not None:
+            self._set_control_alignment(alignment)