Suite and Displays

Typhos has two major widgets that users are expected to interface with. The first is the TyphosDeviceDisplay, which shows device information, and TyphosSuite which contains multiple devices and tools. This is the barebones implementation. No signals, or widgets are automatically populated in the screen. In fact, by default most of the widgets will be hidden. You can then manually add signals to the panels and plots, the panels will only show themselves when you add PVs.

TyphosSuite

class typhos.TyphosSuite(parent: QtWidgets.QWidget | None = None, *, pin: bool = False, content_layout: QtWidgets.QLayout | None = None, default_display_type: DisplayTypes = DisplayTypes.embedded_screen, scroll_option: ScrollOptions = ScrollOptions.auto)

This suite combines tools and devices into a single widget.

A ParameterTree is contained in a QPopBar which shows tools and the hierarchy of a device along with options to show or hide them.

Parameters:

• parent (QWidget, optional)

• pin (bool, optional) – Pin the parameter tree on startup.

• content_layout (QLayout, optional) – Sets the layout for when we have multiple subdisplays open in the suite. This will have a horizontal layout by default but can be changed as needed for the use case.

• default_display_type (DisplayType, optional) – DisplayType enum that determines the type of display to open when we add a device to the suite. Defaults to DisplayType.detailed_screen.

• scroll_option (ScrollOptions, optional) – ScrollOptions enum that determines the behavior of scrollbars in the suite. Default is ScrollOptions.auto, which enables scrollbars for detailed and engineering screens but not for embedded displays.

default_tools

The default tools to use in the suite. In the form of {'tool_name': ToolClass}.

Type:

dict

add_device(device, children=True, category='Devices')

Add a device to the suite.

Parameters:

• device (ophyd.Device) – The device to add.

• children (bool, optional) – Also add any subdevices of this device to the suite as well.

• category (str, optional) – Category of device. By default, all devices will just be added to the “Devices” group

add_lazy_subdisplay(name: str, display_class: type[QWidget], category: str)

Add an arbitrary widget to the tree of available widgets and tools.

Parameters:

• name (str) – Name to be displayed in the tree

• display_class (subclass of QWidget) – QWidget class to show in the dock when expanded.

• category (str) – The top level group to place the controls under in the tree. If the category does not exist, a new one will be made

add_subdisplay(name, display, category)

Add an arbitrary widget to the tree of available widgets and tools.

Parameters:

• name (str) – Name to be displayed in the tree

• display (QWidget) – QWidget to show in the dock when expanded.

• category (str) – The top level group to place the controls under in the tree. If the category does not exist, a new one will be made

add_tool(name: str, tool: type[QWidget])

Add a widget to the toolbar.

Shortcut for:

suite.add_subdisplay(name, tool, category='Tools')

Parameters:

• name (str) – Name of tool to be displayed in sidebar

• tool (QWidget) – Widget to be added to .ui.subdisplay

embed_subdisplay(widget)

Embed a display in the dock system.

classmethod from_device(device: Device, parent: QtWidgets.QWidget | None = None, tools: dict[str, type] | None | DEFAULT_TOOLS = <object object>, pin: bool = False, content_layout: QtWidgets.QLayout | None = None, default_display_type: DisplayTypes = DisplayTypes.detailed_screen, scroll_option: ScrollOptions = ScrollOptions.auto, show_displays: bool = True, **kwargs) → TyphosSuite

Create a new TyphosSuite from an ophyd.Device.

Parameters:

• device (ophyd.Device) – The device to use.

• children (bool, optional) – Choice to include child Device components

• parent (QWidget)

• tools (dict, optional) – Tools to load for the object. dict should be name, class pairs. By default these will be .default_tools, but None can be passed to avoid tool loading completely.

• pin (bool, optional) – Pin the parameter tree on startup.

• content_layout (QLayout, optional) – Sets the layout for when we have multiple subdisplays open in the suite. This will have a horizontal layout by default but can be changed as needed for the use case.

• default_display_type (DisplayTypes, optional) – DisplayTypes enum that determines the type of display to open when we add a device to the suite. Defaults to DisplayTypes.detailed_screen.

• scroll_option (ScrollOptions, optional) – ScrollOptions enum that determines the behavior of scrollbars in the suite. Default is ScrollOptions.auto, which enables scrollbars for detailed and engineering screens but not for embedded displays.

