spinetoolbox.ui_main

Contains ToolboxUI class.

author

16. Savolainen (VTT)

date

14.12.2017

Module Contents

Classes

ToolboxUI

Class for application main GUI functions.

class spinetoolbox.ui_main.ToolboxUI

Bases: PySide2.QtWidgets.QMainWindow

Class for application main GUI functions.

Initializes application and main window.

msg

msg_success

msg_error

msg_warning

msg_proc

msg_proc_error

information_box

error_box

connect_signals(self)

Connect signals.

set_error_mode(self)

Sets Windows error mode to show all error dialog boxes from subprocesses.

See https://docs.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-seterrormode for documentation.

_update_execute_enabled(self)

_update_execute_selected_enabled(self)

update_window_modified(self, clean)

Updates window modified status and save actions depending on the state of the undo stack.

parse_project_item_modules(self)

Collects data from project item factories.

set_work_directory(self, new_work_dir=None)

Creates a work directory if it does not exist or changes the current work directory to given.

Parameters

new_work_dir (str, optional) – If given, changes the work directory to given and creates the directory if it does not exist.

project(self)

Returns current project or None if no project open.

qsettings(self)

Returns application preferences object.

update_window_title(self)

Updates main window title.

init_project(self, project_dir)

Initializes project at application start-up.

Opens the last project that was open when app was closed (if enabled in Settings) or starts the app without a project.

Parameters

project_dir (str) – project directory

new_project(self)

Opens a file dialog where user can select a directory where a project is created. Pops up a question box if selected directory is not empty or if it already contains a Spine Toolbox project. Initial project name is the directory name.

create_project(self, name, description, location)

Creates new project and sets it active.

Parameters

• name (str) – Project name

• description (str) – Project description

• location (str) – Path to project directory

open_project(self, load_dir=None)

Opens project from a selected or given directory.

Parameters

load_dir (str, optional) – Path to project base directory. If default value is used, a file explorer dialog is opened where the user can select the project to open.

Returns

True when opening the project succeeded, False otherwise

Return type

bool

restore_project(self, project_info, project_dir, ask_confirmation=True)

Initializes UI, Creates project, models, connections, etc., when opening a project.

Parameters

• project_info (dict) – Project information dictionary

• project_dir (str) – Project directory

• ask_confirmation (bool) – True closes the previous project with a confirmation box if user has enabled this

Returns

True when restoring project succeeded, False otherwise

Return type

bool

_toolbars(self)

Yields all toolbars in the window.

_disable_project_actions(self)

Disables all project-related actions, except New project, Open project and Open recent. Called in the constructor and when closing a project.

_enable_project_actions(self)

Enables all project-related actions. Called when a new project is created and when a project is opened.

refresh_toolbars(self)

Set toolbars’ color using highest possible contrast.

show_recent_projects_menu(self)

Updates and sets up the recent projects menu to File-Open recent menu item.

save_project(self)

Saves project.

save_project_as(self)

Asks user for a new project directory and duplicates the current project there. The name of the duplicated project will be the new directory name. The duplicated project is activated.

close_project(self, ask_confirmation=True)

Closes the current project.

Returns

True when no project open or when it’s closed successfully, False otherwise.

Return type

bool

rename_project(self, _checked=False)

Opens a dialog where the user can enter a new name for the project.

init_project_item_model(self)

Initializes project item model. Create root and category items and add them to the model.

init_specification_model(self)

Initializes specification model.

make_item_properties_uis(self)

populate_specification_model(self, specification_paths)

Populates specification model.

Parameters

specification_paths (list) – List of specification file paths for the current project

parse_specification_file(self, def_path)

load_specification_from_file(self, def_path)

Returns an Item specification from a definition file.

Parameters

def_path (str) – Path of the specification definition file

Returns

item specification or None if reading the file failed

Return type

ProjectItemSpecification

supports_specifications(self, item_type)

Returns True if given project item type supports specifications.

Returns

True if item supports specifications, False otherwise

Return type

bool

load_specification(self, definition)

Returns Item specification from a definition dictionary.

Parameters

definition (dict) – Dictionary with the definition

Returns

specification or None if factory isn’t found.

Return type

ProjectItemSpecification or NoneType

restore_ui(self)

Restore UI state from previous session.

clear_ui(self)

Clean UI to make room for a new or opened project.

undo_critical_commands(self)

Undoes critical commands in the undo stack.

Returns

False if any critical commands aren’t successfully undone

Return type

Bool

overwrite_check(self, project_dir)

