fsleyes_props.build_parts

Parts for building a GUI.

This module provides definitiions of the parts used by the build module to build a GUI for a HasProperties instance. See the build module documentation for some examples.

Conditional visibility/state

The value of the ViewItem.dependencies parameter determines the required format of the enabledWhen and visibleWhen parameters, and the behaviour which controls the visible/enabled state of the displayed item.

If dependencies is None, the visible/enabled state of the item will be evaluated whenever any property on the target HasProperties instance change. The enabledWhen and visibleWhen functions will be passed this instance.

If dependencies is not None, it must be a list containing the names of properties on the HasProperties instance. The visible/enabled state of the item will then be evaluated whenever the value of these specific properties change, rather than whenever the value of any property changes. In this case, the enabledWhen and visibleWhen functions will be passed the instance, and the values of the specified properties as positional arguments.

If the enabled/visible state of the item is dependent on the value of a property of a different HasProperties instance, the dependencies list can contain a tuple which specifies the dependency as an (instance, propName) pair. The instance may alternately be a function which accepts the primary HasProperties instance as a single argument, and returns the secondary instance (this is useful if you are defining ViewItems before any of the HasProperties instances exist).

This all sounds a bit convoluted, but in practice is pretty simple. Example:

import wx
import fsleyes_props as props

class MyObj1(props.HasProperties):
    myPropA = props.Boolean()

class MyObj2(props.HasProperties):
    myProp1 = props.Int()
    myProp2 = props.Real()
    myProp3 = props.Boolean()

    def __init__(self, mo1):
        self.mo1 = mo1

mo2View = props.VGroup((

    # myProp1 is only visible
    # when MyObj1.myPropA is True
    props.Widget(
        'myProp1',

        # MyObj2 stores a reference to the
        # MyObj1 instance which controls
        # the state of the myProp1 widget.
        dependencies=[(lambda i: i.mo1, 'myPropA')],

        # The visibleWhen callback gets
        # passed the MyObj1 instance,
        # and the value of MyObj2.mo1.myPropA
        visibleWhen=lambda i, mo1val: mo1val),

    # myProp2 is only enabled
    # when MyObj2.myProp3 is True
    props.Widget(
        'myProp2',
        enabledWhen=lambda i: i.myProp3),

    # myProp3 is alway visible/enabled
    'myProp3'))

mo1 = MyObj1()
mo2 = MyObj2(mo1)

app      = wx.App()
mo1Frame = props.buildGUI(None, mo1)
mo2Frame = props.buildGUI(None, mo2, view=mo2View)

mo1Frame.Fit()
mo2Frame.Fit()
mo1Frame.Show()
mo2Frame.Show()
app.MainLoop()
class fsleyes_props.build_parts.ViewItem(key=None, label=None, tooltip=None, visibleWhen=None, enabledWhen=None, dependencies=None, setup=None, **kwargs)[source]

Bases: object

Superclass for Widget, Button, Label and Group. Represents an item to be displayed.

Define a ViewItem.

Parameters:

  • key (str) – An identifier for this item. If this item is a Widget, this should be the property name that the widget edits. This key is used to look up labels and tooltips, if they are passed in as dicts (see buildGUI()).

  • label (str) – A label for this item, which may be used in the GUI.

  • tooltip (str) – A tooltip, which may be displayed when the user hovers the mouse over the widget for this ViewItem.

  • visibleWhen – A function which takes at least one argument (see note about the dependencies parameter above), the HasProperties instance, and returns a bool. When any property values change, the function is called. The return value is used to determine whether this item should be made visible or invisible.

  • enabledWhen – Same as the visibleWhen parameter, except the state of the item (and its children) is changed between enabled and disabled.

  • dependencies – List of dependencies which determine when the visible/enabled state of the item are evaluated, and the arguments that are passed to the visibleWhen/enabledWhen functions.

  • setup – Optional function which is called when te GUI object represented by this ViewItem is first created. The function is passed the HasProperties instance, the wx GUI parent object, and the wx object.

  • kwargs – Any type-specific options which are to be passed through to the creation function, defined in the widgets module.

class fsleyes_props.build_parts.Button(key=None, text=None, callback=None, icon=None, **kwargs)[source]

Bases: ViewItem

Represents a button which, when clicked, will call a specified callback function.

When the button is clicked, the callback function is passed two arguemnts - the HasProperties instance, and the wx.Button instance.

If the icon argument is provided, it is used instead of any specified text. The icon should be a string containing the name of the image file.

Parameters:

  • key – Passed to ViewItem.__init__().

  • text – Text to show on the button (if icons are not used).

  • callback – Function to call when the button is clicked.

  • icon – The name of an icon image to show on the button.

