fsleyes_props.build

Automatically build a wx GUI for a HasProperties instance.

This module provides functionality to automatically build a wx GUI containing widgets which allow the user to change the property values (PropertyBase instances) of a specified HasProperties instance.

This module has two main entry points:

buildGUI	Builds a GUI interface which allows the properties of the given HasProperties object to be edited.
buildDialog	Convenience method which embeds the result of a call to buildGUI() in a wx.Dialog.

A number of classes are defined in the separate build_parts module. The ViewItem class allows the layout of the generated interface to be customised. Property widgets may be grouped together by embedding them within a HGroup or VGroup object; they will then respectively be laid out horizontally or verticaly. Groups may be embedded within a NotebookGroup object, which will result in a notebook-like interface containing a tab for each child Group.

The label for, and behaviour of, the widget for an individual property may be customised with a Widget object. As an example:

import wx
import fsleyes_props as props

class MyObj(props.HasProperties):
    myint  = props.Int()
    mybool = props.Boolean()

# A reasonably complex view specification
view = props.VGroup(
  label='MyObj properties',
  children=(
      props.Widget('mybool',
                   label='MyObj Boolean',
                   tooltip='If this is checked, you can '
                           'edit the MyObj Integer'),
      props.Widget('myint',
                   label='MyObj Integer',
                   enabledWhen=lambda mo: mo.mybool)))

# A simpler view specification
view = props.VGroup(('mybool', 'myint'))

# The simplest view specification - a
# default one will be generated
view = None

myobj = MyObj()

app   = wx.App()
frame = wx.Frame(None)

myObjPanel = props.buildGUI(frame, myobj, view)

See the build_parts module for details on the Widget (and other ViewItem) definitions.

You may also pass in widget labels and tooltips to the buildGUI() function:

labels = {
    'myint':  'MyObj Integer value',
    'mybool': 'MyObj Boolean value'
}

tooltips = {
    'myint' : 'MyObj Integer tooltip'
}

props.buildGUI(frame, myobj, view=view, labels=labels, tooltips=tooltips)

As an alternative to passing in a view, labels, and tooltips to the buildGUI() function, they may be specified as class attributes of the HasProperties instance or class, with respective names _view, _labels, and _tooltips:

class MyObj(props.HasProperties):
    myint  = props.Int()
    mybool = props.Boolean()

    _view = props.HGroup(('myint', 'mybool'))
    _labels = {
        'myint':  'MyObj integer',
        'mybool': 'MyObj boolean'
    }
    _tooltips = {
        'myint':  'MyObj integer tooltip',
        'mybool': 'MyObj boolean tooltip'
    }

props.buildGUI(frame, myobj)

class fsleyes_props.build.PropGUI

Bases: object

An internal container class used for convenience. Stores references to all wx objects that are created, and to all conditional callbacks (which control visibility/state).

__init__()

Initialize self. See help(type(self)) for accurate signature.

__dict__ = mappingproxy({'__module__': 'fsleyes_props.build', '__doc__': 'An internal container class used for convenience. Stores references to\n all :mod:`wx` objects that are created, and to all conditional callbacks\n (which control visibility/state).\n ', '__init__': <function PropGUI.__init__>, '__dict__': <attribute '__dict__' of 'PropGUI' objects>, '__weakref__': <attribute '__weakref__' of 'PropGUI' objects>})

__module__ = 'fsleyes_props.build'

__weakref__

list of weak references to the object (if defined)

fsleyes_props.build._configureEnabledWhen(viewItem, guiObj, hasProps, propGui)

Configures a callback function for this view item, if its enabledWhen attribute was set.

Parameters

• viewItem – The ViewItem object

• guiObj – The GUI object created from the ViewItem

• hasProps – The HasProperties instance

• propGui – The PropGui instance, in which references to all event callbacks are stored

fsleyes_props.build._configureVisibleWhen(viewItem, guiObj, hasProps, propGui)

Configures a callback function for this view item, if its visibleWhen attribute was set. See _configureEnabledWhen().

Parameters

• viewItem – The ViewItem object

• guiObj – The GUI object created from the ViewItem

• hasProps – The HasProperties instance

• propGui – The PropGui instance, in which references to all event callbacks are stored

fsleyes_props.build._configureEventCallback(viewItem, callback, evType, hasProps, guiObj, propGui)

Called by both the _configureVisibleWhen() and _configureEnabledWhen() functions.

Wraps the given callback function (which is essentially a ViewItem.visibleWhen or ViewItem.enabledWhen function) inside another function, which handles the marshalling of arguments to be passed to the callback.

The arguments that are passed to the function depend on the value of the ViewItem.dependencies attribute - see the build_parts module for an explanation.

The resulting callback function is added to the PropGui.onChangeCallbacks list.

Parameters

• viewItem – The ViewItem instance

• callback – The callback function to be encapsulated.

• evType – Purely for logging. Either ‘visible’ or ‘enable’.

• hasProps – The HasProperties instance.

• guiObj – The wx GUI object which has been created from the viewItem specification.

• propGui – The PropGui instance which stores references to all event callbacks.

