Dashboard Items#

Base class#

class labterm.dashboard_item.DashboardItem[source]#

Bases: ABC

Abstract Base Class for all items drawable on the dashboard, associated with a measured quantity or a state of a specific instrument.

Parameters:

  • x – x position in dashboard. The way this value translates to a column of the terminal is decided by xycoords

  • y – y position in dashboard (higher y corresponds to a lower position). The way this value translates to a row of the terminal is decided by xycoords

  • xgrid (int) – If navigable, determines the x position of the item on the navigable grid

  • ygrid (int) – If navigable, determines the y position of the item on the navigable grid

  • channel (int) – A number associating the items with an instrument. Enter a channel equal to the one set for the desired instrument for the two to communicate.

  • data (str) –

    The specific data associated with the item, obtained by the instrument of corresponding channel. Must be one of the keys of the instrument data dict.

    The item will continuosly update the data in the way described by the instrument update_data() method.

  • action (str) – The action to carry out when selecting the item. Must be one of the actions foreseen by the instrument action() method.

  • text_before (str) – A string to be printed before the main item text

  • text_after (str) – A string to be printed after the main item text

  • value – The main content of the item, contains the value (or data structure) to be printed, updated, or modified as wished.

  • decimals (int) – If displaying floats, determines how many decimals to show.

  • xycoords (Literal["prop", "fixed", "xprop", "yprop"]) – Determines how to translate the x,y values into terminal screen coordinates: prop: coordinate system of the axes, x,y are floats between 0 and 1, (0, 0) is top left, and (1, 1) is top right. fixed: exact column and row position, x,y, are ints. xprop: prop for the x axis, fixed for the y axis yprop: prop for the y axis, fixed for the x axis

  • halign (Literal["left", "center", "right"]) – horizontal alignment of the item with respect to the x,y coordinates

  • valign (Literal["top", "center", "bottom"]) – vertical alignment of the item with respect to the x,y coordinates

  • xoffset (int) – number of columns, horizontal offset with respect to the x position. Useful to group together groups of items.

  • yoffset (int) – number of rows, vertical offset with respect to the y position. Useful to group together groups of items.

__init__(x, y, xgrid: int | None = None, ygrid: int | None = None, channel: int | None = None, data: str | None = None, action: str | None = None, text_before: str = '', text_after: str = '', value: Any | None = None, decimals: int = 2, xycoords: Literal['prop', 'int'] = 'prop', halign: Literal['left', 'center', 'right'] = 'left', valign: Literal['top', 'center', 'bottom'] = 'top', xoffset: int = 0, yoffset: int = 0) → None[source]#
abstractmethod draw(screen: window, selected: bool = False, pressed: bool = False) → None[source]#

Draw the item on the screen

editable: bool = False#
enter_edit()[source]#

This method is called when an item enters editing mode.

exit_edit()[source]#

This method is called when an item enters editing mode.

handle_edit_key(key) → tuple[bool, float | None][source]#

Determines what happens when a key is pressed while editing an item.

Returns:

A tuple (exit_editing, commit_value). If exit_editing=True the dashboard will get out of editing mode, and the item action will be called with the commit_value returned. If commit_value=None the dahsboard will cancel the edit.

Return type:

tuple[bool, Optional[float]]

navigable: bool = False#

Available items#

class labterm.dashboard_item.Button[source]#

Bases: DashboardItem

Single-action button.

An interactive control that executes an instrument action when activated. Unlike switches, buttons do not maintain state — they simply trigger an action when pressed.

Parameters:

  • x – x position in dashboard. The way this value translates to a column of the terminal is decided by xycoords

  • y – y position in dashboard (higher y corresponds to a lower position). The way this value translates to a row of the terminal is decided by xycoords

  • xgrid (int) – If navigable, determines the x position of the item on the navigable grid

  • ygrid (int) – If navigable, determines the y position of the item on the navigable grid

  • channel (int) – A number associating the items with an instrument. Enter a channel equal to the one set for the desired instrument for the two to communicate.

  • action (str) –

    The action to carry out when the item is pressed.

    Must be one of the actions foreseen by the instrument action() method.

  • text (str) – The text shown when printing the button

  • **kwargs – See DashboardItem for the full list of accepted arguments.

