JLS Utilities scripts for JAWS For Windows

For Jaws Script Developers

Version 4.4

Written By: The Snowman

Introduction

Note: The installation section is at the end of this manual, in a level 1 heading. Installation

Or, to uninstall, see: UnInstall This is a set of powerful utilities which performs functions similar, but significantly superior to, the scripting mode utilities in jaws, intended for use by advanced script developers, who understand the hierarchical relationships in which windows and objects are arranged, and are comfortable withusing window handles, and peer, or parent/child relationships, to navigate from one window to the next. They allow you to explore even windows which are not presently visible, to rapidly traverse the windows hierarchy, learning all the key attributes of each window, and to determine the routing path to follow to get between two windows of interest, as well as many other very handy features, including the ability to set your utility window to a window containing your mouse cursor, set application focus to a window, and explore "chunks". You can even explore the windows hierarchy outside the application.

In this discussion, most key strokes use the alt+control+windows modifiers, all three held down at once. Since this is almost always the case, we have avoided repeating that fact at every hot key, just to make the document more readable. There are exceptions, and they will be noted. But, unless otherwise stated, assume all three held down at once. This is the default desktop configuration. If you change your assignments, please check the hot key help, normally alt+control+windows+h. You can use the modifiers on either end of the space bar, and jaws should be set up to not differentiate between left and right modifiers. However, it should be set up to differentiate between numPad and extended keys. these are done in the default configuration. Unless otherwise specified, all arrow keys are the NumPad keys.

Layered Keys

There is a layered keymap provided, which uses the alt+control+shift+leftBracket layer. You choose whether to use it at installation time, when you manually modify your default.jkm keymap file. There is also a partially completed laptop keymap.

However, this discussion assumes the non-layered desktop layout To a limited degree, even the desktop layout supports layered hot keys, assuming that your version of JAWS also supports layers. This allows you to press alt+control+windows+LeftBracket to enter the layer, and then to operate some of the jls keys without the need to hold down the alt+control+shift modifiers. When the layer is active, using the desktop layout, you can use the numPad arrow keys to move between windows, the numPad pageUp to set focus, or any of the numbers on the numbers row to quickly hear the value of a particular attribute. Any other key will exit the layer, and return to normal mode. However, it is not necessary to use the special layer at all if you don't want. Just be aware that using the layer has certain risks, until you become very familiary with it, since JAWS provides no notification that you have exited the layer, meaning that pressing keys not defined for the layer will close the layer, and cause those keys to be passed on to the application. If the layer closes, and you don't know it, then pressing keys that would work if the layer was active will not performed their layered function, and will also pass those keys on to the application, or any application scripts that might be attached to those keys.

General Description

The utility window is really a global handle which points to any window in the system. You use the NumPad enter key to initialize it to the window with focus, and the NumPad arrow keys to move it from one window to the next as you explore. Up arrow moves to the parent window. left and right arrows move to prior and next peer windows respectively, and the down arrow moves to the first child.

Note, other utility tool boxes use a paradigm which is rotated 90 degrees from this, where you use up and down arros to move between peers, and left/right arrows to go between parent and child windows, much like a standard windows treeview. If you prefer that arrangement, you can modify the jkm file accordingly, and the hot key help will track along.

This set of utilities is linked into your default scripts through the use of a "use" statement. Hot keys are added to your default key map to allow activation of the utility functions from any application.

Once you get the utilities installed, Press the alt+control+windows+h key, and explore the list of available hot keys with your unmodified up and down arrow keys. Then press escape to return to your application.

Version history

It's worth reading the history, to get a better idea of what is present in the currenet version, since this talks more about additions than corection.

Version 4.4>

  1. Adds better MSAA object support, allowing to move the mouse to the MSAA object, center or edges.
  2. Enhances the f12 summary to include MSAA object information.
  3. Enhanced window report on jls mods PageDown, which can now be double clicked for examination in the virtual viewer.
  4. Adds the direct access numbers row keys, instead of always having to use the numPad plus and minus keys to rotate through the list of what can be spoken.
  5. Click a numbers row key to hear a particular attribute, and double click to set it to the default.
  6. the numPad slash and star keys, for routing the utility handle and the mouse, which duplicated the insert+numPad plus and minus keys, were removed. Use alt+control+windows plus insert NumPad plus and minus
  7. to make room for the direct access numbers row keys, the conversion utilities for hexadecimal support now also require the shift key.
  8. Mouse exploration keys, alt+shift+arrows now enhanced, mostly consistent with HotSpotClicker. this adds setting a reference position, learning distance from mouse to reference, Setting and returning to a mouse bookmark. This bookmark is in addition to the traditional bookmark on jls mods m and n. Also adds the ability to search for a color change in either direction, by adding the windows key to the alt+shift+arrows.
  9. Improved the hotKey help

