Widgets

Typhos uses a few custom widgets to create a clean and concise user interface. While most users should not be interacting with these directly, there may be a need if a user opts to create their display by hand instead of automatically generating one.

Determining widget types

If you would just like a widget for an ophyd.Signal, there is a function available:

typhos.widgets.create_signal_widget(signal, read_only=False, tooltip=None)

Factory for creating a PyDMWidget from a signal

Parameters:

• signal (ophyd.Signal) – Signal object to create widget

• read_only (bool, optional) – Whether this widget should be able to write back to the signal you provided

• tooltip (str, optional) – Tooltip to use for the widget

Returns:

widget – PyDMLabel, PyDMLineEdit, or PyDMEnumComboBox based on whether we should be able to write back to the widget and if the signal has enum_strs

Return type:

PyDMWidget

class typhos.widgets.SignalWidgetInfo(read_cls, read_kwargs, write_cls, write_kwargs)

Provides information on how to create signal widgets: class and kwargs.

Parameters:

• read_cls (type) – The readback widget class.

• read_kwargs (dict) – The readback widget initialization keyword arguments.

• write_cls (type) – The setpoint widget class.

• write_kwargs (dict) – The setpoint widget initialization keyword arguments.

classmethod from_signal(obj, desc=None)

Create a SignalWidgetInfo given an object and its description.

Parameters:

• obj (ophyd.OphydObj) – The object

• desc (dict, optional) – The object description, if available.

typhos.widgets.widget_type_from_description(signal, desc, read_only=False)

Determine which widget class should be used for the given signal

Parameters:

• signal (ophyd.Signal) – Signal object to determine widget class

• desc (dict) – Previously recorded description from the signal

• read_only (bool, optional) – Should the chosen widget class be read-only?

Returns:

• widget_class (class) – The class to use for the widget

• kwargs (dict) – Keyword arguments for the class

typhos.widgets.determine_widget_type(signal, read_only=False)

Determine which widget class should be used for the given signal.

Parameters:

• signal (ophyd.Signal) – Signal object to determine widget class

• read_only (bool, optional) – Should the chosen widget class be read-only?

Returns:

• widget_class (class) – The class to use for the widget

• kwargs (dict) – Keyword arguments for the class

Panels

One of the major design principles of Typhos is that users should be able to see what they need and hide one they don’t. Thefore, many of the widget implementations are placed in “Panels” these consist of QPushButton header that hides and shows the contents. Each variation in Typhos is documented below.

Basic Signal Panels

class typhos.panel.SignalPanel(signals=None)

Basic panel layout for ophyd.Signal and other ophyd objects.

This panel does not support hierarchical display of signals; rather, it flattens a device hierarchy showing all signals in the same area.

Parameters:

signals (OrderedDict, optional) – Signals to include in the panel. Parent of panel.

loading_complete

A signal indicating that loading of the panel has completed.

Type:

QtCore.Signal

NUM_COLS

The number of columns in the layout.

Type:

int

COL_LABEL

The column number for the row label.

Type:

int

COL_READBACK

The column number for the readback widget.

Type:

int

COL_SETPOINT

The column number for the setpoint widget.

Type:

int

See also

CompositeSignalPanel

add_device(device)

Typhos hook for adding a new device.

add_pv(read_pv, name, write_pv=None)

Add a row, given PV names.

Parameters:

• read_pv (str) – The readback PV name.

• name (str) – Name of signal to display.

• write_pv (str, optional) – The setpoint PV name.

Returns:

row – Row number that the signal information was added to in the SignalPanel.layout()`.

Return type:

int

add_row(*widgets, **kwargs)

Add widgets to the next row.

If fewer than NUM_COLS widgets are given, the last widget will be adjusted automatically to span the remaining columns.

Parameters:

*widgets – List of QtWidgets.QWidget.

Returns:

row – The row number.

Return type:

int

add_signal(signal, name=None, *, tooltip=None)

Add a signal to the panel.

The type of widget control that is drawn is dependent on _read_pv, and _write_pv. attributes.

If widget information for the given signal is available in the global cache, the widgets will be created immediately. Otherwise, a row will be reserved and widgets created upon signal connection and background description callback.

Parameters:

• signal (EpicsSignal, EpicsSignalRO) – Signal to create a widget.

• name (str, optional) – The name to be used for the row label. This defaults to signal.name.

Returns:

row – Row number that the signal information was added to in the SignalPanel.layout()`.

