Helper functions: rafcon.gui.helpers

This package contains all GUI helper modules.

Every module covers actions for specific fields concerning labels, text formatting or actions on core objects that also have gui elements like there models (here the state and the state machine).

label

rafcon.gui.helpers.label.append_sub_menu_to_parent_menu(name, parent_menu, icon_code=None)
rafcon.gui.helpers.label.create_button_label(icon, font_size='10')

Create a button label with a chosen icon.

Parameters:

  • icon – The icon

  • font_size – The size of the icon

Returns:

The created label

rafcon.gui.helpers.label.create_check_menu_item(label_text='', is_active=False, callback=None, callback_args=(), is_sensitive=True, accel_code=None, accel_group=None)
rafcon.gui.helpers.label.create_label_widget_with_icon(icon, text, tooltip=None)
rafcon.gui.helpers.label.create_left_bar_window_title(upper_title, lower_title)

Create the title of the un-docked left-bar window based on the open tabs in the upper and lower notebooks.

Parameters:

  • upper_title – The title of the currently-opened tab in the upper notebook

  • lower_title – The title of the currently-opened tab in the lower notebook

Returns:

The un-docked left-bar window title as a String

rafcon.gui.helpers.label.create_menu_box_with_icon_and_label(label_text)
Creates a MenuItem box, which is a replacement for the former ImageMenuItem. The box contains, a label

for the icon and one for the text.

Parameters:

label_text – The text, which is displayed for the text label

Returns:

rafcon.gui.helpers.label.create_menu_item(label_text='', icon_code='', callback=None, callback_args=(), accel_code=None, accel_group=None)
rafcon.gui.helpers.label.create_tab_header_label(tab_name, icons)

Create the tab header labels for notebook tabs. If USE_ICONS_AS_TAB_LABELS is set to True in the gui_config, icons are used as headers. Otherwise, the titles of the tabs are rotated by 90 degrees.

Parameters:

  • tab_name – The label text of the tab, written in small letters and separated by underscores, e.g. states_tree

  • icons – A dict mapping each tab_name to its corresponding icon

Returns:

The GTK Eventbox holding the tab label

rafcon.gui.helpers.label.create_widget_title(title, widget_name=None)
rafcon.gui.helpers.label.ellipsize_labels_recursively(widget, ellipsize=<enum PANGO_ELLIPSIZE_END of type Pango.EllipsizeMode>, width_chars=1)
rafcon.gui.helpers.label.get_label_of_menu_item_box(menu_item)
rafcon.gui.helpers.label.get_notebook_tab_title(notebook, page_num)

Helper function that gets a notebook’s tab title given its page number

Parameters:

  • notebook – The GTK notebook

  • page_num – The page number of the tab, for which the title is required

Returns:

The title of the tab

rafcon.gui.helpers.label.get_widget_title(tab_label_text)

Transform Notebook tab label to title by replacing underscores with white spaces and capitalizing the first letter of each word.

Parameters:

tab_label_text – The string of the tab label to be transformed

Returns:

The transformed title as a string

rafcon.gui.helpers.label.is_event_of_key_string(event, key_string)

Condition check if key string represent the key value of handed event and whether the event is of right type

The function checks for constructed event tuple that are generated by the rafcon.gui.shortcut_manager.ShortcutManager. :param tuple event: Event tuple generated by the ShortcutManager :param str key_string: Key string parsed to a key value and for condition check

rafcon.gui.helpers.label.react_to_event(view, widget, event)

Checks whether the widget is supposed to react to passed event

The function is intended for callback methods registering to shortcut actions. As several widgets can register to the same shortcut, only the one having the focus should react to it.

Parameters:

  • view (gtkmvc3.View) – The view in which the widget is registered

  • widget (Gtk.Widget) – The widget that subscribed to the shortcut action, should be the top widget of the view

  • event – The event that caused the callback

Returns:

Whether the widget is supposed to react to the event or not

Return type:

bool

rafcon.gui.helpers.label.set_button_children_size_request(widget)
rafcon.gui.helpers.label.set_icon_and_text_box_of_menu_item(menu_item, uni_code)
rafcon.gui.helpers.label.set_label_markup(label, text, is_icon=False, size=None, letter_spacing=None)
rafcon.gui.helpers.label.set_notebook_title(notebook, page_num, title_label)

Set the title of a GTK notebook to one of its tab’s titles

Parameters:

  • notebook – The GTK notebook

  • page_num – The page number of a specific tab

  • title_label – The GTK label holding the notebook’s title