The jls keys.txt file, which contains the hot keys you need to add to default.jkm is now divided into to two files for better convenience, jls desktop keys.txt and jls laptop keys.txt.

Provided a desktop version of a layered key interface, in case you prefer layered keys, instead of dedicating all the alt+control+windows keys to jls_utilities. See file JLS Layered Desktop Keys.txt However, even the straight desktop file contains some layered keys. Uses the alt+shift+windows+leftBracket layer, for the arrow keys, and for the numbers row direct access keys.

Version4.3

Adds Stack Analyzer, and new s cript manager scripts.

in version 4.1

This version adds MSAA object navigation mode. To enter or exit this mode, press shift+alt+control+window+o. Read about it here: MSAA Mode

What's New In Version 3.9

New in Version 3.81

These functions were added in the 3.8 cycle. NOTE: Licensing, mentioned below, was later removed. these utilities are now free.

Navigating Around

press alt+control+windows+NumPad enter to set the utility window handle to the window with focus. Then, you can use the numPad arrow keys to move to prior or next windows, first child, or parent windows. Left arrow moves to a prior window, right arrow to the next window on this peer level. Up arrow moves to the parent window, and down arrow moves to the first child. If no window exists, in the direction in which you are moving, jaws will say, not found, and will leave the utility handle in the original location.

if sounds are enabled, jaws will play a special sound when you navigate to the window that currently has focus. The file played is HRTrack5.wav in the settings\enu\jls_audio folder.

Use the Numpad plus and minus keys to choose what attribute gets spoken. After making the selection, the value of the chosen attribute is automatically spoken as you move around. Press the NumPad 5 key to repeat the information, or double click it to place it in the virtual viewer, as well as on the clipboard.

One nice thing about this set is that you can use the utilities right along with your applications without changing any keyboard mode. For example, determine a control ID in your application, then switch to the script manager, find the appropriate editing point, then press the repeat last item hot key to have the control ID spoken again to make sure you didn't forget it. It will repeat the last item spoken, even if it was in a different application.

Double click the NumPad 5 key to place the spoken information in the virtual viewer. This also copies that same text to the clipboard so you can paste it into a script file if needed.

As you move from window to window, you can hear a short beep mixed with the speech if the window has at least one child. This feature is enabled and disabled with the backslash key, which also controls sounds for the window navigation functions, as well as the color change and window boundary functions described below.

There are four attributes in the rotation which report handle values:

The latter 3 of these items are handles which point to other windows. If you want to cause the utilities to jump to that window, just press the enter key, the main enter, not the numPad enter. The global handle will be set to the handle spoken for this attribute, and the item selecter will be forced to 0, your most commonly used attribute. You can then explore the attributes of the new window, using the NumPad plus and minus keys.

To return to the previous window, simply press the backspace key. the utilities global handle will be restored to it's previous value, and the item selection will also be returned to it's original value.

Window Visibility

Get a report on window boundaries and visibility status with the f12 key. To place this information in the virtual viewer, double click the f12 key. The double click action will also place that text on the clipboard.

Using The Mouse Cursor

To either move the utility handle to the window that contains the mouse, or to move the mouse to the window pointed to by the utility, use alt+control+windows with the following:

If you move the mouse to the utility window, and you have Highlighted Text selected as the output mode, the mouse will be moved to the first highlighted text in that window. If you have type and text selected as the output mode, and the window contains text, it will be moved to the first word of text. Otherwise, it is moved to the top left cornor of the window.

Focusing The Application

Change application focus to the utility window with the NumPad page up. This may or may not work, depending on the application, and the window you choose. But, the scripts will inform you whether or not focus has moved.

Window Hierarchy

Find outhow many windows you are from the first window on this peer level, or how far down you are from the top level window, even with jaws 3.5, using the NumPad Home and End keys.

Virtualize Real Window

This is an expansion of the Virtualize function provided with JAWS. This is activated with the v key, and produces a report of all text inside the real window containing the utility handle. The report is placed in the Virtual Viewer. The scripts analyze the real window, looking for child windows. Text wich is thought to be clickable, such as text in buttons, is in a link preceeded by the word click, while text which can be given focus, is in a link preceededc by the word, focus. Place the virtual cursor on a link and press enter to either click, or place focus, on the item.