Return type:

int

clear()

Clear the SignalPanel.

filter_signals(kinds: list[Kind], name_filter: str | None = None, show_names: list[str] | None = None, omit_names: list[str] | None = None)

Filter signals based on the given kinds.

Parameters:

• kinds (list of ophyd.Kind) – List of kinds to show.

• name_filter (str, optional) – Name filter text - show only signals that match this string. This is applied after the “omit_names” and “show_names” filters.

• show_names (list of str, optinoal) – Names to explicitly show. Applied before the omit filter.

• omit_names (list of str, optinoal) – Names to explicitly omit.

label_text_from_attribute(attr, dotted_name)

Get label text for a given attribute.

For a basic signal panel, use the full dotted name. This is because this panel flattens the device hierarchy, and using only the last attribute name may lead to ambiguity or name clashes.

property row_count

Get the number of filled-in rows.

property signals

Get all instantiated signals, omitting components.

Returns:

signals – With the form: {signal_name: signal}.

Return type:

dict

property visible_elements

Get all signals visible according to filters, omitting components.

Returns:

signals – With the form: {signal_name: signal}.

Return type:

dict

property visible_signals

Get all signals visible according to filters, omitting components.

Returns:

signals – With the form: {signal_name: signal}.

Return type:

dict

class typhos.TyphosSignalPanel(parent=None, init_channel=None)

Panel of Signals for a given device, using SignalPanel.

Parameters:

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

• init_channel (str, optional) – The PyDM channel with which to initialize the widget.

class SignalOrder

Options for sorting signals.

This can be used as a base class for subclasses of QtWidgets.QWidget, allowing this to be used in QtCore.Property and therefore in the Qt designer.

add_device(device)

Typhos hook for adding a new device.

property filter_settings

Get the filter settings dictionary.

generate_context_menu()

Generate a context menu for this TyphosSignalPanel.

nameFilter

Get or set the current name filter.

omitNames

Get or set the list of names to omit.

open_context_menu(ev)

Open a context menu when the Default Context Menu is requested.

Parameters:

ev (QEvent)

resizeEvent(event: QResizeEvent)

Fix the parent container’s size whenever our size changes.

This also runs when we add or filter rows.

setVisible(visible: bool)

Fix the parent container’s size whenever we switch visibility.

This also runs when we toggle a row visibility using the title and when all signal rows get filtered all at once.

set_device_display(display)

Typhos hook for when the TyphosDeviceDisplay is associated.

showConfig

Show ophyd.Kind.config signals

showHints

Show ophyd.Kind.hinted signals

showNames

Get or set the list of names to omit.

showNormal

Show ophyd.Kind.normal signals

showOmitted

Show ophyd.Kind.omitted signals

property show_kinds: List[Kind]

Get a list of the ophyd.Kind that should be shown.

sortBy

Get or set the order that the signals will be placed in layout.

Composite Signal Panels

class typhos.panel.CompositeSignalPanel

Composite panel layout for ophyd.Signal and other ophyd objects.

Contrasted to SignalPanel, this class retains the hierarchy built into an ophyd.Device hierarchy. Individual signals mix in with sub-device displays, which may or may not have custom screens.

loading_complete

A signal indicating that loading of the panel has completed.

Type:

QtCore.Signal

NUM_COLS

The number of columns in the layout.

Type:

int

COL_LABEL

The column number for the row label.

Type:

int

COL_READBACK

The column number for the readback widget.

Type:

int

COL_SETPOINT

The column number for the setpoint widget.

Type:

int

add_device(device)

Typhos hook for adding a new device.

add_sub_device(device, name)

Add a sub-device to the next row.

Parameters:

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

• name (str) – The name/label to go with the device.

label_text_from_attribute(attr, dotted_name)

Get label text for a given attribute.

property visible_elements

Return all visible signals and components.

class typhos.TyphosCompositeSignalPanel(parent=None, init_channel=None)

Hierarchical panel for a device, using CompositeSignalPanel.

Parameters:

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

• init_channel (str, optional) – The PyDM channel with which to initialize the widget.

TyphosPositionerWidget

class typhos.TyphosPositionerWidget(parent=None)

Widget to interact with a ophyd.Positioner.

Standard positioner motion requires a large amount of context for operators. For most motors, it may not be enough to simply have a text field where setpoints can be punched in. Instead, information like soft limits and hardware limit switches are crucial for a full understanding of the position and behavior of a motor. The widget will work with any object that implements the method set, however to get other relevant information, we see if we can find other useful signals. Below is a table of attributes that the widget looks for to inform screen design.

