This shows you the differences between two versions of the page.
— |
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 | ||