Karabo GUI API¶

The Bindings¶

class karabogui.api.BaseBinding¶

The base class for all bindings. It represents a single node in an object created from a schema. It has a dictionary of attributes and a value trait which contains the value of the node. The value is validated using normal Traits validation.

Parameters:

attributes – The dictionary of the attributes belonging to the BaseBinding.
config_update – Traits.Event which fires when the value is updated externally
historic_data – Traits.Event which fires when historic data arrives for this object node. The data is contained in the new value passed to notification handlers
value – The value contained in this node. Derived classes should redefine this. The default is Traits.Undefined.
timestamp – The timestamp when the value was last set on the device. Instance of karabo.native.Timestamp.

Parameters:

displayed_name – The displayed name of the property
display_type – The display type of the property. This might provide more options later on.
access_mode – The access mode specification of the binding taking an enum of karabo.native.AccessMode.
assignment – The assignment setting with an enum of karabo.native.Assignment.
options – The list of options for this base binding.
required_access_level – The required access level with enums of karabo.native.AccessLevel.
unit_label – The unit label string combining the unit and metric prefix.

check(value)¶: Check and validate the value of this binding

is_allowed(state)¶

Return True if the given state is an allowed state for this binding.

Parameters:	state – Ideally an instance of karabo.native.State otherwise a string that can be casted to a `State` enum.

There are several util functions for bindings available.

Binding functions¶

karabogui.api.has_options(binding)¶: Returns True if a binding has any options defined.

karabogui.api.get_default_value(binding, force=False)¶: Get the default value from a binding

karabogui.api.get_binding_value(binding, default=None)¶

Get the binding value, this function is used to deal with Undefined or None binding values.

Parameters:	default – return default if value is None or Undefined

karabogui.api.get_min_max(binding)¶: Given a BaseBinding instance, return the minimum and maximum values which can be assigned to its value trait.

karabogui.api.get_native_min_max(binding)¶

Returns the appropriate numeric minimum and maximum for a binding

Note: In of a vector binding the numeric limits of an element are returned

This function neglects binding specific minimum and maximum

karabogui.api.get_min_max_size(binding)¶: Given a BaseBinding instance, return the minimum and maximum size which can be assigned to the vector trait

karabogui.api.get_binding_array_value(binding, default=None)¶

Retrieve the array and timestamp data from a binding belonging to an array binding

Parameters:	default – default value to be returned if no value is available

This function checks for Undefined and None data. If not data is available the default is returned with actual timestamp.

Returns:	data, timestamp

karabogui.api.has_min_max_attributes(binding)¶: Check if there is a limit pair (inclusive, exclusive) in the attributes

karabogui.api.build_binding(schema, existing=None)¶: Given a schema object, build an object binding which matches the structure defined in the schema. All leaf nodes are built with an initial value of Undefined.

The atomic bindings¶

class karabogui.api.BoolBinding¶

class karabogui.api.ByteArrayBinding¶

class karabogui.api.CharBinding¶

class karabogui.api.ComplexBinding¶

class karabogui.api.FloatBinding¶

class karabogui.api.Int8Binding¶

class karabogui.api.Int16Binding¶

class karabogui.api.Int32Binding¶

class karabogui.api.Int64Binding¶

class karabogui.api.StringBinding¶

class karabogui.api.TableBinding¶

class karabogui.api.Uint8Binding¶

class karabogui.api.Uint16Binding¶

class karabogui.api.Uint32Binding¶

class karabogui.api.Uint64Binding¶

class karabogui.api.VectorBoolBinding¶

class karabogui.api.VectorCharBinding¶

class karabogui.api.VectorComplexDoubleBinding¶

class karabogui.api.VectorComplexFloatBinding¶

class karabogui.api.VectorDoubleBinding¶

class karabogui.api.VectorFloatBinding¶

class karabogui.api.VectorHashBinding¶

The VectorHash Binding for Table elements of devices

Parameters:	row_schema – Instance of Hash containing the row schema bindings – A dictionary of bindings associated to the column keys

class karabogui.api.VectorInt8Binding¶

class karabogui.api.VectorInt16Binding¶

class karabogui.api.VectorInt32Binding¶

class karabogui.api.VectorInt64Binding¶

class karabogui.api.VectorStringBinding¶

class karabogui.api.VectorUint8Binding¶

class karabogui.api.VectorUint16Binding¶

class karabogui.api.VectorUint32Binding¶

class karabogui.api.VectorUint64Binding¶

class karabogui.api.VectorNoneBinding¶

Category Bindings¶

class karabogui.api.VectorBinding¶: The base class for all vector binding types

class karabogui.api.VectorNumberBinding¶: The base class for all vector binding types which contain types supported by numpy.

class karabogui.api.NodeBinding¶

class karabogui.api.IntBinding¶: The base class for all integer binding types

class karabogui.api.SignedIntBinding¶: The base class for all signed integer binding types

class karabogui.api.UnsignedIntBinding¶: The base class for all unsigned integer binding types

Available Node Bindings¶

class karabogui.api.NDArrayBinding¶

class karabogui.api.ImageBinding¶

