Output Types

Correct Use of Output Modes

Prior to JAWS 6.0¹, Output Modes (or Output types) were used as a means of controlling information spoken at each verbosity level. With the introduction of Braille Flash Messages in JAWS 6.0, Output Modes are also now used to control which messages are sent as Flash messages to the display. It is thus vital to ensure that correct use of Output Modes is made during scripting to avoid unnecessary Flash messages appearing in Braille. This document outlines the use of Output Modes.

It is very important that correct Output Modes be used not only because of Flash Messages but because JAWS uses the Output Mode in conjunction with all of the JCF options and the Speech and Sounds Scheme in use to determine how text should be spoken. For example, if OT_SPELL is used, JAWS will spell rather than speak the text using the voice alias defined for spelling. Similarly, text spoken using OT_KEYBOARD will honour the current Typing Echo settings. Not all Output Modes are relevant for Braille. Generally, text which is rendered on the display by means of Line or Structured modes does not need to be sent as a Flash Message. For this reason, many of the Output Modes are disabled for Braille altogether. The relevant Output Modes which are configurable for Braille are listed at the end of this document.

::: {#ot_no_disable}

OT_NO_DISABLE

:::

This output Mode should be used very sparingly as messages spoken using it cannot be suppressed and will generate Flash messages.

::: {#ot_help}

OT_HELP

:::

This Output Mode Should be used to speak all Screen Sensitive, Hotkey, Keyboard or other help messages when these messages are not being displayed in the virtual viewer.

::: {#ot_app_start}

OT_APP_START

:::

This Output Mode should only be used to speak messages generated when an application first starts (and only once per JAWS session).

::: {#ot_jaws_message}

OT_JAWS_MESSAGE

:::

This Output Mode should be used to speak messages originating from JAWS, for example when the information is originating from JAWS rather than the application. For example, JAWS for Windows is Ready, JAWS is running in demo mode, or when the user presses a keystroke assigned to a JAWS function, to announce the function name.

::: {#ot_screen_message}

OT_SCREEN_MESSAGE

:::

This Output Mode should be used to speak screen text from application instructions or help messages not considered dialog text. It would typically be spoken via the SayNonHighlightedTextEvent. For example, if a window contains added information about how to interact with the application, but is not essential for interaction with the application. It could be considered supplemental information which the user would perhaps want to hear once but not each time they ran the program. Note that this Output Mode should only be used when the window is automatically spoken. If the user specifically requests the help text via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

OT_CONTROL_GROUP_NAME

This Output Mode should be used to speak the name of a group box surrounding a set of controls. For example, the title of a group of checkboxes. Note that this Output Mode should only be used when the group or a control within the group gains focus or is automatically spoken. If the user specifically requests the control group's title via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_control_name}

OT_CONTROL_NAME

:::

This Output Mode should be used to speak the prompt of a control. For example, the text to the right of an edit or the label of a button. It should not be used to speak type information nor should it be used to speak the control's contents such as the text in an edit. Note that this Output Mode should only be used when the control gains focus or is automatically spoken. If the user specifically requests the control's prompt via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_control_type}

OT_CONTROL_TYPE

:::

This Output Mode should be used to speak type information about the focused control. For example, if scripts are written to support a custom control, the description of the control should be spoken with this Mode. An example might be a new Grid control. The word Grid would be spoken using this Output Mode. Note that this Output Mode should only be used when the control is automatically spoken. If the user specifically requests the control's type via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_dialog_name}

OT_DIALOG_NAME

:::

This Output Mode should only be used to speak the title of a dialog (when a dialog is invoked by the user or application). It should not be used when the user specifically asks for the dialog's title.

::: {#ot_dialog_text}

OT_DIALOG_TEXT

:::

This Output Mode should be used to speak descriptive dialog text essential for correct use of the dialog controls. dialog text is text not part of a control's prompt within the bounds of the current dialog. Note that this Output Mode should only be used when the dialog is automatically spoken. If the user specifically requests the dialog text via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_document_name}

OT_DOCUMENT_NAME

:::

This Output Mode should be used to speak a document's title when a document window gains focus. If the user specifically requests the document title via a keystroke, the OT_USER_REQUESTED_INFORMATION Output Mode should be used instead.

::: {#ot_item_state}

OT_ITEM_STATE

:::

This Output Mode should be used to speak the state of a control, for example, checked or not checked. It should only be used when the state is toggled or changed, not when the state is specifically requested by the user via a keystroke.

::: {#ot_position}

OT_POSITION

OT_POSITION :::

This Output Mode should be used to speak the position of an item relative to others in its container. For example, the current item in a list, the current node in a tree. It should only be used when the position information is spoken automatically, not when it is specifically requested by the user via a keystroke.

::: {#ot_error}

OT_ERROR

:::

This Output Mode should be used to speak error messages generated as a result of the user performing an inappropriate action. For example, trying to invoke the ListOfLinks in a context where no links maybe listed. It is for JAWS user errors, not application errors.

::: {#ot_tool_tip}

OT_TOOL_TIP

:::

This Output Mode should be used to speak tooltips generated by the operating system or application. A tooltip is a small bubble which appears as a result of moving the mouse pointer over a graphical object.

::: {#ot_help_balloon}

OT_HELP_BALLOON

:::

This Output Mode is used to speak Help Balloons generated by the Aplication or operating system. a Help Balloon differs from a tooltip in that it is generated as a result of user action or when the application or operating system wants to inform the user without the use of a dialog.

::: {#ot_status}

OT_STATUS

:::

This Output Mode is used to speak status messages, for example, when the user presses a keystroke which toggles a JAWS setting on or off. The state of the setting is spoken using this output mode whereas the setting's name itself should be spoken using OT_JAWS_MESSAGE.

::: {#ot_smart_help}

OT_SMART_HELP

:::

This Output Mode should be used for supplemental help given by JAWS for efficient use of an application (text which is not on screen). This does not include Screen Sensitive, Keyboard or Hotkey help, these should be spoken using OT_HELP.

::: {#ot_select}

OT_SELECT

:::

This Output Mode should be used to speak the message preceding or following the act of selecting text in an editor.

::: {#ot_tutor}

OT_TUTOR

:::

This Output Mode should be used to speak tutor information when a control gains focus, for example, "Press Enter to activate" or "Type in text".

::: {#ot_access_key}

OT_ACCESS_KEY

:::

This Output Mode should be used to speak the Access Key (underlined character) in a menu or control's prompt. An access key represents the key to press as a short cut to invoking the action described by the prompt of the control. For example, in an Edit Menu, the E maybe underlined which means that the user needs to press E to select that item directly without having to arrow to that item and press Enter.

::: {#ot_user_requested_information}

OT_USER_REQUESTED_INFORMATION

:::

This Output Mode should be used whenever a user requests information to be spoken via a keystroke. For example, if the user presses JAWSKEY + F12 to hear the time, JAWSKEY + T for the window title, etc.

Special Uses

The following Output Modes have special uses:

::: {#ot_blank_line_count}

OT_BLANK_LINE_COUNT

:::

Use this when a script is controlling SayAll to speak the number of blank lines.

::: {#ot_user_buffer}

OT_USER_BUFFER

:::

Use this to redirect the text to the virtual viewer rather than speaking it directly.

::: {#ot_phonetic_char}

OT_PHONETIC_CHAR

OT_PHONETIC_CHAR :::

Use this to cause the string to be expanded to its phonetic rendering. For example, say("a", OT_PHONETIC_CHAR) would say "alpha". If the string contains more than one character, the string will be spelled phonetically.

::: {#ot_braille_message}

OT_BRAILLE_MESSAGE

:::

This Output Mode should be used for messages specifically for Braille which won't ever be spoken. This could be used for displaying a dot pattern which represents some graphical layout information which has no speech equivalent.

::: {#ot_highlighted_screen_text-and-ot_nonhighlighted_screen_text}

OT_HIGHLIGHTED_SCREEN_TEXT and OT_NONHIGHLIGHTED_SCREEN_TEXT

:::

These two Output Modes should be used to speak text from the SayHighlightedText and SayNonHighlightedText functions.

::: {#ot_keyboard}

OT_KEYBOARD

:::

This Output Mode should be used to speak key labels as keys are pressed on either the main keyboard or Braille keyboard.

::: {#ot_spell}

OT_SPELL

:::

When text is spoken using this Output Mode, it is spelled rather than spoken. If a voice alias has been chosen for spelled text, this voice alias will be used as the text is spelled.

::: {#ot_sayall}

OT_SAYALL

:::

This Output Mode should be used when scripts are used to control a SayAll during the speaking of the units of text.

::: {#internal-output-modes}

Internal Output Modes

:::

The following Output Modes are used internally by JAWS and should only be used when the intent is to override default JAWS behaviour in an equivalent situation. For example, the SayWord function is overridden, the text spoken by that function should use OT_WORD. etc. Another example might be a function which automatically speaks a graphic when it appears on the screen, OT_GRAPHIC should be used:

• OT_STRING

• OT_GRAPHIC

• OT_CHAR

• OT_WORD

• OT_FIELD

• OT_CHUNK

• OT_LINE

• OT_TEXT

• OT_FONT

• OT_CURSOR.

::: {#braille-specific-output-modes}

Braille Specific Output Modes

:::

The Output Modes which are relevant to Braille are as follows:

• OT_NO_DISABLE

• OT_HELP

• OT_APP_START

• OT_JAWS_MESSAGE

• OT_ERROR

• OT_TOOL_TIP

• OT_STATUS

• OT_SMART_HELP

• OT_TUTOR

• OT_HELP_BALLOON

• OT_BRAILLE_MESSAGE.

The only one of this list which is not configurable is OT_NO_DISABLE.

The JAWS Message Format

The JAWS message format allows you to create messages just as if you were typing the text of the message in a text editor or word processor. You no longer have to use string concatenation to produce speech output. The message format also gives you the ability to dynamically add information to your messages through the use of embedded place holders.

Using the message format, someone who is not a programmer can also edit the text of existing messages. You can type any character within the body of your message. JAWS can then speak the text or display the text of your message in the virtual viewer with a single function call to either the SayMessage or SayFormattedMessage function.

Although you can declare messages using the message format within a script source file (.jss), it is best to declare those messages within a script message file (.jsm). You then include the message file within your script file using the "Include" statement discussed earlier.

Message Format

The JAWS message format consists of several key words:

• Messages

• @MsgName

• @@

• EndMessages

::: {#messages-keyword}

Messages

:::

The Messages keyword indicates the beginning of the message block. It tells the compiler that everything between this line and the EndMessages line is written in the message format. You can place as many messages as you wish within a message block. You should only place this keyword once at the top of your message file following any comments. You do not need to include the Messages keyword for every individual message you create.

::: {#msgname}

@MsgName

:::

The @MsgName statement indicates the beginning of an individual message. The at symbol ("@") indicates the beginning of an individual message. The "MsgName" portion of this statement is the actual name of the message that you designate. You should follow the same rules for naming messages as you do variables, scripts and user-defined functions. You should use no spaces, capitalize the first letter of each word and no punctuation except for the underline character ("_"). You will use the string of text less the at symbol ("@"), to refer to this message in your scripts and functions that speak the message.

All text following the "@MsgName" statement is part of the message body. All characters typed in the message body are literal, meaning that all characters are part of the individual message. You no longer need to use the backslash ("") character in front of any special characters that previously required it for translation. When you want a new line in your message, you can insert it by pressing ENTER.

You can also use placeholders within the body of your message. These placeholders give you the ability to place information gathered during script or function execution into your message. You can use up to nine placeholders within the body of the message. To add a placeholder in the message, you precede the number of the placeholder with the percent sign ("%").

In addition to placeholders, you can use the KeyFor function to display keystrokes within the body of your message. This functionality is available only when displaying messages within the virtual viewer. When the KeyFor function is used, the keystroke is shown in the virtual viewer as a link. The keystroke can be activated by navigating to the link and pressing ENTER.

To add the KeyFor() function to the body of your message, you must precede the name of the function with the percent sign (%). This indicates the point in your message in which JAWS places the desired keystroke. The KeyFor function requires a single parameter: the name of the script for which the keystroke will be displayed. To add the KeyFor function to the body of any message, use the following syntax:

::: {#statement}

@@ Statement

:::

The "@@" statement indicates the end of an individual message. Each @MsgName must be followed by the @@ statement. There are no spaces between the 2 @ symbols.

::: {#endmessages}

EndMessages

:::

The EndMessages key word indicates the end of the Messages block. Each Messages statement must have a corresponding EndMessages statement. You only need to include this key word once in your message file and usually at the bottom of the file.

::: {#example-message-formats}

Example Message Formats

:::

Messages
@MsgTest
This is a test message.
Note that the text is formatted as you would type it or see it in a dialog box.
@@
EndMessages

The above example contains only one individual message within the message block.

Messages
@MsgTest
This is a test message.
Note that the text is formatted, as you would type it or see it in a dialog box.
@@
@MsgTest2
This is a second message.
Note that multiple Messages can be contained within the message block.
@@
EndMessages

The above example contains two individual messages.

You can find many of these messages in the file Common.jsm. It is recommended you include this file in all your script files, as all messages and string constants contained in it begin with the letter "c" or "sc" to avoid conflicts with your existing definitions. The Default.jsm file is still included to support any legacy code that uses the old JAWS system. If you need to copy some of your own scripts into the default file, just include the default.jsm file if you are using constants from there.

The FormatString Function

The FormatString function gives you the ability to dynamically replace text within the individual message using placeholders. As stated earlier, the placeholder uses the percent sign (%) followed by a number. These placeholders can be placed throughout the individual message.

The FormatString function formats the string containing the message and replaces any placeholders with strings of text. the FormatString function then returns the formatted string to the calling script or function. The syntax of the FormatString function is as follows:

Let sMessage = FormatString (MsgName, sString1, sString2, sString3)

The MsgName variable is the individual message declared within the messages block. The parameters listed next are used to replace their respective placeholders within the message.

When you use the FormatString function and do not use all parameters, you must be sure to remove all commas following the last actual parameter used. For example, if you are using the FormatString function to add text to three place holders within a message called MsgText, the line inserted in your script by the Insert Function dialog looks like the following:

Let sMessage = FormatString (MsgText, sText1, sText2, sText3, , , , , , , )

If you use the arrow keys to review the line above, you will notice seven pairs of commas and spaces between the sText3 parameter and the right parenthesis. To ensure no errors are encountered at the time you try to compile the script containing this statement, you must remove the seven pairs of commas and spaces. Failure to do so will result in a "incorrect parameter format" error message when you try to compile the script or function containing the line above.

Let sMessage = FormatString (MsgText, sText1, sText2, sText3) ; removed extra commas and spaces

The following examples illustrate the use of the FormatString function within a basic "Hello World" script.

::: {#test.jsm}

Test.jsm

:::

; test file containing message statements
Messages
; For msgHello, %1= the first name, %2 = The Last Name
@msgHello
HELLO WORLD! My name is %1 %2.
@@
EndMessages

::: {#test.jss}

Test.jss

:::

; test file To demonstrate the Use of the message format and FormatString Function
Include "HjConst.jsh"; default constants
Include "common.jsm"; default message file
Include "test.jsm"; test message file created above

Script HelloWorld ()
Var
    String sMessage
Let sMessage = FormatString (msgHello, "John", "  "," Doe")
SayFormattedMessage (OT_MESSAGE, sMessage)
EndScript

The spoken output from the above script is:

::: leftbar "HELLO WORLD! My name is John Doe" :::

The SayFormattedMessage Function

In the previous example showing the use of the FormatString function, the SayFormattedMessage function is used to output the text to the synthesizer. The benefit of using the SayFormattedMessage function is that it does a final format of the message in order to account for the %KeyFor() placeholder. The SayFormattedMessage function also gives you the ability to use short and long messages. This added functionality lets you account for the message length option in the Verbosity Options section of the Configuration Manager. You can choose to use short or long messages depending on your verbosity setting and preference.

The SayFormattedMessage function is called using the following syntax:

SayFormattedMessage (OutputMode Constant, LongMessage, ShortMessage)

If you are not using both short and long messages, then you will only need the output mode and long message parameters.

Creating and Speaking Messages Exercises

The following exercises give you practice in creating messages. You will also use the FormatString and SayFormattedMessage built-in functions in these exercises.

Script SayMyName ()
SayFormattedMessage (OT_MESSAGE, MsgMyName, MsgMyName, "John", "Doe")
EndScript

Script SpeakMyName ()
Var
    sMessage,
    String sFirstName,
    String sLastName
InputBox ("Enter your first name:", "First Name Entry", sFirstName)
InputBox ("Enter your last name:", "Last Name Entry", sLastName)
Let sMessage = FormatString (MsgMyName, sFirstName, sLastName)
SayFormattedMessage (OT_MESSAGE, sMessage)
EndScript

::: .hint For more information on the InputBox function, open the builtin.jsd script documentation file within the Script Manager. :::