Skip to content

ui

Graphical user interface (GUI) classes and functions, based on Qt PySide, to build graphical interfaces that use Deadline Cloud.

CancelationFlag

Helper object for background thread cancelation. The destroyed event cannot be connected to a member function of the class. With this object, you can bind it to the cancelation flag's set_canceled method instead.

Example usage:

class MyWidget(QWidget): thread_event = Signal(str)

def __init__(self):
    self.canceled = CancelationFlag()
    self.destroyed.connect(self.canceled.set_canceled)

def _my_thread_function(self):
    ...<processing>...

    if not self.canceled:
        self.thread_event.emit(result)

block_signals(element)

Context manager used to turn off signals for a UI element.

gui_context_for_cli(automatically_install_dependencies)

A context manager that initializes a Qt GUI context for the CLI handler to use.

For example:

with gui_context_for_cli(automatically_install_dependencies) as app: from deadline.client.ui.cli_job_submitter import show_cli_job_submitter

show_cli_job_submitter()

app.exec()

If automatically_install_dependencies is true, dependencies will be installed without prompting the user. Useful if the command is triggered not from a command line.

gui_error_handler(message_title, parent=None)

A context manager that initializes a Qt GUI context that catches errors and shows them in a message box instead of punting them to a CLI interface.

For example:

with gui_context(): from deadline.client.ui.cli_job_submitter import show_cli_job_submitter

show_cli_job_submitter()

dataclasses

Contains dataclasses for holding UI parameter values, used by the widgets.

CliJobSettings dataclass

Settings for a CLI Job.

CustomAmountRequirement dataclass

Settings for a CustomAmountWidget

CustomAttributeRequirement dataclass

Settings for a CustomAttributeWidget

CustomRequirements dataclass

Settings for a CustomRequirementsWidget.

HardwareRequirements dataclass

Settings for a HardwareRequirementsWidget.

HostRequirements dataclass

Settings for a HostRequirementsWidget.

JobBundleSettings dataclass

Settings for the Job Bundle submitter dialog.

OsRequirements dataclass

Settings for a OSRequirementsWidget.

dialogs

DeadlineConfigDialog

Bases: QDialog

A modal dialog box for modifying the AWS Deadline Cloud local workstation configuration.

Example code

DeadlineConfigDialog.configure_settings(parent=self)

configure_settings(parent=None, set_profile_focus=False) staticmethod

Static method that runs the Deadline Config Dialog.

Parameters:

Name Type Description Default
parent Optional[QWidget]

Parent widget

None
set_profile_focus bool

Optional boolean to set the initial focus to the profile selector

False

Returns True if any changes were applied, False otherwise.

DeadlineLoginDialog

Bases: QMessageBox

A modal dialog box for logging in to AWS Deadline Cloud. The return value of the static DeadlineLoginDialog.login() and the modal exec() is True when the login is successful, False otherwise.

Example code

if DeadlineLoginDialog.login(parent=self): print("Logged in successfully.") else: print("Failed to log in.")

exec_()

Runs the modal login dialog, returning True if the login was successful, False otherwise.

handle_login_thread_exception(e)

Handles the signal sent from the background login thread when an exception is thrown.

handle_login_thread_message(message)

Handles the signal sent from the background login thread when the message needs to be set.

handle_login_thread_succeeded(success_message)

Handles the signal sent from the background login thread when the login has succeeded.

login(parent=None, force_refresh=False, close_on_success=True, config=None) staticmethod

Static method that runs the Deadline Login Dialog. Returns True for a successful login, False otherwise.

Parameters:

Name Type Description Default
force_refresh bool, default False

Forces a re-login even when already authorized.

False
close_on_success bool, default True

Closes the dialog on successful login, instead of showing a "successfully logged in" message.

True
config ConfigParser

The AWS Deadline Cloud configuration object to use instead of the config file.

None
JobBundlePurpose

Bases: str, Enum

EXPORT = 'export' class-attribute instance-attribute

A job bundle is being created for export.

SUBMISSION = 'submission' class-attribute instance-attribute

