Control - Advanced

Widget

For a complete explanation of code to write for each function, or to create a class from scratch, please have a look to IControlWidget and example after.

To create a class for standard QWidget, you can copy/paste this code

Widget selector

Here plugin is exactly the same as simple approach, except that it returns XyzControlWidgetSelector instead of XyzControlWidget.

from openalea.oalab.plugin.control import ControlWidgetSelectorPlugin
from openalea.deploy.shared_data import shared_data

class PluginXyzWidgetSelector(ControlWidgetSelectorPlugin):

    controls = ['IXyz'] # Interface name like IInt
    edit_shape = ['responsive']
    name = 'XyzWidgetSelector'

    def __call__(self):
        from mypackage.plugins.selectors import XyzControlWidgetSelector
        return XyzControlWidgetSelector

See also

See IInt example for real case

IInt control widget

All Qt sliders define "value" and "setValue" methods directly compatible with IInt (int), so there is almost nothing to do:

We will use these widgets depending on context:

• QDial for responsive, large and small shapes
• QSlider for vline
• QSpinBox for hline

We define also a widget to edit constraints

Now, lets define widget selector to group all classes together :

You can notice in line 11, instruction to set widget to fit to vline shape.

And finally, lets define plugin that links to it.

Warning

All classes can be defined in same file excepted last one. PluginIntWidgetSelector must be defined in a separated file to allow to load only description.

Glossary

create mode

Users want to create a control from scratch. In other words, it can be considered as "write-only" widget.

view mode

Users want to visualize a control. If control value changes, users may want to see changes. In other words, it can be considered as a "read-only" with option to enable auto-read mode.

edit mode

Users want to edit a control. If control value changes, users may want to reload changes. Users may want theirs changes to be applied dynamically or not. In other words, it can be considered as a "read/write" widget with options to enable both auto-read mode mode and auto-apply mode.

auto-read mode

If widget has auto-read mode enabled: if value changes, view is automatically refreshed to display new value.

auto-apply mode

If widget has auto-apply mode enabled: each time users modify data in the view, changes are automatically applied to object being edited.

control shape

shape supported by a control editor or viewer:

• hline: widget fits well in an horizontal line for example in a cell in a table or spreadsheet, in a 200x20px widget, ...
• vline: widget fits well in a vertical line, for example in 20x200px widget
• small: widget fits well in a small squared widget (100x100 px to 300x300 px)
• large: widget fits well in large space (> 300x300 px)
• responsive: widget can fit well in all shapes and sizes. Hardest to create but easiest to use.

Details

class openalea.oalab.plugin.oalab.control.ControlWidgetSelectorPlugin

Bases: object

controls = []

create_shape = []

edit_shape = []

icon_path = None

implement = 'IWidgetSelector'

name_conversion = 1

paint = False

view_shape = []

class openalea.oalab.plugin.oalab.control.IConstraintWidget(**kargs)

Bases: openalea.core.interface.IInterface

constraints(interface=None)

Returns a dict "constraint name" -> "value"

class openalea.oalab.plugin.oalab.control.IControlWidget

Bases: openalea.core.interface.IInterface

An IControlWidget is a

apply(control)

Update control with widget values.

autoapply(control, auto=True)

Enable auto-apply mode on given control

autoread(control, auto=True)

Enable auto-read mode on given control. Important, control passed to autoread and autoapply can be identical or different. For example if you want to refresh view if a template changes and apply it automatically to your current control.

notify(sender, event)

Method called when Observed control changes. Generally, when control send an event "ValueChanged", we want to refresh widget with new value.

on_value_changed(*args, **kwargs)

Method called when value changed. This method generally read control and refresh view if auto-read mode is enabled.

read(control)

Update widget with control values

reset(value=None, *kargs)

Reset widget to default values.

set(control)

Use control to preset widget. Starts to listen to control events and read control's values

setValue(value)

Change widget value. If your class derivates from an third-party widget, it is sometime necessary to adapt control value type to widget supported type. Example unicode to QString in pyqt API v1.

value(interface=None)

Returns widget value. If your class derivates from an third-party widget, it is sometime necessary to adapt widget value type to control type. If widget supports more than one interface, returned value depends on given interface. If none, returns widget preferred type.

class openalea.oalab.plugin.oalab.control.IWidgetSelector

Bases: openalea.core.interface.IInterface

classmethod create(shape=None)

Returns an instance of IControlWidget that can generate controls.

classmethod edit(control, shape=None)

Returns an instance of IControlWidget that modifies control in place. Control can be updated continuously or on explicit user action (click on apply button for instance)

classmethod edit_constraints()

Returns a widget to edit constraints. This widget must respect IConstraintWidget interface.

classmethod paint(control, painter, rectangle, option=None)

Paints widget using painter. This function never modify control.

classmethod snapshot(control, shape=None)

Returns a widget representing control

classmethod view(control, shape=None)

Returns an instance of IControlWidget that view control. This function never modify control. If you finally want to modify it, you can call "apply" explicitly.