The code for this version of VirtualizeWindow is in file WindowNavigator.jss, and is provided with these scripts. There is already a version of this with jaws, and is used in the quicken Scripts.

Exploring For Colors

These utilities replace the mouse movement keys shift+alt in combination with the numpad arrow keys. The functions now monitor the color at the point of the mouse cursor, and play a brief beep sound if you move to a point where the color has changed. When you stop issuing movement keystrokes, the color is spoken as a name, and as an integer. The integer is not the RGB string, but the undecoded integer value. Repeat the color with the shift+alt and numPad 5. When you do this, the integer value of the color is copied to the clipboard so you can paste it into a script file. Double click the shift+alt NumPad 5 to hear the entire field of text with that same color which contains the mouse cursor. To control how far the mouse moves with each keystroke, enter home row mode and use the NumPad left and right arrow as is standard with jaws. Don't forget to exit home row mode once you have this selected. But, be ware that it gets set back to the default of 3 when you alt tab around.

Detecting Window Boundaries

Detect window boundaries with the mouse. -- A function called HRTrackMouseWindow is provided. If you call this function from the MouseMovedEvent, it will compare the handle of the window presently containing the mouse cursor, with the window containing the mouse last time this event fired. This function will determine if you are entering a child window, breaking out of a child and moving back to a parent window, moving from one peer into another peer window, or if you are leaving the family altogether. It might also be useful to call this from the focus changed event in some cases to learn where the application goes as you operate the keys. Unique sounds are played for each case. you can supply your own sound files, but these are the sounds shipped. You will hear these sounds combined with the color change beep if you use the alt+shift+arrow keys. Enable and disable these sounds with the backslash key. If you are using software speech with a single channel sound card, these sounds may not operate correctly.

Comparing Windows for Family relationship

Imagine that you have two child windows side by side, but with a small distance between them. As you move with the mouse cursor, having the sounds enabled, you learn that there is a small strip of some other window showing in the tiny region between these two windows. Each time you cross one of the window boundaries, you hear the breaking glass sound, indicating that you have left the window family. So, you don't know anything about the family ralationship between the two child windows, because they are not adjacent, and thus can not be compared.

To learn if these two windows are related, place the mouse cursor in one of the windows, and press the right mouse button. this will set the utility handle to the current window. Now, move the mouse cursor across the window border, through the small intermediate region, and into the second child window. you will hear the breaking glass with each border crossing. Once in the second child, press alt+control+shift+windows+f. This will cause a family comparison between the two children, one where the mouse resides, and the other where the utility handle is pointed. You will hear the sound effect indicating the relationship, even if sounds are turned off. This allows you to compare two windows which are not physically adjacent.

Sound Files

All sounds played by the JLS utilities are placed in the jls_audio folder, under the settings\enu folder. Some of these are active at all times, while others operate only when the sounds are enabled.

Chunks

Move between chunks of text to figure out how to use the GetChunk functions more effectively. Use the six pack end key to speak current chunk, the one containing the mouse cursor. Sixpack page up gets the prior chunk, six pack page down gets the next chunk. The mouse moves along from chunk to chunk as you go. The scripts will call the beep function if you attempt to move to next or prior chunk, but the mouse fails to move.

To place the present chunk on the clipboard, as well as in the virtual viewer, double click the six pack End key.

Position Within Window

To find the distance between the mouse cursor and the nearest edges of the window containing the mouse, use the delete key on the six pack. control+windows gives you the distance to the left and right sides. And, alt+windows gives you the distance to the top and bottom.

Labeling And Returning To Locations

Label a location on the screen. Place the mouse cursor at a location and press the l key, then type in a label for this location, and press enter. You can do this multiple times, building a list of locations and names as you go. Each time you use the l key, the present label will be added to the growing list. Press the c key to copy the list to the clipboard and clear the list. The clipboard is formatted for inclusion in a const section of your scripts. Constants are generated which define the percentage of horizontal distance, and the percentage of virtical distance across the window that contains the jaws cursor. These percentages are called "window Relative coordinants" and are integers in tenths of percent of the window dimension. So, 100% would be represented by a value of 1000. A bias of 100000 is added to the horizontal component if the point is closer to the right side of the window. Similarly, the vertical demension is biased up by 100000 if the point is closer to the bottom side of the window. The reason for this bias is that JAWS will not allow constants to be negative. And, you get better pixel resolution with lower percentages. So,saying that you are 1 percent in from the right edge, is more accurate than saying that you are 99% in from the left edge. This is because of the integer math used in this calculation.

