The Virtual Viewer

In previous versions of JAWS, the virtual viewer was only used in applications such as Internet Explorer and Microsoft Outlook Express. When you pressed JAWSKEY + H to review the list of JAWS hot keys for a given application, the keystrokes were spoken and you had no way of reviewing the list without pressing JAWSKEY + H a second time. This functionality, at times, made it difficult to get the desired hot key for the application.

JAWS now displays all help messages such as those created for the hot key help script performed by pressing JAWSKEY + H, the JAWSKEY + W, and JAWSKEY + F1 in the virtual viewer. When JAWS displays the information in the virtual viewer, the virtual cursor is active. You can use the normal navigation keystrokes to read, select, and copy the selected text to your favorite text editor.

You can use this same functionality in your scripts to display help information. From a script development standpoint, the virtual viewer is a Virtual Buffer created using the JAWS Scripting Language as the interface. The virtual viewer is also known as the user buffer.

The JAWS message format gives you greater flexibility when displaying text in the virtual viewer. You can format the text using spaces, carriage returns, tab stops, etc. After formatting your message, JAWS displays the text in the virtual viewer with the same look and feel as text found in a text editor or word processor. By default, JAWS displays all text in the virtual viewer in black on a white background (except for links). The text also has a font type of Arial, and a point size of 12.

Displaying Text in the Virtual Viewer

Before you display text in the virtual viewer, you should check the status of the virtual viewer to make sure it is not currently being displayed. You can use the built-in function, UserBufferIsActive, to check the status of the virtual viewer. The function returns a value of 1 when the virtual viewer is active or displayed and a value of 0 when the viewer is not being displayed. When the virtual viewer is active, you can use the built-in function, UserBufferDeactivate, to close the virtual viewer prior to redisplaying text. Deactivating the virtual viewer before JAWS displays new information prevents the user buffer text from running together.

The following code example illustrates the use of the UserBufferIsActive() and UserBufferDeactivate() functions. You should place these statements before the virtual viewer is activated by either the SayMessage or SayFormattedMessage functions.

If UserBufferIsActive () Then
    UserBufferDeactivate () ; closes the virtual viewer
EndIf

You can use either the SayMessage and SayFormattedMessage functions to display information in the virtual viewer. You pass the output type of OT_User_Buffer as the first parameter in either function to tell JAWS to display the message in the virtual viewer. Each function also accepts two additional parameters. The second parameter is the long message. This is the text of your message and can be in the form of a message contained in a message file, a string of text or a string variable containing the message. The third parameter contains the short message. Like the long message, the short message can be a message contained in a message file, a string of text or a string variable containing the message. If you are displaying information in the virtual viewer, JAWS ignores this parameter. Therefore, it is not necessary to pass any information in this parameter.

You can call either function using the following syntax:

SayMessage (OT_USER_BUFFER, "This text is being displayed in the virtual viewer")
; OR
SayFormattedMessage (OT_USER_BUFFER, "This text is being displayed in the virtual viewer.")

Displaying Keystrokes as Links

You can also create keystroke links in the virtual viewer by using the %KeyFor function. The %KeyFor function replaces the older use of the GetScriptKeyName function. Using the older method of speaking or displaying messages, you had to concatenate the string using the GetScriptKeyName function. Using the new message format, you can insert the script name directly into your message by adding the following line:

The percent sign preceding the function name acts as a placeholder for the keystroke. When the message is displayed in the virtual viewer, the function retrieves the keystroke for the script named in the functions parameter. The keystroke is displayed as a link that can be activated by pressing ENTER on the line containing the keystroke.

The following script and message file additions illustrate the use of the JAWS message format to display text in the virtual viewer:

::: {#test.jsm-1}

Test.jsm

:::

Const ; Strings For edit prompt:
    sDlgName = "Enter Name",
    sFirstPrompt = "First Name: ",
    sLastPrompt = "Last Name: "

Messages
; For msgHello, %1= the first name, %2 = The Last Name
@MsgHello
HELLO WORLD! My name is %1 %2.
Press, %KeyFor(HelloWorld), To redisplay this message.
Press ESCAPE To close this message.
@@
EndMessages

::: {#test.jss-1}

Test.jss

:::

Include "HjConst.jsh"; default constant definitions
Include "HjGlobal.jsh"; default global variable definitions
Include "common.jsm"; default virtual viewer constants and Messages
Include "test.jsm"; test message file

Script HelloWorld ()
Var
    String sFirstName,
    String sLastName,
    String sMessage
If UserBufferIsActive () Then; determine If user buffer is active
    UserBufferDeactivate (); close or deactivate the virtual buffer
EndIf
InputBox (sFirstPrompt, sDlgName, sFirstName) ; prompt For the first name
InputBox (sLastPrompt, sDlgName, sLastName) ; prompt For the last ;name
Let sMessage = FormatString (MsgHello, sFirstName, sLastName)
; replace the % place holders with data
SayFormattedMessage (OT_USER_BUFFER, sMessage) ; display the message in the user buffer
EndScript

In the above example, the script begins by checking the status of the virtual viewer. If the viewer is active, then JAWS deactivates it before the script continues processing. The two InputBox statements retrieve the first and last names from user input. The FormatString function then takes the first and last name information and combines it with the message to create a final version of the message. The message is then displayed in the virtual viewer using the SayFormattedMessage function.

If you create the script above, assign it to CONTROL + 1 and you enter "John" for the first name and "Doe" for the last name, JAWS displays the following text in the virtual viewer:

::: leftbar "HELLO WORLD! My name is John Doe. Press, CONTROL + 1, to redisplay this message. Press ESCAPE to close this message." :::

Using the Virtual Viewer Exercises

The following exercises give you practice creating and using messages in the virtual viewer. Before you start these exercises, make sure you have the Notepad.jss script file open within the Script Manager. This file should contain any practice scripts from earlier chapters of this manual. If you run Script Manager from within Notepad and a blank file is opened, type the following lines at the top of the file:

; Script file For Notepad
; JAWS version 12.0
Include "hjconst.jsh"
Include "common.jsm"

Script DisplayVirtualViewer ()
If UserBufferIsActive () Then
    UserBufferDeactivate ()
EndIf
SayFormattedMessage (OT_USER_BUFFER, MsgVirtualViewer)
EndScript