GWKB1006 : So You Want to Write a Set File?

Product: Window-Eyes
Author: Raul Gallegos
Date Added: 09/20/2005
Last Modified: 06/06/2011

So You Want to Write a Set file?

The information in this article applies to Window-Eyes 7.5. While the majority of the information is true for older versions, the steps used to accomplish certain things will be different due to the older user interface in versions prior to version 7.5.

Writing set files is not as hard as you might think. Did you know that every time you increase or decrease your rate of speech, add or remove an entry in a dictionary, increase or decrease the cursor delay, define or undefined a hotkey, you are making changes that can be saved to a set file? Set files can also include user window definitions, hyperactive window definitions, chain read windows, verbosity settings, and more. So as you can see, set files contain the­ most basic settings, as well as advanced settings. If you want to change the way that Window-Eyes behaves in a particular program every time you launch that program, you want to create a set file.

What is a set file?

A set file is a list of customizations that instructs Window-Eyes on how to behave in a given program. Think of a set file as a "settings" file where specific Window-Eyes changes can be saved.

Example 1

Let's say you want your speech rate to be very fast while surfing the web in Internet Explorer, but you want your speech rate much slower for editing a document in Microsoft Word. You can go into Internet Explorer, increase the voice rate to something really fast, and save the Internet Explorer set file. Then you can go into Word, decrease the voice rate to something slow, and save the Word set file. When you switch between the programs, you will notice that the voice rate is slower in Word, because that is where you want to do your editing. The voice rate in Internet Explorer will be faster, because that is where you want to do your reading. You can set up voice rates (as well as other speech characteristics) for every program you have installed on your machine.

Example 2

Let's say you want to use a contact management program which allows you to manage names, addresses, and phone numbers of people. You want Window-Eyes to speak phone numbers and zip codes as single digits for this program only, and as words, (which is the default), for all other programs. By creating a set file for this program, you can change the way numbers speak, and the change will only affect this program.

What is an active set file?

Contrary to what some may think, an active set file is not one that moves around a lot. Instead, an active set file is simply a set file that is currently in use. For example, if you are using Notepad, and you open the Window-Eyes control panel by pressing Control-Backslash, you will notice that the active set file is notepad.set. The reason that the Notepad set file is loaded is because NOTEPAD is the active program, making the Notepad set file, the active set file.

What is an associated set file?

Associated set files are probably the most misunderstood component of set files in general. When saving set files there has to be some sort of reference that Window-Eyes can examine in order to determine what program those saved set files should be associated with. If no reference existed, then Window-Eyes would not know what set file to load with any program. There are two basic ways that Window-Eyes can tell which set file belongs to which program: window name, and window class. The window name is usually the title of a program. For example, if you open up Notepad, the title bar will read "Untitled - Notepad." Window-Eyes will consider this the window name. Window-Eyes will often associate set files with a program's window name, but this is not always a good idea. Some programs, such as Internet Explorer and Firefox, have a different window name every time they launch (this is due to their listing of the current URL, or web page title, in the browser's title bar). For example, if you saved an Internet Explorer set file while the window name was "Welcome to a Random Page - Microsoft Internet Explorer," then in order for that set file to load every time, the page's title would have to be "Welcome to a Random Page - Microsoft Internet Explorer." As you can imagine, you are only going to see that title when you visit that particular web page. Associated with window name will work a lot of the time, but as you can see, it will not work in every case.

To combat this problem, there is a second way that you can associate set files to a program, and that is by class name. Along with a window name, every window belongs to a class. A class is a general group of objects. For example, a class called shapes might contain a number of objects like circles, squares, trapezoids, equilateral triangles, etc. Each object, or shape in this example, has characteristics of the class. If that example is not working for you, think of a class as a school class. Let us say that you signed up for Set Files 101. Set Files 101 is the name of the class, and the class is comprised of a number of students, with each student having the knowledge that the class provides (knowledge about set files). A student from the French Cuisine 101 class would not fit into the Set Files 101 class, so they would have their own label (in this case, French Cuisine), with their own specific knowledge (how to cook slugs).

