Today we will try to write a new simple function in orca. This new
function will cause Orca say Hello world when a key is pressed.
I am assuming that:
1. You have read and understood the two e-mails on this subject
written previously.
2. You already has git installed and configured in your machine.
3. You know python.
4. You know how to compile and install orca manually.
5. you have another copy of the orca installed so that you can use
it if anything goes wrong.
The first thing that we need to define is where to write our new
function, and to define this, we need to answer a simple question:
The say hello must be announced by orca in any application?
The answer is yes and in this case a good candidate is default.py
because the script present in this file seems to be extended by all
scripts. This means that the new function will be present in all
scripts too.
Before we begin I strongly suggest that we create one branch in git
to receive the changes that will be made in Orca. Although this is
not necessary, I consider good practice in development.
$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean
$ git branch hello-world
$ git checkout hello-world
Switched to branch 'hello-world'
$ git status
On branch hello-world
nothing to commit, working directory clean
We are working in a branch called hello-world.
Now edit the file src/orca/scripts/default.py and include in the end
of the file the following code:
------
def presentHelloWorld(self, inputEvent):
""" Presents the Hello world message. """
message = "Hello world from orca"
self.presentMessage(message)
return True
------
Important: The ------ are not part of the code.
Seems that the function must always return true.
The function presentMessage used in our function is a orca function.
The documentation of the presentMessage( function says:
def presentMessage(self, fullMessage, briefMessage=None,
voice=None):
"""Convenience method to speak a message and 'flash' it in
braille.
Arguments:
- fullMessage: This can be a string or a list. This will be
presented
as the message for users whose flash or message verbosity
level is
verbose.
- briefMessage: This can be a string or a list. This will be
presented
as the message for users whose flash or message verbosity
level is
brief. Note that providing no briefMessage will result in
the full
message being used for either. Callers wishing to present
nothing as
the briefMessage should set briefMessage to an empty string.
- voice: The voice to use when speaking this message. By
default, the
"system" voice will be used.
"""
Ok, our presentHelloWorld function is done but we need to tell orca
that this function must be exposed as a command, so that a key can
be binded to it. This is done in the function
setupInputEventHandlers present in the file default.py, the same
file that we are editing.
The documentation of this function is:
def setupInputEventHandlers(self):
"""Defines InputEventHandler fields for this script that can be
called by the key and braille bindings."""
In the function setupInputEventHandlers we have the following sequence:
self.inputEventHandlers["presentDateHandler"] = \
input_event.InputEventHandler(
Script.presentDate,
cmdnames.PRESENT_CURRENT_DATE)
We can include after that the following code:
self.inputEventHandlers["presentHelloWorldHandler"] = \
input_event.InputEventHandler(
Script.presentHelloWorld,
cmdnames.PRESENT_HELLO_WORLD)
Pay attention to the indentation since it is crucial in python.
The next step is edit the src/orca/cmdnames.py and create the
variable PRESENT_HELLO_WORLD. This variable contains a brief summary
describing what the function does.
In the end of the file include the following code:
# Translators: this is for orca say hello world.
PRESENT_HELLO_WORLD = _("Say a hello message.")
To finish our function we need edit the file
src/orcacommon_keyboardmap.py and include in that file the following:
("y", defaultModifierMask, ORCA_MODIFIER_MASK,
"presentHelloWorldHandler"),
This lines must be included before the following text present in the
end of the file.
("", defaultModifierMask, NO_MODIFIER_MASK,
"shutdownHandler"),
)
The "presentHelloWorldHandler" is the same used in the
setupInputEventHandlers.
We can also associate a key bind to our new function. Take a look in
this file for examples. I am using in this example orca_key+y.
Ok, the function is ready, we can compile and install orca and test
the new function.
Press orca_key+y to hear a simple Hello world.
Since the script is working, you can commit the changes to your
branch, hello-world.
$ git status
On branch hello-world
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working
directory)
modified: src/orca/cmdnames.py[m
modified: src/orca/common_keyboardmap.py[m
modified: src/orca/scripts/default.py[m
no changes added to commit (use "git add" and/or "git commit -a")
[hello-world cbb9973] A helloWorld function
3 files changed, 17 insertions(+)
$ git commit -a -m'A helloWorld function'
[hello-world cbb9973] A helloWorld function
3 files changed, 17 insertions(+)
That is it for while.
Thanks.
_______________________________________________
orca-list mailing list
orca-list gnome org
https://mail.gnome.org/mailman/listinfo/orca-list
Visit http://live.gnome.org/Orca for more information on Orca.
The manual is at
http://library.gnome.org/users/gnome-access-guide/nightly/ats-2.html
The FAQ is at http://live.gnome.org/Orca/FrequentlyAskedQuestions
Log bugs and feature requests at http://bugzilla.gnome.org
Find out how to help at http://live.gnome.org/Orca/HowCanIHelp
