User Tools

Site Tools


simple_orca_plugin_system

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

simple_orca_plugin_system [2017/07/12 10:55] (current)
chrys created
Line 1: Line 1:
 +====== 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:
 +<code bash>/​usr/​share/​SOPS/​install-for-current-user.sh</​code>​
 +
 +===== 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:
 +<code bash>$ ./ensop <​pluginname></​code>​
 +The command to disable and unload a plug-in is: 
 +<code bash>$ ./dissop <​pluginname></​code>​
 +Both commands basically just create or delete links in <code bash>​~./​.config/​SOPSP/​plugins-enabled</​code>​ 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 ''​__+__''​.
 +<code bash><​description>​__-__[<​command>​__+__command...][__+__<​modifier>​__+__<​modifier>​__+__key_<​key>​].ext</​code>​
 +
 +==== 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 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''​
 +<code bash>
 +#!/bin/sh
 +echo "Hello World"
 +</​code>​
 +
 +=== 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''​
 +<code python>
 +#​!/​bin/​python
 +import orca.orca
 +orca.chnames.chnames["​!"​] = "​bang"​
 +</​code>​
 +
 +===== 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: 
 +<code bash>/​usr/​share/​SOPS/​tools/​hosting.txt</​code>​
 + 
 +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