Let's examine the shapes analogy a little bit closer. Notice that shapes is the class name, while the circle, square, trapezoid, and equilateral triangle objects are the titles. If you wanted to create settings for all shapes, you would not want to associate a set file with the title of every shape. That would be cumbersome. At the same time, if each shape required different and unique settings, then you would not want to apply those settings to all shapes. Herein lays the power of an associated set file.

Here is an example: With the above information in mind, you can begin to see how Window-Eyes can associate set files with a particular class name. If you ran a number of programs that all used the class OpenDialog for their windows that let you open files, it would make more sense to associate a set file with the class name than it would to associate the set files with the window names. If you have twelve of these programs, and you were associating via window name, you would have at least twelve different set files. If you use the window class association, then you would only have one set file that would open each time a window of that class type opened.

What does "Window-Eyes active blah.set associated blah.set" mean?

Now that you know how a set file can be associated, it is time to examine what Window-Eyes means when it announces, "Window-Eyes active blah.set associated blah.set." Active, we now know, simply means the set file that is currently open. In addition, associated, as we now know, means the set file that is associated with the program that we are running. Most of the time, these two set files will have the same name. There can be times, however, when you open up a different set file other than the one that is associated to try different settings. For example, let's say you are editing some text files in the Notepad program. Let's also say that in addition to the normal Notepad.set set file, you also have a proofread.set set file. The difference in the proofread.set set file is that the speech rate is slower than normal, the punctuation is turned on, and blank lines are set to on. This way it makes it easier to proofread your files. Normally when you launch Notepad, both the active and associated set file is notepad.set. However when you want to proofread your files, you would then load the proofread.set set file. If you bring up the Window-Eyes control panel while you have this proofread.set set file loaded, you will hear, "Window-Eyes active proofread.set associated notepad.set." When you think about it, this makes perfect sense. Although notepad.set is the associated set file, proofread.set is now the active set file because you want the speech to be slower, all punctuation spoken, and blank lines announced. When you are done proofreading your files, you can open back up the notepad.set to resume reading files like normal.

How does a set file get associated?

A set file is associated from the "Association" > "Current Association" node of the Window-Eyes control panel. In order to gain access to these settings, "Advanced Options" need to be enabled from the Help menu of the Window-Eyes control panel.

The following is a description of what is found here:

  • Set File - Edit Box
  • The name for the active set file goes here.

  • Association - Combo Box
  • This combo box lets you determine how the Set file should be associated to the current program. If you choose Title, the Set file will load when the text in the program's title bar matches what is present when you configure this association. If you choose by Class, then Window-Eyes will load the Set file when the window class of the program to which you are associating gains focus. If you choose None, Window-Eyes will not automatically associate the Set file to the active program.

  • Save and Associate - Button
  • This button causes Window-Eyes to create the set file specified above if it does not already exist along with the type of program association, if any.

Where does Window-Eyes keep association reference?

To create the association reference (the stuff Window-Eyes looks up to know what set file to load, and when to load it), Window-Eyes creates a file with a .WE extension. This is a text file that you can open up in a text editor such as Notepad, although we strongly discourage making any changes. In this text file, there is a section titled [windowSettings]. Under this section, there is the name of either the window, or the class (depending on how your set was associated), and then the name of the associated set file. Here is an example:

[windowSettings]
WordPad=WORDPAD.set
New=WORDPADD.set
Paragraph=WORDPADD.set
Tabs=WORDPADD.set

There is no way to tell whether the association is by class or by name. In fact, Window-Eyes does not know whether the association is by class or name. Window-Eyes simply examines each line in the windowSettings section of a .WE file, looking for an association by window name first. If it cannot find a window name that matches the first part of the line (the left hand side of the equals sign), it will then assume class association. Once Window-Eyes has verified either the window name, or the class name, it will load the set file mentioned in the second half of the line (the right hand side of the equals sign).

How do I actually create a set file?

Now that you know what a set file consists of, and how set files are associated with programs, you can begin to create your own. Let us start with a simple example:

Suppose that you want punctuation read while you are editing a document in a word processing program called Edit Plus. In addition, suppose that you want the voice rate to be slower to minimize the amount of spelling mistakes. Start by opening the program that you are going to be working with. I.E. Edit Plus. Since this is a made-up editor, we are assuming that no set file already exists for it. Once Edit Plus is open, you will need to create a "blank" set file to create your customizations in. To do this, bring up the Window-Eyes control panel with Control-Backslash. Before doing anything, make sure that "Advanced Options" are enabled from the Window-Eyes Help menu.