Widget	Attribute Selection
User Readback	The readback_attribute property is used, which defaults to user_readback. Linked to UI element user_readback.
User Setpoint	The setpoint_attribute property is used, which defaults to user_setpoint. Linked to UI element user_setpoint.
Limit Switches	The low_limit_switch_attribute and high_limit_switch_attribute properties are used, which default to low_limit_switch and high_limit_switch, respectively.
Soft Limits	The low_limit_travel_attribute and high_limit_travel_attribute properties are used, which default to low_limit_travel and high_limit_travel, respectively. As a fallback, the limit property on the device may be queried directly.
Set and Tweak	Both of these methods simply use Device.set which is expected to take a float and return a status object that indicates the motion completeness. Must be implemented.
Stop	Device.stop(), if available, otherwise hide the button. If you have a non-functional stop method inherited from a parent device, you can hide it from typhos by overriding it with a property that raises AttributeError on access.
Move Indicator	The moving_attribute property is used, which defaults to motor_is_moving. Linked to UI element moving_indicator.
Error Message	The error_message_attribute property is used, which defaults to error_message. Linked to UI element error_label.
Clear Error	Device.clear_error(), if applicable. This also clears any visible error messages from the status returned by Device.set.
Alarm Circle	Uses the TyphosAlarmCircle widget to summarize the alarm state of all of the device’s normal and hinted signals.

class KindLevel(value)

Options for TyphosAlarm.kindLevel.

acceleration_attribute

The attribute name for the acceleration time signal.

add_device(device)

Add a device to the widget

property all_linked_attributes: list[str]

All linked attribute names.

property all_linked_signals: list[Signal]

All linked signal names.

clear_error()

Clear the error messages from the device and screen.

The device may have errors in the IOC. These will be cleared by calling the clear_error method.

The screen may have errors from the status of the last move. These will be cleared from view.

property device

The associated device.

error_message_attribute

The attribute name for the IOC error message label.

failed_move

The last requested move failed

high_limit_switch_attribute

The attribute name for the high limit switch signal.

high_limit_travel_attribute

The attribute name for the high (soft) limit travel signal.

low_limit_switch_attribute

The attribute name for the low limit switch signal.

low_limit_travel_attribute

The attribute name for the low limit signal.

moving

Current state of widget

This will lag behind the actual state of the positioner in order to prevent unnecessary rapid movements

moving_attribute

The attribute name for the motor moving indicator.

negative_tweak()

Tweak negative by the amount listed in ui.tweak_value

positive_tweak()

Tweak positive by the amount listed in ui.tweak_value

readback_attribute

The attribute name for the readback signal.

set()

Set the device to the value configured by ui.set_value

setpoint_attribute

The attribute name for the setpoint signal.

show_expert_button

If True, show the expert button.

The expert button opens a full suite for the device. You typically want this False when you’re already inside the suite that the button would open. You typically want this True when you’re using the positioner widget inside of an unrelated screen. This will default to False.

show_ui_type_hints()

Show type hints of widgets included in the UI file.

stop()

Stop device

successful_move

The last requested move was successful

tweak(offset)

Tweak by the given offset.

update_alarm_text(alarm_level)

Label the alarm circle with a short text bit.

velocity_attribute

The attribute name for the velocity signal.

Functions and Methods

class typhos.func.FunctionPanel(methods=None, parent=None)

Function Panel.

Similar to SignalPanel but instead displays a set of function widgets arranged in a row. Each provided method has a FunctionDisplay generated for it an added to the layout.

Parameters:

• methods (list of callables, optional) – List of callables to add to the FunctionPanel.

• parent (QWidget)

add_method(func, *args, **kwargs)

Add a FunctionDisplay.

Parameters:

• func (callable) – Annotated callable function.

• args – All additional parameters are passed directly to the FunctionDisplay constructor.

• kwargs – All additional parameters are passed directly to the FunctionDisplay constructor.

class typhos.TyphosMethodButton(parent=None)

QPushButton to access a method of a Device.

The function provided by the loaded device and the method_name will be run when the button is clicked. If use_status is set to True, the button will be disabled while the Status object is active.

add_device(device)

Add a new device to the widget.

Parameters:

device (ophyd.Device)

execute()

Execute the method given by method_name.

classmethod from_device(device, parent=None)