All other arguments are passed through to ViewItem.__init__().

class fsleyes_props.build_parts.Toggle(key=None, callback=None, icon=None, **kwargs)[source]

Bases: ViewItem

Represents a toggle widget of some sort (e.g. a check box, or a toggle button) which, when clicked, calls a specified callback function.

Create a Toggle.

Parameters:

  • key – Passed to ViewItem.__init__().

  • callback – Function to call when the toggle widget is clicked. Must accept two arguments - the HasProperties instance, and the toggle widget.

  • icon – The name of an image file, or a list of two image file names.

All other arguments are passed through to ViewItem.__init__().

class fsleyes_props.build_parts.Label(viewItem=None, **kwargs)[source]

Bases: ViewItem

Represents a static text label.

Define a label.

Label objects are automatically created for other ViewItem objects, which are to be labelled.

Bases: ViewItem

Represents a checkbox which allows the user to control whether a property is linked (a.k.a. bound) to the parent of the HasProperties object.

Define a ViewItem.

Parameters:

  • key (str) – An identifier for this item. If this item is a Widget, this should be the property name that the widget edits. This key is used to look up labels and tooltips, if they are passed in as dicts (see buildGUI()).

  • label (str) – A label for this item, which may be used in the GUI.

  • tooltip (str) – A tooltip, which may be displayed when the user hovers the mouse over the widget for this ViewItem.

  • visibleWhen – A function which takes at least one argument (see note about the dependencies parameter above), the HasProperties instance, and returns a bool. When any property values change, the function is called. The return value is used to determine whether this item should be made visible or invisible.

  • enabledWhen – Same as the visibleWhen parameter, except the state of the item (and its children) is changed between enabled and disabled.

  • dependencies – List of dependencies which determine when the visible/enabled state of the item are evaluated, and the arguments that are passed to the visibleWhen/enabledWhen functions.

  • setup – Optional function which is called when te GUI object represented by this ViewItem is first created. The function is passed the HasProperties instance, the wx GUI parent object, and the wx object.

  • kwargs – Any type-specific options which are to be passed through to the creation function, defined in the widgets module.

class fsleyes_props.build_parts.Widget(propName, index=None, **kwargs)[source]

Bases: ViewItem

Represents a widget which is used to modify a property value.

Define a Widget.

Parameters:

  • propName (str) – The name of the property which this widget can modify.

  • index (int) – If provided, it is assumed that the property is a List, and the index specifies the list item that this widget will be bound to.

  • kwargs – Passed to the ViewItem constructor.

class fsleyes_props.build_parts.Group(children, showLabels=True, border=False, grow=True, **kwargs)[source]

Bases: ViewItem

Represents a collection of other ViewItem objects.

This class is not to be used directly - use one of the subclasses:

Define a Group.

Parameters:

Parameters:

  • children – List of ViewItem objects, the children of this Group.

  • showLabels (bool) – Whether labels should be displayed for each of the children. If this is True, an attribute will be added to this Group object in the _prepareView() function, called childLabels, which contains a Label object for each child.

  • border (bool) – If True, this group will be drawn with a border around it. If this group is a child of another VGroup, it will be laid out a bit differently, too.

  • grow (bool) – If True, this group will be resized if its parent window is resized.

  • kwargs – Passed to the ViewItem constructor.

class fsleyes_props.build_parts.NotebookGroup(children, **kwargs)[source]

Bases: Group

A Group representing a GUI Notebook. Children are added as notebook pages.

Define a NotebookGroup.

Parameters:

children – List of ViewItem objects - a tab in the notebook is added for each child.

class fsleyes_props.build_parts.HGroup(children, wrap=False, vertLabels=False, **kwargs)[source]

Bases: Group

A group representing a GUI panel, whose children are laid out horizontally.

Create a HGroup.

Parameters:

  • wrap – If True the children are wrapped, via a wx.WrapSizer; if there is not enough horizontal space to display all children in a single row, the remaining children are displayed on a new row.

  • vertLabels – If True child labels are displayed above the child.

class fsleyes_props.build_parts.VGroup(children, **kwargs)[source]

Bases: Group

A group representing a GUI panel, whose children are laid out vertically.

Define a Group.

Parameters:

Parameters:

  • children – List of ViewItem objects, the children of this Group.

  • showLabels (bool) – Whether labels should be displayed for each of the children. If this is True, an attribute will be added to this Group object in the _prepareView() function, called childLabels, which contains a Label object for each child.

  • border (bool) – If True, this group will be drawn with a border around it. If this group is a child of another VGroup, it will be laid out a bit differently, too.

  • grow (bool) – If True, this group will be resized if its parent window is resized.

  • kwargs – Passed to the ViewItem constructor.