Returns:

The new title of the notebook

rafcon.gui.helpers.label.set_window_size_and_position(window, window_key)

Adjust GTK Window’s size, position and maximized state according to the corresponding values in the runtime_config file. The maximize method is triggered last to restore also the last stored size and position of the window. If the runtime_config does not exist, or the corresponding values are missing in the file, default values for the window size are used, and the mouse position is used to adjust the window’s position.

Parameters:

  • window – The GTK Window to be adjusted

  • window_key – The window’s key stored in the runtime config file

state (helper)

rafcon.gui.helpers.state.add_state(container_state_m, state_type, add_position=None)

Add a state to a container state

Adds a state of type state_type to the given container_state

Parameters:

  • container_state_m (rafcon.gui.models.container_state.ContainerState) – A model of a container state to add the new state to

  • state_type (rafcon.core.enums.StateType) – The type of state that should be added

  • add_position ((float, float)) – The position, to add the state at, relative to the container_state_m in item coordinates.

Returns:

True if successful, False else

rafcon.gui.helpers.state.change_state_type(state_m, target_class)
rafcon.gui.helpers.state.check_expected_future_model_list_is_empty(target_state_m, msg, delete=True, with_logger=None)

Checks if the expected future models list/set is empty

Return False if there are still elements in and also creates a warning message as feedback.

Parameters:

  • target_state_m (StateModel) – The state model which expected_future_models attribute should be checked

  • msg (str) – Message for the logger if a model is still in.

  • delete (bool) – Flag to delete respective model from list/set.

  • with_logger – A optional logger to use in case of logging messages

Return type:

bool

Returns:

True if empty and False if still model in set/list

rafcon.gui.helpers.state.create_new_state_from_state_with_type(source_state, target_state_class)

The function duplicates/transforms a state to a new state type. If the source state type and the new state type both are ContainerStates the new state will have not transitions to force the user to explicitly re-order the logical flow according the paradigm of the new state type.

Parameters:

  • source_state – previous/original state that is to transform into a new state type (target_state_class)

  • target_state_class – the final state class type

Returns:

rafcon.gui.helpers.state.create_state_model_for_state(new_state, meta, state_element_models)

Create a new state model with the defined properties

A state model is created for a state of the type of new_state. All child models in state_element_models ( model list for port, connections and states) are added to the new model.

Parameters:

  • new_state (StateModel) – The new state object with the correct type

  • meta (Vividict) – Meta data for the state model

  • state_element_models (list) – All state element and child state models of the original state model

Returns:

New state model for new_state with all childs of state_element_models

rafcon.gui.helpers.state.extract_child_models_of_state(state_m, new_state_class)

Retrieve child models of state model

The function extracts the child state and state element models of the given state model into a dict. It only extracts those properties that are required for a state of type new_state_class. Transitions are always left out.

Parameters:

  • state_m – state model of which children are to be extracted from

  • new_state_class – The type of the new class

Returns:

rafcon.gui.helpers.state.group_states_and_scoped_variables(state_m_list, sv_m_list)
rafcon.gui.helpers.state.insert_state_as(target_state_m, state, as_template)

Add a state into a target state

In case the state to be insert is a LibraryState it can be chosen to be insert as template.

Parameters:

  • target_state_m (rafcon.gui.models.container_state.ContainerStateModel) – State model of the target state

  • state (rafcon.core.states.State) – State to be insert as template or not

  • as_template (bool) – The flag determines if a handed state of type LibraryState is insert as template

Returns:

rafcon.gui.helpers.state.negative_check_for_model_in_expected_future_models(target_state_m, model, msg, delete=True, with_logger=None)

Checks if the expected future models list/set includes still a specific model

Return False if the handed model is still in and also creates a warning message as feedback.

Parameters:

  • target_state_m (StateModel) – The state model which expected_future_models attribute should be checked

  • model (Model) – Model to check for.

  • msg (str) – Message for the logger if a model is still in.

  • delete (bool) – Flag to delete respective model from list/set.

  • with_logger – A optional logger to use in case of logging messages

Return type:

bool

Returns:

True if empty and False if still model in set/list

rafcon.gui.helpers.state.prepare_state_m_for_insert_as(state_m_to_insert, previous_state_size)

Prepares and scales the meta data to fit into actual size of the state.

rafcon.gui.helpers.state.substitute_state(target_state_m, state_m_to_insert, as_template=False)