Create a TyphosMethodButton from a device.

method_name

Name of method on provided Device to execute.

use_status

Use the status to enable and disable the button.

Miscellaneous

class typhos.widgets.ClickableBitIndicator(parent: QWidget | None = None, circle: bool = False)

A bit indicator that emits clicked when clicked.

mousePressEvent(self, a0: QMouseEvent | None)

class typhos.widgets.ImageDialogButton(init_channel, text=None, icon=None, parent=None)

QPushButton to show a 2-d array.

Notes

• Used for variety array-image (readback)

parent_widget_class

alias of QMainWindow

widget()

Create PyDMImageView

class typhos.widgets.SignalDialogButton(init_channel, text=None, icon=None, parent=None)

QPushButton to launch a QDialog with a PyDMWidget

icon = NotImplemented

parent_widget_class

alias of QWidget

show_dialog() → QDialog

Show the channel in a QDialog

text = NotImplemented

widget()

Return a widget created with channel

class typhos.widgets.SubDisplay

QDockWidget modified to emit a signal when closed

closeEvent(self, event: QCloseEvent | None)

class typhos.widgets.TyphosArrayTable(*args, variety_metadata=None, ophyd_signal=None, **kwargs)

A table widget which reshapes and displays a given waveform value.

Notes

• Used for variety array-tabular (setpoint)

value_changed(value)

Callback invoked when the Channel value is changed.

Parameters:

new_waveform (np.ndarray) – The new waveform value from the channel.

property variety_metadata

Additional component variety metadata.

class typhos.widgets.TyphosByteIndicator(*args, variety_metadata=None, ophyd_signal=None, **kwargs)

Displays an integer value as individual, read-only bit indicators.

Notes

• Used for variety bitmask (readback)

property variety_metadata

Additional component variety metadata.

class typhos.widgets.TyphosByteSetpoint(*args, variety_metadata=None, ophyd_signal=None, **kwargs)

Displays an integer value as individual, toggleable bit indicators.

Notes

• Used for variety bitmask (setpoint)

numBits

Number of bits to interpret.

Re-implemented from PyDM to support changing of bit indicators.

value_changed(value)

Receive and update the TyphosTextEdit for a new channel value.

class typhos.widgets.TyphosComboBox(*args, variety_metadata=None, ophyd_signal=None, **kwargs)

Notes

• Used for variety text-enum (setpoint)

• Used for variety enum (setpoint)

enum_strings_changed(new_enum_strings)

Callback invoked when the Channel has new enum values. This callback also triggers a value_changed call so the new enum values to be broadcasted

Parameters:

new_enum_strings (tuple) – The new list of values

wheelEvent(self, e: QWheelEvent | None)

class typhos.widgets.TyphosCommandButton(*args, variety_metadata=None, ophyd_signal=None, **kwargs)

A pushbutton widget which executes a command by sending a specific value.

See also

TyphosCommandEnumButton

Notes

• Used for variety command-setpoint-tracks-readback (setpoint)

• Used for variety command-proc (setpoint)

• Used for variety command (setpoint)

enum_strings_changed(new_enum_strings)

Callback invoked when the Channel has new enum values. This callback also triggers a value_changed call so the new enum values to be broadcasted

Parameters:

new_enum_strings (tuple) – The new list of values

property variety_metadata

Additional component variety metadata.

class typhos.widgets.TyphosCommandEnumButton(*args, variety_metadata=None, ophyd_signal=None, **kwargs)

A group of buttons which represent several command options.

These options can come from directly from the control layer or can be overridden with variety metadata.

See also

TyphosCommandButton

Notes

• Used for variety command-enum (setpoint)

enum_strings_changed(new_enum_strings)

Callback invoked when the Channel has new enum values. This callback also triggers a value_changed call so the new enum values to be broadcasted.

Parameters:

new_enum_strings (tuple) – The new list of values

property variety_metadata

Additional component variety metadata.

class typhos.widgets.TyphosLabel(*args, display_format=None, ophyd_signal=None, **kwargs)

Reimplementation of PyDMLabel to set some custom defaults

Notes

• Used for variety array-nd (setpoint)

• Used for variety text-multiline (readback)

• Used for variety text-enum (readback)

• Used for variety text (readback)

• Used for variety scalar-tweakable (readback)

• Used for variety scalar-range (readback)

• Used for variety scalar (readback)

• Used for variety enum (readback)

• Used for variety command-setpoint-tracks-readback (readback)

