5.2   Naming Icons, Symbols, and Pointers

This section describes outSPOKEN's features for labeling graphical images 
such as icons, symbols, and pointer shapes (Sections 3.1, 3.2). This is all 
done through two outSPOKEN dialog boxes, Rename Graphic and Edit Graphics 
Dictionary. To change the name of a graphic, place the pointer on the 
graphic and bring up the Rename Graphic dialog (CTRL-KPD PLUS). Type the new 
name and press ENTER, or click on the OK button. This saves the new name to 
a file on the hard disk called a graphics dictionary. It is important to 
note that naming a graphic names all graphics that have that image, not 
merely the individual graphic being named. Thus naming a single icon 
automatically names all identical icons.

A graphics dictionary is a file which contains one or more graphic images 
(or bitmaps), along with a user-defined name for each graphic. Each 
dictionary has the file extension ".DIC" and is located in the outSPOKEN 
directory (usually C:\OSW). Each graphic and its associated name are called 
an "entry" in that graphics dictionary. Unless otherwise specified, all new 
graphic names are stored in the default dictionary, "DEFAULT.DIC". If you 
are a beginner, there is no need to be overly concerned about how graphics 
dictionaries operate. It is enough to know that these files contain the 
images and names of the graphics you define in the Rename Graphic dialog. 
For more information about dictionaries, advanced users may wish to read the 
final sub-section of this chapter, "More About Graphics Dictionaries." 

Whenever outSPOKEN encounters a graphic, it searches its graphics 
dictionaries to find a name for that bitmap. If an entry is found, outSPOKEN 
speaks the assigned name when announcing that graphic. If none is found, 
outSPOKEN assigns the graphic a unique number, such as "Icon 7" or "Icon 9." 
This numbering scheme serves to distinguish one unnamed graphic from 
another. outSPOKEN numbers icons separately from symbols (Section 3.2). This 
means that "Icon 7" is not the same image as "Symbol 7." These numbers are 
not saved to disk, but are regenerated each time outSPOKEN is launched. This 
means that an unnamed graphic's number will probably change each time you 
restart outSPOKEN.

The pointer takes on many forms, depending on the state of the system and 
the item under the pointer. As the pointer changes shape, outSPOKEN 
announces the new cursor. Most of the standard shapes have been pre-defined 
in an existing dictionary. As with graphics, any unrecognized pointer is 
given a unique number. For more information about renaming pointers, see the 
sub-section called "Editing Graphics Dictionaries."

5.2.1   The Rename Graphic Dialog

An icon or symbol can be renamed at any time by placing the pointer on it 
and opening the Rename Graphic dialog (CTRL-KPD PLUS). In this dialog, an 
edit box contains the current graphic name in highlighted text, and OK is 
the default button. Thus, typing a new name replaces the old one, and 
pressing ENTER selects the OK button. The new name is saved, and the Rename 
Graphic dialog closes, returning the pointer to the graphic which has just 
been renamed. 

In addition to the previously mentioned edit box and OK button, there are a 
number of other important features of this dialog. To the right of the edit 
box is an image of the graphic itself. This serves to positively identify 
the graphic being renamed. Below the edit box is a check box labeled Ignore 
Graphic. If this box is checked, outSPOKEN will not speak the displayed 
graphic when reading. To the right of this check box is a combo box showing 
the currently selected graphics dictionary. This setting determines the 
dictionary to which the displayed graphic will be saved. In the lower-right 
corner of the dialog is the Edit Dictionary button, which brings up a sub-
dialog from which any graphic in the current dictionary can be renamed. To 
the left of the Edit Dictionary button are the OK and Cancel buttons.

When the Rename Graphic dialog opens, the edit box contains the graphic's 
current name. The name is highlighted, so any new text typed from the 
keyboard immediately replaces the old name. This is a normal edit box, and 
standard editing keys, such as RIGHT-ARROW, LEFT-ARROW, BACKSPACE, and DELETE, 
can be used to correct any errors made while typing. A graphic name can be 
up to five-hundred and twelve characters long, but extremely long names may 
not entirely show in the edit box. 

