1. Qube
2. Submission Interfaces

Submission Interfaces

Like the menu and panel plugin types, the submission plugins are written in Python 3. Each submission plugin is executed directly by the plugin system, so for example you can use Python to automate the building of parameters, pre-fill default values, or adapt to changes the user makes.

At last count Qube! UI ships with 33 submission plugins that you can find in the plugins/submission directory under the application directory (or under QubeUI\bin on Windows). Looking through the submission dialogs for each type in the UI and then reading the corresponding section of it's plugin file is a good way to quickly find how to do what you need in a particular situation.

Submission plugin terminology

Field

See parameter.

Page

Submission plugin pages are used to group related parameters. Only a single page is shown by the submission dialog at one time.

Parameter

A submission plugin is built up of multiple parameters and is the main mechanism for getting input from the user. Some examples of submission parameters could be an output directory path, an image file type, or a verbosity flag. The terms parameter and field are synonymous and are used interchangeably in this documentation.

Creating a new submission type plugin

The best place to start when creating a new submission plugin is to copy an existing one that's closest to what you intend to make. For the purposes of this documentation we'll start from scratch and create a new plugin for making proxy images using imagemagick.

The process is as follows:

1. Add the submission type.
2. Add a new page.
3. Add parameters.
4. Override defaults for fields in the Qube Basics page.
5. Set the command template.

1. Add the submission type

The first thing to do is tell the UI we're adding a new submission plugin, we do this by calling the built-in function add_submission_type(). For this example we use the following parameters:

Check the documentation for add_submission_type() for information on the command's arguments.

2. Add a new page

Use pages to group related fields together. We add pages by calling add_page() with a single argument, the page's name.

3. Add parameters

After you add a page it becomes current, every field that follows is added to that page until you add a new one. We'll add a Source Path parameter using add_field().

A description of all supported field types and their arguments is included at the end of this page so we'll just go over the arguments used in this example here. The first argument is always the name of the parameter and is generally shown along side the parameter in the submission dialog. The type argument is optional but recommended, it explicitly specifies what kind of parameter this is, such as a text field, a list or in this case a directory path (if we wanted a file path we'd use 'filename' as the parameter type). The required argument, when True, stops the user from submitting their job until the parameter has a valid value in the submission dialog. The destination argument tells the UI to store the value of the parameter in the submitted Qube! job in the specified position, in our example we store the Source Path in the job package. After submitting the job we can retrieve the value like this:

You can also view it in the Job Package section of the Job Internals panel inside Qube! UI.

Let's keep going and make a new Output page and parameter for the output path.

The Destination Path parameter is nearly identical to our Source Path parameter so we'll skip the explanation and move on.

We now add a parameter to specify the scale of the proxy as a percentage, this parameter is also required but since it also has a default (50%) we don't need to fill it manually, as long as we're happy with a 50% proxy that is. Notice that we haven't specified the parameter type, the UI infers that this is a integer spin box from the fact that we have min / max arguments and their values are integers. If no type can be inferred by the arguments the UI will use a single line text filed ( string type), this would have been the case for our source/destination path parameters if we hadn't explicitly set the type to path .

Our last field is a simple single line text field that allows the user to specify a file glob for the images to be resized, we set it's default to *.exr . 

3. Override defaults for fields in the Qube Basics page

For our proxy submission type we only want a single worker processing the images so we need to override some preexisting values controlling this.

To set existing fields we use their page and parameter names and pass in a new value. Note that both page and parameter names are case sensitive.

4. Set the command template.

The command template is where we specify the commands to be run on a Qube! worker during job execution. Firstly, for those new to Python you can create a string variable like this:

The command template works in the same way, where the parameter names act as the keys to the dictionary. In our example command template we make a new directory and then run magick to resize the images.

Submission Plugin Functions

add_submission_type

Create a new submission plugin. Each plugin should have exactly one call to add_submission_type() . 

add_page

Add a new page to the submission dialog and make it current. New fields are added to the current page.

add_field

Add a parameter to the current page.

Common arguments

string

A simple single line text field.

text

A multi line text field.

bool

A checkbox.

int

A integer spinbox.

float

A floating point spinbox.

combo

A drop down menu, allows for a single selection from a list of items.

path

A single line text field with a browse button that opens a file dialog to select a directory path.

combo_path

The same as the path parameter type but also allows for selection of paths from a combo .

filename

A single line text field with a browse button that opens a file dialog to select a file path.

combo_file

The same as the filename parameter type but also allows for selection of file paths from a  combo .

list

A list box where the user can select either a single or multiple values.

table

A table of values of given dimensions that the user can enter values.

datetime

A date and time selection parameter.

selectorString

A selectorString parameter uses a Python function to generate a list of strings, take this example from the Worker Selection page (found in python/99_qube_parameters.py in the standard plugin path on your system).

Here we create a Python function that takes no arguments and returns a list. We use the Qube! Python API module qb to find all Qube! workers and return that. Here's how that looks on my Qube! network after clicking the corresponding ... button.

set_field

Set the value of an existing field.

set_command_template

Set the command template for Qube! jobs submitted with this submission type.