Function PositionInWindow, in file WindowNavigator.jss, can be used in the application scripts to use these constants, and will position the mouse accordingly. It is aware of the bias of 100000, and treats the number accordingly, using the appropriate window oedge as it's basis. In addition, constants are generated for the window control id, type and subtype code to aid in locating the handle of the window.

When you paste the clipboard, containing a label, into a script file, the name you typed for the label will have an underscore, plus the following suffixes appended to create a series of constants. The suffixes and meanings are as follows:

Moving to Window Relative Positions Manually

Move the Jaws cursor to a window relative position. To do this, set the utility handle to the window of interest, then press the modifiers and the shift+r key. You are presented with an edit box where you can type in the horizontal and vertical window relative components, separated by a space. These numbers can be generated with the l key. They are defaulted to the last position you labeled, or the values you entered last time you used the shift+r key, whichever is more recent. Defaulted to 0 0 the first time you do this after a jaws restart.

To specify pixel counts relative to the window edges, leave out the shift key. The shift key included means you are entering window relative percentages. But, absence of the shift key means pixel addresses from the top and left edges. To make an address relative to the bottom or right side, make that coordinant a negative number.

Remember, Window Relative percentages are horizontal and vertical distances in tenths of a percent of the corresponding window dimension.

Note that Jaws or invisible cursor must be active to do this.

Moving To Screen Absolute Locations Manually

To move the jaws or invisible cursor to an absolute cursor location, relative to screen edges, use the A key. Type in the horizontal and virtical pixel addresses, separated by a space. The values are defaulted to the last position labeled, or the values typed in the last time you used the A key, whichever is most recent. Defaulted to 0 0 the first time you do this after a jaws restart. These are relative to the left and top edges of the screen

Marking Cursor Locations

Set a marker so you can return the jaws or invisible cursor to an absolute location while exploring the screen. Activate either jaws or invisible cursor, move to the position you want to mark, then, press the m key. You can return the cursor to this position using the n key. Separate marker locations are saved for jaws and invisible cursors.

Copying Text To The Clipboard

Once you have marked a cursor location on the screen which represents one corner of the rectangle in which you want the text, you can move the JAWS or Invisible cursor to the diagonally opposite corner of a rectangle. Note that this might be a position further to the right on the same line. Then, press the k key. The text inside the rectangle will be added to an internal buffer. You can do this many times, adding text each time, as you move around the screen collecting text snippets. Each snippet is separated from it's neighbors in the internal buffer by a character which is defined in the Clipboard section of the jls_utilities.jsi file.

once you have collected the snippets you want, press the c key to copy the internal buffer to the clipboard and clear the internal buffer. then, you can paste the standard windows clipboard wherever you like.

Marking And Returning To a Window

As you move from one window to the next, it is often desireable to mark a particular window so you can conveniently return to it. To mark the current utility window, press the modifiers, in conjunction with shift+m. The current value of the utility handle will be saved. to return to this window, press the modifiers in conjunction with shift+n. The utility handle will be reset to the value present at the time you marked the window.

If you are in object mode, the utility object is marked instead, and returning will return to that object.

Exchanging Jaws And Invisible Cursors

Exchange the jaws and invisible cursors with the x key. This will toggle which cursor is active, as well as exchange their positions. This is useful when you are labeling graphics which change when the mouse is on the graphic. You can turn screen echo to all to hear the tool tips when spoken, place the invisible cursor well out of the way, and place the jaws cursor on a graphic to learn it's function, label the graphic, then exchange the cursors with the x key and label the graphic a second time to make sure both bases are covered. Now, yu can press x again to cause the jaws cursor to return to the graphic.

Detecting Window Creation

Capture window creation - call function HRCaptureNewWindow from a WindowCreatedEvent in the default file, or in your application as is appropriate, passing it the handle of the new window. Pressing the w key will enable capturing. The next time this function is called, it will place a report about the new window on your clipboard and clear the capturing flag so that subsequent new windows will not be captured. This is especially handy for those dynamic windows which appear for only an instant, then disappear before you can explore them. If, while watching is active, you press the w key again, watching will be disabled.

Searching For Control IDs