Substitutes the target state

Both, the state to be replaced (the target state) and the state to be inserted (the new state) are passed via parameters. The new state adapts the size and position of the target state. State elements of the new state are resized but kepp their proportion.

Parameters:

  • target_state_m (rafcon.gui.models.container_state.AbstractStateModel) – State Model of state to be substituted

  • state_m_to_insert (rafcon.gui.models.container_state.StateModel) – State Model of state to be inserted

Returns:

rafcon.gui.helpers.state.substitute_state_as(target_state_m, state, as_template, keep_name=False)

Substitute a target state with a handed state

The method generates a state model for the state to be inserted and use function substitute_state to finally substitute the state. In case the state to be inserted is a LibraryState it can be chosen to be inserted as template. It can be chosen that the inserted state keeps the name of the target state.

Parameters:

  • target_state_m (rafcon.gui.models.state.AbstractStateModel) – State model of the state to be substituted

  • state (rafcon.core.states.State) – State to be inserted

  • as_template (bool) – The flag determines if a handed state of type LibraryState is insert as template

  • keep_name (bool) – The flag to keep the name of the target state

Returns:

rafcon.gui.helpers.state.toggle_show_content_flag_of_library_state_model(state_m)
rafcon.gui.helpers.state.ungroup_state(state_m)
rafcon.gui.helpers.state.update_models_recursively(state_m, expected=True)

If a state model is reused the model depth maybe is to low. Therefore this method checks if all library state models are created with reliable depth

Parameters:

expected (bool) – Define newly generated library models as expected or triggers logger warnings if False

state_machine (helper)

This module covers functionality which is state machine model related, e.g. use selection, dialogs ,storage and that are basically menu bar functions. Further the it holds methods that are not StateModel based and more generic. Additional this module holds methods that employing the state machine manager. Maybe this changes in future.

rafcon.gui.helpers.state_machine.add_data_port_to_selected_states(data_port_type, data_type=None, selected_states=None)
rafcon.gui.helpers.state_machine.add_new_state(state_machine_m, state_type, target_position=None)

Triggered when shortcut keys for adding a new state are pressed, or Menu Bar “Edit, Add State” is clicked.

Adds a new state only if the parent state (selected state) is a container state, and if the graphical editor or the state machine tree are in focus.

Parameters:

  • state_machine_m – the state machine model to add the state to

  • state_type – the state type of the state to be added

  • target_position ((float, float)) – The position, to add the state at, relative to the graphical editor.

rafcon.gui.helpers.state_machine.add_outcome_to_selected_states(selected_states=None)
rafcon.gui.helpers.state_machine.add_scoped_variable_to_selected_states(data_type=None, selected_states=None)
rafcon.gui.helpers.state_machine.add_state_by_drag_and_drop(state, data)
rafcon.gui.helpers.state_machine.auto_layout_state_machine()
rafcon.gui.helpers.state_machine.bake_selected_state_machine(path=None)
rafcon.gui.helpers.state_machine.change_background_color(state_model)
rafcon.gui.helpers.state_machine.change_state_type_with_error_handling_and_logger_messages(state_m, target_class)
rafcon.gui.helpers.state_machine.delete_core_element_of_model(model, raise_exceptions=False, recursive=True, destroy=True, force=False)

Deletes respective core element of handed model of its state machine

If the model is one of state, data flow or transition, it is tried to delete that model together with its data from the corresponding state machine.

Parameters:

  • model – The model of respective core element to delete

  • raise_exceptions (bool) – Whether to raise exceptions or only log errors in case of failures

  • destroy (bool) – Access the destroy flag of the core remove methods

Returns:

True if successful, False else

rafcon.gui.helpers.state_machine.delete_core_elements_of_models(models, raise_exceptions=True, recursive=True, destroy=True, force=False)

Deletes all respective core elements for the given models

Calls the delete_core_element_of_model() for all given models.

Parameters:

  • models – A single model or a list of models of respective core element to be deleted

  • raise_exceptions (bool) – Whether to raise exceptions or log error messages in case of an error

  • destroy (bool) – Access the destroy flag of the core remove methods

Returns:

The number of models that were successfully deleted

rafcon.gui.helpers.state_machine.delete_selected_elements(state_machine_m)
rafcon.gui.helpers.state_machine.find_libraries_dependencies(library_path, new_library_path)

Find and resolve all dependencies of all libraries of a library directory

Parameters:

  • library_path (str) – the library path

  • new_library_path (str) – the new library path