fsleyes_props.build._createLinkBox(parent, viewItem, hasProps, propGui)

Creates a checkbox which can be used to link/unlink a property from its parent property.

fsleyes_props.build._createLabel(parent, viewItem, hasProps, propGui)

Creates a wx.StaticText object containing a label for the given ViewItem.

fsleyes_props.build._createButton(parent, viewItem, hasProps, propGui)

Creates a wx.Button object for the given Button object.

fsleyes_props.build._createToggle(parent, viewItem, hasProps, propGui)

Creates a widget for the given Toggle object. If no icons have been set, a wx.CheckBox is used. Otherwise a BitmapToggleButton is used.

fsleyes_props.build._createWidget(parent, viewItem, hasProps, propGui)

Creates a widget for the given Widget object, using the makeWidget() function (see the props.widgets module for more details).

fsleyes_props.build._makeGroupBorder(parent, group, ctr, *args, **kwargs)

Makes a border for a Group.

If a the border attribute of a Group object has been set to True, this function is called. It creates a parent wx.Panel with a border and title, then creates and embeds the GUI object representing the group (via the ctr argument). Returns the parent border panel, and the group GUI object. Parameters:

Parameters

• parent – Parent GUI object

• group – VGroup, HGroup or NotebookGroup

• ctr – Constructor for a wx.Window object.

• args – Passed to ctr. You don’t need to pass in the parent.

• kwargs – Passed to ctr.

fsleyes_props.build._createNotebookGroup(parent, group, hasProps, propGui)

Creates a fsleyes_widgets.notebook.Notebook object from the given NotebookGroup object.

The children of the group object are also created via recursive calls to the _create() function.

fsleyes_props.build._layoutHGroup(group, parent, children, labels)

Lays out the children (and labels, if not None) of the given HGroup object. Parameters:

Parameters

• group – HGroup object

• parent – GUI object which represents the group

• children – List of GUI objects, the children of the group.

• labels – None if no labels, otherwise a list of GUI Label objects, one for each child.

fsleyes_props.build._layoutVGroup(group, parent, children, labels)

Lays out the children (and labels, if not None) of the given VGroup object. Parameters the same as _layoutHGroup().

fsleyes_props.build._createGroup(parent, group, hasProps, propGui)

Creates a GUI panel object for the given HGroup or VGroup.

Children of the group are recursively created via calls to _create(), and laid out via the _layoutHGroup or _layoutVGroup functions.

fsleyes_props.build._createHGroup(parent, group, hasProps, propGui)

Alias for the _createGroup() function.

fsleyes_props.build._createVGroup(parent, group, hasProps, propGui)

Alias for the _createGroup() function.

fsleyes_props.build._getCreateFunction(viewItemClass)

Searches within this module for a function which can parse instances of the specified ViewItem class.

A match will be found if the given class is one of those defined in the build_parts module, or has one of those classes in its base class hierarchy. In other words, application-defined subclasses of any of the build_parts classes will still be built.

fsleyes_props.build._create(parent, viewItem, hasProps, propGui)

Creates a GUI object for the given ViewItem object and, if it is a group, all of its children.

fsleyes_props.build._defaultView(hasProps)

Creates a default view specification for the given HasProperties object, with all properties laid out vertically. This function is only called if a view specification was not provided in the call to the buildGUI() function

fsleyes_props.build._prepareView(hasProps, viewItem, labels, tooltips, showUnlink)

Recursively steps through the given viewItem and its children (if any).

If the viewItem is a string, it is assumed to be a property name, and it is turned into a Widget object. If the viewItem does not have a label/tooltip, and there is a label/tooltip for it in the given labels/tooltips dict, then its label/tooltip is set. Returns a reference to the updated/newly created ViewItem.

fsleyes_props.build._finaliseCallbacks(hasProps, propGui)

Calls all defined ViewItem visibleWhen and enabledWhen callback functions, in order to set the initial GUI state.

Also registers a listener on the top level GUI panel to remove all property listeners from the hasProps instance when the panel is destroyed.

fsleyes_props.build.buildGUI(parent, hasProps, view=None, labels=None, tooltips=None, showUnlink=False)

Builds a GUI interface which allows the properties of the given HasProperties object to be edited.

Returns a reference to the top level GUI object (typically a wx.Frame, wx.Panel or Notebook).

Parameters:

Parameters

• parent – The parent GUI object. If None, the interface is embedded within a wx.Frame.

• hasProps – The HasProperties instance.

• view – A ViewItem object, specifying the interface layout.

• labels – A dictionary specifying labels.

• tooltips – A dictionary specifying tooltips.

• showUnlink – If the given hasProps instance is a SyncableHasProperties instance, and it has a parent, a ‘link/unlink’ checkbox will be shown next to any properties that can be bound/unbound from the parent object.

fsleyes_props.build.buildDialog(parent, hasProps, view=None, labels=None, tooltips=None, showUnlink=False, dlgButtons=True)

Convenience method which embeds the result of a call to buildGUI() in a wx.Dialog.

See the buildGUI() documentation for details on the paramters.

Parameters

dlgButtons – If True, the dialog will have ‘Ok’ and ‘Cancel’ buttons.