plover.engine – Steno engine#
The steno engine is the core of Plover; it handles communication between the machine and the translation and formatting subsystems, and manages configuration and dictionaries.
- class plover.engine.StenoEngine(config, controller, keyboard_emulation)#
- config: Dict[str, any]
A dictionary containing configuration options.
- controller: plover.oslayer.controller.Controller
An instance of
Controllerfor managing commands sent to this Plover instance. This is provided during startup.
- keyboard_emulation: plover.oslayer.keyboardcontrol.KeyboardEmulation
An instance of
KeyboardEmulationprovided during startup.
- HOOKS: List[str]#
A list of all the possible engine hooks. See Engine Hooks below for a list of valid hooks.
- machine_state: str#
The connection state of the current machine. One of
- output: bool#
Trueif steno output is enabled,
- config: plover.config.Config#
Configobject containing the engine’s configuration.
- translator_state: plover.translation._State#
_Stateobject containing the current state of the translator.
- starting_stroke_state: StartingStrokeState#
StartingStrokeStaterepresenting the initial state of the formatter.
- dictionaries: plover.steno_dictionary.StenoDictionaryCollection#
StenoDictionaryCollectionof all the dictionaries Plover has loaded for the current system. This includes disabled dictionaries and dictionaries that failed to load.
- _in_engine_thread() bool #
Returns whether we are currently in the same thread that the engine is running on. This is useful because event listeners for machines and others are run on separate threads, and we want to be able to run engine events on the same thread as the main engine.
Starts the steno engine.
Quits the steno engine, ensuring that all pending tasks are completed before exiting.
Quits and restarts the steno engine, ensuring that all pending tasks are completed.
Starts the steno engine, translating any strokes that are input.
Joins any sub-threads if necessary and returns an exit code.
- load_config() bool #
Loads the Plover configuration file and returns
Trueif it was loaded successfully,
Resets the machine state and Plover’s connection with the machine, if necessary, and loads all the configuration and dictionaries.
- send_engine_command(command: str)#
Runs the specified Plover command, which can be either a built-in command like
set_configor one from an external plugin.
commandis a string containing the command and its argument (if any), separated by a colon. For example,
lookupcommand (the same as stroking
run_shellcommand with the argument
Toggles steno mode. See
outputto get the current state, or
set_output()to set the state to a specific value.
- set_output(enabled: bool)#
Enables or disables steno mode. Set
Trueto enable steno mode, or
Falseto disable it.
- __getitem__(setting: str) any #
Returns the value of the configuration property
- __setitem__(setting: str, value: any)#
Sets the configuration property
- get_suggestions(translation: str) List[plover.suggestions.Suggestion] #
Returns a list of suggestions for the specified
Resets the translator to an empty state, as if Plover had just started up, clearing the entire translation stack. If
True, this also reverts all previous translations on the stack (which could include a lot of backspaces).
- hook_connect(hook: str, callback: Function)#
callbackto the list of handlers that are called when the
hookhook gets triggered. Raises a
hookis not in
The expected signature of the callback is depends on the hook; see Engine Hooks for more information.
- hook_disconnect(hook: str, callback: Function)#
callbackfrom the list of handlers that are called when the
hookhook is triggered. Raises a
hookis not in
HOOKS, and a
callbackwas never added as a handler in the first place.
The following methods simply provide a way to access the underlying
StenoDictionaryCollection. See the documentation there for more complete information.
- lookup(translation: Tuple[str]) str #
Returns the first translation for the steno outline
translationusing all the filters.
- raw_lookup(translation: Tuple[str]) str #
lookup, but without any of the filters.
- lookup_from_all(translation: Tuple[str]) List[str] #
Returns all translations for the steno outline
translationusing all the filters.
- raw_lookup_from_all(translation: Tuple[str]) List[str] #
lookup_from_all, but without any of the filters.
- reverse_lookup(translation: str) List[Tuple[str]] #
Returns the list of steno outlines that translate to
- casereverse_lookup(translation: str) List[Tuple[str]] #
reverse_lookup, but performs a case-insensitive lookup.
- add_dictionary_filter(dictionary_filter: Function[Tuple[str], str, bool])#
dictionary_filterto the list of dictionary filters. See
StenoDictionaryCollection.filtersfor more information.
- remove_dictionary_filter(dictionary_filter: Function[Tuple[str], str, bool])#
dictionary_filterfrom the list of dictionary filters.
- add_translation(strokes: Tuple[str], translation: str[, dictionary_path: str = None])#
Adds a steno entry mapping the steno outline
translationin the dictionary at
dictionary_path, if specified, or the first writable dictionary.
- class plover.engine.StartingStrokeState(attach, capitalize)#
An object representing the starting state of the formatter before any strokes are input.
- attach: bool#
Whether to delete the space before the translation when the initial stroke is translated.
- capitalize: bool#
Whether to capitalize the translation when the initial stroke is translated.
- class plover.engine.MachineParams(type, options, keymap)#
An object representing the current state of the machine.
- type: str#
The name of the machine. This is the same as the name of the plugin that provides the machine’s functionality.
- options: Dict[str, any]#
A dictionary of machine specific options. See
plover.configfor more information.
- keymap: plover.machine.keymap.Keymap#
Keymapmapping the current system to this machine.
- class plover.engine.ErroredDictionary(path, exception)#
A placeholder class for a dictionary that failed to load. This is a subclass of
- path: str#
The path to the dictionary file.
- exception: any#
The exception that caused the dictionary loading to fail.
Plover uses engine hooks to allow plugins to listen to engine events. By
engine.hook_connect and passing the
name of one of the hooks below and a function, you can write handlers that are
called when Plover hooks get triggered.
- hook stroked(stroke: plover.steno.Stroke)#
The user just sent a stroke.
- hook translated(old, new)#
- hook machine_state_changed(machine_type: str, machine_state: str)#
Either the machine type was changed by the user, or the connection state of the machine changed.
machine_typeis the name of the machine (e.g.
Gemini PR), and
machine_stateis one of
- hook output_changed(enabled: bool)#
The user requested to either enable or disable steno output.
Trueif output is enabled,
- hook config_changed(config: Dict[str, any])#
The configuration was changed, or it was loaded for the first time.
configis a dictionary containing only the changed fields. Call the hook function with the
StenoEngine.configto initialize your plugin based on the full configuration.
- hook dictionaries_loaded(dictionaries: plover.steno_dictionary.StenoDictionaryCollection)#
The dictionaries were loaded, either when Plover starts up or the system is changed or when the engine is reset.
- hook send_string(s: str)#
Plover just sent the string
sover keyboard output.
- hook send_backspaces(b: int)#
Plover just sent backspaces over keyboard output.
bis the number of backspaces sent.
- hook send_key_combination(c: str)#
Plover just sent a keyboard combination over keyboard output.
cis a string representing the keyboard combination, for example
- hook add_translation()#
The Add Translation command was activated – open the Add Translation tool.
- hook focus()#
The Show command was activated – reopen Plover’s main window and bring it to the front.
- hook configure()#
The Configure command was activated – open the configuration window.
- hook lookup()#
The Lookup command was activated – open the Lookup tool.
- hook suggestions()#
The Suggestions command was activated – open the Suggestions tool.
- hook quit()#
The Quit command was activated – wrap up any pending tasks and quit Plover.