User Tools

Site Tools


simple_orca_plugin_system

Orca Plugin System

With the Simple Orca Plugin System (SOPS) you can extend the functionality of the Orca screen reader. It offers the possibility to add plug-ins in nearly any programming language in an easy way. The settings for the plug-ins are controlled via the filename.

Installation

  • Arch:
    • Just Install the package simpleorcapluginsystem from the AUR.
  • Manual:
    • download
    • copy SOPS folder to /usr/share/SOPS/

Setup

To setup the plug-in system for the current user, run:

/usr/share/SOPS/install-for-current-user.sh

Administration

Basics

  • The Installation path. This contains the default plug-ins, the documentation,the plugin loader and the administration tools: /usr/share/SOPS/
  • The path for user plug-ins is:

~/.config/SOPS/plugins-available/

  • The following path is used for all enabled (active) plug-ins. All plug-ins in that folder will be loaded, if they are valid:

~/.config/SOPS/plugins-enabled/

Administration tools

The tools are located in the “tools” folder beneath the installation directory. The following command enables/activates a plug-in, but you have to rename the filename to create a shortcut and pass a command to the plug-in:

$ ./ensop <pluginname>

The command to disable and unload a plug-in is:

$ ./dissop <pluginname>

Both commands basically just create or delete links in

~./.config/SOPSP/plugins-enabled

and make the plug-ins executable. You have to configure the plug-ins manually. Restart Orca to reload the plug-ins after changes. SOPS also provides a plug-in manager, it is available after the installation. To open the plug-in manager use orca+ctrl+p while Orca is running. It can be used to activate, deactivate, install or configure plug-ins. Orca gets re-started automatically after closing the plug-in manager.

Plug-ins

You can find some fully predefined example plugins in: /usr/share/SOPS/examples

Structure of the filename

The shortcut, plug-in type and preference of a plug-in are controlled by its filename. The descriptive part of the filename has to be separated from the preferences part with -. The commands, modifier and the key has to be separated by +.

<description>__-__[<command>__+__command...][__+__<modifier>__+__<modifier>__+__key_<key>].ext

Run a plug-in

There are two different ways to run a plug-in:

If none of those are present. the plug-in won't load. There are some more Commands to control the behaviour of a plug-in.

Modifiers/ Shortcuts

With modifiers you can set different shortcut combinations for a key. You always have to press the Orca-modifier. The order of the three modifier keys do not matter:

  • control is the modifier for the ctrl key on the keyboard
  • shift is the modifier for the shift key on the keyboard
  • alt is the modifier for the alt key on the keyboard
  • key_<key> defines the basic shortcut that is used for the plug-in, maybe together with the defined modifiers (example_plugin-key_d.sh uses orca+d).
Valid shortcuts

Only a few combinations of modifiers are valid. Those are predefined by Orca. Valid combinations are:

  • alt i.e. description-alt+key_y.sh
  • control i.e. description-control+key_b.sh
  • shift i.e. description-shift+key_c.sh
  • control + alt i.e. description-control+alt+key_w.py
  • shift + alt i.e. description-shift+alt+key_y.sh

As key_<key> you can use any alphanumerical key.

Commands/ Preferences

Preferences for plug-ins are called commands. A command defines the action to pass to the plug-in. With commands you control the behaviour of the plug-ins. You may add more than one command. The order of the commands do not matter. You can use them for all kinds of plug-ins.

  • startnotify announces “start <description>” before the plug-in is executed. It is useful as feedback for plug-ins with longer progress times. (all plug-ins)
  • stopnotify announces “finish <description>”. This is useful as feedback for plug-ins with no output. (all plugins)
  • blockcall do not start the plug-in in a thread. Be careful, as this locks Orca until the plug-in is finished. By default, plug-ins each run in a dedicated thread. (all plug-ins)
  • error announces returned errors. (all plug-ins)
  • supressoutput ignores the output of STDOUT. This is useful for plugins that may have a UI and do not pass output to STDOUT. (sub process plug-in only)
  • parameters_<parameter1> [parameter2] [parameter3]… passes the parameters to the plug-in. (sub process plug-in only)
  • exec run the plug-in once while loading it. Mostly useful as advanced-plug-in. (all plug-ins)
  • loadmodule does not load as a sub process plug-in but loads it as advanced plug-in. (advanced plug-in only)

Examples

  • Plugin name-startnotify+control+alt+key_n.sh Run with orca+ctrl+alt+n and announce the start of the process.
  • PluginName-error+stopnotify+shift+key_y.py Run with orca+shift+m and announce the finishing. Does also read occurring errors .
  • Plugin_Name-key_m.py Run with orca+m
  • Plugin_Name-exec.py Run once at starting Orca.

Types of plug-ins

Basically there are two different types of plug-ins.

Sub process plug-ins

Sub process plug-ins are simple plug-ins of a default type. They may be any type of application or script that writes to STDOUT or STDERR. Orca executes the plug-in, reads from STDOUT/ STDERR and announces the result to the user, when the defined shortcut is pressed or the plug-in is executed via exec while starting the screen reader.

Requirements
  • Execution permission
  • key_<key> or exec have to be defined in the filename.
Example

Say “Hello World when pressing orca+y: Filename:Hello_world-key_y.sh

#!/bin/sh
echo "Hello World"

Advanced plug-ins

Those type of plug-ins are loaded with the spec.loader.exec_module. you can load them by using loadmodule in the filename. They are fully integrated into Orca as soon as it starts. Advanced plug-ins are more powerful, because you are able to work in the Orca context. They are mostly similar to the orca-customizations.py. See also for “real” Orca scripting: https://wiki.gnome.org/Projects/Orca/FrequentlyAskedQuestions/CustomizingOrca

Requirements
  • Correct code written in python3
  • Fileextension .py
  • Use loadmodule in the filename
  • key_<key> or exec have to been defined in filename
Example

Configure Orca to speak/braille the word “bang” instead of the ”!“ while loading the plug-in. Filename:replace_chnames-loadmodule+exec.py

#!/bin/python
import orca.orca
orca.chnames.chnames["!"] = "bang"

Plug-in hosting

You can also host plug-ins, making them available for installation via the plug-in manager. If you want to Host plug-ins, read:

/usr/share/SOPS/tools/hosting.txt

The default online resource is: https://stormdragon.tk/orca-plugins/index.php

simple_orca_plugin_system.txt · Last modified: 2017/07/12 10:55 by chrys