[orca-list] Orca Customizations Tutorial

[Storm Dragon <stormdragon2976 gmail com>]

Hi,
I had written about creating this a while back but then a lot of stuff came up and kept me busy for a while.  Things are settling down at the moment.  So, I am taking this lull in the storm and using it to write the promised tutorial.  Attached is the rough draft.  Let me know what you think, what should be changed, if I got something wrong, etc.  This is in rough draft form and I am probably the world's worst at spelling, so expect lots of mistakes.
Thanks
Storm


Orca Script Tutorial
Written By Storm Dragon with Lots of help
Note:
I originally meant to try and teach the basics of Python in this tutorial.  However, trying to do everything here would make this document incredibly long.  So instead, I will give a link to an excellent Python tutorial.  This is where I got my start.  The link is:
http://www.sthurlow.com/python/
1: Creating Scripts
There are two ways to go about this.  For scripts to add global functionality such as time and date, battery status, weather, etc creating a file, ~/.orca/orca-customizations.py, will do the trick.
Open a terminal, and type the following:
cd .orca
gedit orca-customizations.py
This will create the file if it doesn't exist already.
The second way is to create your own custom script area.  This is actually quite a bit easier than it sounds.  To set up your custom script area, open a terminal if you haven't done so already and type the following commands.
cd .orca
mkdir orca-scripts
cd orca-scripts
touch __init__.py
There, you've done it!  Your very own custom script area.  Go ahead and celibrate, we'll wait...
Now, for an explination of what was just done.
cd .orca changes you to the .orca directory.  It begins with a . because it is a hidden folder, so if you are in your home directory you won't know it is there unless you have view hidden directories on.  Any file or folder that starts with a . is hidden.  Just for reference, this is different from starting something with ./ which runs or executes a program.
mkdir orca-scripts creates a new directory called orca-scripts.  Just remember, mkdir equals make directory.
cd orca-scripts Can you guess what this does?
That's right, takes you into the orca-scripts directory. (2 points!)
touch __init__.py is a neat command.  It creates a file with nothing in it called, you guessed it, __init__.py.  It's much easier than firing up your favorite text editor and navigating through a bunch of folders just to save a blank file.
So, now that you have your very own custom script area, you may be wondering why you need such a thing.  When a new program is loaded or gains focus, let's say Firefox for example, Orca searches several places to find out how it is supposed to handle the new program.  In general, Orca is going to look for a script module whose name matches
the name of the application in use.  If that's not found, it's going to
look for a module whose name matches the name of the toolkit in use.  If
that's not found, then it falls back to default.py.  This can be changed
by adding to settings._scriptMappings by calling
settings.setScriptMapping.  You can change the Firefox behavior by creating your own custom firefox.py script in the orca-scripts folder.  This presents a special case though.  IN the case of Firefox, you will most likely want to keep all of the abilities it has already like skip to next/previous heading etc.  So, in your custom script, you will need to import orca.scripts.toolkits.Gecko in your script.
Ok, if I haven't lost you so far, it gets easier, trust me. IN the next section I will give your brain as well as mine a chance to quit smoking.  Let's write a script to add time functionality to Orca.
2: What Time Is It?
Most screen readers have a key combination that when pressed speaks the time.  Orca, however, does not have this feature built in to it.  No big deal though, we'll just roll our own.
The following script is an adaptation from the script found at:
http://live.gnome.org/Orca/FrequentlyAskedQuestions#head-6a8c1c2511ba01d7397f68f754eec0d923d166f1
to get started, lets go to the .orca directory.  To get to your .orca directory type:
cd ~/.orca
gedit orca-customizations.py
This will open up a new file in Gedit.  You can use your text editor of choice instead of course.
Enter the following lines in as they are shown.  Remember that indentation is of upmost importants in Python.  So, if two spaces appear at the beginning of the line here, they must also be at the beginning of the line in your script.
"""This script adds time functionality to Orca
Adapted by Storm Dragon from the script posted at:
http://live.gnome.org/Orca/FrequentlyAskedQuestions#head-6a8c1c2511ba01d7397f68f754eec0d923d166f1
feel free to modify and/or redistribute this script as you see fit."""
import orca.input_event # watches for input that Orca recognizes
import orca.keybindings # Handles binding keystrokes for Orca to use.
import orca.orca # Imports the main screen reader
import orca.speech # Handles Orca's speaking abilities
import orca.braille # Displays information in Braille format
import re # Not sure

myKeyBindings = orca.keybindings.KeyBindings()

#Define the sayTime function
def sayTime(script, inputEvent=None):
  import time # imports the Python time library
  message = time.strftime("%I:%M%p", time.localtime())
  orca.speech.speak(message)
  orca.braille.displayMessage(message)
  return True
#end sayTime function

sayTimeHandler = orca.input_event.InputEventHandler(
    sayTime,
    "Speaks and/or Brailles the time.") # Shows the function of the key press in learn mode

myKeyBindings.add(orca.keybindings.KeyBinding(
    "t",
    1 << orca.settings.MODIFIER_ORCA,
    1 << orca.settings.MODIFIER_ORCA,
    sayTimeHandler)) # Sets Orca-t as the say time key

orca.settings.keyBindingsMap["default"] = myKeyBindings
#end time code