class karabogui.api.WidgetNodeBinding¶

The Property Proxy¶

The key proxy that is contained in a widget controller on a scene. The so-called PropertyProxy. It contains all the necessary information and is passed on updates to the controller’s methods.

class karabogui.api.PropertyProxy¶

A proxy for a single device property

Parameters:	path – Full path of the property key – Full ‘key’ of the property: <device ID>.<path> binding – The binding for the property value – The value for the property (from the binding instance) edit_value – A user-entered value root_proxy – Parent device proxy pipeline_parent_path – Potential parent path if binding is a child of a Pipeline Output

Util functions for Property Proxies¶

karabogui.api.get_editor_value(property_proxy, default=None)¶

Return the correct value of a PropertyProxy to show in an editor

Parameters:	default – return default if value is None or Undefined

karabogui.api.axis_label(proxy)¶: Return the axis label for a PropertyProxy instance

karabogui.api.is_proxy_allowed(proxy)¶: Retrieve if the reconfiguration of the PropertyProxy is allowed

The GUI Parameter - The displayType¶

Karabo devices provide a self description of their properties, the so-called device schema. In most cases this Schema is static and does not change on runtime of the device.

In order for the KaraboGUI client to know how to act on certain properties, the displayType attribute can be specified on certain device properties.

The GUI then can react with a different kind of coloring in the Configurator, or provide a different set of widget controllers for this property.

The Widget Controller¶

The BaseBindingController class is the base class of the controllers that are visible on a scene. Every widget containing a device property must inherit this class.

class karabogui.api.BaseBindingController¶

The base class of controllers which mediate the connection between a data binding model (and a scene model) and a scene widget view.

add_proxy(proxy)¶

Implemented by subclasses to catch new PropertyProxy instances as they are added to the controller. Returns True if the controller can make use of the added proxy instance.

OPTIONAL: Not all widgets are capable of visualizing mutiple properties

binding_update(proxy)¶

Implemented by subclasses to receive notifications that the binding trait of a proxy attached to the controller has been updated.

OPTIONAL: Not all widgets care when their bindings change.

create_widget(parent)¶: Implemented by subclasses to create the widget needed to visualize a binding.

deferred_update()¶

Implemented by subclasses to update controller as requested by update_later.

OPTIONAL: Override this method to run long-running code, and call update_later instead.

state_update(proxy)¶

Implemented by subclasses to receive notifications that the device parent of proxy has updated its state.

OPTIONAL: Not all widgets care about device state

update_later()¶

Call longer-running code at a later time

If the controller has code that takes a while to run, it should be moved to the deferred_update method and the widget should call update_later to schedule this update.

This keeps the GUI responsive.

This is especially important for properties which change often, as deferred_update will only be called after many updates have finished.

value_update(proxy)¶

Implemented by subclasses to receive notifications that the data value in a proxy attached to the controller has been updated.

“OPTIONAL”: Not all widgets care when their values change, but most do.

A BaseBindingController must be registered in the scene model factory

class karabogui.api.register_binding_controller(*, ui_name='', klassname='', binding_type=(), is_compatible=None, priority=0, can_edit=False, can_show_nothing=True)¶

A class decorator for BaseBindingController subclasses which registers the widget for the various UI builders and adds some useful metadata.

Parameters:

ui_name – The name seen by users in the widget selection menu
klassname – The name of the widget in the scene file format. This is used for disambiguation in some of the legacy widgets.
binding_type – A tuple of BaseBinding classes which denotes the types understood by the controller.
can_edit – If True, this controller is recognized as an editor.
is_compatible – A callable which gives the controller extra control over the process of checking a binding instance for compatibility with this controller. The callable should accept one argument of type BaseBinding.
priority – A priority value for this controller which can influence sorting and picking of defaults when dragging from the configurator.
can_show_nothing – If True, the controller should be able to tolerate calls of its value_update and state_update with binding instances whose timestamp is None. see BaseBindingController.finish_initialization

Util functions for controllers¶

karabogui.api.with_display_type(display_type)¶: Create a checker function for the is_compatible argument of register_binding_controller which looks for a specific display type of property.

karabogui.api.add_unit_label(proxy, widget, parent=None)¶: Add a unit label to a widget, if available.

Util functions to work with arrays and images¶

karabogui.api.get_array_data(proxy, default=None)¶

Retrieve the array and timestamp data from a property proxy belonging to an array binding

Parameters:	default – default value to be returned if no value is available

This function checks for Undefined on the proxy value and None data. If not data is available the default is returned with actual timestamp.

Returns:	data, timestamp

karabogui.api.get_image_data(image_node, dimX, dimY, dimZ)¶: Calculate a numpy array from the given image_node depending on the given dimensions and return it to use for image display. In case no data is included, a NoneType is returned.

karabogui.api.get_dimensions_and_encoding(image_node)¶: The dimensions and the encoding of the given image_node are returned.

Validators¶

The KaraboGUI api offers a variety of QValidators that can be set on widgets.

karabogui.api.BindingValidator¶

karabogui.api.ListValidator¶

karabogui.api.SimpleValidator¶