:rtype list(rafcon.core.state_machine.StateMachine) :return: library dependencies

rafcon.gui.helpers.state_machine.find_library_dependencies(library_os_path, library_path=None, library_name=None, new_library_path=None, new_library_name=None)

Find and resolve all dependencies of a library

Parameters:

  • library_os_path (str) – the library os path

  • library_path (str) – the library path

  • library_name (str) – the library name

  • new_library_path (str) – the new library path

  • new_library_name (str) – the new library name

:rtype list(rafcon.core.state_machine.StateMachine) :return: library dependencies

rafcon.gui.helpers.state_machine.find_library_root_dependencies(library_root_name, new_library_root_name)

Find and resolve all dependencies of all libraries of a library root

Parameters:

  • library_root_name (str) – the library root name

  • new_library_root_name (str) – the new library root name

:rtype list(rafcon.core.state_machine.StateMachine) :return: library dependencies

rafcon.gui.helpers.state_machine.generate_linux_launch_files(target_path, config_path, state_machine_path)
rafcon.gui.helpers.state_machine.get_root_state_description_of_sm_file_system_path(file_system_path)
rafcon.gui.helpers.state_machine.get_root_state_file_path(sm_file_system_path)
rafcon.gui.helpers.state_machine.get_root_state_name_of_sm_file_system_path(file_system_path)
rafcon.gui.helpers.state_machine.group_selected_states_and_scoped_variables()
rafcon.gui.helpers.state_machine.insert_state_into_selected_state(state, as_template=False)

Adds a State to the selected state

Parameters:

  • state – the state which is inserted

  • as_template – If a state is a library state can be insert as template

Returns:

boolean: success of the insertion

rafcon.gui.helpers.state_machine.is_selection_inside_of_library_state(state_machine_m=None, selected_elements=None)

Check if handed or selected elements are inside of library state

If no state machine model or selected_elements are handed the method is searching for the selected state machine and its selected elements. If selected_elements list is handed handed state machine model is ignored.

Parameters:
Returns:

True if elements inside of library state

rafcon.gui.helpers.state_machine.is_state_machine_stopped_to_proceed(selected_sm_id=None, root_window=None)

Check if state machine is stopped and in case request user by dialog how to proceed

The function checks if a specific state machine or by default all state machines have stopped or finished execution. If a state machine is still running the user is ask by dialog window if those should be stopped or not.

Parameters:

  • selected_sm_id – Specific state mine to check for

  • root_window – Root window for dialog window

Returns:

rafcon.gui.helpers.state_machine.new_state_machine(*args)
rafcon.gui.helpers.state_machine.open_library_state_separately()
rafcon.gui.helpers.state_machine.open_state_machine(path=None, recent_opened_notification=False)

Open a state machine from respective file system path

Parameters:

  • path (str) – file system path to the state machine

  • recent_opened_notification (bool) – flags that indicates that this call also should update recently open

:rtype rafcon.core.state_machine.StateMachine :return: opened state machine

rafcon.gui.helpers.state_machine.paste_into_selected_state(state_machine_m, cursor_position=None)
Parameters:

cursor_position ((float, float)) – the cursor position relative to the main window.

rafcon.gui.helpers.state_machine.reduce_to_parent_states(models)
rafcon.gui.helpers.state_machine.refresh_after_relocate_and_rename(affected_libraries)

Save all library dependencies, refresh the open libraries and the library tree view

Parameters:

affected_libraries (str) – the affected libraries

rafcon.gui.helpers.state_machine.refresh_all(force=False)

Remove/close all libraries and state machines and reloads them freshly from the file system

Parameters:

force (bool) – Force flag to avoid any checks

rafcon.gui.helpers.state_machine.refresh_libraries()
rafcon.gui.helpers.state_machine.refresh_selected_state_machine()

Reloads the selected state machine.

rafcon.gui.helpers.state_machine.relocate_libraries(libraries_os_path, libraries_name, new_directory, logger=None)

Relocate a library directory

Parameters:

  • libraries_os_path (str) – the libraries os path

  • libraries_name (str) – the libraries name

  • new_directory (str) – the new directory

  • logger (logger) – the logger

rafcon.gui.helpers.state_machine.relocate_library(library_os_path, library_path, library_name, new_directory, logger=None)

Relocate a library

Parameters:

  • library_os_path (str) – the file system path of the library

  • library_path (str) – the path of the library

  • library_name (str) – the name of the library

  • new_directory (str) – the new directory

  • logger (logger) – the logger

