So You Want to Write an App (Part 1)

Introduction

The window eyes App Developer's Reference manual has several good explanations of particular scripting issues; and a good list of resources to help you learn about various aspects of programming which may help you write an app. There are also at least three apps I know of written specifically for the purpose of helping beginners advance their scripting knowledge.

What I don't know of is a comprehensive document, which attempts to make a start at explaining the various topics you'll need to understand in order to write an app; and perhaps help take you from a scripting beginner to a scripting expert over time. You need not be a professional programmer in order to write Window-Eyes apps.

Starting out

You have to start somewhere; I'll start by saying that in order to write an app, you've got to know how to program in some computer programming language. A lot of the documentation in the WE App Developer's Reference manual, and the wiki articles here, try to be helpful regardless of which language you're using, but they usually assume a working knowledge of VBScript. You're first step should be to learn how to program if you don't already know how to; and since that usually involves learning a programming language, go out and try to find a programming tutorial book which uses VBScript. There exist a lot of beginning programming tutorials on the internet, and many of them use VBScript. Here is a simple VBScript tutorial. And here is a more advanced VBScript tutorial organized by topic.

 In addition, there are audio archives (with text file examples) of a VBScript and Window-Eyes class at  Class archives taught by Chip Orange (other instructors are invited to make additional contributions).

here's a chapter of an online book on object-oriented programming, followed by a chapter on learning VBScript.

Or Try here for a VBScript tutorial if you already know how to program.

These links, along with many others, can be found on the GW Micro Scripting Developer Resources page.

One more important learning resource are the recorded audio seminars GW Micro has given from time-to-time on beginning scripting programming. You can find these on their audio presentations page.

What Else You Will Need to Know

In order to write very advanced apps, in addition to an object-oriented programming language, you will need to know about low-level Windows programming. This is a topic that covers the organization of, and data structures used by, all the Windows and the controls they contain, along with the Windows file system, and sometimes it's low-level internet communications. Try here for a summary from MS on the organization and terminology related to Windows as both a place to start, and later as a reference page with detailed links.

Why Write a Window-Eyes App?

Here's a list, in no particular order, of answers to that question:

• they can improve the accessibility (to WE only of course) of a particular program. If there's a particular program which can't be made to work well with WE, it's quite possible you can change that significantly with a app (referred to as a "program-specific app"). Even if the program works well enough with WE, you can add "convenience features" to it with an app, so that it's faster or easier to use.
• You can also create similar accessibility "convenience features" with an app, which are available in all programs (referred to as a "global app"). An example might be an app which makes it particularly easy to spell the word under the cursor, or spell it phonetically.
• Sometimes these convenience features may have nothing to do with accessibility or WE, in which case they may look like "general purpose programming" (e.g. looking up a word under the cursor on the internet); however, the WE scripting environment makes writing this kind of program much easier than would a general purpose programming language, and so a WE app may be used simply for the convenience of the developer, as well as the virtual guarantee that the resulting "application" will be accessible to those using both speech and/or braille.
• Another important aspect of the "convenience of the developer" is the ability to design visual interfaces, such as a dialog which contains windows controls (listboxes, editboxes, radio buttons, etc.), without sighted assistance, and have this interface appear aestheticly pleasing and have it function well. This type of programming is particularly difficult for blind programmers (often requiring the use of a purely visual dialog layout aplication, which is not easily accessible), in almost every programming environment. However, WE scripting has added "xml-based dialogs" which allow blind programmers to do this type of interface programming, and so developing a program with a user interface similar to the Windows standard model is made much easier. This is a capability, which to my knowledge, exists in no other screen reader's scripting environment.

Capabilities of WE Apps

What makes WE apps absolutely unique amongst screen readers with some sort of scripting facility is it's wealth of capabilities which are built in to it's scripting environment. One such capability has already been mentioned: the XML dialog facility. WE apps have many other unique abilities to work with; all of these together are known as the "window eyes object model". Incredibly, WE also allows any of these capabilities to be used from any programming language.

Below are just some of the capabilities of the object model that aps may make use of, listed in broad categories:

