OWWidget

The OWWidget is the main component for implementing a widget in the Orange Canvas workflow. It both defines the widget input/output capabilities and implements it’s functionality within the canvas.

Widget Meta Description

Every widget in the canvas framework needs to define it’s meta definition. This includes the widget’s name and text descriptions but more importantly also its input/output specification.

class IntConstant(OWWidget):
    name = "Integer Constant"
    description = "A simple integer constant"

    class Outputs:
        constant = Output("Constant", int)

    ...

    def commit(self):
        """Commit/send the outputs."""
        self.Outputs.constant.send(42)

Omitting the implementation details, this defines a simple node named Integer Constant which outputs (on a signal called Constant) a single object of type int.

The node’s inputs are defined similarly. Each input is then used as a decorator of its corresponding handler method, which accepts the inputs at runtime:

class Adder(OWWidget):
    name = "Add two integers"
    description = "Add two numbers"

    class Inputs:
        a = Input("A", int)
        b = Input("B", int)

    class Outputs:
        sum = Input("A + B", int)

    ...

    @Inputs.a
    def set_A(self, a):
        """Set the `A` input."""
        self.A = a

    @Inputs.b
    def set_B(self, b):
        """Set the `B` input."""
        self.B = b

    def handleNewSignals(self):
        """Coalescing update."""
        self.commit()

    def commit(self):
        """Commit/send the outputs"""
        sef.Outputs.sum.send("self.A + self.B)

Input/Output Signal Definitions

Widgets specify their input/output capabilities in their class definitions by defining classes named Inputs and Outputs, which contain class attributes of type Input and Output, correspondingly. Input and Output require at least two arguments, the signal’s name (as shown in canvas) and type. Optional arguments further define the behaviour of the signal.

Note: old-style signals define the input and output signals using class attributes inputs and outputs instead of classes Input and Output. The two attributes contain a list of tuples with the name and type and, for inputs, the name of the handler method. The optional last argument is an integer constant giving the flags. This style of signal definition is deprecated.

class Orange.widgets.widget.Input(name, type, id=None, doc=None, replaces=None, *, multiple=False, default=False, explicit=False)[source]

Description of an input signal.

The class is used to declare input signals for a widget as follows (the example is taken from the widget Test & Score):

class Inputs:
    train_data = Input("Data", Table, default=True)
    test_data = Input("Test Data", Table)
    learner = Input("Learner", Learner, multiple=True)
    preprocessor = Input("Preprocessor", Preprocess)

Every input signal must be used to decorate exactly one method that serves as the input handler, for instance:

@Inputs.train_data
def set_train_data(self, data):
    ...
Parameters:
  • (str) (id) – signal name
  • (type) (type) – signal type
  • (str) – a unique id of the signal
  • (str, optional) (doc) – signal documentation
  • (list of str) (replaces) – a list with names of signals replaced by this signal
  • (bool, optional) (explicit) – if set, multiple signals can be connected to this output (default: False)
  • (bool, optional) – when the widget accepts multiple signals of the same type, one of them can set this flag to act as the default (default: False)
  • (bool, optional) – if set, this signal is only used when it is the only option or when explicitly connected in the dialog (default: False)
class Orange.widgets.widget.Output(name, type, id=None, doc=None, replaces=None, *, default=False, explicit=False, dynamic=True)[source]

Description of an output signal.

The class is used to declare output signals for a widget as follows (the example is taken from the widget Test & Score):

class Outputs:
    predictions = Output("Predictions", Table)
    evaluations_results = Output("Evaluation Results", Results)

The signal is then transmitted by, for instance:

self.Outputs.predictions.send(predictions)
Parameters:
  • (str) (id) – signal name
  • (type) (type) – signal type
  • (str) – a unique id of the signal
  • (str, optional) (doc) – signal documentation
  • (list of str) (replaces) – a list with names of signals replaced by this signal
  • (bool, optional) (dynamic) – when the widget accepts multiple signals of the same type, one of them can set this flag to act as the default (default: False)
  • (bool, optional) – if set, this signal is only used when it is the only option or when explicitly connected in the dialog (default: False)
  • (bool, optional) – Specifies that the instances on the output will in general be subtypes of the declared type and that the output can be connected to any input signal which can accept a subtype of the declared output type (default: True)

Sending/Receiving

The widgets receive inputs at runtime with the handler method decorated with the signal, as shown in the above examples.

If an input is defined with the flag multiple set, the input handler method also receives a connection id uniquely identifying a connection/link on which the value was sent (see also Channels and Tokens)

The widget sends an output by calling the signal’s send method, as shown above.

Accessing Controls though Attribute Names

The preferred way for constructing the user interface is to use functions from module Orange.widgets.gui that insert a Qt widget and establish the signals for synchronization with the widget’s attributes.

gui.checkBox(box, self, “binary_trees”, “Induce binary tree”)

This inserts a QCheckBox into the layout of box, and make it reflect and changes the attriubte self.binary_trees. The instance of QCheckbox can be accessed through the name it controls. E.g. we can disable the check box by calling

self.controls.binary_trees.setDisabled(True)

This may be more practical than having to store the attribute and the Qt widget that controls it, e.g. with

self.binarization_cb = gui.checkBox(
box, self, “binary_trees”, “Induce binary tree”)

Class Member Documentation

class Orange.widgets.widget.OWWidget(*args, **kwargs)[source]

Base widget class

name = None

Widget name (str) as presented in the Canvas

description = ''

Short widget description (str optional), displayed in canvas help tooltips.

icon = 'icons/Unknown.png'

Widget icon path relative to the defining module

priority = 9223372036854775807

Widget priority used for sorting within a category (default sys.maxsize).

inputs = []

A list of published input definitions

outputs = []

A list of published output definitions

want_basic_layout = True

Should the widget have basic layout (If this flag is false then the want_main_area and want_control_area are ignored).

want_main_area = True

Should the widget construct a mainArea (this is a resizable area to the right of the controlArea).

want_control_area = True

Should the widget construct a controlArea.

buttons_area_orientation = 1

Orientation of the buttonsArea box; valid only if want_control_area is True. Possible values are Qt.Horizontal, Qt.Vertical and None for no buttons area

want_message_bar = True

Specify whether the default message bar widget should be created and placed into the default layout. If False then clients are responsible for displaying messages within the widget in an appropriate manner.

graph_name = None

Widget painted by Save graph button

resizing_enabled = True

If false the widget will receive fixed size constraint (derived from it’s layout). Use for widgets which have simple static size contents.

settingsHandler = None

type – SettingsHandler

settings_version = 1

Version of the settings representation Subclasses should increase this number when they make breaking changes to settings representation (a settings that used to store int now stores string) and handle migrations in migrate and migrate_context settings.

UserAdviceMessages = []

A list of advice messages (Message) to display to the user. When a widget is first shown a message from this list is selected for display. If a user accepts (clicks ‘Ok. Got it’) the choice is recorded and the message is never shown again (closing the message will not mark it as seen). Messages can be displayed again by pressing Shift + F1

Type:list of Message
set_basic_layout()[source]

Provide the basic widget layout

Which parts are created is regulated by class attributes want_main_area, want_control_area, want_message_bar and buttons_area_orientation, the presence of method send_report and attribute graph_name.

save_graph()[source]

Save the graph with the name given in class attribute graph_name.

The method is called by the Save graph button, which is created automatically if the graph_name is defined.

resizeEvent(event)[source]

Overloaded to save the geometry (width and height) when the widget is resized.

moveEvent(event)[source]

Overloaded to save the geometry when the widget is moved

hideEvent(event)[source]

Overloaded to save the geometry when the widget is hidden

closeEvent(event)[source]

Overloaded to save the geometry when the widget is closed

showEvent(event)[source]

Overloaded to restore the geometry when the widget is shown

wheelEvent(event)[source]

Silently accept the wheel event.

This is to ensure combo boxes and other controls that have focus don’t receive this event unless the cursor is over them.

reshow()[source]

Put the widget on top of all windows

openContext(*a)[source]

Open a new context corresponding to the given data.

The settings handler first checks the stored context for a suitable match. If one is found, it becomes the current contexts and the widgets settings are initialized accordingly. If no suitable context exists, a new context is created and data is copied from the widget’s settings into the new context.

Widgets that have context settings must call this method after reinitializing the user interface (e.g. combo boxes) with the new data.

The arguments given to this method are passed to the context handler. Their type depends upon the handler. For instance, DomainContextHandler expects Orange.data.Table or Orange.data.Domain.

closeContext()[source]

Save the current settings and close the current context.

Widgets that have context settings must call this method before reinitializing the user interface (e.g. combo boxes) with the new data.

retrieveSpecificSettings()[source]

Retrieve data that is not registered as setting.

This method is called by Orange.widgets.settings.ContextHandler.settings_to_widget. Widgets may define it to retrieve any data that is not stored in widget attributes. See Orange.widgets.data.owcolor.OWColor for an example.

storeSpecificSettings()[source]

Store data that is not registered as setting.

This method is called by Orange.widgets.settings.ContextHandler.settings_from_widget. Widgets may define it to store any data that is not stored in widget attributes. See Orange.widgets.data.owcolor.OWColor for an example.

saveSettings()[source]

Writes widget instance’s settings to class defaults. Usually called when the widget is deleted.

onDeleteWidget()[source]

Invoked by the canvas to notify the widget it has been deleted from the workflow.

If possible, subclasses should gracefully cancel any currently executing tasks.

handleNewSignals()[source]

Invoked by the workflow signal propagation manager after all signals handlers have been called.

Reimplement this method in order to coalesce updates from multiple updated inputs.

statusMessageChanged

Widget’s status message has changed.

setStatusMessage(text)[source]

Set widget’s status message.

This is a short status string to be displayed inline next to the instantiated widget icon in the canvas.

statusMessage()[source]

Return the widget’s status message.

keyPressEvent(e)[source]

Handle default key actions or pass the event to the inherited method

setBlocking(state=True)[source]

Set blocking flag for this widget.

While this flag is set this widget and all its descendants will not receive any new signals from the workflow signal manager.

This is useful for instance if the widget does it’s work in a separate thread or schedules processing from the event queue. In this case it can set the blocking flag in it’s processNewSignals method schedule the task and return immediately. After the task has completed the widget can clear the flag and send the updated outputs.

Note

Failure to clear this flag will block dependent nodes forever.

isBlocking()[source]

Is this widget blocking signal processing.

resetSettings()[source]

Reset the widget settings to default

workflowEnv()[source]

Return (a view to) the workflow runtime environment.

Returns:env
Return type:types.MappingProxyType
workflowEnvChanged(key, value, oldvalue)[source]

A workflow environment variable key has changed to value.

Called by the canvas framework to notify widget of a change in the workflow runtime environment.

The default implementation does nothing.

classmethod migrate_settings(settings, version)[source]

Fix settings to work with the current version of widgets

Parameters:
  • settings (dict) – dict of name - value mappings
  • version (Optional[int]) – version of the saved settings or None if settings were created before migrations
classmethod migrate_context(context, version)[source]

Fix contexts to work with the current version of widgets

Parameters:
  • context (Context) – Context object
  • version (Optional[int]) – version of the saved context or None if context was created before migrations
class Orange.widgets.widget.Message(text, persistent_id, icon=None, moreurl=None)[source]

A user message.

Parameters:
  • text (str) – Message text
  • persistent_id (str) – A persistent message id.
  • icon (QIcon or QStyle.StandardPixmap) – Message icon
  • moreurl (str) – An url to open when a user clicks a ‘Learn more’ button.