JAWS and Braille

When you use a Braille display in structured mode, you can control the order and type of information shown on the display. There are several parts of JAWS that work together to place the desired information on the display. These areas include:

• JAWS user interface

• Configuration Manager

• JAWS Braille structured file

• Default Braille functions

The JAWS user interface and Configuration Manager are used to customize the information shown on your display. The Braille structured file contains settings used by JAWS to determine the type and order of information shown on the display. The default Braille functions are called internally from within JAWS to place the desired information on your display.

JAWS User Interface and Configuration Manager

You can access the Braille Options section of Configuration Manager in one of two ways. To reach the Braille Options section through the JAWS user interface, do the following:

• Press JAWSKEY + J to activate the JAWS user interface.

• Press ALT + O to open the Options menu.

• Press L to open the Braille Basic settings dialog.

• Press ALT + A to activate the Advanced... button.

• You are placed in the Braille Options section of the default configuration file, Default.jcf, within Configuration manager.

To reach the Braille Options section through the Configuration Manager, do the following:

• Press JAWSKEY + F2 to display the JAWS managers list.

• Press ENTER on Configuration Manager. This is the first item in the list so you will need to type C to reach the item.

• Press ALT + S to open the Set Options menu.

• Press B to open the Braille Options dialog.

This list box contains all the control types JAWS shows on the Braille display. The list box has 2 columns. The first column contains the actual control name such as button or checkbox. The second column contains the symbol for the control that is shown on the Braille display. For example, a button has an entry in the list box of: button btn