Checks if given directory is a project directory and/or empty And asks the user what to do in that case.

Parameters

project_dir (str) – Abs. path to a directory

Returns

True if user wants to overwrite an existing project or if the directory is not empty and the user wants to make it into a Spine Toolbox project directory anyway. False if user cancels the action.

Return type

bool

item_selection_changed(self, selected, deselected)

Synchronizes selection with scene. The scene handles item/link de/activation.

refresh_active_elements(self, active_project_item, active_link)

_set_active_project_item(self, active_project_item)

Parameters

active_project_item (ProjectItemBase or NoneType) –

_set_active_link(self, active_link)

Parameters

active_link (Link or NoneType) –

activate_no_selection_tab(self)

Shows ‘No Selection’ tab.

activate_item_tab(self)

Shows active project item properties tab according to item type.

activate_link_tab(self)

Shows link properties tab.

import_specification(self)

Opens a file dialog where the user can select an existing specification definition file (.json). If file is valid, calls add_specification().

_save_specificiation_file(self, specification)

Saves the given spec. If the spec doesn’t have the definition_file_path attribute set, prompts the user to select a path.

Parameters

specification (ProjectItemSpecification) –

_prompt_to_save_specification_file(self, specification, candidate_def_file_path)

Shows a dialog for the user to select a path to save given spec.

Parameters

• specification (ProjectItemSpecification) – The spec

• candidate_def_file_path (str) – A proposed location.

Returns

True if the spec is saved successfully, False otherwise

Return type

bool

_do_save_specification(self, specification, new_def_file_path)

_emit_specification_saved(self, specification)

Prints a message in the event log, saying that given spec was saved in a certain location, together with a clickable link to change the location.

Parameters

specification (ProjectItemSpecification) –

add_specification(self, specification, update_existing=False, widget=None)

Adds given specification to the project if there’s no one with the same name. Otherwise it updates the existing one.

Parameters

• specification (ProjectItemSpecification) –

• update_existing (bool, optional) – If True, updates a spec with the same in the project. If False (the default), it complains instead.

• widget (QWidget, optional) – The specification editor widget that calls this method. Used to parent the QMessageBox

Returns

True if successful, False if not.

Return type

bool

do_add_specification(self, specification, row=None)

Adds a ProjectItemSpecification instance to project.

Parameters

specification (ProjectItemSpecification) – specification that is added to project

update_specification(self, row, specification)

Saves the given spec to disk, then sets it for the given row in the model, then refreshes the spec in all items that use it.

Parameters

• row (int) – Row of tool specification in ProjectItemSpecificationModel

• specification (ProjectItemSpecification) – An updated specification

remove_selected_specification(self, checked=False)

Removes specification selected in QListView.

remove_specification(self, row, ask_verification=True)

_get_items_with_spec(self, specification)

Yields project items with given specification.

Parameters

specification (ProjectItemSpecification) –

do_remove_specification(self, row, ask_verification=True)

Removes specification from ProjectItemSpecificationModel. Removes also specifications from all items that use this specification.

Parameters

• row (int) – Row in ProjectItemSpecificationModel

• ask_verification (bool) – If True, displays a dialog box asking user to verify the removal

remove_all_items(self)

Removes all items from project. Slot for Remove All button.

register_anchor_callback(self, url, callback)

Registers a callback for a given anchor in event log, see open_anchor(). Used by ToolFactory.repair_specification().

Parameters

• url (str) – The anchor url

• callback (function) – A function to call when the anchor is clicked on event log.

open_anchor(self, qurl)

Open file explorer in the directory given in qurl.

Parameters

qurl (QUrl) – The url to open

show_specification_context_menu(self, ind, global_pos)

Context menu for item specifications.

Parameters

• ind (QModelIndex) – In the ProjectItemSpecificationModel

• global_pos (QPoint) – Mouse position

edit_specification(self, index, item)

Open the tool specification widget for editing an existing tool specification.

Parameters

• index (QModelIndex) – Index of the item (from double-click or context menu signal)

• item (ProjectItem, optional) –

open_specification_file(self, index)

Open the specification definition file in the default (.json) text-editor.

Parameters

index (QModelIndex) – Index of the item

new_db_editor(self)

_handle_zoom_minus_pressed(self)

Slot for handling case when ‘-’ button in menu is pressed.

_handle_zoom_plus_pressed(self)

Slot for handling case when ‘+’ button in menu is pressed.

_handle_zoom_reset_pressed(self)

Slot for handling case when ‘reset zoom’ button in menu is pressed.

