plover.gui_qt – Qt plugins

This module provides the Qt-based steno engine, which is necessary for developing GUI tool plugins.

class plover.gui_qt.Engine

This is largely just a subclass of :class:StenoEngine<plover.engine.StenoEngine>, except for some Qt-specific logic, such as the signals below.

Since Qt’s signals will fit better into the Qt processing model than Plover’s default engine hooks, GUI plugins should use the API provided by this engine over the built-in one where possible.

signal_connect(name: str, callback: Function)

Registers callback as a callback to be called when the name hook is triggered. The callback is called with the arguments shown in Engine Hooks when the hook is triggered.

The individual Qt signals are also available below for convenience, for example if you need to trigger them manually. For example, engine.signal_lookup.emit() would trigger the lookup hook. The arguments for each signal are shown in Engine Hooks.

signal_stroked: QSignal

The signal version of the stroked hook.

signal_translated: QSignal

The signal version of the translated hook.

signal_machine_state_changed: QSignal

The signal version of the machine_state_changed hook.

signal_output_changed: QSignal

The signal version of the output_changed hook.

signal_config_changed: QSignal

The signal version of the config_changed hook.

signal_dictionaries_loaded: QSignal

The signal version of the dictionaries_loaded hook.

signal_send_string: QSignal

The signal version of the send_string hook.

signal_send_backspaces: QSignal

The signal version of the send_backspaces hook.

signal_send_key_combination: QSignal

The signal version of the send_key_combination hook.

signal_add_translation: QSignal

The signal version of the add_translation hook.

signal_focus: QSignal

The signal version of the focus hook.

signal_configure: QSignal

The signal version of the configure hook.

signal_lookup: QSignal

The signal version of the lookup hook.

signal_suggestions: QSignal

The signal version of the suggestions hook.

signal_quit: QSignal

The signal version of the quit hook.


Plover provides a helper class for creating GUI tools:

class plover.gui_qt.tool.Tool(engine)

A subclass of QDialog for creating GUI tools. When writing a GUI tool, you would typically subclass both Tool and some generated code class (named Ui_YourTool or something) to take care of the UI setup.


Sets up the user interface for this tool. You would typically call this in the __init__ method of your subclass to actually build the UI. Make sure to pass self in if you do.

TITLE: str

The title that would show up in the main window’s toolbar and the tools list in the main menu.

ICON: str

The path to the icon for this tool, usually of the form :/icon.svg. This file should be included as a resource in the GUI plugin.

ROLE: str

A unique name to identify this tool when saving and loading state.


A keyboard shortcut to activate this window, for example Ctrl+F.

_save_state(settings: QSettings)

Saves the current state of this tool to settings. Call settings.setValue(key, value) to store individual properties in this settings object.

_restore_state(settings: QSettings)

Restores the current state of this tool from settings. Call settings.value(key) to retrieve values for the desired properties.

Machine Options

class plover.gui_qt.machine_options.MachineOption

Represents the user interface for manipulating machine-specific configuration options. Each MachineOption class is also a subclass of a QWidget and is set up with a UI, similar to Tool above.

This isn’t itself a real class, though; in order to support a machine options UI for your machine, subclass QWidget and your UI class of choice and implement the method and attribute below.


Sets the contained value to value.

valueChanged: QSignal

A signal that gets emitted when the contained value is changed. Callbacks are called with the new value.

class plover.gui_qt.machine_options.KeyboardOption

A :class:MachineOption class for keyboard-specific options.

class plover.gui_qt.machine_options.SerialOption

A :class:MachineOption class for serial connection-specific options.


plover.gui_qt.utils.ToolBar(*action_list: List[QAction]) QToolBar

Returns a toolbar with a button for each of the specified actions.

plover.gui_qt.utils.find_menu_actions(menu: QMenu) Dict[str, QAction]

Returns a dictionary mapping action names to action objects in menu. This traverses the entire menu tree recursively.