• show_displays (bool, optional) – If True (default), open all the included device displays. If False, do not open any of the displays.

• **kwargs – Passed to TyphosSuite.add_device()

classmethod from_devices(devices: list[Device], parent: QtWidgets.QWidget | None = None, tools: dict[str, type] | None | DEFAULT_TOOLS = <object object>, pin: bool = False, content_layout: QtWidgets.QLayout | None = None, default_display_type: DisplayTypes = DisplayTypes.detailed_screen, scroll_option: ScrollOptions = ScrollOptions.auto, show_displays: bool = True, **kwargs) → TyphosSuite

Create a new TyphosSuite from an iterator of ophyd.Device

Parameters:

• device (ophyd.Device)

• children (bool, optional) – Choice to include child Device components

• parent (QWidget)

• tools (dict, optional) – Tools to load for the object. dict should be name, class pairs. By default these will be .default_tools, but None can be passed to avoid tool loading completely.

• pin (bool, optional) – Pin the parameter tree on startup.

• content_layout (QLayout, optional) – Sets the layout for when we have multiple subdisplays open in the suite. This will have a horizontal layout by default but can be changed as needed for the use case.

• default_display_type (DisplayTypes, optional) – DisplayTypes enum that determines the type of display to open when we add a device to the suite. Defaults to DisplayTypes.detailed_screen.

• scroll_option (ScrollOptions, optional) – ScrollOptions enum that determines the behavior of scrollbars in the suite. Default is ScrollOptions.auto, which enables scrollbars for detailed and engineering screens but not for embedded displays.

• show_displays (bool, optional) – If True (default), open all the included device displays. If False, do not open any of the displays.

• **kwargs – Passed to TyphosSuite.add_device()

get_subdisplay(display: Device | str, instantiate: bool = True)

Get a subdisplay by name or contained device.

Parameters:

• display (str or Device) – Name of screen or device

• instantiate (bool, optional) – Instantiate lazy sub-displays if they do not already exist. Raise otherwise.

Returns:

widget – Widget that is a member of the ui.subdisplay

Return type:

QWidget or partial

Example

suite.get_subdisplay(my_device.x)
suite.get_subdisplay('My Tool')

hide_subdisplay(widget)

Hide a visible subdisplay.

Parameters:

widget (SidebarParameter or Subdisplay) – If you give a SidebarParameter, we will find the corresponding widget and hide it. If the widget provided to us is inside a DockWidget we will close that, otherwise the widget is just hidden.

hide_subdisplays()

Hide all open displays.

save()

Save suite settings to a file using typhos.utils.save_suite().

A QFileDialog will be used to query the user for the desired location of the created Python file

The template will be of the form:

import sys
import typhos.cli

devices = {devices}

def create_suite(cfg=None):
    return typhos.cli.create_suite(devices, cfg=cfg)

if __name__ == '__main__':
    typhos.cli.typhos_cli(devices + sys.argv[1:])

save_device_screenshots(filename_format: str) → dict[str, str]

Save screenshot(s) of devices to filename_format.

save_screenshot(filename: str) → bool

Save a screenshot of this widget to filename.

show_subdisplay(widget: QWidget | SidebarParameter | str) → QWidget

Open a display in the dock system.

Parameters:

widget (QWidget, SidebarParameter or str) – If given a SidebarParameter from the tree, the widget will be shown and the sidebar item update. Otherwise, the information is passed to get_subdisplay()

Returns:

widget – The subdisplay that was shown.

Return type:

QWidget

property tools

Tools loaded into the suite.

property top_level_groups

Get top-level groups.

This is of the form:

{'name': QGroupParameterItem}

TyphosDeviceDisplay

class typhos.TyphosDeviceDisplay(parent: QWidget | None = None, *, scrollable: bool | None = None, embedded_templates: list[str] | None = None, detailed_templates: list[str] | None = None, engineering_templates: list[str] | None = None, display_type: DisplayTypes | str | int = 'embedded_screen', scroll_option: ScrollOptions | str | int = ScrollOptions.auto, nested: bool = False)

Main display for a single ophyd Device.

This contains the widgets for all of the root devices signals, and any methods you would like to display. By typhos convention, the base initialization sets up the widgets and the from_device() class method will automatically populate the resulting display.

Parameters:

• parent (QWidget, optional) – The parent widget.