__init__(x, y, xgrid: int, ygrid: int, channel: int, action: str, text: str, **kwargs) → None[source]#
draw(screen: window, selected, pressed)[source]#

Draw the item on the screen

editable: bool = False#
navigable: bool = True#
class labterm.dashboard_item.Editable[source]#

Bases: DashboardItem

Editable numeric input field.

An interactive control for setting numeric instrument parameters. Press Enter to enter edit mode, type a value, then press Enter again to commit (or Escape to cancel). The committed value is sent to the instrument via the specified action.

Parameters:

  • x – x position in dashboard. The way this value translates to a column of the terminal is decided by xycoords

  • y – y position in dashboard (higher y corresponds to a lower position). The way this value translates to a row of the terminal is decided by xycoords

  • xgrid (int) – If navigable, determines the x position of the item on the navigable grid

  • ygrid (int) – If navigable, determines the y position of the item on the navigable grid

  • channel (int) –

    A number associating the items with an instrument.

    Enter a channel equal to the one set for the desired instrument for the two to communicate.

  • data (str) –

    The specific data associated with the item, obtained by the instrument of corresponding channel. Must be one of the keys of the instrument data dict.

    The item will continuosly update the data in the way described by the instrument update_data() method.

  • action (str) –

    The action to carry out after the item value was edited (i.e. when pressing enter again after having edited the item). Typically indicates what should the Instrument do with the new value.

    Must be one of the actions foreseen by the instrument action() method.

  • initial_value (bool) – The initial value stored in the item.

  • **kwargs – See DashboardItem for the full list of accepted arguments.

__init__(x, y, xgrid: int, ygrid: int, channel: int, data: str, action: str, initial_value=0.0, **kwargs)[source]#
draw(screen: window, selected: bool, **kwargs)[source]#

Draw the item on the screen

editable: bool = True#
enter_edit()[source]#

This method is called when an item enters editing mode.

exit_edit()[source]#

This method is called when an item enters editing mode.

handle_edit_key(key) → tuple[bool, float | None][source]#

Determines what happens when a key is pressed while editing an item.

Returns:

A tuple (exit_editing, commit_value). If exit_editing=True the dashboard will get out of editing mode, and the item action will be called with the commit_value returned. If commit_value=None the dahsboard will cancel the edit.

Return type:

tuple[bool, Optional[float]]

navigable: bool = True#
class labterm.dashboard_item.Header[source]#

Bases: DashboardItem

Horizontal divider with optional title.

A decorative element that draws a window-wide horizontal line, optionally containing centered or positioned text. Useful for visually separating dashboard sections.

Parameters:

  • x – x position of the header text in dashboard. The way this value translates to a column of the terminal is decided by xycoords

  • y – y position in dashboard (higher y corresponds to a lower position). The way this value translates to a row of the terminal is decided by xycoords

  • text (str) – The text to be printed

  • **kwargs – See DashboardItem for the full list of accepted arguments.

__init__(x, y, text: str = '', **kwargs)[source]#
draw(screen: window, **kwargs)[source]#

Draw the item on the screen

class labterm.dashboard_item.Label[source]#

Bases: DashboardItem

Static text label.

A non-interactive display element, for headers, row/column labels, and annotations. Does not respond to user input or update from instrument data.

Parameters:

  • x – x position in dashboard. The way this value translates to a column of the terminal is decided by xycoords

  • y – y position in dashboard (higher y corresponds to a lower position). The way this value translates to a row of the terminal is decided by xycoords

  • text (str) – The text to be printed

  • **kwargs – See DashboardItem for the full list of accepted arguments.

__init__(x, y, text: str, **kwargs)[source]#
draw(screen: window, **kwargs)[source]#

Draw the item on the screen

class labterm.dashboard_item.Light[source]#

Bases: DashboardItem

Boolean status indicator.