A job bundle is being created for immediate submission.

SubmitJobProgressDialog

Bases: QDialog

A modal dialog box for the submission progress while submitting a job bundle to AWS Deadline Cloud.

closeEvent(event)

Overrides the closeEvent function to shutdown any running threads before closing the dialog. If the submission is complete then any button, even 'X', should result in the dialog being accepted.

exec_()

Runs the modal job progress dialog, returns the submitted job ID if it was successful, otherwise None.

handle_create_job_thread_succeeded(job_id)

Handles the signal sent from the background CreateJob thread when the job creation has finished.

handle_hashing_thread_progress_report(progress_metadata)

Handles the signal sent from the background thread when reporting hashing progress. Sets the progress bar in the dialog based on the callback progress data from job attachments.

handle_print(message)

Handles the signal sent from the background thread to print messages to the log.

handle_request_warning_dialog(message, default_response)

Presents a dialog with the provided message.

Parameters:

Name Type Description Default
message str

The message to present to the user.

required
default_response bool

True if the default is to continue. This adds a "Do not ask again" button as well. False if the default is to Cancel.

required
handle_thread_exception(e)

Handles the signal sent from the background threads when an exception is thrown.

handle_upload_thread_progress_report(progress_metadata)

Handles the signal sent from the background thread when reporting upload progress. Sets the progress bar in the dialog based on the callback progress data from job attachments.

start_job_submission(job_bundle_dir, job_parameters=[], **kwargs)

Starts a job submission background thread and returns immediately. It wires up appropriate callbacks and then forwards all arguments.

See the documentation for deadline.client.api.create_job_from_job_bundle for more details.

SubmitJobToDeadlineDialog

Bases: QDialog

A widget containing all the standard tabs for submitting an AWS Deadline Cloud job.

If you're using this dialog within an application and want it to stay in front, pass f=Qt.Tool, a flag that tells it to do that.

Parameters:

Name Type Description Default
job_setup_widget_type QWidget

The type of the widget for the job-specific settings.

required
initial_job_settings dataclass

A dataclass containing the initial job settings

required
initial_shared_parameter_values dict[str, Any]

A dict of parameter values {, , ...} to override default queue parameter values from the queue. For example, a Rez queue environment may have a default "" for the RezPackages parameter, but a Maya submitter would override that default with "maya-2023" or similar.

required
auto_detected_attachments AssetReferences

The job attachments that were automatically detected from the input document/scene file or starting job bundle.

required
attachments AssetReferences

The job attachments that have been added to the job by the user.

required
on_create_job_bundle_callback OnCreateJobBundleCallback