::: {#modify-control-button}

Modify Control... Button

:::

The modify control button, when activated, lets you change the type and order of information shown on the Braille display. When this button is activated, the define properties dialog for the highlighted item in the control types list is displayed. The focus is placed in the Show on Display Combo box. This combo box lists all the components that are shown on the Braille display for the selected control. You can think of a component as a piece of information shown on your Braille display about the highlighted control. Examples of components are name, type, state, and value.

You can use the Remove button to remove the highlighted component from the list, or use one of the movement buttons to change the order of components shown on the display. For example, when the control type of button is highlighted, the Show On Display combo box lists name, type, and state in this order.

When you remove a component from the list, the component is shown in the Available Items to Add list box. Once you have removed a component, the add button is available. If you decide at a later date that you want that component shown on the display, the Add button is used to place the removed component back into the Show On Display combo box.

::: {#modify-braille-symbol-button}

Modify Braille Symbol... Button

:::

When you activate this button, the Control Properties dialog box is displayed. The focus is placed in an edit box containing the current symbol for the highlighted component in the control types list. This is the symbol that is shown on the Braille display and represents the component. You can change the characters used to represent the component by typing a new value. For example, when the control type of button is highlighted, the Braille symbol shown in this dialog is btn. You can change the symbol from btn to bt or another value of your choice.

State Properties Page

When this page of the Control Type Options dialog is active, the focus is placed in a list box containing the various states used to show control states on your Braille display. Examples of entries found in this list box are:

• Unchecked < >

• PartiallyChecked <->

• checked <X>

The above examples are all used on a Braille display to represent the checked, partially checked, and unchecked states of a check box. You can modify the characters used to represent the states of various controls by pressing TAB to the Modify Braille Representation button, or, by pressing F2.

Section 3: The JAWS Braille Structured File

When you modify structured mode, those changes are stored in a JAWS Braille structured or jbs file. The jbs file is an ini style file consisting of a variety of sections and keys. You can modify structured mode so that the changes take effect across the entire operating system or in a specific application. When you make changes globally, those changes are stored in the default JAWS Braille structured file, default.jbs. If the changes you have made to structured mode are application specific, then those changes are stored in the jbs file for the active application.

Some of the sections found in the default jbs file, default.jbs, include control type, component aliases, state aliases, and control states. Each of these sections is used internally by JAWS to determine what is shown on a Braille display.

Component Aliases Section

This section defines component aliases used internally by JAWS to display information on your Braille display. It is also used to display component information in the Braille Options Control Options Control Properties dialog in Configuration Manager. Component aliases make the connection to the components contained in the jbs file and the information shown in the Control Options Control Properties dialog.

A component alias consists of an ini style key and it's corresponding value. The key is used within the jbs file to determine what is shown on a Braille display and in what order. The key value is more descriptive and used within the Control Options Control Properties dialog. An example of a component alias follows:

dlgTEXT=Dialog Text

In the above example the key, dlgTEXT, is used within the jbs file. This key value tells JAWS to display dialog text on your Braille display. The key value, dialog text, is what you see in the Control Options Control Properties dialog.

State Aliases and Control States Sections

The state aliases section is used to determine what is shown in the Control Options State Properties dialog for control states. Some of the controls that can have various states are buttons, checkboxes, and tree views.

Each item listed in this section consists of an ini style key and it's corresponding value. The key is used internally by JAWS to indicate the state of a control such as a checkbox or a button. The corresponding key value is used within the Control Options State Properties dialog as an English representation of the state. An example of a state alias follows:

csChecked=Checked

In the above example the key, csChecked, is used internally by JAWS to show a checked state for a checkbox. The key value, checked, is listed in the Control Options State Properties dialog.

The control state section of the default jbs file consists of key and key values that determine what characters are shown on a Braille display for a given control state. The key is used by JAWS to display the control state on your display. The corresponding key value is the actual characters that are used to show the state on the display. An example of a control state is: csChecked=<X>

In the above example the key, csChecked, is used internally by JAWS to show a checked state for a checkbox on a Braille display. The key value, <X>, are the characters actually displayed on the display when a checkbox has a checked state.

Both of these sections work together to create a link between the information shown in the Control Options State Properties dialog and the characters shown on a display for a given control state. It is the key values in both examples that are displayed in the Control Options State Properties dialog. The key value is the link between both sections. The entry in the user interface for a checked control state is: Checked <X>

The key value, csChecked, makes the link between the state alias of "Checked" and the control state of "<X>". When you make a change to the state shown on your display for a checkbox that is checked, it is the Control State entry that is modified. For example, you decide to change the checked state representation of <X> to <Y> for a checkbox. After you make the change in the Control Options State Properties dialog, the control state key value is modified in the jbs file and looks like: csChecked=<Y>

Control Type Section

Each standard windows control has a section located in the default jbs file. This section tells JAWS what components to show on the Braille display, what order they are to be shown, and the Braille symbol to be used for the control. The control type section uses the subtype code of each window JAWS recognizes as part of the section name. In the default jbs file, you will find sections for control types such as button, combo box, list box, and so on.

Each control type section contains 4 keys with their respective values. The names of these keys are:

• components

• type

• removed

• displayname

An example of a control type section follows:

; Section For checkbox
{[}SubtypeCode20{]}
components=name,state,type
type=chk
removed=
displayname=

::: {#components-key}

Components Key

:::

The components key and its respective value tell JAWS what to show on your display and in what order. The key value consists of components found in the components aliases section discussed earlier. When you modify the order or components shown on your display from the Control Options dialog found in the Braille Options section of Configuration Manager, the changes are saved in this key for the control you are modifying.

Using the control type section for a checkbox from above, the components key has a value of name, type, value. The key value tells JAWS to display the name of the checkbox first, the type of control second, and the state of the checkbox third.

::: {#type-key}

Type Key

:::

The type key contains the characters used by JAWS to display the type of control on your display. The type key is used within the components key to display the control type. From the control type section for a checkbox from above, the characters shown on your display for a checkbox are chk.

When you make changes to the Braille symbol used to show the control type on your display, the change is stored in this key. For example, you decide that you want to change the chk used to show the checkbox control type. If you change the symbol to ck, the type key entry for a checkbox would look like: type=ck

::: {#removed-key}

Removed Key

:::

The removed key and its corresponding value list any components that have been removed from within the user interface. For example, if you decide to remove the state component from the components key for a checkbox then the removed key looks like: removed=state

After the modification, the components key looks like: components=name,type

::: {#display-name-key}

Display Name Key

:::

The displayname key and its corresponding value contain the display name of the control in the JAWS user interface. This line is normally used for custom controls which do not have a SubTypeCode associated with them.

Section 4: Adding Custom Components

When the default Braille support within JAWS does not show the correct information on a Braille display, it may be necessary to modify the components shown. For example, you may be working with an application that does not show the dialog box name on the Braille display. In this instance, it may be difficult to easily identify what dialog box is active based solely on the information shown on the Braille display.

You can find a good example of default functionality not displaying all relevant control information in the Microsoft Outlook 2003 email application. When you choose to display the Navigation Pane by pressing ALT + F1, the application displays a tree view containing all of your e-mail folders on your system. The application also displays the total of unread messages for each folder to the right of the folder name. By default, JAWS does not show this extra information on your Braille display. Thus, the following information is shown for the Inbox folder:

::: {#tv-inbox}

Tv Inbox

:::

This information tells you that the active control is a tree view, and the folder name is Inbox. However, the total number of unread messages is not shown. If you were only using Braille without speech, then you would not have this additional piece of information available to you.

In order to provide the equivalent information in both speech and Braille, the script developers at Freedom Scientific had to alter the way in which information is shown on your Braille display for tree views. In addition to the default information, the script developers added the additional unread message information through additions to the Braille structured file for Microsoft Outlook 2003, Microsoft Outlook 2003.jbs. IN addition to these changes, additional functionality was added to the Microsoft Outlook 2003 script file to allow JAWS to correctly show this information on your display.

By making these changes, complete information about the active tree view item is shown. Now in addition to the name, type, level and other information relating to a tree view item, the number of unread messages is also shown. So, now the following is shown on your Braille display for a tree view item that has unread messages:

::: leftbar Tv 8 unread Inbox :::

Adding extra information on a Braille display involves two procedures:

• Modifying the application specific .jbs file

• Creating an application version of a Braille function

After these two procedures are completed, complete information is shown on the Braille display.

Modifying the Application Specific .JBS File

The first step to adding information to a Braille display involves creating a component alias in the application specific .jbs file. The component alias is then used in the section of the control for which the extra information is to be displayed.

Using the Outlook 2003 example from above, the component aliases and dialog control sections of the Microsoft Outlook 2003.jbs file look like the following:

{[}Component Aliases{]}
UnreadMessageCount=Number of Unread Messages
; Section For treeview.
{[}SubtypeCode31{]}
components=ContextHelp, name, type, level, value, state, position, UnreadMessageCount
type=tv
removed=
displayname=

The string of text to the left of the = sign in the line, "UnreadMessageCount=Number of Unread Messages," is used in the "components=" line of the tree view control section, [SubTypeCode41], to list the additional component information on the Braille display. The string of text to the right of the = sign is displayed in the Control Type Properties Define Control dialog.

Creating an Application Specific Version of a Braille Function

In order to show the custom component on the Braille display, you should create an application specific version of one of the BrailleAddObject... functions. The function to be created depends on the component you wish to show on the Braille display. Using the Microsoft Outlook 2003 example from above, an application specific version of any the BrailleAddObject... function should be created in the Microsoft Outlook 2003.jss file. For our purposes here, we will use the default version of the BrailleAddObjectName function. The code of the function follows:

Int Function BrailleAddObjectName(Int nSubtypeCode)
Return False
EndFunction

The code of an application specific version of the BrailleAddObject... function follows:

Void Function BrailleAddObjectUnreadMessageCount (Int nSubTypeCode)
Var
    Int nAttribBits
Let nAttribBits = GetCharacterAttributes()
If GetCurrentControlID() ==ciFolderTreeView Then
    If !StringIsBlank (gsUnRedMsgs) Then
        BrailleAddString (gsUnRedMsgs,0,0,nAttribBits)
        Return True
    EndIf
EndIf
Return False
EndFunction

Both functions require the subtype code to be passed as a single parameter and return an integer value. It is important to note the difference between the default and application specific versions of this function. The default function name ends with the word "Name", while the application specific version of the function has the string, "UnreadMessageCount ", before the "BrailleAddObject" contained within the function name. The "UnreadMessageCount " portion of the function name tells JAWS to add the component, UnreadMessageCount to the Braille display.