The Ignore Graphic check box, located below the edit box, is used to omit 
specific graphics when reading with outSPOKEN. To turn off an icon or 
symbol, check this control in the Rename Graphic dialog when viewing that 
graphic. In other words, to turn off a graphic, place the pointer on the 
graphic to be turned off, invoke the Rename Graphic dialog (CTRL-KPD PLUS), 
select the Ignore Graphic check box, and press OK. When this control is 
checked, outSPOKEN ignores the graphic, and neither navigates to it nor 
speaks it. From within the Rename Graphic dialog, this control can be 
toggled with the hotkey combination ALT-I. This setting can be overridden by 
turning on the "Verbose Graphics" option in the outSPOKEN Graphics 
Preferences sub-dialog (Section 5.1.3).

A graphics dictionary is a file which contains a group of graphics and their 
names (Section 5.2.3). The combo box to the right of the Ignore Graphic 
check box displays the name of the graphics dictionary where the current 
graphic is stored. A status line above the combo box also indicates the 
graphic's dictionary. If the graphic has not yet been saved, the dictionary 
name displayed in the combo box is "DEFAULT.DIC", and the status line 
reports that the graphic has not yet been stored. This means that pressing 
OK will store the newly named graphic in the dictionary "DEFAULT.DIC". 
Another dictionary can be selected by clicking in the combo box and choosing 
another name from the list. If another dictionary is selected, the graphic 
is filed in that dictionary when OK is pressed.

Along the bottom of the Rename Graphic dialog are three buttons labeled OK, 
Cancel, and Edit Dictionary. The OK button accepts all the settings in the 
dialog, saves them to the selected dictionary, and closes the dialog. 
Pressing the hotkey combination ALT-O from within the Rename Graphic dialog 
also selects this button. The Cancel button, which can alternately be 
selected with the hotkey combination ALT-C, closes the dialog, but makes no 
changes to any dictionary. This button discards any changes made while in 
the dialog and returns to the location of the original graphic. Selecting 
Close from the Control menu is equivalent to pressing the OK button. The 
Edit Dictionary button, which produces a sub-dialog, is explained in detail 
in the following section. This button can be selected with the hotkey 
combination ALT-E.

Please note that the Cancel button only discards changes made in the 
Rename Graphic dialog. If changes are made in the Edit Dictionary sub-
dialog, pressing the Cancel button in the Rename Graphic dialog will 
not undo those changes.

5.2.2   Editing Graphics Dictionaries

The Edit Graphics Dictionary sub-dialog is opened by selecting the Edit 
Dictionary button at the bottom-right corner of the Rename Graphic dialog 
(CTRL-KPD PLUS). The dictionary to be edited is selected with the combo box 
in the Rename Graphic dialog. The sub-dialog allows the user to view all of 
a dictionary's entries, as well as any graphics that have not yet been 
named. From within this sub-dialog, entries can be browsed and specific 
names can be searched for. From the Rename Graphic dialog, a shortcut to 
this sub-dialog is provided by the hotkey combination Alt-E.

This sub-dialog contains six significant controls. Two of these, the edit 
box and the Ignore Graphic check box, are similar to those found in the 
Rename Graphic dialog (Section 5.2.1). Along the bottom of the sub-dialog 
are four buttons labeled Previous, Next, Find, and Done. A line of text at 
the top of the dialog displays the current graphic name, as well as an image 
of the graphic itself.

As in the Rename Graphic dialog, the edit box where the new name is to be 
typed contains the graphic's current name. When the sub-dialog is first 
opened, the text in the edit box is highlighted, and can therefore be 
replaced by typing a new name. This is a normal edit box and standard 
editing keys, such as RIGHT-ARROW, LEFT-ARROW, BACKSPACE, and DELETE, can be 
used to edit its contents. A graphic name can be up to five-hundred and 
twelve characters, but extremely long names may not entirely show in the 
edit box. 

As explained in the previous section, the Ignore Graphic check box, located 
to the right of the edit box, is used to omit certain graphics when reading 
with outSPOKEN. To turn off a specific icon or symbol, select this box when 
viewing that graphic's dictionary entry. When this control is checked, 
outSPOKEN ignores the graphic, and neither navigates to it nor speaks it. 
From within the Edit Graphics Dictionary sub-dialog, this control can be 
toggled on and off with the hotkey combination ALT-I. The Ignore Graphic 
setting can be overridden by turning on the Verbose Graphics option in the 
outSPOKEN Graphics Preferences sub-dialog (Section 5.1.3).

