Jump to content

# Simple Orca Plugin System

From ArchWiki

With the Simple Orca Plugin System (SOPS) you can extend the functionality of the Orca screen reader (orca). 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

Install the package simpleorcapluginsystem-gitAUR.

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

Tip 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:

- shortcut (See #Modifiers/ Shortcuts)
- exec run once when the plug-in loads. (See #Commands/ Preferences)

If none of those are present. the plug-in does not load. There are some more #Commands/ Preferences 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 does 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 every 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 does not matter. You can use them mostly 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 plugins.

#### Sub process plug-ins

Sub process plug-ins are simple plug-ins and the 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 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 included 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`.

##### 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`

    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[dead link 2023-09-16—domain name not resolved]

Category:

- Accessibility

Hidden category:

- Pages with dead links

Simple Orca Plugin System
Add topic