Find a window by Control ID - Position the utility to the window that is to be the starting point of the search. Press the f key, and enter the control ID you are looking for. The edit box will default to the last control ID you searched for. The FindDescendantWindow function will look from your present window, downward in the hierarchy. IF the control ID is found, the utility will position to the new window. If you want to return to the window that was the starting point of the search, press backspace. Since the Backspace does not destroy the original book mark, you can use this feature to mark a window. You must search for a control ID to record the book mark first. But, once it has been recorded, you can press backspace multiple times, and always return to that same window. Press the f3 key to repeat the search. This is used when engaging in trial and error to figure out the correct starting point for a control ID search.

Searching For a Graphic

Position the utility to a window that contains a graphic of interest. Then, pres the g key. You will be presented with an edit box where you can type in the name of the graphic,followed by the enter key. You need to have jaws or invisible cursors active to do this. If the graphic is found, the active cursor will be placed on the graphic.

Constructing Routing Paths

Coolest of all, these scripts will even write code for you. There are many cases where windows do not have unique control ID's, or where the control id is the same as the handle, and changes each time you run the application. In such cases, you need an alternative way to get from one window to another. If you are focused on window x, and you want to somehow navigate to window y by climbing through the window hierarchy, these scripts can figure out the routing path and actually write the necessary code to get there. You might feel like optomizing that code, but this will give you a starting point.

Set the utility window to your starting point, and place the mouse in the window that is the ending point of the navigation. Then press the six pack home key. The virtual viewer displays the series of steps required. Press enter on the link at the bottom of the page, and a new virtual window opens, showing you the code generated. this entire code fragment is placed on your clipboard. but, if you like, you can select portions of the code, and copy only that part to the clipboard with the control+c key, overwriting the bulk copy which was done automatically. Press escape to close that window and return to your application. Now, you can go to the appropriate point in your script file, and paste the clipboard to get code to which you can provide the handle of the starting window, and which will find the handle of the ending window.

Because this is a very complex task, this function does not always produce correct results, but it's pretty darn close.

Moving The Mouse To Window Edges

To explore from the edge or corner of the window pointed to by the utility, you can use the extended arrow keys to position the mouse. You must have the user option to differentiate between NumPad and Extended keys turned on in the default.jcf file to use this feature. When you press one of the mid section arrow keys, the JAWS cursor is activated, and the JAWS cursor is placed on the edge of the current utility window corresponding to the arrow key you struck. If you double click that arrow key, the mouse will be centered along that edge. If you do not double click, then the orthogonal component will be preserved. This allows you to be positioned outside the window, but to move to a point which is lined up with one edge of the window.

For example, suppose your mouse cursor is positioned in a data sheet of some kind, and is on a line at the top of this data sheet which contains a series of headers. Further down the screen, and yet inside this data sheet, is a series of edit box windows which are positioned so as to visually line up with the various headers at the top of the data sheet. You want to keep the mouse cursor on the same line with the headers, but to adjust the left right position to line up with the left edge of one of those edit boxes down below. Piece of cake.

Use the JLS navigation keys to position the utility to the edit window of interest. The mouse cursor is not affected, only the global window handle will be adjusted. Now, press the extended left arrow. The horizontal position of the mouse is adjusted to line up with the left side of the edit box, but the vertical position is not changed. So, the jaws cursor is still outside the edit box, but it is directly above the left edge of the edit box. If you double clicked the extended left arrow, you will hear a small beep, and the vertical position will also be changed. In fact, the mouse will be moved to mid way between the top and bottom of the edit box.

Likewise, extended up arrow will move to the top edge of the window. Extended down arrow will move to the bottom edge of the window. And extended right arrow will move to the right edge.

When you use the extended up, down, left, and right arrows, jaws will say good, meaning that the mouse moved as intended, already good, meaning that the mouse was already in the correct position, or bad, meaning that the mouse did not move to the intended location.

If you are in object mode, the cursor is moved to the corners or the edges of the MSAA object instead. Object mode is entered and exited with alt+control+windows+shift+o.

Speak Object Value

If the window you navigate to is an object, you can speak it's value with the o key. Double click this key to place the information in the virtual viewer, as well as on the clipboard.

Distance To Center Of Window

One good use for this feature, is when attempting to associate a prompt with an input box. In many cases, there are windows containing static text surrounding an edit box. but, it is not always clear which one is the prompt. Sometimes, the distance can be an indicator, in that, the static text which is closest to the input box is actually the prompd. To aid in this evaluation, two keys are supplied.

Getting Text From a JAWS Frame

To specify the name of a JAWS frame from which you would like to obtain the text, press alt+control+windows+shift+9 on the numbers row. You will be prompted for the name of the frame of interestThe name is defaulted to the previously entered name. Enter the name and press enter. The contents of the frame will be spoken. If you want to just repeat a text acquisition from the frame whose name you have already entered, leave out the shift key, and press alt+control+windows+9 on the numbers row. double click that key to place the contents in the virtual viewer and copy it to the clipboard.

