Skip to content

How to develop

Jump to bottom
yadizhou edited this page Nov 19, 2017 · 11 revisions

Overview

To understand how to create new widgets, first let’s look at the class hierarchy and relationships of those core classes in labpype.widget.

A widget is composed of attributes, behaviors, a set of anchors for input and output, a dialog for interaction, and the task it does. By subclassing Widget and Dialog class, and occasionally Anchor and BaseWidget class, we create new widgets.

Classes in blue are the ones provided by LabPype:

  • BaseWidget - Defines everything else of a widget except for the components we just mentioned.
  • Widget - A subclass of BaseWidget that tells the base class how to behave. This built-in child class of BaseWidget is a 5-state state machine that is sufficient for most cases.
  • Anchor - It is used for building connections between widgets.
  • Dialog - The superclass of all dialogs that are associated with widgets. It has many useful functions to make it simple for us to create dialogs.

Classes in green are the ones we would normally subclass. Subclass the Widget class, then specify a few class attributes and implement the task, we get a new widget. Among the class attributes, INCOMING and OUTGOING are the ones that specify the data type for input and output. They are by default instances of Anchor, which we do not need to subclass in most cases. Another attribute DIALOG specifies what dialog class should be used for interacting with this widget. If the widget is simple enough, then a dialog can be generated automatically by introspection. In this case, the base class Dialog will be assigned to the widget. To start, see section Basic

Classes in yellow are the ones that we only subclass when more flexibility is needed. For example, we can create a new subclass of BaseWidget that is an 8-state state machine, so that it can have more complicated behaviors. By subclassing the Anchor, we can change how connections are made and used in the workflow. See section Advanced for more details.

Basic

First, "a set of widgets" means a python package that is installed in LabPype. From now on, we will call it a widget package. It has the following minimal structure:

a_widget_package/
    __init__.py
    widget.py
    dialog.py
  • __init__.py - tells LabPype what widgets it provides and what types of connections can be made between the widgets.
  • widget.py - contains widgets that are child classes of Widget.
  • dialog.py - contains dialogs that are child classes of Dialog.

We can put other scripts or resources in the widget package. Note that, we cannot know where this package will be installed on the user's computer. Therefore, to refer to files in the package folder, always use __file__ to find the current path for the widget package:

pkgPath = os.path.dirname(os.path.realpath(__file__))

Here are the general steps for making a widget package. For more details, see Class Reference.

  1. Create the file structure as mentions before.
  2. In the widget.py, first define data types (also called anchor types) by subclassing ANCHOR_REGULAR (from labpype.widget). Note that this is different from subclassing Anchor. The purpose of Anchor is to define behaviors, while the anchor types simply represent a type of data. They are empty classes that are used to define legit connections between anchor types later. Then, subclass Widget for as many widgets as you have.
  3. Create dialogs for your widgets.
  4. In the __init__.py, import all the anchor types and widget classes you created in step 2. You do not need to import the dialogs, as they are the value of class attribute DIALOG of widgets. Then, define all kinds of legit connections between those anchor types in a list called ANCHORS. Last, put all the widgets in a list called WIDGETS, along with their colors and icons.
  5. Now you can move this package into workspace/installed/, restart LabPype. If no errors occurred, you should see the new widget set in the widget panel. Alternatively, you can zip the package, and in the widget manage dialog, install the package, as demonstrated in How to use section.

I strongly suggest that you take a look at the code in the ToyWidgetSet. Download and install the ToyWidgetSet, then check out workspace/installed/toy/.

Now skip the next section. Try to build some widgets with the help from Class Reference.

Advanced

TODO

Clone this wiki locally