A visual indicator that displays instrument boolean data as a colored circle: green (●) for True, red (●) for False. Non-interactive, use Switch if you need user control.

Parameters:

  • x – x position in dashboard. The way this value translates to a column of the terminal is decided by xycoords

  • y – y position in dashboard (higher y corresponds to a lower position). The way this value translates to a row of the terminal is decided by xycoords

  • xgrid (int) – If navigable, determines the x position of the item on the navigable grid

  • ygrid (int) – If navigable, determines the y position of the item on the navigable grid

  • channel (int) –

    A number associating the items with an instrument.

    Enter a channel equal to the one set for the desired instrument for the two to communicate.

  • data (str) –

    The specific data associated with the item, obtained by the instrument of corresponding channel. Must be one of the keys of the instrument data dict.

    The item will continuosly update the data in the way described by the instrument update_data() method.

  • initial_value (bool) – The initial value stored in the item.

  • **kwargs – See DashboardItem for the full list of accepted arguments.

__init__(x, y, channel: int, data: str, initial_value=False, **kwargs)[source]#
draw(screen: window, **kwargs)[source]#

Draw the item on the screen

class labterm.dashboard_item.Readonly[source]#

Bases: DashboardItem

Read-only numeric display.

A live display that continuously updates from instrument data but cannot be edited by the user. Useful for measurements, status values, and computed results.

Parameters:

  • x – x position in dashboard. The way this value translates to a column of the terminal is decided by xycoords

  • y – y position in dashboard (higher y corresponds to a lower position). The way this value translates to a row of the terminal is decided by xycoords

  • xgrid (int) – If navigable, determines the x position of the item on the navigable grid

  • ygrid (int) – If navigable, determines the y position of the item on the navigable grid

  • channel (int) –

    A number associating the items with an instrument.

    Enter a channel equal to the one set for the desired instrument for the two to communicate.

  • data (str) –

    The specific data associated with the item, obtained by the instrument of corresponding channel. Must be one of the keys of the instrument data dict.

    The item will continuosly update the data in the way described by the instrument update_data() method.

  • initial_value (bool) – The initial value stored in the item.

  • **kwargs – See DashboardItem for the full list of accepted arguments.

__init__(x, y, channel: int, data: str, initial_value=0.0, **kwargs)[source]#
draw(screen: window, **kwargs)[source]#

Draw the item on the screen

class labterm.dashboard_item.Switch[source]#

Bases: DashboardItem

Toggle switch for boolean instrument states.

An interactive control that displays and toggles between two states (e.g., ON/OFF, ENABLED/DISABLED). Pressing Enter while selected inverts the state and triggers the associated instrument action.

Parameters:

  • x – x position in dashboard. The way this value translates to a column of the terminal is decided by xycoords

  • y – y position in dashboard (higher y corresponds to a lower position). The way this value translates to a row of the terminal is decided by xycoords

  • xgrid (int) – If navigable, determines the x position of the item on the navigable grid

  • ygrid (int) – If navigable, determines the y position of the item on the navigable grid

  • channel (int) – A number associating the items with an instrument. Enter a channel equal to the one set for the desired instrument for the two to communicate.

  • data (str) –

    The specific data associated with the item, obtained by the instrument of corresponding channel. Must be one of the keys of the instrument data dict. Must be of boolean nature.

    The item will continuosly update the data in the way described by the instrument update_data() method.

  • action (str) –

    The action to carry out when the item switches between the two possible states.

    Must be one of the actions foreseen by the instrument action() method.

  • initial_value (bool) – The initial value stored in the item.

  • text (tuple[str,str]) – The text shown in the two different states of the switch. Defaults to (“ON”, “OFF”)

  • **kwargs – See DashboardItem for the full list of accepted arguments.

__init__(x, y, xgrid: int, ygrid: int, channel: int, data: str, action: str, initial_value: bool = False, text: tuple[str, str] = ('ON', 'OFF'), **kwargs) → None[source]#
draw(screen: window, selected, pressed)[source]#

Draw the item on the screen

editable: bool = False#
navigable: bool = True#