• change any of the WE configuration settings within the WE control panel
• control the speech (it's voice, rate, other parameters), and the braille display
• define a hotkey, which can cause something to happen in your app (something spoken, something displayed, the window eyes environment is changed, etc.)
• examine what text is in any window; watch for specific text to appear, or to change, and take some action (such as speaking it)
• take some action when the user tabs to a new field, or perhaps when he presses a particular key (such as the arrow keys)
• cause window eyes not to speak certain text it would otherwise speak, or to speak it differently
• activate a particular window, or cause a particular control to have the focus
• send keystrokes into a specific program, as if they were typed on the keyboard
• open a dialog (using standard Windows controls) to get data from the user, and then process this data in some way

Finally, Starting to Write Some Code!

Hopefully by now you've had a chance to look at some VBScript tutorials. You will have seen how easy writing simple VBScript programs can be. Next, we need to add the specialized knowledge which is specific to Window-Eyes, so you can combine the two into a true WE app.

Important Resources and Scripting Concepts

It is absolutely critical that you know about, and use, the WE App Developer's manual. This is a separate help file, aimed entirely at just scripting, and it's full of the technical information that you must have in order to write a WE app. In order to open this file you go to the WE control panel, choose alt-H for the help menu, and press down arrow once to get to the Documentation choice. Expanding it using the right arrow key gives you choices of the standard Window-Eyes manual, and the App Developer Reference (which is the one you want at the moment), along with the WE Read Me file.

The entire WE object model is documented in the WE App Developer Reference, but only by listing every possible object, property, or method in alphabetical order. A beginning scripter would therefore benefit from a higher-level overview, introducing capabilities in some logical order (such as simple to advanced), and grouped by similar functionality. The App Developer Reference manual is designed to be a reference book; one where you look up a specific item, not a tutorial. This wiki set of articles is therefore designed to compliment it's information with the step-by-step developmen of concepts and information that will be needed by someone who moves from beginning to advanced scripting.

In addition to the App Developer's Reference manual, You will also benefit greatly if you download and install an app written by GW Micro for script programmers; it is the WEScript Framework Wizard. It both helps you easily lookup information in the WE App Developer's manual, and will actually write an entire app for you, just by having you answer a few questions. You can then begin to enhance and expand this initial version of the app. It can be an invaluable aid for beginning scripters, who may not be sure what to include in any basic app, and how to properly structure the program.

GW has also included with WE, a library of useful programming functions and objects, known as the GWToolKit. These can be used by any VBScript or JScript, and are provided as a script which is always running. These additional programming aids are documented separately in their own help file, and this help file is reached by going through the help option of the GWToolKit script; it is not a part of the WE scripting manual. See the article in the GW support knowledgebase Getting to know the GW ToolKit.

It is useful to know that WE has configured 2 particular programming languages (VBScript and JScript) so that they are more tightly integrated with the WE object model than is normally the case. A script written in one of these 2 languages need not open the Window Eyes COM object model at all (it is done automatically), and are referred to as "internal" apps (or "hosted apps"). All other apps, which may be written in other programming languages, are referred to as "external" apps, and must open the Window Eyes COM object in order to make use of it's object model. External apps also have a few additional requirements, documented in the wiki article Internal and External Scripts.

Whether a script is internal or external is not immediately obvious in the list of scripts shown in the script manager, and it is of no importance to someone using the scripts in Window Eyes, only the developer need be concerned with the differences.

WE also has two types of scripts, based on when the script first starts running, and when it stops. These two types of scripts are explicitly differentiated in the script manager. You can either have a script start to run when window eyes starts, and optionally stay running as long as WE is running (referred to as a "global app"), or, have WE start a script when a particular program starts, and stop the script when the program closes down (referred to as a "program-specific app"). Possibly your first decision, when designing a app, will be whether it should run all the time (a global app), or only when a given program is running (a program-specific app).

All of these apps are running concurrently, and independantly of each other. They are also stored separately from WE, so that if you upgrade your version of WE, you need to do nothing at all; your apps will continue to run under the newer version of WE.

Root Level Objects

If you're an experienced object-oriented programmer, you're used to opening a COM object for some application, and storing it in a variable. Then, each time you go to make use of it you have to specify this variable which holds the COM object, followed by some symbol separating it from the property or method you mean to actually make use of. When external scripts make use of the WE object model this is still the case; however, internal scripts need not do this. WE, in combination with the Windows Active Scripting facility, allows certain scripting languages, which are written for the Active Scripting facility, to make use of the WE object model without having to open it, and without having to specify a variable containing the WE COM object, and then an operator separating it from a property or method name.

This means that all of the top-level properties and methods in the "Application" object of the WE object model can be used in your VBScript or JavaScript statements without specifying the WE application object and without use of the dot operator which normally follows the object variable. These special properties and methods, which can be used without explicitly naming their parent object and following it with a dot operator, are known as "root level" objects.

In addition to the Application object's methods and properties being "root level" objects, there are two other objects who themselves, like the Application object, have been given special status so that their properties and methods are also root level objects. These are the "Speech" and the "Script" objects (note that the "script" object is not available to external scripts).

using the methods of these 3 objects, which are at the root level, gives a script the appearance that many extra commands have been added to the VBScript language just for WE.

For example, if you wanted to use the SPEAK method of the SPEECH object, you would ordinarily write something like the following:

set WE = createObject ("windoweyes.application")
WE.speech.speak "hello"

However, in the VBScript integrated with WE, you only have to write:

speak "hello"

That's it! The WE application COM object is already opened for you, along with the Speech and the Script objects, and their methods and properties are available to you as root level objects, which you do not need to specify in order to use. The WE scripting documentation does indicate in the help topic for a given object if that object is a root level object, so that you can easily know when there is no need to specify another object in order to use it.

Below is a list of root level objects; they are listed here so that you can more easily go into the scripting help documentation, and read more about them, and in particular their methods. I've found that anything which has been made into a root level object is something which you are likely to need much more frequently than the other hundred or so other objects:

• application
• braille
• brailleDisplays
• browseMode
• clientInformation
• clipBoard
• clips
• cursor
• Dialog
• INIFile
• keyboard
• menu
• mouse
• MSAAEventSource
• OSVersion
• profiles
• screen
• script
• sharedObjects
• speech
• startupOptions
• synthesizers
• text
• utilities
• WEDialogs
• WEPM

Creating Your First Script

This is a good time to read the entire first major section in the WE scripting help file (the introduction to scripting). Don't worry; it' not too technical, it's not going to get into programming; but it's a very good overview of concepts you'll need to know in order to grasp the "big picture" of how WE scripts operate.

However, there is one point which could use attention: how do you create the file which is going to be your first script? The manual gives you the explanation as to why it's helpful to store your scripting files in the default location for scripts. That way, when you see the list of scripts in the script manager, you don't have to hear the complete path to each one every time you arrow past it. If it's stored in the default directory for scripts, then you only have to hear it's name. Unfortunately, this default directory is very hard to find; one reason is that it's actual path is different for each user. This is because the default directory is in the current WE profile (and you can have more than one of those), and this in turn is stored as part of the directory tree which is your Windows user profile (and this is named based on your login name). In the end, it's a very long path string, and it's some trouble to get it right, and impossible for someone to tell you ahead of time exactly what it is.

So, what I do is to go to the file menu of the WE control panel, before I go into the script manager, and choose it's User Profiles choice. We're not in this dialog to create or change user profiles however; there is also a command button in here, who's shortcut is alt-o, which opens the directory for your current WE profile. (The name of the menu choice is a little misleading; this dialog allows you to do things with WE profiles, and not Windows user profiles, which are a different set of directories).

When you press alt-o or click the open button in this user profiles dialog, a Windows Explorer window opens for the directory which contains all your scripts by default, and this is now your active window. You now need to create the file which will hold the new script, and then you need to tell the script manager to load it.

once it's in the script manager's list of scripts, you can edit it in the future from the script manager (with the alt-I shortcut), and you need not open this directory again unless you need to create another new file, or delete one.

To create a new script file, which is just a text file, you choose the file menu, the new sub-menu, and the text file choice. Windows Explorer will then prompt you for the new file's name, with something like "new text document.txt" already filled in, if you were to just press enter without entering a name. If you start typing this will be wiped out, but later versions of windows will still preserve the .txt extension; you however want it to have a .vbs file extension (for VBScript), and so you will need to press shift-end, wich selects the text from your current location to the end of the line, and press delete to remove this file extension. now you can enter the file name with a .vbs extension and press enter. Windows will prompt you with a yes/no question, about being sure that you really want to change the file extension from .txt. Respond with alt-Y for yes, and you're done with the file creation.

Note that any time you see a .vbs file in a Windows Explorer file list, it is possible for you to press enter on that file name, and since it is a program, the windows script host will try to run it. this is not what you want to happen; because you have written a WE script, it is designed to only run properly from the WE script manager. if you try and run it from the Windows Explorer, using the windows script host, it will not work properly, and you will get an error message.

you can now go into the app manager from the WE control panel by returning to the WE control panel,and press alt-A, and P), in order to go into the script manager.