If the jaws or invisible cursor is active when you do this, and the frame is valid, that cursor will be moved to the top left corner of the frame. To preserve the jaws or invisible cursor position, activate the PC cursor first.

Getting HTML Element Descriptions

When focused on a web page, move the virtual cursor to an element of interest and press this hot key. the virtual viewer will activate, showing the report JAWS provides for this element and it's ancestors. By default, the utilities report up to 5 ancestors. You can change this default by editing the HTML section of the jls_utilities.jsi file.

Monitoring Events

The utilities provide five functions which you can call from various points of interest in your code. Each of these functions will trigger a brief tone of a different frequency. If that monitoring channel is enabled, then a call to that function will trigger the short beep, and will increment an event counter for that channel. This is very handy for monitoring when the various assynchronous event functions run. but, you can call these from any spot in your code, not just an event. And there is a event Monitoring dialog in which you can observe the results of these calls.

There are three kinds of functions. And there are five functions of each kind, one for each channel.

The first kind is the void functions. These simply cause the associated sound to play, and increment the event counter for the corresponding channel. The functions are named, HRHook1, HRHook2, HRHook3, HRHook4, and HRHook5. These functions are void, and require no parameters. You don't need to declare them in any way, just call them. Jaws will find them because they are part of the default set once the utilities are installed. But, don't forget to remove the hooks from the code before moving your scripts to a machine where the utilities are not installed. Otherwise, you will experience an annoying barrage of error messages, unless you condition the call upon the global variable JLSUtilitiesActive. Declare this variable as a global integer in your code. It will be set to 1 if the utilities are installed and authorized, 0 otherwise. No, setting this variable to 1 does not cause unauthorized utilities to become active. sorry. Nice try.

the Second kind, is the string functions. These five are called HRHook1s through HRHook5s. Here, you can provide a string label, and a string value. for example,
HRHook1s (StringValue, "My label")
where the two string values will accept up to 32 characters of data. These functions, one per channel, will record a label and a string value which will be shown in the Event Monitoring dialog. This allows you to track variable values as your code executes.

Most conveniently, if you do not feel like providing a label, because you are lazy, or you are pretty sure you will know what the value represents, you can simply omit the second parameter, , such as:
HRHook1s (StringValue)
and the "label = " portion of the string will not appear in the resulting line in the monitor dialog.

the third kind are the integer functions. they are named HRHook1i through HRHook5i, and are used like this:
HRHook1i (integerValue, "my string label")
Again, you can omit the label string if you do not wish to provide one.

There is a Clear All Values link in the Event Monitoring dialog which lets you make these labels and values disappear if you want.

the sounds activated by these functions do not depend on the sounds enable hot key, alt+control+windows+backSlash. They are individually enabled and disabled through the Event Monitoring dialog as described below

When you press the shift+alt+control+windows+w hot key, you are presented with a dialog where you can enable and disable each of the various channels. Each channel's counter is also displayed, so you can see how many times that event has fired since it was last enabled. The event counter is cleared when that channel is enabled.

To the right of the event counter on each channel line, is a value field, which will not appear if no value has been recorded for that channel since the last clearAllValues command. However, if one of the hook functions for this channel has been called, and a value was recorded, data will appear here. If a label was provided, this field will be of the form
Label = Value
Or, if no label was provided, this field will be of the form:
Value

Cursor up and down this dialog, and press enter on a channel to change it's state. When you enable the channel, you will hear the sound which will be played when that event fires. These files are the various tone.wav files located in the JLS_Audio folder, under the settings\enu folder. So, you can easily replace them with sounds of your own. Tones used are:

The counts and values displayed are captured at the time the dialog opens, and also when any channel is toggled on or off. However, they are not normally updated in real time. This is because manipulating the virtual buffer can actually cause some event functions to fire unexpectedly. It was, therefore, considered best to keep this dialog static unless a key was pressed requiring some change in it's contents.

However, if you really want the counters and values to stay up to date as your hooks are called, you can do so by editing the [EventMonitoring] section of the jls_utilities.JSI file. The value called UpdateRate is the refresh interval in tenths of a second. A value less than 5 is forced to 0 to prevent JAWS from being overloaded. A value of 0 means no periodic refresh will occur. If you set this value to something greater than 5, the counters and values will update periodically. Note that this is not synchronous with the calling of the hook functions. They are kept as simple as possible so as to have as little impact on the real-time performance of your application scripts as possible.

