Differences

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

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

Linux Accessibility Wiki

User Tools

Site Tools

Differences

Page Tools