add_zoom_action(self)

Setups zoom widget action in view menu.

restore_dock_widgets(self)

Dock all floating and or hidden QDockWidgets back to the main window.

set_debug_qactions(self)

Set shortcuts for QActions that may be needed in debugging.

add_menu_actions(self)

Add extra actions to Edit and View menu.

toggle_properties_tabbar_visibility(self)

Shows or hides the tab bar in properties dock widget. For debugging purposes.

update_datetime(self)

Returns a boolean, which determines whether date and time is prepended to every Event Log message.

add_message(self, msg)

Append regular message to Event Log.

Parameters

msg (str) – String written to QTextBrowser

add_success_message(self, msg)

Append message with green text color to Event Log.

Parameters

msg (str) – String written to QTextBrowser

add_error_message(self, msg)

Append message with red color to Event Log.

Parameters

msg (str) – String written to QTextBrowser

add_warning_message(self, msg)

Append message with yellow (golden) color to Event Log.

Parameters

msg (str) – String written to QTextBrowser

add_process_message(self, msg)

Writes message from stdout to process output QTextBrowser.

Parameters

msg (str) – String written to QTextBrowser

add_process_error_message(self, msg)

Writes message from stderr to process output QTextBrowser.

Parameters

msg (str) – String written to QTextBrowser

restore_original_logs_and_consoles(self)

override_logs_and_consoles(self)

override_item_log(self)

Sets the log document of the active project item in Item Execution Log and updates title.

_do_override_item_log(self, document)

override_python_console(self)

Sets the python console of the active project item in Python Console and updates title.

_do_override_python_console(self, console)

override_julia_console(self)

Sets the julia console of the active project item in Julia Console and updates title.

_do_override_julia_console(self, console)

override_execution_list(self)

Displays executions of the active project item in Executions and updates title.

restore_original_item_log_document(self)

Sets the Item Execution Log document back to the original.

restore_original_python_console(self)

Sets the Python Console back to the original.

restore_original_julia_console(self)

Sets the Julia Console back to the original.

_update_item_log_title(self)

Updates Event Log title.

static _set_override_console(widget, console, new_title)

_refresh_execution_list(self)

Refreshes Executions as the active project item starts new executions.

_select_execution(self, current, _previous)

Sets the log documents of the selected execution in Event and Process Log, and any consoles in Python and Julia Console.

show_add_project_item_form(self, item_type, x=0, y=0, spec='')

Show add project item widget.

supports_specification(self, item_type)

Returns True if given item type supports specifications.

Parameters

item_type (str) – item’s type

Returns

True if item supports specifications, False otherwise

Return type

bool

show_specification_form(self, item_type, specification=None, item=None, **kwargs)

Shows specification widget.

Parameters

• item_type (str) – item’s type

• specification (ProjectItemSpecification, optional) – specification

• item (ProjectItem, optional) – project item

• **kwargs – parameters passed to the specification widget

get_all_multi_tab_spec_editors(self, item_type)

_get_existing_spec_editor(self, item_type, specification, item)

show_settings(self)

Show Settings widget.

show_about(self)

Show About Spine Toolbox form.

show_user_guide(self)

Open Spine Toolbox documentation index page in browser.

show_getting_started_guide(self)

Open Spine Toolbox Getting Started HTML page in browser.

show_item_context_menu(self, pos)

Context menu for project items listed in the project QTreeView.

Parameters

pos (QPoint) – Mouse position

show_project_item_context_menu(self, pos, index)

Creates and shows the project item context menu.

Parameters

• pos (QPoint) – Mouse position

• index (QModelIndex, None) – Index of concerned item or None

show_link_context_menu(self, pos, link)

Context menu for connection links.

Parameters

• pos (QPoint) – Mouse position

• link (Link(QGraphicsPathItem)) – The concerned link

refresh_edit_action_states(self)

Sets the enabled/disabled state for copy, paste, duplicate, and remove actions in File-Edit menu, project tree view context menu, and in Design View context menus just before the menus are shown to user.

enable_edit_actions(self)

Enables project item edit actions after a QMenu has been shown. This is needed to enable keyboard shortcuts (e.g. Ctrl-C & del) again.

tear_down_project(self)

Calls the tear_down method on the project.

tear_down_consoles(self)

CLoses the ‘base’ Python and Juliö Consoles if running.

_tasks_before_exit(self)

Returns a list of tasks to perform before exiting the application.

Possible tasks are:

• “prompt exit”: prompt user if quitting is really desired

• “prompt save”: prompt user if project should be saved before quitting