There are two capture modes, as controlled by parameter CaptureFirst, in the Event Monitoring section of file jls_utilities.JSI. If this parameter is set to 1, then all hooks will only capture a value if no value associated with that channel has been captured since the last ClearAllValues command. So, you'll get the first value recorded, and subsequent values will be ignored. If this parameter is set to 0, then each value recorded will overwrite the previous value. And, what you see in the dialog, will be the most recent value.

In general, it is best to uncheck the option in the default configuration, under user options, which causes the virtual viewer to appear on screen. This allows you to operate the event monitoring dialog without causing changes in the application. You can have it appear on screen if you like, but, I recommend not doing so, unless truly necessary. This is especially true when configuring the dialog for automatic update.

Actually, the usefulness of this function depends on the creativity with which you apply it. Arguably, the best reason to implement it was just to play with the virtual viewer to see what kind of custom interface could be implemented. But, at least, you can install these hooks in your various event functions, and conveniently turn them on and off at will. You don't have to remove them, just to make them stop bugging you for a while. And, you can see how many times they are getting called.

There is a pannick key, in case you get overwhelmed with beeping tones, and can't figure out what is going on. Just press alt+control+windows+escape to turn all channels off. Don't forget that key. Enjoy the silence.

One great application for this, for example, is to go to the FocusChanged event in your application script file, and add a call to HRHook1(). Then, recompile your script file and switch to the application. Open the event monitoring dialog, and enable channel 1. Then, press escape to close the dialog, placing focus back in the application. Now, you will hear a beep each time the FocusChanged Event fires, and the counter will be incremented. You can always open the dialog at any time to check on the counter value.

Hexidecimal Arithmetic Functions

Ever wanted a translator between decimal and hexidecimal number formats? Now, you have one. Press alt+control+windows+shift+4 on the numbers row to convert a hexidecimal string to decimal format. alt+Control+windows+shift+8 converts a decimal integer to hex format. In both cases, make the first character a dash if you want it interpretted as a signed negative number. Hex numbers should begin with a number. for example 0f, rather than just f for the value 15 decimal.

The JLS_Utilities.JSI File

File JLS_Utilities.JSI in the settings\enu folder contains custom information used to control behavior of the utilities. There are four sections in this file:

After editing the JLS_utilities.JSI file, it is best to close and restart jaws, to assure that all values get read.

Customizing The Attribute Rotation

As you use the NumPad plus and minus keys to rotate among the list of window attributes to be spoken, you may find that you prefer a different order than is provided. fortunately, you can do this. To do so, Use Notepad or other pure text editor to modify file jls_utilities.jsi. You can change the numbers to indicate the order in which the items should appear. but, you don't need to sort the lines into order. The small beep sounder will always occur at item 0. do not modify the Max item unless you want to eliminate some of the existing items. Max represents the index at which the rotation will return to 0.

the philosophy to use, is that, while all attributes are potentially useful, some of them are more commonly used, and are especially handy for simply identifying the pattern of the hierarchy as you browse it. Make your favorite attribute item be item 0 in the rotation. Cluster your other favorites in the low numbers, such as 1 and 2, with the rest of your favorites in the high numbers, just below the max number. This would place those you would be least likely to use, on the opposite side of the rotation circle, arount item 6. In this way, when you are on item 0, where the beep occurs, you will be closest to your most often used attributes.

MSAA Object Mode

This mode is mutually exclusive with window mode, and is used to navigate the tree of active accessibility (MSAA) objects. You can freely move back and forth between these modes.
To enter or exit this mode, use shift+alt+control+windows+o.
To initialize to the object currently at the active cursor, press alt+control+windows+enter. Use the alt+control+windows arrow keys, just as you do with window mode, using left or right to move among peer objects, up arrow to go to the parent object, and down arrow to go to the first child object.
Use numPad plus and minus to choose what gets spoken, and numpad 5 to repeat it.
Some objects also contain a list of what are referred to as simple elements. To move through the list of simple elements, use numPad 1 and 3 keys, which is the end and page down keys. To go back to the first simple element, press shift+alt+control+windows+NumPad1.
To place focus on the current object, press the alt+control+windows+numPad 9 key.

Selecting Object Attributes To Be Spoken

Use the numPad plus and minus keys to choose what gets spoken as you move around. Or, you can use the alt+shift+control plus a numbers row key to directly access the attribute of choice. Double click taht key to make that attribute the default.