• Used for variety command-enum (readback)

• Used for variety array-nd (readback)

dynamic_font_size

Dynamically adjust the font size

enum_strings_changed(new_enum_strings)

Callback invoked when the Channel has new enum values. This callback also triggers a value_changed call so the new enum values to be broadcasted

Parameters:

new_enum_strings (tuple) – The new list of values

unit_changed(new_unit)

Callback invoked when the Channel has new unit value. This callback also triggers an update_format_string call so the new unit value is considered if `showUnits` is set.

Parameters:

new_unit (str) – The new unit

class typhos.widgets.TyphosLineEdit(*args, display_format=None, **kwargs)

Reimplementation of PyDMLineEdit to set some custom defaults

Notes

• Used for variety text (setpoint)

• Used for variety scalar (setpoint)

send_value()

Update channel value while recording setpoint history

setpointHistoryCount

Number of items to show in the context menu “setpoint history”

property setpoint_history

timestamp}

Type:

History of setpoints, as a dictionary of {setpoint

unit_changed(new_unit)

Callback invoked when the Channel has new unit value. This callback also triggers an update_format_string call so the new unit value is considered if `showUnits` is set.

Parameters:

new_unit (str) – The new unit

widget_ctx_menu()

Fetch the Widget specific context menu which will be populated with additional tools by assemble_tools_menu.

Returns:

If the return of this method is None a new QMenu will be created by assemble_tools_menu.

Return type:

QMenu or None

class typhos.widgets.TyphosScalarRange(*args, variety_metadata=None, ophyd_signal=None, **kwargs)

A slider widget which displays a scalar value with an explicit range.

Notes

• Used for variety scalar-range (setpoint)

connection_changed(connected)

Callback invoked when the connection state of the Channel is changed. This callback acts on the connection state to enable/disable the widget and also trigger the change on alarm severity to ALARM_DISCONNECTED.

Parameters:

connected (int) – When this value is 0 the channel is disconnected, 1 otherwise.

property delta_signal

Delta signal, used as the source for “delta_value”.

delta_value

Delta value, an alternative to “num_points” provided by PyDMSlider.

num_points is calculated using the current min/max and the delta value, if set.

property variety_metadata

Additional component variety metadata.

class typhos.widgets.TyphosSidebarItem(param, depth)

Class to display a Device or Tool in the sidebar

Notes

embed_requested(triggered)

Request to open embedded display for sidebar item

hide_requested(triggered)

Request to hide display for sidebar item

open_requested(triggered)

Request to open display for sidebar item

treeWidgetChanged()

Update the widget when add to a QTreeWidget

class typhos.tweakable.TyphosTweakable(parent=None, init_channel=None, variety_metadata=None, ophyd_signal=None)

Widget for a tweakable scalar.

Parameters:

• parent (QWidget) – The parent widget.

• init_channel (str, optional) – The channel to be used by the widget.

Notes

• Used for variety scalar-tweakable (setpoint)

negative_tweak()

Tweak negative by the amount listed in ui.tweak_value

positive_tweak()

Tweak positive by the amount listed in ui.tweak_value

tweak(offset)

Tweak by the given offset.

property variety_metadata

Additional component variety metadata.

class typhos.textedit.TyphosTextEdit(parent=None, init_channel=None, variety_metadata=None, ophyd_signal=None)

A writable, multiline text editor with support for PyDM Channels.

Parameters:

• parent (QWidget) – The parent widget.

• init_channel (str, optional) – The channel to be used by the widget.

• (setpoint) (* Used for variety text-multiline)

send_value()

Emit a send_value_signal to update channel value.

set_display()

Set the text display of the TyphosTextEdit.

value_changed(value)

Receive and update the TyphosTextEdit for a new channel value.

property variety_metadata

Additional component variety metadata.

write_access_changed(new_write_access)

Change the TyphosTextEdit to read only if write access is denied

class typhos.widgets.WaveformDialogButton(init_channel, text=None, icon=None, parent=None)

QPushButton to show a 1-d array.

Notes

• Used for variety array-histogram (readback)

• Used for variety array-timeseries (readback)

parent_widget_class

alias of QMainWindow

widget()

Create PyDMWaveformPlot

Designer

class typhos.widgets.TyphosDesignerMixin(init_channel=None)

A mixin class used to display Typhos widgets in the Qt designer.

alarmSensitiveBorder

alarmSensitiveContent

channel

The channel address to use for this widget