• “save”: save project before quitting

Returns

a list containing zero or more tasks

_perform_pre_exit_tasks(self)

Prompts user to confirm quitting and saves the project if necessary.

Returns

True if exit should proceed, False if the process was cancelled

_confirm_exit(self)

Confirms exiting from user.

Returns

True if exit should proceed, False if user cancelled

_confirm_save_and_exit(self)

Confirms exit from user and saves the project if requested.

Returns

True if exiting should proceed, False if user cancelled

remove_path_from_recent_projects(self, p)

Removes entry that contains given path from the recent project files list in QSettings.

Parameters

p (str) – Full path to a project directory

update_recent_projects(self)

Adds a new entry to QSettings variable that remembers twenty most recent project paths.

closeEvent(self, event)

Method for handling application exit.

Parameters

event (QCloseEvent) – PySide2 event

_serialize_selected_items(self)

Serializes selected project items into a dictionary.

The serialization protocol tries to imitate the format in which projects are saved.

Returns

a dict containing serialized version of selected project items

Return type

dict

_deserialized_item_position_shifts(self, item_dicts)

Calculates horizontal and vertical shifts for project items being deserialized.

If the mouse cursor is on the Design view we try to place the items unders the cursor. Otherwise the items will get a small shift so they don’t overlap a possible item below. In case the items don’t fit the scene rect we clamp their coordinates within it.

Parameters

item_dicts (dict) – a dictionary of serialized items being deserialized

Returns

a tuple of (horizontal shift, vertical shift) in scene’s coordinates

Return type

tuple

static _set_deserialized_item_position(item_dict, shift_x, shift_y, scene_rect)

Moves item’s position by shift_x and shift_y while keeping it within the limits of scene_rect.

_deserialize_items(self, items_dict, duplicate_files=False)

Deserializes project items from a dictionary and adds them to the current project.

Parameters

items_dict (dict) – serialized project items

project_item_to_clipboard(self)

Copies the selected project items to system’s clipboard.

project_item_from_clipboard(self, duplicate_files=False)

Adds project items in system’s clipboard to the current project.

Parameters

duplicate_files (bool) – Duplicate files boolean

duplicate_project_item(self, duplicate_files=False)

Duplicates the selected project items.

propose_item_name(self, prefix)

Proposes a name for a project item.

The format is prefix_xx where xx is a counter value [01..99].

Parameters

prefix (str) – a prefix for the name

Returns

a name string

Return type

str

_share_item_edit_actions(self)

Adds generic actions to project tree view and Design View.

_show_message_box(self, title, message)

Shows an information message box.

_show_error_box(self, title, message)

_connect_project_signals(self)

Connects signals emitted by project.

_set_execution_in_progress(self)

_unset_execution_in_progress(self)

set_icon_and_properties_ui(self, item_name)

Adds properties UI to given project item.

Parameters

item_name (str) – item’s name

project_item_properties_ui(self, item_type)

Returns the properties tab widget’s ui.

Parameters

item_type (str) – project item’s type

Returns

item’s properties tab widget

Return type

QWidget

project_item_icon(self, item_type)

_open_project_directory(self, _)

Opens project’s root directory in system’s file browser.

_open_project_item_directory(self, _)

Opens project item’s directory in system’s file browser.

_remove_selected_items(self, _)

Removes selected project items and links.

_rename_project_item(self, _)

Renames current project item.

item_category_context_menu(self)

Creates a context menu for category items.

Returns

category context menu

Return type

QMenu

project_item_context_menu(self, additional_actions)

Creates a context menu for project items.

Parameters

additional_actions (list of QAction) – actions to be prepended to the menu

Returns

project item context menu

Return type

QMenu

_start_base_julia_console(self)

Shows and starts the ‘base’ Julia Console if not running or activates the window if running.

_start_base_python_console(self)

Shows and starts the ‘base’ Python Console if not running or activates the window if running.

destroy_base_console(self, console_window_title)

Destroys the Python or Julia Console window reference.

Parameters

console_window_title (str) – Used in determining which console ref to destroy

make_console(self, name, item, kernel_name, connection_file)

Creates a new SpineConsoleWidget for given connection file if none exists yet, and returns it.

Parameters

• name (str) – Console name

• item (ProjectItem) – Item that owns the console

• kernel_name (str) – Name of the kernel

• connection_file (str) – Path of kernel connection file

Returns

SpineConsoleWidget

_shutdown_engine_kernels(self)

Shuts down all kernels managed by Spine Engine.