Because lots of MSAA objects are sparcely filled out, it is often nice to have JLS monitoring multiple items as you arrow around. To add the current item to the list of items to be automatically spoken, press shift+alt+control+windows+NumPad plus. This will toggle the current item inm, or out, of the autoAnnounce list. Double click this key to clear the list.
To force the autoAnnounce list back to tracking the single selected item, as in previous versions, press shift+alt+control+windows+NumPad minus. This will toggle between using the custom list, and using the single selected item.
This also works in Window mode.

When the AutoAnnounce list is not empty, using the plus and minus keys to go through the list of attributes, will cause an audible click to play when the currently selected item is in the autoAnnounce list.

Learning The Sound Effects

If you have sounds turned on, with the backslash key, JLS will play special sounds when you are navigating objects. These sounds indicate information about the current object, in the context of its surroundings. The sounds played depend on the direction of navigation. for example, when navigating vertically, sounds are played to indicate whether each new object has peer-level objects, either to left or right or both, and whether that object has simple elements. This will alert you as to whether you should bother arrowing in those directions to explore the details. Likewise, when navigating horizontally, sounds indicate whether the current object has child objects, and whether it also has simple elements associated with it.

To familiarize yourself with the sounds made when object navigating, Press shift+alt+control+windows+h. Down arrow to a condition and press enter to hear the sound that gets played when that condition is encountered.

Installation

First, if you don't already have it, Download The Installer. and run it. This will copy the necessary files, and recompile them for your version of jaws.

To install these scripts, it is necessary to add keys to your default.jkm file, and to add statements to your default.jss and recompile the default script file.

In recent versions of jaws, you need to make sure there is a file in your user-specific settings\enu folder called default.jkm. Normally, this file resides only in the shared settings area. If you already have default.jkm in the user-specific settings\enu folder, then make a copy of that file before you install this utility. That will provide the best means of easily uninstalling these utilities if desired. If default.jkm exists only in the shared settings area, then copy that file to the user-specific settings area.

Use a text editor to open one of the files that contains the JLS key assignments. Choose from:

  1. jls desktop keys.txt
  2. jls layered desktop keys.txt - in case you prefer layered keys, uses the alt+control+windows+leftBracket layer.
  3. JLS LapTop Keys
Copy the entire contents to the clipboard. then, open the user-specific version of default.jkm in paste the clipboard at the top of the corresponding section of the jkm file. the section names are enclosed in left bracket and right btracket [], and correspond to your keyboard layout.

If you find that your alt+shift+arrow keys, which move the mouse and speak color, don't work any differently than they always did, then, in Default.jkm, you should manually remove the existing assignments for shift+alt+up down left and right arrows. These are assigned to function HRMouseUp, down left and right. respectively in the jls keys.txt file by default, and your additions should replace the existing default assignments. This is usually not necessary. You can remove a key assignment by placing a semicolon ";" at the left end of the line.

Remember to go to the default configuration file, and enable the keyboard option to differentiate between numPad and extended keys. In some cases with other applications, that may affect which cursor keys you must use in order to interact properly with the application. But, it is necessary to enable certain JLS features, such as speaking chunks, and learning mouse positioning information inside a window.

Next, you must open default.jss with the scrip manager, and add the following statements. Make sure you do these exactly as shown. You can compile correctly, while still having mistyped these lines, and the results are very annoying until you get it corrected:

Then, recompile the default scripts. Your utility scripts are now installed. It's definitely a good idea to restart jaws, to get it to read the default key map.

The hot key help is tied to alt+control+windows+h. Alt+control+windows+q will report the current version of the utilities.

UnInstall

To uninstall:
  1. Open default.jss with the script manager, and remove or comment the line that says:
    Use "jls_utilities.jsb"
  2. If you installed the optional call to HRCaptureNewWindow in your windowCreatedEvent, comment out, or remove that line.
  3. recompile default.jss then recompile.
  4. Use notepad or a text editor to open file default.jkm in the user-specific settings area.
    If you followed the installation recommendation to put the jls keys at the top of the section for your keyboard layout, You can select from the start of that section down to a line that says: ;jls end
    And delete that selection. Or, you can simply restore your old version of default.jkm.
  5. close and then restart jaws.
JLS_utilities is now removed. You can delete the jls_*.* files from your user-specific settings if you like. However, the total space occupied is only a few hundred kBytes. Why bother? You'll probanbly change your mind.

Free Scripts Included

This section lists extra script files included with this distrubution.