• scrollable (bool, optional) – Semi-deprecated parameter. Use scroll_option instead. If True, put the loaded template into a QScrollArea. If False, the display widget will go directly in this widget’s layout. If omitted, scroll_option is used instead.

• embedded_templates (list, optional) – List of embedded templates to use in addition to those found on disk.

• detailed_templates (list, optional) – List of detailed templates to use in addition to those found on disk.

• engineering_templates (list, optional) – List of engineering templates to use in addition to those found on disk.

• display_type (DisplayTypes, str, or int, optional) – The default display type.

• scroll_option (ScrollOptions, str, or int, optional) – The scroll behavior.

• nested (bool, optional) – An optional annotation for a display that may be nested inside another.

TemplateEnum

alias of DisplayTypes

add_device(device, macros=None)

Add a Device and signals to the TyphosDeviceDisplay.

The full dictionary of macros is built with the following order of precedence:

1. Macros from the device metadata itself.
2. If available, `name`, and `prefix` will be added from the device.
3. The argument ``macros`` is then used to fill/update the final
   macro dictionary.

This will also register the device’s signals in the sig:// plugin. This means that any templates can refer to their device’s signals by name.

Parameters:

• device (ophyd.Device) – The device to add.

• macros (dict, optional) – Additional macros to use/replace the defaults.

copy_to_clipboard()

Copy the display image to the clipboard.

property current_template

Get the current template being displayed.

property device

Get the device associated with this Device Display.

device_class

Get the full class with module name of loaded device.

device_name

Get the name of the loaded device.

display_type

Get or set the current display type.

property display_widget

Get the widget generated from the template.

property effective_display_type: DisplayTypes

Return the native display type of the current selected template.

It’s possible to request e.g. an embedded screen or an engineering screen and get the detailed screen or tree instead.

This returns the actual type of the screen that was chosen for use in code that needs to respond to the actual template in use, rather than the one requested.

If no template has been selected yet, this falls back to the specified display type.

force_template

Force a specific template.

classmethod from_class(klass, *, template=None, macros=None, **kwargs)

Create a new TyphosDeviceDisplay from a Device class.

Loads the signals in to the appropriate positions and sets the title to a cleaned version of the device name.

Parameters:

• klass (str or class)

• template (str, optional) – Set the display_template.

• macros (dict, optional) – Macro substitutions to be placed in template.

• **kwargs – Extra arguments are used at device instantiation.

Return type:

TyphosDeviceDisplay

classmethod from_device(device, template=None, macros=None, **kwargs)

Create a new TyphosDeviceDisplay from a Device.

Loads the signals in to the appropriate positions and sets the title to a cleaned version of the device name

Parameters:

• device (ophyd.Device)

• template (str, optional) – Set the display_template.

• macros (dict, optional) – Macro substitutions to be placed in template.

• **kwargs – Passed to the class init.

get_best_template(display_type, macros)

Get the best template for the given display type.

Parameters:

• display_type (DisplayTypes, str, or int) – The display type.

• macros (dict) – Macros to use when loading the template.

hideEmpty

Toggle hiding or showing empty panels.

load_best_template()

Load the best available template for the current display type.

property macros

Get or set the macros for the display.

minimumSizeHint(self) → QSize

scroll_option

Place the display in a scrollable area.

search_for_templates()

Search the filesystem for device-specific templates.

classmethod suggest_composite_screen(device_cls)

Suggest to use the composite screen for the given class.

Returns:

composite – If True, favor the composite screen.

Return type:

bool

to_image()

Return the entire display as a QtGui.QImage.

Returns:

The display, as an image.

Return type:

QtGui.QImage

Standardized Display Title

class typhos.display.TyphosDisplayTitle(title='${name}', *, show_switcher=True, show_underline=True, parent=None)

Standardized Typhos Device Display title.

Parameters:

• title (str, optional) – The initial title text, which may contain macros.

• show_switcher (bool, optional) – Show the TyphosDisplaySwitcher.

• show_underline (bool, optional) – Show the underline separator.

• parent (QtWidgets.QWidget, optional) – The parent widget.

add_device(device)

Typhos hook for setting the associated device.

pop_out_help()

Pop out the help widget.

set_device_display(display)

Typhos callback: set the TyphosDeviceDisplay.

show_switcher

Get or set whether to show the display switcher.

show_underline

Get or set whether to show the underline.