To create a new association do the following:

  1. Press Alt-E to focus the Settings tree view.
  2. Arrow to the Association node and press Right Arrow to open it.
  3. Press Down Arrow once to the Current Association setting.
  4. Press Tab and you will see an edit box which shows the name of the current set file. Since in this example there is no associated set file, the name "default.set" is used.
  5. Type the name you want to call the new set file. We suggest that the name you give the set file matches the program you want to associate it with. So for this example type "Edit Plus.set".
  6. Press Tab and you will see the combo box which contains the types of associations. The choices are none, by class, or by title. Since we are starting out with no association, the None choice is selected by default.
  7. Press the Arrow keys to choose the type of association you want. You will notice that the class name and title name is given along with the choice so that you can better decide how you want to create the association. In this example we will associate by class.
  8. Press Tab and you will see the Save Association button.
  9. Press Enter on this button and a new, blank set file called "Edit Plus.set" will be saved and associated with the Edit Plus program.

Technically speaking, you just created a new set file. That is all there is too it. Right now, however, the set file that you just created is a copy of the default.set set file with the global defaults. The only thing left to do is change the settings for punctuation and speech rate, and we will be done.

To change the punctuation settings do the following:

  1. Press Alt-E to focus the Settings tree view.
  2. Arrow to the Screen node and press Right Arrow to open it.
  3. Press Down Arrow until you reach the Punctuation setting.
  4. Now as you press Tab repeatedly in this section, you will first see the Global/Program scope button for the setting, and then the setting itself. For example, press Tab once and you will reach the Math punctuation scope button, press it again and you will reach the Math punctuation setting itself.
  5. You will notice that the settings are in alphabetical order. Math, Miscellaneous, Space, and Textual. We are interested in all except the Space setting, (which can be left alone).
  6. Toggle the scope for Math, Miscellaneous, and Textual to Program by pressing Space on each button. Then set each of those settings to On with the arrow keys.

It is important to set the scope to Program in the 3 types of punctuation settings. If you leave it at Global, then the punctuation changes you make will happen everywhere, not just in this program. Every Window-Eyes setting which can be changed to affect just the one program or all programs has a scope button just before the setting itself. The only thing left to do in our newly created set file is change the screen reading voice to be slower.

To change the screen voice settings do the following:

  1. Press Alt-E to focus the Settings tree view.
  2. Arrow to the Screen node and press Right Arrow to open it.
  3. Press Down Arrow until you reach the Voice setting.
  4. Now as you press Tab repeatedly in this section, you will first see a check box to make the Keyboard and Mouse voices match whatever you set the Screen voice to.
  5. Press Tab again and you will reach the Global/Program scope button for the rate setting, and then the setting itself.
  6. The settings are as follows. Rate, Pitch, Tone, and Volume. We are only interested in the rate setting.
  7. Toggle the scope for Rate to Program by pressing Space on the button. Then set the rate to something slower by using the arrow keys.

It is important to set the scope to Program in the Rate setting. If you leave it at Global, then the slower speech would be everywhere instead of in the program itself.

We have now completed the configuration of our punctuation settings and our speech rate setting, and have made these configurations apply to this set file only. In order to make sure that these settings are always available when you run Edit Plus, we need to save the changes that we made. To do that, press Control-S from the Window-Eyes control panel. Alternatively you can tab to the Save Settings button and press Enter.

Congratulations, you just made a set file! Pretty easy, wasn't it? With all of the options that Window-Eyes has available, it might seem that the more settings you change, the harder creating a set file becomes. That is not the case. Whether you are creating a simple set file, or an advanced set file, the format is still the same. Create a blank set file, customize your settings, and then save the set file. That's it. What you do during the "customize your settings" portion is up to you, and will be the meat of what your set file can do.

What else can a set file do?

There are a number of options in Window-Eyes, and almost all of them can be saved to a set file. If you feel like your set file is not good enough, or you feel that you could make it better if you only knew how, try reading through the manual. Specifically, the section called "The Window-Eyes Control Panel," explains the menus and settings tree view of Window-Eyes, the scope buttons, and every other setting available to you.