It is absolutely important that you now stop and read all of the main WE help file on working with apps and the App Manager.

There is some setup work for you to do in the App manager if this is your first time in it (configuring it to see additional options, and setting your default editor); these steps are detailed in the WE main help file.

Your app is not yet shown in the list of apps in the App manager, you will need to set your script display to "global", and then "load" your app (detailed in the main WE help file), before it will show in the app manager list of apps.

Once you load it, you should be able to find the newly created empty file in your list of apps; you can now highlight it, and pressing alt-I will take you into your editor of choice so that you can actually enter commands into it.

When you finish creating your app, and close the editor, your script is configured to run by default, but it will not automatically start to run until WE starts again. To get it to run right now, you will need to "reload" it with the alt-R command.

One more thing to take note of: you may not want this new app to run each time you startup WE, and so in order to keep it from doing so, you need to disable it. To disable it, just highlight it and press the alt-E shortcut (for the enable/disable button), and it's status will changed to disabled. You may want to do this before closing down WE.

Some Example Apps

The syntax for a WE VBScript app is exceptionally simple. It's a rather expected example in all programming textbooks and tutorials for the first example to show you what is the minimum necessary for a program which will produce the mesage "hello world"; so, below is this example, which is just 1 line!

speak "Hello world!"

This will cause the phrase "hello world" to be spoken, or appear in braille. It works because while "speak" is not a VBScript command, the WE object model is automatically opened for you, and in the root level objects described above, "speak" is one of the methods of the "speech" object.

This app will only run once, when WE is first started; it will also run each time you use the "reload" command of the App manager for it.

To continue reading this article series, for some scripting examples which are used to teach you all about the particulars of scripting for different problem types, see the wiki article So you want to write a script? (part 2: scripting examples).