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

## Setup

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

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

This will create the directory ~/.config/SOPS and its subdirectories and enable three plugins: plugin_manager, workspacenumber and clipboard.

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.

## Administration

### Basics

- The Installation path is `/usr/share/SOPS/`. It contains the default plug-ins, the documentation,the plugin loader and the administration tools:
- 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:

    $ /usr/share/SOPS/tools/enssop <pluginname>

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

    $  /usr/share/SOPS/tools/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.

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

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

If none of those are present. the plug-in won't load. There are some more #Commands to control the behavior 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`.

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