The Previous and Next buttons display the previous and next dictionary 
entries, respectively. Which entry is "previous" and which is "next" is 
determined by outSPOKEN according to the bitmap of the graphic. The Previous 
and Next buttons can be used to browse through each entry in the current 
dictionary, as well as all entries of unnamed graphics. The Previous and 
Next buttons can be selected with the hotkey combinations ALT-P and ALT-N, 
respectively.

The Find button in the Edit Graphics Dictionary sub-dialog is used to locate 
specific dictionary entries, or unnamed graphics. When this button is 
pressed, an extremely simple sub-dialog is produced. Contained in this Find 
Graphic sub-dialog are an edit box, an OK button, and a Cancel button. From 
within the Edit Graphics Dictionary sub-dialog, a shortcut for selecting the 
Find Graphic sub-dialog is provided by the hotkey combination ALT-F.

When the Find Graphic sub-dialog opens, the name of the graphic to be 
searched for can be typed into the empty edit box. To start the search, 
press ENTER or select OK. Select Cancel to abort the search and return to 
the current dictionary entry. 

Find Graphic is only able to locate entries that exactly match the request. 
Capitalization does not matter, but spaces and punctuation must be typed 
correctly. If Find Graphic is unable to locate a request, it behaves as if 
Cancel had been pressed, closing the Find Graphic sub-dialog and returning 
to the current entry in the Edit Graphic Dictionary sub-dialog. If the 
requested entry is located, the Find Graphic sub-dialog is closed and the 
newly found entry is displayed in the Edit Graphics Dictionary sub-dialog.

When searching for unnamed pointers, icons, or symbols using the Find 
Graphic sub-dialog, be sure to include a space before the graphic's number. 
As explained in the introduction to this section, unnamed graphics are each 
assigned a unique number until named by the user. When outSPOKEN assigns a 
number to an unknown graphic, the name is of the form Icon-space-number. It 
is important to include the space because Find Graphic can only locate 
graphics that exactly match the name that is typed. Since all unnamed 
graphics are locatable from the Edit Graphic Dictionary sub-dialog, this is 
an alternative to using the Rename Graphic dialog. 

To rename a pointer, enter the Edit Graphics Dictionary sub-dialog and use 
Previous, Next, or Find to locate the desired pointer. This is the only way 
to rename a pointer, because the usual method of naming graphics (by placing 
the pointer on them and invoking the Rename Graphic dialog) will not work 
for a pointer. Unnamed pointers are numbered in the same way icons and 
symbols are, but are called cursors (e.g., "cursor 1"). 

There are two ways to exit from the Edit Graphics Dictionary sub-dialog. 
Pressing the Done button closes the sub-dialog and returns to the Rename 
Graphic dialog. When this button is pressed, all dictionary modifications 
are immediately saved to disk. Selecting the Close option from the Control 
menu discards any changes made to the current entry and closes the dialog. 
This saves all entries except the current one to the dictionary, and returns 
to the Rename Graphic dialog. Effectively, this provides a method of exiting 
the dialog without saving changes to the current dictionary entry. However, 
when the dialog is closed in this way, changes that were made to any 
graphics besides the current one will be saved.

Please note that pressing Cancel from the Rename Graphic dialog does 
NOT undo any changes made in the Edit Graphics Dictionary sub-dialog.

5.2.3   More About Graphics Dictionaries

Graphics dictionaries are files which contain information about a graphic's 
name, bitmap, and Ignore Graphic status. Each such set of information about 
an individual graphic is called an "entry," and a dictionary can contain any 
number of entries. Each dictionary has the file extension ".DIC", and is 
located in the outSPOKEN directory (usually C:\OSW). Unless otherwise 
specified, all new graphic names are stored in the default dictionary, 
"DEFAULT.DIC". If you are a beginner, there is no need to be overly 
concerned about how graphics dictionaries operate. It is enough to know that 
these files contain the images and names of the graphics you define in the 
Rename Graphic dialog. Advanced users may wish to read the following two 
sub-sections for more information about graphics dictionaries. 

5.2.3.1   Managing Dictionaries

