GNOME.org
 

Re: [orca-list] orca and scripts, part 3


I like one thing the best in this.
While it is not doing any thing serious persay, you inculcated good habbits of project management, sich as branching. 
Really well done.
Now I would expect others who know orca code very well to chime in and contribute to such a crutial aspect of documentation which can take Orca a long way further. 
happy hacking.
Krishnakant.
On 01/12/2015 07:33 AM, José Vilmar Estácio de Souza wrote:
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
    modified:   src/orca/common_keyboardmap.py
    modified:   src/orca/scripts/default.py

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
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]