A function to call when the dialog needs to create a Job Bundle. It is called with arguments: (widget, job_bundle_dir, settings, queue_parameters, asset_references, host_requirements, purpose). It can return either None or a dict with parameters about the submission. Currently, the additional parameters supported are: { # See documentation for deadline.client.api.create_job_from_job_bundle about these parameters "job_parameters": [{"name": "ParameterName", "value": "Parameter Value", ...}], "known_asset_paths": ["/path/1", ...], }

required
parent Optional[QWidget]

parent of the widget

None
f WindowFlags

Qt Window Flags

WindowFlags()
show_host_requirements_tab bool

Display the host requirements tab in dialog if set to True. Default to False.

False
submitter_name Optional[str]

Override the default submitter_name value

None
keyPressEvent(event)

Override to capture any enter/return key presses so that the Submit button isn't "pressed" when the enter/return key is.

on_export_bundle()

Exports a Job Bundle, but does not submit the job.

on_job_template_parameter_changed(parameter)

Handles an edit to a job template parameter.

When a queue parameter and a job template parameter have the same name, we update between them to keep them consistent.

on_shared_job_parameter_changed(parameter)

Handles an edit to a shared job parameter, for example one of the queue parameters.

When a queue parameter and a job template parameter have the same name, we update between them to keep them consistent.

on_submit()

Perform a submission when the submit button is pressed

save_job_parameters_to_job_bundle(job_bundle_dir, job_parameters)

Saves the job parameters to the job bundle. If the job bundle already has a parameter_values file, it updates it. Otherwise it creates it.

widgets

CustomAmountWidget

Bases: CustomCapabilityWidget

UI element to hold a single custom attribute.

get_requirement()

Returns an OpenJD parameter definition dict with a "value" key filled from the widget.

An amount capability is prefixed with "amount.worker.".

CustomAttributeValueWidget

Bases: QWidget

UI element to hold a single custom attribute value.

CustomAttributeWidget

Bases: CustomCapabilityWidget

UI element to hold a single custom attribute.

get_requirement()

Return an OpenJD parameter definition dict with a "value" key filled from the widget, and a list of values.

An attribute capability is prefixed with "attr.worker".

CustomCapabilityWidget

Bases: QGroupBox

UI element to hold a single custom requirement, either Attribute or Amount.

CustomRequirementsWidget

Bases: QGroupBox

UI elements to hold custom host requirements.

Parameters:

Name Type Description Default
parent Optional[QWidget]

The parent Qt Widget.

None
get_requirements()

Returns two lists of OpenJD parameter definition dicts for both amounts and attributes requirements.

DeadlineAuthenticationStatusWidget

Bases: QGroupBox

A Qt GroupBox widget that displays the current AWS Deadline Cloud authentication status.

This widget provides a visual indicator of the authentication status, showing an appropriate icon, profile name, and relevant action buttons based on the current authentication status.

Signals

switch_profile_clicked: Emitted when the user clicks to switch AWS profiles. login_clicked: Emitted when the user clicks the login button. logout_clicked: Emitted when the user clicks the logout option.

__init__(parent=None, show_profile_switch=True)

Initialize the authentication status widget.

Parameters:

Name Type Description Default
parent Optional[QWidget]

The parent Qt widget. Defaults to None.

None
show_profile_switch bool

Whether to show the switch profile control. Defaults to True.

True
DeadlineCloudSettingsWidget

Bases: QGroupBox

UI component for the Deadline Cloud settings.

refresh_setting_controls(deadline_authorized)

Refreshes the controls for UI items that depend on the AWS Deadline Cloud API for their values.

Parameters:

Name Type Description Default
deadline_authorized bool

Should be the result of a call to api.check_deadline_available, for example from an AWS Deadline Cloud Status Widget.

required
DirectoryPickerWidget

Bases: QWidget

A LineEdit + Directory Picker button, for choosing a directory.

If it is in the user's home directory, the value is shortened to ~/<subdir...>.

The caller can listen to the path_changed signal to be notified of modifications.

Parameters:

Name Type Description Default
initial_directory str

The directory to show initially.

required
directory_label str

The name of the directory for GUI messages. For example, "Job History Dir".

required
collapse_user_dir bool

Whether to collapse the user home directory to "~" or not.

False
setText(directory)

Sets the current directory value

text()

Gets the current directory value.

HardwareRequirementsWidget

Bases: QGroupBox

UI elements to hold list of hardware requirements.

Parameters:

Name Type Description Default
parent Optional[QWidget]

The parent Qt Widget.

None
get_requirements()

Returns a list of OpenJD parameter definition dicts with a "value" key filled from the widget.

Set the following capabilities according to OpenJD spec. - amount.worker.vcpu - amount.worker.memory - amount.worker.gpu - amount.worker.gpu.memory - amount.worker.disk.scratch

HostRequirementsWidget

Bases: QWidget

UI Elements that hold host requirements settings across all job types.

Parameters:

Name Type Description Default
parent Optional[QWidget]

The parent Qt Widget.

None
get_requirements()

Returns a list of OpenJD parameter definition dicts with values filled from the widget. If requirement settings are not enabled, then return None.

dict[str, Any] = {

"amounts": [ , ... ], # @optional "attributes": [ , ... ] # @optional

}

InputFilePickerWidget

Bases: _FileWidget

A LineEdit + File Picker button, for choosing an input file.

If it is in the user's home directory, the value is shortened to ~/<subdir...>.

The caller can listen to the path_changed signal to be notified of modifications.

Parameters:

Name Type Description Default
initial_filename str

The filename to show initially.

required
file_label str

The name of the file for GUI messages. For example, "Input Scene File".

required
filter str

Selects file types. E.g. "Images (.png .xpm .jpg)" for a single filter, or for multiple filters, "Images (.png .xpm .jpg);;Text files (.txt);;XML files (.xml)".

required
selected_filter str

Chooses which filter to show by default.

required
collapse_user_dir bool

Whether to collapse the user home directory to "~" or not.

False
JobAttachmentsWidget

Bases: QWidget

The Widget for showing which files and folders will be attached, and to let the user configure more. The files and folders in auto_detected_attachments cannot be removed from the list, but they can be hidden or shown.

Parameters:

Name Type Description Default
auto_detected_attachments FlatAssetReferences

The job attachments that were automatically detected from the input document/scene file or starting job bundle.

required
attachments AssetReferences

(FlatAssetReferences): The job attachments that have been added to the job by the user.

required
get_asset_references()

Creates an asset_references object that can be saved as the asset_references.json|yaml file in a Job Bundle.

get_require_paths_exist()

Returns the checkbox value of whether to allow empty paths or not.

refresh_ui(auto_detected_attachments, attachments)

Refresh the job attachment lists if provided

JobBundleSettingsWidget

Bases: QWidget

Widget containing job setup specific to CLI jobs.

Signals

parameter_changed: This is sent whenever a parameter value in the widget changes. The message is a copy of the parameter definition with the "value" key containing the new value.

Parameters:

Name Type Description Default
initial_settings CliJobSettings

dataclass containing the job-specific settings.

required
parent Optional[QWidget]

The parent Qt Widget.

None
get_parameters()

Returns a list of OpenJD parameter definition dicts with a "value" key filled from the widget.

on_load_bundle()

Browse and load the selected submission bundle

set_parameter_value(parameter)

Given an OpenJD parameter definition with a "value" key, set the parameter value in the widget.

If the parameter value cannot be set, raises a KeyError.

update_settings(settings)

Update a settings object with the latest values.

OpenJDParametersWidget

Bases: QWidget

Widget that takes the set of Open Job Description parameters, for example from a job template or a queue, and generates a UI form to edit them.

Open Job Description has optional UI metadata for each parameter specified under "userInterface".

Signals

parameter_changed: This is sent whenever a parameter value in the widget changes. The message is a copy of the parameter definition with the "value" key containing the new value.

Parameters:

Name Type Description Default
parameter_definitions List[Dict[str, Any]]

A list of Open Job Description parameter definitions.

[]
async_loading_state str

A message to show its async loading state. Cannot provide both this message and the parameter_definitions.

''
parent Optional[QWidget]

The parent Qt Widget.

None
get_parameters()

Returns a list of OpenJD parameter definition dicts with a "value" key filled from the widget.

rebuild_ui(*, parameter_definitions=[], async_loading_state='')

Rebuilds the widget's UI to the new parameter_definitions, or to display the async_loading_state message.

set_parameter_value(parameter)

Given an OpenJD parameter definition with a "value" key, set the parameter value in the widget.

If the parameter value cannot be set, raises a KeyError.

OutputFilePickerWidget

Bases: _FileWidget

A LineEdit + File Picker button, for choosing an output file.

If it is in the user's home directory, the value is shortened to ~/<subdir...>.

The caller can listen to the path_changed signal to be notified of modifications.

Parameters:

Name Type Description Default
initial_filename str

The filename to show initially.

required
file_label str

The name of the file for GUI messages. For example, "Render Output Image".

required
filter str

Selects file types. E.g. "Images (.png .xpm .jpg)" for a single filter, or for multiple filters, "Images (.png .xpm .jpg);;Text files (.txt);;XML files (.xml)".

required
selected_filter str

Chooses which filter to show by default.

required
collapse_user_dir bool

Whether to collapse the user home directory to "~" or not.

False
SharedJobPropertiesWidget

Bases: QGroupBox

UI element to hold top level description components of the submission

The settings object should be a dataclass with
  • name: str The name of the Job to submit.
  • description: str The description of the Job to submit.
get_parameters()

Returns a list of OpenJD parameter definition dicts with a "value" key filled from the widget.

limited_max_worker_count_radio_button_toggled(state)

Enable the max worker count text box when limited max worker count radio button is enabled.

set_parameter_value(parameter)

Given an OpenJD parameter definition with a "value" key, set the parameter value in the widget.

If the parameter value cannot be set, raises a KeyError.

update_settings(settings)

Update a given instance of scene settings with updated values.

SharedJobSettingsWidget

Bases: QWidget

Widget that holds Job setup shared across all job types.

Signals

parameter_changed: This is sent whenever a parameter value in the widget changes. The message is a copy of the parameter definition with the "value" key containing the new value.

Parameters:

Name Type Description Default
initial_settings Any

dataclass containing the job-specific settings.

required
initial_shared_parameter_values dict[str, Any]

(dict[str, Any]): A dict of parameter values {, , ...} to override default queue parameter values from the queue. For example, a Rez queue environment may have a default "" for the RezPackages parameter, but a Maya submitter would override that default with "maya-2023" or similar.

required
parent Optional[QWidget]

The parent Qt Widget.

None
get_parameters()

Returns a list of OpenJD parameter definition dicts with a "value" key filled from the widget.

refresh_queue_parameters(load_new_bundle=False)

If the default queue id or job bundle has changed, refresh the queue parameters.

set_parameter_value(parameter)

Given an OpenJD parameter definition with a "value" key, set the parameter value in the widget.

If the parameter value cannot be set, raises a KeyError.

TimeoutEntryWidget

Bases: QWidget

A widget representing a single timeout row with checkbox, status icon, and time input fields.

Contains all the UI elements and logic for managing a single timeout entry including checkbox state, validation indicators, and time value calculations.

get_timeout_seconds()

Calculates the total timeout in seconds from the current days, hours, and minutes values.

Returns:

Name Type Description
int int

Total number of seconds represented by the current time values

set_enabled(enabled)

Enables or deactivates all time input fields in this row.

Parameters:

Name Type Description Default
enabled bool

If True, enables the input fields; if False, deactivates them

required
set_error_style(is_error)

Sets the error styling for the time input fields.

Parameters:

Name Type Description Default
is_error bool

If True, applies error styling; if False, removes it

required
set_status_icon(status)

Sets the status icon (warning or error) next to the checkbox.

Parameters:

Name Type Description Default
status str

The icon to display (WARNING_ICON, ERROR_ICON, or empty string)

required
set_timeout(total_seconds)

Sets the timeout value by converting seconds into days, hours, and minutes.

Parameters:

Name Type Description Default
total_seconds int

Total number of seconds to be distributed across time fields

required
update_state()

Updates the complete state of the row including enabled state, validation indicators, and suffixes based on current values and checkbox state.

update_suffix()

Updates the suffix of time input fields to be singular or plural based on their values. For example: "1 day" vs "2 days"

TimeoutTableWidget

Bases: QGroupBox

A widget for managing multiple timeout settings in a tabular format.

This widget provides a user interface for configuring multiple timeout entries, each consisting of a checkbox for activation/deactivation and time input fields for days, hours, and minutes. It includes validation, warning indicators, and error messages for invalid configurations.

Features: - Individual timeout rows with checkbox activation - Time input fields for days, hours, and minutes - Visual indicators for warnings and errors - Real-time validation and feedback - Automatic suffix updates (singular/plural) - Comprehensive error messaging

Parameters:

Name Type Description Default
timeouts TimeoutTableEntries

Configuration object containing timeout entries

required
parent QWidget

Parent widget. Defaults to None.

None
refresh_ui(timeouts)

Refreshes all UI elements to reflect the current timeout settings.

Parameters:

Name Type Description Default
timeouts TimeoutTableEntries

List of TimeoutEntry objects containing the current settings

required
update_settings(timeouts)

Updates the timeouts with the current values from the UI.