When outSPOKEN is launched, it searches the outSPOKEN directory for 
dictionary files and loads them into memory. This means that adding or 
removing a dictionary is as simple as moving a dictionary file into, or out 
of, the outSPOKEN directory. Graphics dictionaries are saved to disk at 
several times: when exiting outSPOKEN, when leaving the Rename Graphic 
dialog or the Edit Graphics Dictionary dialog, and when exiting Windows. A 
graphics dictionary can be prevented from loading by deleting it or by 
changing the file extension to something other than ".DIC". This can be done 
from File Manager or from DOS. Dictionaries can be added simply by copying a 
dictionary file into the outSPOKEN directory. If a dictionary is added to or 
deleted from the outSPOKEN directory while the program is running, outSPOKEN 
must be restarted before the change takes effect. 

outSPOKEN must have at least one graphics dictionary to work with. When it 
launches, outSPOKEN looks for a dictionary called "DEFAULT.DIC". If this 
file is not found, outSPOKEN creates an empty file with that name. This 
guarantees that when the user wishes to name a graphic, there is a 
dictionary in which to save it. This file is also offered as the default 
dictionary when naming a graphic which has not yet been saved.

The best way to create a new graphics dictionary is to remove or rename the 
current default dictionary and restart outSPOKEN. outSPOKEN automatically 
creates a new default dictionary. A group of new graphics, such as from a 
new application, can then be defined and stored in it. Once these new 
graphics have been saved in the default dictionary, the dictionary can be 
renamed (in File Manager or DOS) to some other dictionary name. The next 
time outSPOKEN is launched, an empty default dictionary will again be 
created. Following this procedure, groups of related icons and symbols from 
specific applications can be kept in individual graphics dictionaries and 
shared with other outSPOKEN users. For example, we provide a dictionary 
called "WORD.DIC", which is a file containing all of the graphics found in 
Microsoft Word. Although we provide graphics dictionaries for some 
applications, it would be impossible to support all of them. For this 
reason, we encourage the sharing of dictionaries via electronic bulletin 
boards, anonymous FTP, and any other means available.

5.2.3.2   Dictionary Restrictions

A graphic can be stored in only one dictionary at a time, and a particular 
image can have only one name. When loading dictionaries, if outSPOKEN comes 
across a graphic that has been defined in an earlier dictionary (i.e., a 
dictionary loaded earlier in the startup process), the definition in the 
later dictionary replaces the older entry. The next time outSPOKEN makes a 
change to the dictionaries on disk, it deletes the entry from the earlier 
dictionary. This ensures that only one definition exists for any given 
graphic.

For this reason one should be careful when adding new dictionaries to the 
outSPOKEN directory. If a new dictionary is added which has definitions for 
graphics that are defined in previously existing dictionaries, any graphic 
names defined in dictionaries which load earlier than the new dictionary 
will be replaced by the new definitions. If you then quit outSPOKEN, the 
previously defined names will be permanently removed from the original 
dictionaries. This makes it a good idea to make regular backups of all 
important graphics dictionaries. 

Graphics dictionaries are loaded by outSPOKEN in their order of appearance 
in a DOS directory list. From DOS, typing the command "DIR C:\OSW\*.DIC" 
will display the dictionary file names in their loading order. If you have 
installed outSPOKEN to a directory other than "C:\OSW", substitute the 
proper drive letter and path name in the command line above.

Although a graphic can have only one name, there can be any number of 
different graphics possessing the same name. This means that several 
different graphics (even graphics which look completely different) can have 
the same label. For example, suppose there were two icons, one of a dog and 
one of a cat. If the user labeled both icons "Dog," outSPOKEN would have no 
objection, even though one of the icons is, in fact, a cat.

It is important to note that when outSPOKEN assigns a name to a graphic, it 
is doing so for a specific bit depth (number of colors). When the bit depth 
is changed, a previously named graphic appears to outSPOKEN as a new image. 
outSPOKEN has not forgotten the previous label, it simply needs a label for 
the new bitmap. Because outSPOKEN allows multiple graphics to share the same 
name, renaming the bitmap in the new bit depth solves the problem. When you 
return to the previous bit depth, the previously assigned name returns. It 
is often a good idea to maintain different dictionaries for different bit 
depths. This allows the flexibility of removing unused high bit depth 
dictionaries to make more memory available and to speed up outSPOKEN's 
startup process.