toggle_help(show)

Toggle the help visibility.

class typhos.display.TyphosDisplaySwitcher(parent=None, **kwargs)

Display switcher set of buttons for use with a TyphosDeviceDisplay.

add_device(device)

Typhos hook for setting the associated device.

new_jira_widget()

Open a new Jira issue reporting widget.

set_device_display(display: TyphosDeviceDisplay) → None

Typhos hook for setting the associated device display.

class typhos.display.TyphosTitleLabel

A label class intended for use as a standardized title.

toggle_requested

A Qt signal indicating that the user clicked on the title. By default, this hides any nested panels underneath the title.

Type:

QtCore.Signal

mousePressEvent(event)

Overridden qt hook for a mouse press.

Tool buttons

class typhos.display.TyphosToolButton(icon=None, *, parent=None)

Base class for tool buttons used in the TyphosDisplaySwitcher.

Parameters:

• icon (QIcon or str, optional) – See get_icon() for options.

• parent (QtWidgets.QWidget, optional) – The parent widget.

DEFAULT_ICON

The default icon from fontawesome to use.

Type:

str

generate_context_menu()

Context menu request: override in subclasses.

classmethod get_icon(icon=None)

Get a QIcon, if specified, or fall back to the default.

Parameters:

icon (str or QtGui.QIcon) – If a string, assume it is from fontawesome. Otherwise, use the icon instance as-is.

open_context_menu(ev)

Open the instance-specific context menu.

Parameters:

ev (QEvent)

class typhos.display.TyphosDisplaySwitcherButton(display_type, *, parent=None)

A button which switches the TyphosDeviceDisplay template on click.

generate_context_menu() → _QMenu | None

Context menu request.

class typhos.display.TyphosDisplayConfigButton(icon=None, *, parent=None)

The configuration button used in the TyphosDisplaySwitcher.

This uses the common “vertical ellipse” icon by default.

create_hide_empty_menu(panels, base_menu)

Create the hide empty filtering menu.

Parameters:

• panels (list of TyphosSignalPanel) – The panels to filter upon triggering of menu actions.

• base_menu (QMenu) – The menu to add actions to.

create_kind_filter_menu(panels, base_menu, *, only)

Create the “Kind” filter menu.

Parameters:

• panels (list of TyphosSignalPanel) – The panels to filter upon triggering of menu actions.

• base_menu (QMenu) – The menu to add actions to.

• only (bool) – False - create “Show Kind” actions. True - create “Show only Kind” actions.

create_name_filter_menu(panels, base_menu)

Create the name-based filtering menu.

Parameters:

• panels (list of TyphosSignalPanel) – The panels to filter upon triggering of menu actions.

• base_menu (QMenu) – The menu to add actions to.

generate_context_menu()

Generate the custom context menu.

Embedded
Detailed
Engineering
-------------
Refresh templates
-------------
Kind filter > Show hinted
              ...
              Show only hinted
Filter by name
Hide Empty Panels

hide_empty(search=True)

Wrap hide_empty calls for use with search functions and action clicks.

Parameters:

search (bool) – Whether or not this method is being called from a search/filter method.

set_device_display(device_display)

Typhos callback: set the TyphosDeviceDisplay.

Utilities

typhos.display.normalize_display_type(display_type: DisplayTypes | str | int) → DisplayTypes

Normalize a given display type.

Parameters:

display_type (DisplayTypes, str, or int) – The display type.

Returns:

display_type – The normalized DisplayTypes.

Return type:

DisplayTypes

Raises:

ValueError – If the input cannot be made a DisplayTypes.

typhos.display.hide_empty(widget, process_widget=True)

Recursively hide empty panels and widgets.

Parameters:

• widget (QWidget) – The widget in which to start the recursive search.

• process_widget (bool) – Whether or not to process the visibility for the widget. This is useful since we don’t want to hide the top-most widget otherwise users can’t change the visibility back on.

typhos.display.show_empty(widget)

Recursively shows all panels and widgets, empty or not.

Parameters:

widget (QWidget)

typhos.display.toggle_display(widget, force_state=None)

Toggle the visibility of all TyphosSignalPanel in a display.

Parameters:

• widget (QWidget) – The widget in which to look for Panels.

• force_state (bool) – If set to True or False, it will change visibility to the value of force_state. If not set or set to None, it will flip the current panels state.