rafcon.gui.helpers.state_machine.relocate_library_root(library_root_name, new_directory, logger=None)

Relocate a library root

Parameters:

  • library_root_name (str) – the library root name

  • new_directory (str) – the new directory

  • logger (logger) – the logger

rafcon.gui.helpers.state_machine.rename_library(library_os_path, new_library_os_path, library_path, library_name, new_library_name, logger=None)

Rename a library

Parameters:

  • library_os_path (str) – the library os path

  • new_library_os_path (str) – the new library os path

  • library_path (str) – the library path

  • library_name (str) – the library name

  • new_library_name (str) – the new library name

  • logger (logger) – the logger

rafcon.gui.helpers.state_machine.rename_library_root(library_root_name, new_library_root_name, logger=None)

Rename a library root

Parameters:

  • library_root_name (str) – the library root name

  • new_library_root_name (str) – the new library root name

  • logger (logger) – the logger

rafcon.gui.helpers.state_machine.replace_all_libraries_by_template(state_model)
rafcon.gui.helpers.state_machine.save_all_libraries(target_path)
rafcon.gui.helpers.state_machine.save_library(library, path)

Save a library and its meta data to a path

Parameters:

  • library (str) – the library

  • path (str) – the path

rafcon.gui.helpers.state_machine.save_library_config(target_path)
rafcon.gui.helpers.state_machine.save_library_dependencies(library_dependencies)

Save all library dependencies and their meta data to a path

Parameters:

library_dependencies (str) – the library dependencies

rafcon.gui.helpers.state_machine.save_open_libraries()

Save all open libraries

rafcon.gui.helpers.state_machine.save_selected_state_as()

Save selected state as separate state machine

:return True if successfully stored, False if the storing process was canceled or stopped by condition fail :rtype bool: :raises exceptions.ValueError: If dialog response ids are out of bounds

rafcon.gui.helpers.state_machine.save_state_machine(delete_old_state_machine=False, recent_opened_notification=False, as_copy=False, copy_path=None)

Save selected state machine

The function checks if states of the state machine has not stored script data abd triggers dialog windows to take user input how to continue (ignoring or storing this script changes). If the state machine file_system_path is None function save_state_machine_as is used to collect respective path and to store the state machine. The delete flag will remove all data in existing state machine folder (if plugins or feature use non-standard RAFCON files this data will be removed)

Parameters:

  • delete_old_state_machine (bool) – Flag to delete existing state machine folder before storing current version

  • recent_opened_notification (bool) – Flag to insert path of state machine into recent opened state machine paths

  • as_copy (bool) – Store state machine as copy flag e.g. without assigning path to state_machine.file_system_path

Returns:

True if the storing was successful, False if the storing process was canceled or stopped by condition fail

Rtype bool:

rafcon.gui.helpers.state_machine.save_state_machine_as(path=None, recent_opened_notification=False, as_copy=False)

Store selected state machine to path

If there is no handed path the interface dialog “create folder” is used to collect one. The state machine finally is stored by the save_state_machine function.

Parameters:

  • path (str) – Path of state machine folder where selected state machine should be stored

  • recent_opened_notification (bool) – Flag to insert path of state machine into recent opened state machine paths

  • as_copy (bool) – Store state machine as copy flag e.g. without assigning path to state_machine.file_system_path

Returns:

True if successfully stored, False if the storing process was canceled or stopped by condition fail

Rtype bool:

rafcon.gui.helpers.state_machine.selected_state_toggle_is_start_state()
rafcon.gui.helpers.state_machine.substitute_selected_library_state_with_template(keep_name=True)
rafcon.gui.helpers.state_machine.substitute_selected_state(state, as_template=False, keep_name=False)

Substitute the selected state with the handed state

Parameters:

  • state (rafcon.core.states.state.State) – A state of any functional type that derives from State

  • as_template (bool) – The flag determines if a handed the state of type LibraryState is insert as template

Returns:

rafcon.gui.helpers.state_machine.substitute_selected_state_and_use_choice_dialog()
rafcon.gui.helpers.state_machine.ungroup_selected_state()

text_formatting

rafcon.gui.helpers.text_formatting.format_default_folder_name(folder_name)
rafcon.gui.helpers.text_formatting.format_folder_name_human_readable(folder_name)
rafcon.gui.helpers.text_formatting.limit_string(text, max_length, separator='&#x2026;')