w The SnowMan's Scripts for Jaws For Windows

 

Hot Spot Clicker Build 242

(c) copyright 2005-2020 by Jim Snowbarger, (the Snowman)


Use your heading navigation commands in jaws, h and shift+h, or the JawsKey+f6 list of headings dialog, if you want to get an overview of the content of this document.
note: The jawsKey+f6 list headings option, is very useful for quickly navigating to headings whose name is familiar, since you are able to use single or multi letter navigation within the list view, to immediately jump to headings beginning with the letters you type. navigating headings in this dialog also avoids the heading level announcements spoken by the h and shift+h keystroeks.
As you read, You may also find it useful to utilize the one shot temporary bookmark feature of jaws, control+k, before following this page links to skip to other sections of this document. pressing K or shiftK, will then provide a convenient method of returning quickly to your previous location, to recommence further reading.

Additions and Changes in build 242

terms Of Use

First, it is important to recognize that a volunteer effort like that which created HotSpotClicker simply does not have the resources to do adequate testing to assure that you can not possibly run into problems through the use of HotSpotClicker. We have gone to great lengths to try to insure that you will have success in the use of this utility. but, There are far too many possible combinations of circumstances to anticipate them all. You should create a backup of any scripts, including all associated configuration files, to which you wish to connect this utility, just in case your modifications, or inadvertent editing errors, cause undesired changes in the applicaition scripts.

Just as do Microsoft, and Freedom Scientific, and practically every software vendor in the world, I make no warrantees, implied or expressed, that these scripts will do exactly what you expect them to do, nor that unintended consequences will not result from their use. they are offered free of charge, and you use them, as is, at your own risk. Use discretion and caution, and be prudent.

These scripts are free for unlimited use, on any number of computers. You can share them freely, and you can modify them for your own use. If you wish, you can submit code modifications for consideration. If they are accepted, you'll get your name listed in the credits, if you like. You can even sell your services applying HSC for other people, and we won't even ask you for a cut of the action, though you might reasonably consider making a donation toward HSC development.

What you can not do, is sell the scripts themselves, or any derivative of them without binding agreement with Jim snowbarger (The Snowman). TheSnowman@Snowmanradio.com

Credits.

Sincere, heart-felt Thanks go to several other individuals who have played important roles in making HotSpotClicker possible.

Geoff Chapman -- Thanks to Geoff for his invaluable support and inspiration. His relentless commitment to excellence was the impetus for many useful and creative features, and help to bring this project to fruition and make it available for free download. Geoff has also generously offered to provide frontend support to those who have problems getting this utility installed and working on their machine. you may contact him at: gch@internode.net.au

Andrew Heart -- Much deserved thanks also go to Andrew Heart for providing the hscsrvr.dll, which was used to replace problematic JAWS file input/output routines, and to dramatically accelerate color searches. andrew pulled us out of a very difficult spot, and your experience will be much more rewarding, thanks to his efforts.

Jim Bauer -- Greatful Thanks also goes to Jim bauer for providing the code which allows multiple, or nested, post-processing functions.

Doug Lee -- Thanks to Doug Lee, for letting us scavange his clever solution to the multiple-letter navigation problem posted by some recent versions of JAWS.

Bryan Garaventa -- Thanks to Bryan for letting us use the JFetch utility, to allow checking for updates online.

Victor Tsaran -- Thanks to Fictor, for his invaluable help creating the hotSpotClicker installation and uninstallation routines, using the nullsoft scriptable installer. And, ya just gotta love that endearing podcast about HSc. Ignore his advice though, and do read the documentation.

Steve Spamer -- Thanks to Steve for Context Lists, hidden spots, and several other useful additions.
Steve is the author of a heck of a lot of HotSpot sets for a variety of audio production applications. Visit him at VIPAudioAccess.com

PradipChandra Sikdar -- thanks to PradipChandra Sikdar the HSC Menus. Great idea.

Jean-Philippe Rykiel -- Thanks to Jean-Philippe for encouraging us to implement Spot preChains.

Jim Shaffer -- Jim provided the ToneGen dll that significantly proved the usefulness of the table column tone graphing feature. Now, we can produce nice, smooth, properly compensated audio tones to convey audio graphs of numerical information.
Jim's Web site is: The CyberBlink

Phil Muir -- And finally, Thanks to Philfor spot rings, and graciously hosting HotSpotClicker.org.

Now, if we can just fine an organized person, with a good command of English to reorganize the documentation, well ... then we'd be in luck. Any volunteers?

QuickStart guide.

For you technically savvy hotshots, who already know all about computers and scripts, and just want to get up and running with a minimum amount of happy talk, we have created the quick start guide. it's language and explanations are substantially more to the point. Consequently, it assumes a medium knowledge of computers and computer concepts. By all means, click below to open this quickstart guide, as you may well find it the fastest way to learn the basics, about setting up hotSpotClicker to work with your favorite applications.
But, in order to gain the most from the HotSpotClicker tool, we strongly encourage both new, and experienced users, to come back and explore this InDepth user manual as, while being slightly more verbose than the Encyclopedia Brittanica, it does contain important Clicker concepts not present in the quickstart guide.

tip: to open this quickStart guide in a new window, enabling Alt+tab navigation between the two open documents, if using Jaws and internet explorer, when focused over the link below, instead of pressing enter, press the NumPad star, (right mouseButton emulation key.) Then, from the resultant context menu, choose, "open in new window," and press enter. Click here to open the hotspotClicker quickstart guide. skip to HotSpotClicker download and installation instructions.

Note To Developers.

If you are a script developer, and want to make your scripts HSC-ready, so users can connect HSC into your scripted application without requiring any further modification to your scripts, download the .zip file below. it contains condensed notes on how to interface HSC with your scripts, as well as a place holder jsb file to provide the null stub functions which you will need to call, and rules you will need to follow in order to make it work. Download HSCStubsForDevelopers.zip

Hot Keys

HotSpotClicker, often refered to as HSC, allocates a bunch of hot keys from your applications for purposes of controlling it's operations. Most hotkeys use alt, control and shift, all held down at once. This is often referred to as HSC mods. So, hsc mods f1 really means, alt+control+shift+f1.

Introduction.

From time to time, I am approached by people who are having problems in their work situations, because their employer has started using software that requires that various spots on the screen be clicked with the mouse, but jaws thinks such spots are blank. there is no graphic, or other item which JAWS can latch onto in order to reliably find the location. In some cases, these people are at risk of even losing their jobs if they can't figure out a way to overcome that relatively minor problem.

Well, it is minor if you know how to overcome it, because JAWS offers several tools within it's powerful scripting language to facilitate doing that. But, it can be a big deal indeed if you don't.

As blind computer users, we've all experienced what at best, can be very frustrating, and at worst, potentially totally debilitating situations, in which a sighted friend or coleague is immediately able to effect a necessary task in a computer application that we may've been struggling to figure out for a lengthy period of time, by simply, "just clicking over here!". now, With hotspot clicker, you can be ready when this situation occurs again!

Having Hot spot clicker on hand may simply eliminate, or significantly reduce, those incredibly frustrating situations where you may've previously been forced to await the arrival of either a blindness agency I T consultant, or for customized scripts to be released, or for the often long and drawn out process of writing to the developer of the problem application, seeking to engage their interest in providing a more keyboard friendly user interface. Which, as we've all experienced, is often a somewhat less than successful endeavor.

Many modern programs are increasingly becoming useable predominantly via the operation of the mouse, and they are becoming more and more dificult to operate effectively and productively, via the keyboard alone. They often require the mouse to be clicked at certain locations, in order to either bring focus to certain parts of the program, or to perform certain tasks. in some situations, if you can not easily find a way of efficiently navigating the mouse to those locations, you simply can not operate such programs at all.

even some applications which display their screen area labels in bit mapped text, which is completely unreadable via screen readers, with some initial sighted assistance, can often be labelled, and thus made usable through the use of hotspot clicker.

Of course, you can make jaws do a mouse click at any location you want, as long as you know where that location is. But, actually implementing a set of robust scripts to do it, complete with a speech friendly front end user interface, requires a few steps that are offten a bit daunting even to the moderately experienced scriptor. So, this free set of scripts is designed to facilitate the process, and is my gesture toward those who find themselves in situations like that, but whom I could not help at the time. It may even be of help to those who do simple scripting to adapt such software for their clients.

But please do not think that Hotspot clicker is just for people in critical work situations. basically, if you've ever found yourself as a blind person using a computer, needing to click with the mouse (or jaws cursor,, in jaws they are one in the same,) somewhere onscreen to affect a certain task, and wishing it could be done more quickly and easily than crawling tediously around with the jaws cursor looking for it, then hotspot clicker can very likely help you. For at it's most basic level, this is the primary function hotspot clicker has been designed to facilitate.

HotSpotClicker can even be used to improve the interface to programs that are already mostly keyboard accessible. It can do this by having user's define screen locations where certain mouse actions are required, or important text items you wish to "glance at" are located, and by associating such screen locations with hot keys, and/Or user defined names.
Even in applications where the controls may all be accessible via the keyboard, either through the menu system, or perhaps via multiple and thus somewhat inefficient presses of the tab key, Hotspot clicker can very often bring increased speed, efficiency, and ease of use, by being able to immediately bring focus to, or click on, those controls that you use the most, and attach operation of those controls, to easily accessible shortcut keys of your choice.

The windows Volume control application provides just one universal example of a program in which hotspot clicker can be of immediately obvious benefit in this kind of situation. Imagine being able to immediately design your own hotkeys, either to bring focus instantly to the sliders you desire to adjust most often, or perhaps to immediately click on the buttons which may either mute or select the mixer controls of most interest to you, without having to tediously tab through all of them to locate them. HotSpotClicker can help you do all that, and a great deal more.

HSC Versus Frames Manager.

At first blush, one might be tempted to think that the frames manager utility, already built into jaws, could be made to achieve some of what we've been describing. So why the need for an extra utility like the HotSpot Clicker?

It is certainly true that The JAWS Frames Manager is very powerful, and can in the hands of a capable and patient person, be used to do some of the things that the HotSpotClicker can do. In fact, frames manager can still provide some functionality that hotspot clicker currently does not. such as to monitor certain areas of an application and automatically speak text appearing there, or to silence chatty portions of an application etc.

Frames Manager certainly does have an important place an any good adaptive technologist's tool kit. However, it does have a number of very frustrating design flaws, which can make it difficult and very time consuming to use in some situations. In the next few paragraphs, we will contrast HotSpotClicker with the Frames manager in an effort to highlight some of the improvements we are attempting to make available.

The HotSpotClicker has been designed for ease of use, and has some nice advantages:

What Can I Do with this thing?

Oh boy! Get Ready, because there is a bunch of stuff.
With Hotspot Clicker, You are able to:

Installation and connection of the hotSpotClicker.

First, it's important to understand that unlike many other, "stand alone," software applications, HotSpotClicker is actually a set of jaws scripts, which relies on being plugged in to another hoast jaws environment. Because of this, there is a distinct difference between installing, and actually connecting, the HotSpotClicker to your problem applications, such that you can then begin using it to define hotSpots in those programs. i.e. Simply installing Hsc on your system, places relevant files in their correct places., but the hsc product does not become active and ready for practical use in a given environment, until it has been individually connected to the jaws scripts for each application in which it's functionality is desired.

So, to summarize, before you can begin actually using Hotspot clicker within an a particular application, there are two main steps:
1. Installing the hsc product on your system; and
2. Individually connecting it to the applications in which you wish to utilize it.

Fortunately, neither process is particularly difficult, and we've tried to provide thorough instructions for both the installation, and application connection processes. Though it is worth noting, that the complexity of the individual application connection process, will in some measure, depend on whether the particular application to which you wish to connect the clicker, already has some Jaws scripts written for it, or not.
If it doesn't, the hotspot clicker connection process is remarkably straight forward. if it does, the full connection process, is slightly more involved. But a medium level skill in accurate text editing, should be amply sufficient to complete the process successfully.

A note about hotSpotClicker uninstallation.

First, it seems appropriate to offer the uninstallation details, so you know what is involved. It's not terrible, just a little more complicated than your typical applicaition.
But, if you're not concerned about that, and are just ready to install it, skip to the next heading.

Installing and connecting HSC is relatively straight forward, as described below. But before outlining this process, because of the nature of the individual application connection procedure, it's worth noting that uninstalling hsc from a system, retaining any non-hsc related changes which may've been implemented to hsc connected application scripts since installation of the clicker, is a bit more involved. This is because each time you connect HSC to an application, changes are automatically made to the jaws keymap file for that application, by way of the addition of the HotSpotClicker master keys. In addition, each time a hotspot is defined in an application, and a shortCut key is chosen to activate it, this too is added to that application's keymap file.
Beginning with HotSpotClicker version 7.6, a new feature has been added to the internal hsc actions menu, which now facilitates a fast and convenient method of removing all hsc related keystrokes from an application's keyMap file, retaining any other changes which may've been made since hsc was connected to the application.
However, because connecting hotspot clicker for actual use in any application, also requires that a few small code additions be made to the jaws script source file for that application, The uninstaller is not aware of all those manual changes. So it cannot be made to automatically restore those particular files to their preHsc status, retaining any other manual jss changes which may've been implemented since the clicker was installed.
So Before you actually uninstall HSC by choosing the Uninstall option from the new hotSpotClicker entry in the start menu, you will need to undo those manual clicker connection steps that were taken for each application.
The Simplest way to do this, is to place semi-colon characters, (;), at the very leftHand end of any additional lines of code added to the jss file during hotSpotClicker connection, and recompiling the jss file by hitting control+s.

For complete instructions upon uninstalling hsc from your system, please see: how to uninstall HotSpotClicker

Installing HotSpotClicker.

Click below to download hotSpotClicker build 242
Download the Hot Spot Clicker 242 executable installer. When requested, Choose the save option from the internet explorer download dialog. Take note of the "save in," field, in order to more easily relocate the file once downloaded.

Once the file has completed downloading, navigate to the file, and press enter. The hsc installer program will open.
Follow the on-screen instructions. If you already have a version installed, tell the installer that you do not wish to perform removal steps. It will successfully install over the top of and existing version.

note: It is only possible to install hotspot clicker into one version of jaws in any given installation session. However, you may of course reRun the installer at a later time, to install the clicker into as many supported jaws versions as you wish. Each installation is entirely independent. So, you can actually have different versions of HSC is each of your jaws installations.

The installer will now create a HotSpotClicker folder in the Program Files folder, which will contain all hotSpotClicker documentation, plus a couple of other important non script related hotspot clicker files. It will also deposit several hsc script files in the user-specific settings area of your installation of JAWS, usually in english installations, ...\settings\enu. But before doing this, the installer will now capture a backup copy of this ENU folder before hsc installation, to preserve your initial settings, in the event that you should wish to completely restore this folder to it's pre hsc installation state.

If an earlier version of hotspot clicker is detected in the particular version of jaws into which hsc is being installed, you will be asked whether you would like to create a backup folder containing the scripts for this previous hsc version.

At the successful conclusion of a fresh installation, you will be asked to reboot the system, to complete the installation process.
note that it is important that this be carried out before inadvertently giving focus to any application which may already have hsc connection code installed.

Connecting The Hot Spot Clicker To Your application.

The first thing to establish before seeking to connect the HotSpotClicker to an application, is whether that application already has any factory, or custom, jaws Scripts written for it, or not.
(please See below for step by step instructions on how to determine this.)
If it doesn't, the full hsc connection process is remarkably straight forward, and will be covered first. If it does, then the full connection process may vary in complexity, depending on two main factors:
A.) the particular way the script author has chosen to construct a couple of key functions in the jaws script file; and,
B.) whether you require the full hsc feature set for that application, Namely, the Automatic set switching, and Spot Prompter features, or not.
For more information on these two features, please see: Automatic hsc set switching feature. and, Hsc Window prompt creator, "spot prompter."

Note that you will need to perform the steps in this section once for each application with which you wish to use the Hotspot Clicker.
*** Important Note! the described method below should only be applied, for applications for which you have not purchased any custom scripts, where the author has deliberately withheld the jaws script source, (jss,) file. Such as Dancing Dots CakeTalking, or TAndT consultencies Itunes scripts, etc. You can not use HotSpotClicker to supplement scripts such as these, unless the author has already included the necessary code in their scripts. Following the below procedure in these situations, will almost certainly break functionality of such scripts, most likely requiring a script reinstall to repair. If you are Unsure about this, before follwoing the below procedure, focus in your desired application, and press JawsKey+q. if you hear jaws report that your application name scripts are loaded, and then you follow the below procedure and discover at step 3, what appears to be a blank jss file, then it almost certainly means you should not proceed past step 3, and should close the script manager with alt+f4, without making any changes or recompiling that jss file.

To determine whether your application already has any jaws scripts associated with it, do the following:

  1. focus within the application to which you would like to connect hsc.
  2. Pres jawsKey+0 from the top numbers row, to open the jaws script manager. (note: you can alternatively press jawsKey+f2, s, then enter if you prefer.)
    If successful, you should hear jaws say something like, "jaws script manager, - [YourApplicationName].jss.
  3. Carefully explore the file by pressing the down Arrow key a few times, taking care not to bump any letters or numbers on your keyboard.
    If you continually hear a windows error sound, and/Or, jaws saying, "blank," then excluding the special situation noted above, this means that jaws has no prior script file previously constructed for your application; In this case, follow the steps below to fully connect the hotspot clicker to this application.

  4. (If however, you find the jss script file already contains some information, please click below to skip to: What if my jss file already contains prior information/code.

note: Insure to fully read the following steps before actually clicking the link to open the new window, in order to be aware of the tasks to be performed once the window is open.

  1. Click the link at the end of this list to open a new browser window, containing the full HotSpotClicker connection code to be pasted into the blank jss file.
  2. When this new window opens, press control+A, to select all the text therein.
  3. Press Control+c to copy the selected text to the clipboard.
  4. Close the window using alt+f4.>
  5. Press Alt+tab until you arrive at the jaws script manager window, with your application's blank jss file.
  6. Press Control+v, to paste the contents of the clipboard into the jss file. Your Cursor should now be at the bottom of the newly pasted information.
  7. carefully explore the top and bottom of the file with your arrow keys, to insure the very last line in the file says,

    end function

    And that the very first line in the file, says,

    "Use "HotSpotClicker.jsb"

    (Tip: use control+Home to jump the cursor quickly to the top of the file for first line examination.)

  8. Press Control+s to both save, and recompile the script file. If successful, you should hear a happy sound from windows, and jaws should say, "compile complete."
    if you do, then Congratulations! That's it! your done! Press Alt+f4 to close the script manager. You Are now ready to try defining your first hotSpot.
fully HotSpotClicker connection code

What If My JSS File Already Contains Prior Information/code.

If after opening and exploring the jss file for the application to which you'd like to connect hsc, you find it already contains some prior code, then the next question you need to ask yourself, is, whether you feel you require the two additional hsc features referred to above.
Namely, the Automatic hsc set switching feature. and, Hsc Window prompt creator, "spot prompter."
if the answer is no, or your not really sure yet whether you will need those features or not, and you would just like to get up and running as quickly as possible, then we suggest simply following the simple main hotSpotClicker connection process below for now.
If however, you are already sure that you would like to add support for these 2 features, or, if you would like to add hotSpotClicker with auto set switching support to the internet explorer application, then please see: Adding support for auto set switching and spot prompter features to my non-blank jss file.

Assuming you have opened your application's jss file in the jaws script manager, and you've found it contains some prior script code, do the following to add main HotSpotClicker functionality to the application.

  1. Carefully select the line exactly as it appears below, and then press control+c, to copy it to the clipboard:
  2. use "HotSpotClicker.jsb"

  3. Press Alt+tab until you arrive at the jaws Script manager, with your application's jss file open.
  4. Insure your cursor is at the very top of your jss file, and at the very beginning of the first line, by pressing control+home, then the home key.
  5. Press Control+v, to paste this single line into the Jss file.
  6. Now press control+s, to both save and recompile the script file with the new hotSpotClicker support.
    If successful, you should hear a happy sound from windows, and jaws should say, "compile complete."
    That's it! your done! And You Are ready to try defining your first hotSpot.
Note: Just for technical information, any lines that you may see within your application's non-blank jss file, that have a semi-colon, as their left most character, are author comments, and as such, are not actually part of the compiled script code.

Adding support for auto set switching and spot prompter features to my non-blank jss file.

Do this if you want to install the complete set of HSC features.
If you are comfortable with the scripting language, you can discern the changes required simply by examining the full HotSpotClicker connection code But, for everybody else, the details are listed below.

Place focus in the application you are trying to adapt. In the following discussion, we will assume that you do not have a set of scripts from an author who does not provide the script source. In general, you can not connect HSC to such scripts, unless the author has chosen to install the necessary interfaces. And, attempting to recompile such scripts will most certainly require re-installation of the scripts. This is discussed more in Connecting HotSpotClicker To YourApplication In this section, we will assume that you are not connecting HSC to such proprietary scripts.

press insert+0 on the numbers row to open the script manager with a script file for that application. If none exists, one will be automatically created, and you can refer to the JSS Is Blank section For a quick way to create the necessary script file.

If, on the other hand, your file is not blank, then you should follow the directions in this section, to add the necessary lines to incorporate the clicker into your application. When all steps are complete, press control+s in the script manager to compile your scripts and place them in effect.

Near the top of the file, include the following statement, including the double quotes:
use "HotSpotClicker.jsb"
You can make that the top line of the script file if you like, or, if there are comment lines at the top of the file which start with a semicolon, you can move down past those comments, but prior to any script or function definitions. This allows your application file to link to the HotSpotClicker scripts for basic functionality.

To install automatic set switching, read and follow directions in the folowing section Can My Scripts Automatically Activate A HotSpot Set?

To install the window prompt feature, read and follow instructions in the section HSC window prompt creator Now, press control+s to compile your application scrip file, and then close the script manager.

This completes the connection between HSC and your application. When you place focus inyour application, a skeleton .HSC file will be created for that application, and a backup copy of the application JKM file will be created. Then, all the HSC master hotKeys will be added to the existing JKM file. then, you will be ready to start creating hot spots.

Once focused in your application, press control+alt+shift+h to view a list of all hotkeys assigned to the HotSpotClicker.

Dealing With JAWS Updates

Updating to a new version of jaws has some special considerations for maintaining HSC.
HotSpotClicker must be installed once into each version of jaws with which you wish to use it. If you are just updating jaws to a minor version, such as going from 12.0.170 to 12.0.171, you don't need to do anything. Since jaws 12 is still being used, HSC will still be installed. However, if you then install jaws 13, that new version of jaws will not have hotSpotClicker installed in it. So, you will need to run the installer again, selecting jaws 13 as the target.

If you then merge your old scripts over from jaws 12 to 13, any scripts which called upon HSC from the jaws 12 installation, will now call upon it in jaws 13. The first time HSC runs for an application, and does not find a basic hotSpot file for that application, HSC will create an original HotSpot Set for that application. This set will not inherit any hotSpots you had previously defined for jaws 12. So, you will need to copy those over manually, as shown below. And, if you already ran HSC at least once, since that new, blank hotSpot set will now exist, you be warned by windows, as to whether you really want to overwrite that file. The answer is that you do want to overwrite the new set with your original set from the old version of JAWS.
To make this least painfil, follow the steps below.

  1. Install the new version of jaws, but don't merge yet.
  2. Go to the windows start menu, find the old version of jaws, and choose, explore JAWS, then Explore My Settings. In your settings\enu folder of the old version of jaws, there is a Personalized Settings folder. In the Personalized Settings folder, HSC will create one subfolder for each application. Those subfolders each contain one or more .HSC files.
    You can recognize the folders by name, associating them mentally with applications for which you know you have HotSpots. Copy all of those folders into the equivalent Personalized Settings folder in the new version of jaws.
    If you were using HotSpotClicker prior to version 7.6, you will have a bunch of .HSC files in the Personalized Settings folder, rather than application folders. Hotspots created with version 7.6 or later will be organized into folders by application.
  3. Now, you are free to perform the merge, or to copy across all the script files you want from the old version. Those go in the settings\enu folder.
  4. Now that the HotSpots have been copied, run the HotSpotClicker installer to install HSC into the new version of JAWS
  5. When you focus in each HSC-connected application, the keymap should be updated. If it isn't, then go to the actions menu, and choose the item that says:
    Keymap, refresh.
    the key map for that application will be updated with your hotspot keys.

Including The clicker In Your Application's Keyboard Assignments.

When you focus in your application for the first time with the HotSpot clicker , the clicker will check your key map to see if the hot keys required for clicker operation are already installed. If not, it will install them automatically. Normally, this step requires no manual intervention on your part.

However, if any of those keys are already assigned to a different script, the virtual viewer will open, informing you of the conflict. press enter on the single link in that dialog to open your web browser, which will allow you to refer to a relevant location in the file you are presently reading for more information.

After the master hot keys have been installed for the first time, you may find that you have to place focus elsewhere, then return it to the application before the HotSpotClicker will start working. This is because some versions of JAWS, such as 6.0 and later, do not detect that the KeyMap file has been altered, and are operating out of memory. The elegant and proper solution for this problem has been attempted but, unfortunately, leads to other kinds of malfunctions which are even less desireable. So, switching focus away, then switching it back again is sometimes necessary to get JAWS properly initialized.

The KeyPressedEvent.

This is a special consideration when connecting HSC to Internet Explorer, but may apply to other applications as well. If you want to use HotSpotClicker with Internet Explorer, read this section for basic background, and also read and follow specific instructions in the next section.

For many applications, you don't have to be concerned with this section at all. however, If the clicker does not detect key presses when you are assigning a hot key during the hotspot creation process, the problem most likely relates to the KeyPressedEvent. This is a special function which is invoked by JAWS each time a key is pressed. This problem occurs when your application script has a KeyPressedEvent function, but that function does not also call KeyPressedEvent. What normally happens, is that there are several functions by the same name, and all of them should run. When a key is pressed, jaws calls the KeypressedEvent which resides in your script file. If no such function exists in your script file, then JAWS will look in the HotSpotClicker file, and call the KeyPressedEvent that resides there. But, if your script does have a KeyPressedEvent, then that function should also call a function by that same name. And, when it sees that second call, JAWS will invoke the version in the HotSpotClicker as well. In this way, both versions will run, which is what you want. But, if your script KeyPressedEvent, does not also call KeyPressedEvent, then the chain is broken, and the version in the HotSpotClicker does not run.

this is in fact, the precise situation that does occur when seeking to tie the hotspotClicker into the internet explorer5-6.jss script file.

Should you encounter this problem, in something other than Internet Explorer, revise your KeyPressedEvent as follows.

To find this function in your applicaition script file:
A.) focus in the application for which you are seeking to integrate hotspot clicker.
B.) press either JawsKey+TopRowNumber0, or jawsKey+f2, then s, then enter, to open the script manager with your application scripts loaded; C.) press control+f, and type the words "KeyPressedEvent" into the edit box, without quotation marks, and press enter.

If you find a KeyPressedEvent, Down arrow past any variable declarations, until you find the first line that does not start with any of the following:
var,
int,
string,
or a semicolon ";".
Just above that first executable line, make a blank line and paste in the following line, exactly as it appears below:

KeyPressedEvent (nKey, strKeyName, nIsBrailleKey, nIsScriptKey)

now, If after doing this, you get an error when saving/recompiling this file with control+s, it may be because the writer of your script has used different variable names in your KeyPressedEvent function than we show here. If that happens, then you need to make sure that the names mentioned in parentheses in the above pasted line, are the same as your script author used in the opening line of their KeypressedEvent.
You will need to Change the names in parenthisies within the above pasted line in that particular script, to match the ones used in the top line of the KeyPressedEvent function in the script file you are dealing with.

Connecting to Internet Explorer Scripts

The FS-supplied scripts for Internet explorer do not pass the KeyPressedEvent on to the default scripts in all cases. So, it is necessary to slightly modify the fs-supplied script code to tell HotSpotClicker about the key press.
Using the instructions in the previous section, open the InternetExplorer scripts, and find the KeyPressedEvent. Cursor down a few lines, until you find a block of code that looks like the following:

ProcessBXModifiedKey(strKeyName)
if UserBufferIsActive() then
KeyPressedEvent(nKey,strKeyName,nIsBrailleKey,nIsScriptKey) ; default
return
endIf

This block calls the default version of KeyPressedEvent, only if the userBuffer is active, and not otherwise. When that happens, HotSpotClicker will also receive the key stroke. But, when the user buffer is not active, which is most of the time, HSC will not receive the keystroke. For some reason, these scripts do not want the Kdefault version called under some circumstances. We can honor that by adding two extra lines to this block. This will allow HSC to be notified in cases where the user buffer is not active.

Insert two lines just above the endif as follows

else
HSCKeyPressed (nKey,strKeyName,nIsBrailleKey,nIsScriptKey) ; default
When you are done, that block of code should look like the following:

ProcessBXModifiedKey(strKeyName)
if UserBufferIsActive() then
KeyPressedEvent(nKey,strKeyName,nIsBrailleKey,nIsScriptKey) ; default
return
else
HSCKeyPressed (nKey,strKeyName,nIsBrailleKey,nIsScriptKey)

Installing Auto Set switching and the Spot Prompter feature.

Just to recap, remember, for basic hsc functionality in any application, you need to insert that
use "hotSpotClicker.jsb"
line into the application's script file, Save/Recompile that file with control+s, , and perhaps double check the keypressed event situation, for each application in which you want hsc to operate.

Please be aware however, that we have not yet installed the hsc spot prompter, nor the dynamic auto set switching facilities. If you are eager to just start defining hot spots as quickly as possible, without dealing with multiple hotspot sets, or spot prompts, then you can leave installation of those facilities to a later time.
However if you would like to take full advantage of all hsc has to offer, and would like to install these features now, then please see: Can My Scripts Automatically Activate A HotSpot Set? and, Hsc Window prompt creator, "spot prompter."

Key Conflicts.

There are two kinds of keyboard assignment conflicts that can occur.

Master Key Conflicts.

One opportunity for conflict, involves those keys which are installed by the clicker when you first run it with your application. This occurs when hot keys normally assigned to support the clicker operation are already assigned in your application's key map. you have two options:

  1. Open the JAWS Keyboard manager for your application, find and change the hot key, mentioned in the error message you received from the clicker, to a different hot key.
  2. tell the Hot Spot Clicker to use different key assignments. This is described in Changing Hot Key Assignments.

Hot spot Hot Key conflicts.

A second situation in which conflict can occur happens during normal operation when you are assigning hot spots, and you press a hot key that is already assigned to a script in your application's script file, or which has been assigned to a previously assigned hot spot which you are now redefining. In such cases, you can choose to overwrite the present assignment, or you can choose a different hot key for your hot spot by clicking the "no" button in the wizard. You will be prompted for a different hot key, or you can press cancel to terminate the process entirely.

How It Works.

Definitions.

First, a few definitions.

In this document, we use the shortcut symbol $jaws to refer to the complex full path to the personalized settings\enu folder. This is the path to the folder you open when you go to the start menu, type j until you hear your version of jaws, press right arrow twice to go to "explore my settings", and press enter. This path includes your user name, and thus is specific to your account. An example definition for $jaws is:
C:\Documents and Settings\MyUserName\Application Data\Freedom Scientific\JAWS\6.20\settings\enu

When we say hot spot, we mean a location where you would like to have the mouse either perform some kind of mouse click, or simply be moved to that location, to speak text or analyze color, or to serve as a starting point for a text or graphics search. Specialized forms of hotspots can set focus on the window in which they reside, or can switch to a different set of hotspots.

when we say Spot Prompt, or sometimes we say Window Prompt, we mean a window or control which should be monitored for acquiring focus, and an action which should be performed when focus lands in that window.

When we say toolTip, we mean an area on the screen which, when the mouse is allowed to dwell inside that area, displays a text label describing what will happen if you click there.

When we say Hot Key, we mean a user assigned key stroke which, when pressed, will activate the Hot Spot to which the Hot Key is assigned.

When we say Window, we mean a small region which JAWS thinks of as an area on the screen. These "windows" may or may not be apparent to a visual user, since they may not have visible borders. Usually, a larger area, such as a top level window, or an application main window, will be apparent. But, actually, every point on the screen is contained inside some kind of "window. That window may be very tiny, and may be completely included inside some larger window, which is called it's parent window. Windows are contain inside larger windows. And, at some point, some parent window, or grand parent window will be large enough to be made visible. edit boxes are windows, and usually are visible. Some other windows are not visible, but are known to the program, primarily for grouping items together for internal purposes, such as managing the dragging of controls.

So, when we talk about "the window containing the cursor", we are talking about the smallest window which completely encloses the cursor position, a window which may or may not have borders and be visible as a window to sighted users. A TopLevelWindow is usually a larger window that contains the child, and which has a title bar, but is contained inside the application main window. The application main window is usually the entire application, containing all windows for that application.
the key point of all this, is simply to alert you that there are more windows on screen than sighted people are aware of, and that JAWS makes use of these windows to identify various portions of the program. The JAWS HomeRow utility, activated with jawsKey+Spacebar is a rudamentary way for interested parties to navigate and explore the windows hierarchy, should that become necesary.

Creating And Activating Hotspots

The first thing to do is to position a cursor at the location where the spot should be defined. HSC will grab the location of whichever cursor is active at the time the spot is defined. If you are collaborating with a sighted person, who will be positioning the mouse prior to definition, then make sure the jaws cursor is active before defining the spot. Any spot that will require some kind of mouse click action shoudl be defined using the jaws cursor. However, for cases that do not involvemouse clicks, the invisible cursor, which will be moved when the spot is executed, provides less distraction for visual users, and also will not be noticed by the application, which may actually change screen appearance as the mouse moves around, complicating matters in cases where color searches are required. In general, consider using the invisible cursor if you don't need the spot to do mouse clicks.

HotSpotClicker integrates with existing custom scripts for your application, and allows you to position the active cursor at a screen location of interest, then to press a special hot key which captures the screen location, and other relevant information defining that location, and leads you through a short series of dialogs which allow you to fully define the Hot Spot, including the method to use when specifying the location, the kind of mouse action to be performed, and the name of the hot spot. You can assign a Hot Key to the Hot spot if you like, or you can simply identify the Hot Spot by specifying a text label. You can select whether the label should be spoken when activating the hot spot. All this information is stored in a file which is associated with the application with focus when you define the hot spot.

there are two ways of activating a hot spot. If a hot key has been assigned, you can simply press the hot key to activate it. Or you can bring up a list of all currently active hot spots, arrow through the list, or simply type the first letter or letters of the hotspot label you wish to directly jump to, and press enter on the item of your choice to activate it. Those hot spots which have hot keys assigned will also list the key assignment.

The processing which occurs upon hotspot activation can be summarized as follows:

  1. The user activates the hotspot, either by pressing the associated hot key, or choosing the hotspot from a list and pressing enter.
  2. HSC positions the jaws or invisible cursor, depending on which was active when the HotSpot was defined, at the target location. This can also include searching a small area around the hotspot for a graphic, one of a list of colors, or even searching a window for a graphic name or a string of onscreen text. The invisible cursor should be used if no mouse click is required, and the application responds to the mouse ghobering over a location by changing the visual appearance. Such changes can affect the success of color or graphics searches.
  3. Optionally, a user-supplied function can be run to modify, or further qualify the cursor location.
  4. HSC performs the mouse action, if any, including all the various forms of mouse click.
  5. Finally, a user supplied function can be run, if desired, to take any required action in the form of post-click processing.

You can also create multiple sets of hot spots. A special hot key brings up a list of existing sets, allowing you to choose the set to be activated, or to create a new hotspot set. Only one set is active at any one time, but that set will be active, even if you close and reopen the application.

You can also configure hotspot clicker, so that certain hotspot sets will automatically become active when specific windos, or parts of your application, gain focus. This makes it very convenient both to assign new hotspots as you learn about them, and have them be saved to the correct set for that situation, and also to have available in the hotspot list, only those relevant to the window with focus.
you can also have hotspotClicker load a hotspot set as part of a user created custom function, that can be attached to any hotspot itself, for situations in which there is no topLevelWindow change to trigger a set to load automatically.

For more information about creating additional sets, see Creating Additional Sets Of Hot Spots.

**There

Deleting A Hot Spot.

Firstly, it is important to make sure the proper HotSpot set is selected. if you have multiple sets of hotSpots defined, double click the control+alt+shift+f1 key, then use the arrow keys to make sure the set containing the hot spot you want to delete is selected as the active set. then, press enter to close that dialog.

With the proper HotSpot set selected, tripple click the Control+alt+Shift+f1 key. This will bring up a list of Hotspots in the current set. This dialog looks very much like the HotSpot help dialog. The top line of this buffer indicates whether you are actually viewing a list of hotspots, or a list of window prompts. press enter on this line to toggle to the opposite view. The rest of the language in this section refers to hotspots. but, the principals are the same, even if you are actually deleting window prompts.

Once you have selected the view you want, use the arrow keys to select the HotSpot you wish to delete, and press enter.

You will then be presented with a confirmation dialog, which allows you to confirm that you actually do wish to delete that hotSpot. The default answer is "no". so, shift+tab, or leftArrow, to the yes button, and press enter. the Selected Hotspot will be deleted from the currently active set, and the hot key, if is not attached to a hotspot in another set, will be removed from your application's key map.

remember, it is not really necessary to delete a hot spot before redefining it.You can just define it again, and the new definition will replace the old one, which will be saved by it's label. Or, if a spot by that name already exists, HSC will prompt you for a label by which the old spot should be saved.

Master Hot Keys

When HotSpotClicker is first connected to your application, it updates the key map for that application with the hot keys necessary to operate the clicker.

Unless otherwise noted, all HSC hot keys use the control+alt+shift modifiers together, in an effort to avoid most commonly used key assignments. a file is provided to allow you to change these assignments if necessary. This is discussed more in Key Conflicts

One of the primary hotkeys, (Control+alt+shift+A,), is assigned to initiate one of the two alternate versions of the hot spot assignment process.
The second primary operation hotkey, is assigned to the expanded hotspot assignment wizard, for identifying text string, color, or graphic searche criteria, control+alt+shift+g.
The third primary operation hotkey, (Control+alt+Shift+f1), is a multi purpose hotkey, selectable via single, double or tripple clicking the key. A single press of the key brings up the list of currently assigned hot spots in the currently active set.
Double clicking the key allows selection of the active set from the list of available sets, and provides the option to create a new set.
Tripple clicking that same key lets you select a hot spot to be deleted from the currently active set. For a complete list of hot keys, see List Of Hot Keys. or press Control+Alt+Shift+h in an application into which the hsc has been installed, and use the arrow keys to browse the list.

HotSpot Sets

For many users, it may not be necessary to have more than one hotspot set per application. However, Often, it will be the case that clicking the same exact screen location, does different things in different situations. While it is certainly possible to assign two hot spots in the same set to the same location with different HotSpot labels, and different shortcut keys, placing those two hotSpots in different sets helps prevent confusion which could lead to taking the wrong action at the wrong time.

You can define hotSpot sets which are unique to a particular internet web page in internet explorer. When a web page loads, for which you have defined a hotSpot set, the set can load automatically. This is discussed in more detail in Loading A Set Based On A Web Page URL

In other situations, complex aplications can host a multitude of mini-applications, often referred to as "pluggins". Again, the use of multiple Hot spot sets facilitates management of hot spots, localized to the context in which they are relevant, and helps make more efficient use of hot keys, since the same physical hot key can be used in multiple hot spot sets. But, it can be assigned to different meaningful names, and click different screen locations in each hot spot set.

For example, in audio/midi editing programs such as sound forge or sonar, which can hoast a number of soft synth and effects pluggins, it may be desirable to create a separate hotspot set for each of these pluggins. This may both facilitate faster and more efficient navigation to each hotspot within the list of available hotspots limited to that pluggin, and could enable the assignment of identical hotkeys to similar functions or parameters, in a variety of pluggin applications.

For example, you may find you have more than one type of compressor, reverb or soft synthesizer pluggin that you'd like to use, which all have similar parameters. Such as reverb time, compressor attack, effect mix, filter envelope etc, to which you'd like to assign identical hotkeys in each separate pluggin.

You might assign control+Shift+r to double click in a Reverb time edit box in one reverb pluggin, but the screen location which must be clicked in order to edit that parameter in another reverb pluggin, is almost certainly going to be quite different; In addition, this second alternate reverb pluggin may only provide graphical knobs, with no edit boxes at all, to interface with parameter values.
No problem! You can define one hotspot set for each pluggin, and have a unique hotspot in each set, which can perform different mouse actions suitable to operating that control in it's environment, that is dedicated to Reverb time. But, you can attach control+Shift+r to each of those hotspots. so, no matter which pluggin is active at the time, control+shift+r is always the magic key which you would use to edit Reverb time, using whatever method the individual pluggin requires.

Techniques like this would make it easier to both remember the shortcut key to activate that hotspot, or to locate identical hotspot labels for those parameters within the hotspot list for each pluggin, within each hotspot set.

Creating additional Sets Of Hotspots.

You can define additional sets of hot spots, at any time, by following the steps in this section. If you only want one set for now. you can skip to the next heading.

When you create a new set, consider whether you might like taht set to be loaded automatically as you operate your application. HSC will suggest an appropriate set name based on the method that will be used to activate the new set. For the typical non-internet application, the technique to use would be window title based switching. However, if you are building a set for a web page, or a subpage of a web site, the technique to be used will be URL based switching. Before creating a new set, double click the hsc mods f1 key. Down at the bottom of that dialog, you can choose which technique to use. If HSC says that automatic window title switching is not installed, refer to the installation instructions for how to connect HSC to your application. Usually, this means that the function HSCFocusChanged is not being called from the applications FocusChangedEvent.
Once that is installed correctly, you can enable automatic window title switching.

If you only want to activate the set manually, neither autimatic option needs to be selected.

Once you have selected the method for automatic activation. Change your application to focus in a different TopLevelWindow, for which you would like to create a hot spot set. Then Double click the Control+Alt+shift+f1 key to see the list of sets currently available. Initially, only one set will exist, which will be named after the application main window. Arrow down to the item that says
Create a New Hot Spot Set,
and press enter.

If web page switching is being used, jaws will ask if you want to create a set for the specific page that is loaded, or to create a set for the entire domain. In this case, if you use automatic switching, HSC wil look for an exact match between the address of the page being loaded, and a set name. If it does not find an exact match, it will look for a set for the entire domain. If that is not found, it will load the generic internet explorer main set.

If Window title switching is being used, An edit box will open, showing the ToplevelWindow name which jaws suggests as the name for this new set. At a minimum, you should remove information from this string which will change as your application is operated. Leave only those characters which will always be present in the top level window name. If you prefer, you can totally arase the suggested name, and type in one of your own. However, if you plan to have JAWS switch hot spot sets automatically, as described in: Can My Scripts Automatically Activate A HotSpot Set?, then it is recommended that you use a name which is derived from the name suggested.

Once your name has been finalized, press enter. A new .HSC file will be created based on the name you entered,, and the new set will become the active set.

You will have been returned to your application, ready to begin defining hotspots in your newly created set, for that portion of your program. The set will initially be empty. However, any hot spots you define while this set is the active set, will be added to this set.

Tip: It is perfectly valid to have multiple sets, with different user friendly names, but referring to the same exact .HSC file. This might be appropriate if one common set will be used in multiple situations, but you would like to refer to them using different names. To do this, you must manually edit your main .HSC file, and add a line to the [hotspot file list] which looks like this:
YourFriendlyName=Filename.hsc
Where "YourFriendlyName" is a name you create, and the filename.hsc is the name of an existing hot spot set file in your Personalized Settings folder.

For information on how to allow your custom scripts to automatically cause the clicker to activate a different set of hot spots, see: Can My Scripts Automatically Activate A HotSpot Set?

Activating A HotSpot Set.

To manually choose which hotspot set is active, double click Control+alt+shift+f1. A dialog will open, listing the currently defined sets. The currently active set will be highlighted. Use your arrow keys to select the desired set and press enter. The new set will now be active.

Remember, you can also define a hotspot to switch to a new hotspot set, so you can load additional sets at the touch of a key. When defining the hot key, choose, "switch to a different hotspot set" as the positioning mode.

to have the set loaded automatically, read the section entitled Can My Scripts Automatically Activate A HotSpot Set?

Loading A Set Based On A Web Page URL

Using HotSpotClicker to manipulate a web page is tricky, and a bit unstable, because HSC works in terms of fixed locations relative to certain key items, such as window borders or text strings on screen. Because most web pages are too complex to fit on one screen, the page must be scrolled as you arrow around the page. This means that items appear to move, and for example, a text string you are searching for may be on the web page, but not currently on the screen. Still, patient and persistent people have had success with HSC in that environment.

More success can be achieved by using virtual cursor relative positioning, because the virtual cursor can force the screen to update to place the located virtual item on screen. Additional positioning to a fixed distance from the virtual cursor is supported.

This feature lets you define a hotSpot set, named according to the URL of the page currently loaded. If automatic URL switching is enabled, as controlled by the URL switching option in the double click of HSC mods f1 dialog, then the hotSpot set will automatically load when the web page loads. Just as with window title switching, if you manually choose a set from that dialog, then the automatic URL switching option is disabled.

Window title automatic switching is discussed in Can My Scripts Automatically Activate A HotSpot Set?

HSC is specifically defined to cooperate with Internet Explorer, but could be extended to other browsers with small modifications to the code. The main HSC file will be the Internet Explorer.hsc file, and each web page you visit could be a hotspot set.

The rules governing which set will be loaded automatically are as follows:

  1. if there is a set for the current page, use that set.
  2. If not, if there is a set for the main page for this site, then use that set.
  3. If not, then use the Internet Explorer main set.
Of course, you can always switch sets manually to any set you want.

For example, supposed you defined two sets, google.com and google.com/x. if the page currently open in your browser is google.com/x, then google.com/x.hsc will be loaded.
If you back out to google.com, then google.com.hsc will be loaded.
If you navigate to google.com/y, there is no set for that, but there is a set for the base page google.com, so google.com.hsc will be loaded.
If you now move to FreedomScientific.com, there is no set of any kind for that, not even the base page, so Internet Explorer.hsc will be loaded.

A filtering option has been added to the double click of hsc mods+f1, which allows you to only see set names which are associated with the current site. To toggle that filtering on or off, go to the jaws verbosity menu, and choose URL filtering. Press space bar to turn it on or off. When, off, all html related sets are displayed when Internet Explorer is the current application
If this option is enabled, then, from our examples above, the google sets would only appear in the list, if google.com, or one of the google subpages is loaded.

Organizing Spots Into Sets

Very often, in the interests of just getting up and running, you may start creating hotspots and window prompts for your application before you really have a good understanding of how your application is organized. All of your early hotspots and prompts will be contained in the main, default set. But, as you become more familiar with the application, you may realize that organizing hotspots and window prompts into sets provides a lot of convenience and clarity, and can dramatically increase the efficiency of your usage of hotkey real estate.

First, you must create the sets into which things will be shuffled. Double click HSC mods+f1, and choose "Create A new Set". As a default name of the new set, HSC will offer the name of the topLevel window that has focus at the time you create the set. If you wish to have HSC activate the new set automatically, you should use the offered name, taking care to remove dynamic information from the name. However, if you are willing to switch manually, you can specify any name you like, assuming it doesn't conflict with any existing set, or any automatic set you will want to create in the future. If you need to change a set name, you can do it manually by renaming the corresponding .hsc file, and by changing the corresponding entry in the [hotspot file list] section of the main .hsc file.

Once you have created your new sets, you can now move or copy hotspots or window prompts from the main set into any of your secondary sets.
Press hsc mods+f5 to bring up the organizer, and choose an organizing activity. Once you choose the activity, and then specify a target set, HSC will present a list of items of the chosen type, from the currently active set, on which you can perform the selected action. Press enter to perform the action. The list will remain open, so you can perform the same action on other items in the currently active set.
You will notice that, if you move an item, it will no longer appear in the list, since it no longer resides in the source set. Press escape when you have finished with those items.
If you want to perform a different action, or specify a different target set, you must press escape to close the organizer, then start it up again with hsc mods+f5.

Deleting a HotSpot Set.

To delete an entire secondary hotspot set, double click control+alt+shift+f1, and choose Delete A Hotspot Set from the menu. Then, select the set you wish to delete and press enter. If you answer yes to the cconfirmation, all hotspots in that set will be deleted, and the set will be removed. Also, all hotkeys which are unique to the deleted set will be removed from the jaws key map.

Importing A HotSpot Set

Use this when someone gives you a HotSpot set which you want to incorporate into the hotspots you have already created for that same application. You must have allowed HSC to create the main set first.
Plase the .hsc files containing the new sets into the folder for your application, in the Base Folder. Double click control+alt+shift+f1, and choose Import A HotSpot set.
You can then choose the name of the new set from the list provided. Or, if multiple sets are involved, you can choose Import All Sets, to force all listed sets to be imported.
The files will be updated, and the key map will be refreshed with the new keys from the imported set, or sets.

The set name will be inferred from TopLevelWindowName data inside the imported set. If you are importing an individual set, an edit box will open, allowing you to change that set name if you like. However, if automatic set switching is to be employed, you should accept the set name as suggested by HSC, since it will be expected to match the topLevelWindow name which will appear when the set should be activated.

Delete A HotSpot Set

Double click control+alt+shift+f1, and choose Delete A Hotspot Set. The Set will be removed, and any hotkeys, associated solely with hotSpots in the set being deleted will be deleted from your keymap. The .HSC file will be deleted from your system. This operation is permanent.

Copy A HotSpot Set

Use this when you want to clone a hotspot set. For example, if you want two sets which are nearly identical, but with a few minor changes, you can copy the original set, and then substitute new hotspots for those which need to be different in the new set. Double click control+alt+shift+f1, and choose Copy A HotSpot Set.

Custom Documentation

If you create a set of hotspots you want to share with others, you might want to create a custom help file, to convey more detailed information to describe the use of your HotSpots. HSC allows you to create two levels of custom help for each hotspot set.
The first level is a custom hotKey summary. If you choose to create this level, then, your users can double click hsc mods+h, and read your custom summary. The first level help for the currently active set, if it is present, will be displayed in the virtual viewer, and can contain links which, when activated, will execute the hotspots you choose to mention in your summary.

In addition, you can creaate extended, detailed documentation of your hotspot set, which is referenced from the custom summary, and which will open in a separate window, based on the kind of file you choose to create. For example, if you create an .HTML file, your web browser will open, showing the second level help document, allowing your users to alt tab back and forth between that document, and the adapted application.

But, you must first create the custom summary in order to provide a link from HSC to your detailed file. In the next few paragraphs, we'll describe how to create the first level custom file, and how to encode the links, either to hotspots in the currently active set, or to the detailed document.

In the Base Folder there is one subfolder for each application into which the .hsc files for that application are placed.
Note that HotSpotClicker prior to version 7.5 did not organize in this structure, but simply placed all .hsc files in the PersonalizedSettings folder. However, you can freely organize them into such folders manually, as long as the folder name is the same as the jaws configuration used for that application. HotSpotClicker will still find them.

To create the first level summary, inside the folder for your application, make a .txt file for each .hsc file you want to document. For example, if your set name is myApp.hsc, then create myApp.txt. the file is a free-format text file with two special considerations.

If you want to create a link to a hotspot in this set, you should enclose the hotspot name, or hotkey if one is attached, in less than and greater signs. All text on the line containing such a tag will be assumed to be the link text for activating that hotSpot. For example:
To speak the total, press <control+shift+1>
Note, don't rely on word wrap to do this. Press enter before starting a line which you intend to be a link, and enter again at the end of that line.

To create a link to your second level detailed document, specify the name of the file, including the extension, in a tag that looks like the following:
Read the detailed help document here <help=My detailed Help Document.html>

The example above is only illustrative. The words outside the enclosed tag on this line will form the text of the link associated with this file.
Note that the only spaces in this tag, are those which are actually part of the file name. But don't put spaces around the equal sign, Note also, just as above, don't rely on word wrap to do this. Press enter before starting a line which you intend to be a link, and enter again at the end of that line.

The detailed document is assumed to be placed in the same folder as the rest of the .hsc files for this application. It is not possible to Specify an alternate path name in this tag. The application which will open to display the file will be whatever application is associated with the file extension on the client's computer.

To omit the first-level virtual viewer file, and have double click of hsc mods +h jump directly to the detailed document, you must still provide a setName.txt file. But, the file should contain a single line, which defines the link to the detailed help file. If, for example, your detailed document was an html file, The single line should look like this:
<help=MyDetailedHelpFile.html>
If the first-level .txt file contains that single line, the virtual viewer will not open. Instead, the application associated with the extension you provide will open with the detailed document.

Positioning Methods.

Initially, The most obvious way to implement a clicker feature like this, might seem to be to simply have JAWS click at a pixel address relative to the edges of the screen. However such an unqualified technique has it's drawbacks, and is clearly an approach of last resort. The problem is that in such a case, JAWS will be blindly clicking at a predetermined screen location. If your screen is resized, or the application is dragged around, or in some special mode, clicking on a fixed screen location can have unexpected and unintended consequences. To help deal with this, you can specify one of several modes for establishing your screen location which can help adjust your locations for changes in screen format.

Positioning methods relate to how HSC determines the screen coordinates for the hotspot in question. In general, your screen is composed of individual dots of light, called pixels, which are arranged in a standard, square grid pattern. A particular location on the screen can be identified by specifying the number of pixels in from the left side, and a number of pixels down from the top of the screen. but, as you will see, HSC has some more sophisticated ways of determining screen locations.

If you feel unsure about which positioning method to use, don't be surprised. It is not always a clear cut decision. and, sometimes experimentation is the only way to know for sure. But, in most situations, you can not simply edit the definition, and change the positioning mode, because other information in the definition would need to change as well. To use a different positioning method, it is best to delete the hotspot, and redefine it from scratch with a different positioning mode.

If you get that hotSpot working, only to find later that it doesn't work any more, using the incorrect positioning method is one likely cause of such failures. Not faithfully removing dynamic information from window names is another likely cause.

For most situations, Application or Toplevelwindow relative positioning is a pretty good guess. but, in case it helps clarify, following is additional discussion of these methods.

Absolute Positioning

this method records the pixel addresses relative to the top and left edges of the screen. With this mode, you can even click locations outside your application, which can be useful, so long as the same exact set of applications is opened, with all of them in the same state, as when you defined the Hotspot. the disadvantage is that, if any of your applications are dragged around, the absolute location will not map to the same spot in your aplication window. If screen absolute positioning is used, then no validation is performed at all. The mouse click is simply performed at that absolute pixel address, without regard to any window criteria, or what application resides at that location at the time. this is really the most brute force method. Some applications are so horrible, that the JAWS functions which acquire things like control ID's or window names, simply return the same values for every window in the applicaition. so, no distinction can be made between various windows. This method essentially frees you from any restrictions, and just lets you click anywhere you want, regardless of how the screen changes.

Application Positioning

This method records pixel addresses as the number of pixels from the top and left edges of your application main window. In this mode, the hot spot will move as your application is moved. At the time the hot spot is activated, the clicker moves to the intended location inside the application, and determines the attributes of the window which presently contains that location. The clicker expects those attributes to match the class, name, control ID, type and subtype codes of the child window which were present at that same location, at the time the hot spot was defined. Overriding these child window criteria, allowing the hotspot to be considered valid, so long as the application window attributes are correct, is discussed in: Customizing Comparison Criteria. This method is good for relatively simple applications, where a given location always performs the same function.

If Application relative, or TopLevelwindow positioning is used to define the HotSpot, then the hot spot will normally work only when the hotspot location lies inside the same window that was present at definition time. In other words, at the time the hot spot is defined, these scrips capture the class, name, control ID, TypeCode, and SubtypeCode of the window containing the mouse. When you activate the hot spot, jaws will expect that point to lie in a window matching all those criteria, and will not perform the mouse click if the criteria are not satisfied. To disable that check, and allow clicking outside the reference window, set the RestrictToWindow parameter in the definition to 0. The diference between these, is which window will serve as the reference point for determining the hot spot location. HSC records the absolute row and column, but those are not used in these modes. Only the WindowColumn and Windowrow values are used, and represent the distances from the top and left borders of the chosen window.

Parameters WindowRowbottom and WindowcolumnRight are filled in as well, and represent the distances between the hotSpot location, and the bottom and right sides of the windows respectively. These are used when you want to use a different corner of the window as a reference.

In Application Relative positioning - the cursor is positioned relative to the top and left edges of the application main window. The same location will be clicked, no matter what item has focus at the time the click is performed.
A disadvantage, is that, if the point of interest lies inside some child window, and that child window is moved around for some reason, then the actual point of interest will also move, and will no longer match the location of the originally defined hotspot. This would mean that activating that hotspot would cause the mouse to click at the wrong location, and will not produce the desired results.

Application Plus Current Relative

This method takes a 2-level approach to identifying the position. At the time the spot is defined, the cursor position is recorded in two separate ways. The distance from the top left corner of the application is recorded, along with the distances from the top left corner of the smallest window containing the active cursor . The data that identifies the window, such as name, class, etc, pertain to that smaller window.

AT activation time, HSC indexes from the top left corner of the application, using the first set of coordinates. It then picks up the handle of the window that contains that indexed point. It then uses the second pair of coordinates to index the window it finds there.

This technique is good for cases where the smaller window does not have a name, or can not otherwise be uniquely identified, and found through a search. It presumes that, even though the smaller window may shift around some, it will not shift so far that the original spot location will no longer be inside that window. The first set of coordinates is simply used to find that window in the application frame, rather than a search, or some other technique. The second set is used to adjust the spot location to track the movement of the smaller window.

TopLevelWindow Positioning

This mode establishes it's coordinates relative to the edges of what JAWS thinks is the TopLevelWindow, as acquired through the GetTopLevelWindow builtin function. The window in question is usually some inner portion of the application which contains the control which presently has focus. This method is good for hotspots which are only valid when certain portions of the application have focus. Use this method when you want to prevent clicking when focus is not correct, or when clicking here will not bring focus to the desired portion of the program. The window at the hotspot location inside the application is validated based on the class, name, control ID, type and subtype codes of that same point, captured at the time the hot spot was defined. Again, to generalize this definition, ignoring the child window attributes, see: Customizing Comparison Criteria. If TopLevelWindow positioning is used to define the HotSpot, then the hot spot will normally work only when the hotspot location lies inside the same window that was present at definition time. In other words, at the time the hot spot is defined, these scrips capture the class, name, control ID, TypeCode, and SubtypeCode of the window containing the mouse. When you activate the hot spot, jaws will expect that point to lie in a window matching all those criteria, and will not normally perform the mouse click if the criteria are not satisfied. To disable that check, and allow clicking outside the wreference window, set the RestrictToWindow parameter in the definition to 0. The diference between this and application positioning mode, is which window will serve as the reference point for determining the hot spot location. HSC records the absolute row and column, but those are not used in these modes. The WindowColumn and Windowrow values are used, and represent the distances from the top and left borders of the chosen window. Parameters WindowRowbottom and WindowcolumnRight are filled in as well, and represent the distances between the hotSpot location, and the bottom and right sides of the windows respectively.

in TopLevelwindow positioning - the clicker starts with the window with focus, and drills upward in the windows hierarchy, looking for what JAWS considers a "topLevelwindow". . the cursor is positioned relative to the top and left edges of this topLevelwindow. Usually, this is some smaller window, contained inside the application main window, which has a title, and usually represents the area in which you are presently working. If this inner top level window gets moved around, your hot spot location will move along with it, making it more likely that the click location will still be in the correct place, to invoke the originally desired result.
The disadvantage with this positioning mode is that,if you are not focused on an item within the window which has the same toplevelWindowName as the one captured by your hotspot when you defined it, then you will receive an error announcement regarding unexpected topLevelWindowName, and you will need to operate the application to place focus within the window where the hotspot was initially defined.

To take a trivial example, suppose you are in NotePad, and have popped open the file open dialog. Initially, the edit box where you would type the filename has focus. the top level window is the file open dialog itself. That dialog is a smaller window which resides inside the notepad application main window. So, the main window contains the dialog, which contains the edit box. If you set a hotspot on the edit box, both methods would record the attributes of the edit box, and expect the spot location to reside inside a window with those same attributes. Application positioning would record the position as the distance from the top and left edges of the application main window. But, top level positioning would first check to see what control had focus, then find its top level window, which is the dialog, and record the position as the distance from the top and left edges of that dialog, and would also record the attributes of the dialog itself.
At activation time, Application positioning would find the application main window, jump so many pixels in from the top left corner, and expect to find an edit box. It could be a totally different dialog, but as long as it found an edit box at that location, the spot would be valid. On the other hand, topLevel positioning would determine what control had focus, find it's top level window, verify that that top level window had the correct attributes, and then jump in so many pixels from the top left corner of the top level window, and verify that an edit box resides at that locaition. In this case, if the dialog was not the correct dialog, the spot would have been considered invalid.

TopLevel Hierarchical

This method determines the smallest window enclosing the mouse at definition time, and then creates a series of instructions on how to use the window hierarchy to climb through the window structure,to find the TopLevel Window. It then records those instructions, along with the cursor position relative to that small inner window into the hotSpot definition.

At activation time, HSC finds the window with focus, uses that window to find the TopLevel window that contains focus, then uses the instructions, in reverse order, to descend from the TopLevel Windo down to the window of interest. Finally, it indexes the mouse against the top left corner of that small inner window to find the actual spot location.

Spots of this form are discussed in more detail in Window Browser

Window Search Positioning

This mode records the location inside the smallest window presently containing the mouse, along with the window name, real window name, Application window name, control ID, Type, subtype and Class of the window. When the hot spot is activated, a system-wide search is made for a window matching all those criteria. When it is found, then the cursor is positioned relative to one of the corners of that window. This method can be used when the window of interest is uniquely named, and can be found by searching the logical hierarchy. It doesn't much matter where the window resides physically.

If Window search Relative positioning is used, then, HSC does a system wide search for a window matching all the criteria specified in the .HSC file. It first searches the application, then expands the search to the rest of the system. Only if such a window is found will a hot spot be activated. this mode can be useful if you wish to try and activate a hotspot in a window which may not currently have focus, but which may be partially visible onscreen. It is also especially good for pluggins, or little applets that are spawned off of the main application.

Focus Window Rlative Positioning

This mode is good when you have several similar windows, each of which might have focus, and you want to define a hotSpot which is positioned relative to the edges of the window with focus. So, your hotSpot will move around, as you change focus from one window to the next.
When you define a spot like this, the jaws cursor must first be placed inside the window that has focus at the time.
At the time the spot is activated, the attributes of the window with focus will be compared with the attributes specified in the HotSpot definition. To get a spot like qthis to be valid for all of the windows that might have focus, it is often necessary to generalize some of the validation criteria after the spot has been defined. This is discussed more in: CustomizingComparisonCriteria

Current Mouse Position relative positioning

This kind of spot is used to perform some action based on the location of the mouse at the time the spot is activated. The spot does not position the mouse, but depends on unspecified previous activities to establish the position. A typical use for this is as the second spot in a chain, where the first spot positions the mouse, and validates the position, then chains to a Mouse relative spot to perform some processing.

When defining a spot like this, position the mouse at a location that will be typical of the kind of location at which this spot will be used. From that, you can establish color, graphics, window class information, and other data that will help the spot do it's job. In practice, the spot will be used at this, and other similar locations, where identical factors are present.

Choosing a Reference Corner.

For hotspots using Application, Application Plus Current, TopLevel, Window Search or focus window positioning modes, you can choose which corner of the window will serve as the positioning reference. For all new hotspots, generated using HSC version 7.6 or later, a parameter called ReferenceCorner will be added to the definition. The parameter will be defaulted to TopLeft, consistent with earlier behavior, but can be changed to reference any of the other three corners of the reference window, using the definition editor, attached to hsc mods plus f4.

Older hotspots do not contain this parameter, and are defaulted to assume topLeft referencing. However, you can add this numeric parameter manually, using the definition editor. Also, due to errors in how the two alternative row and collumn numbers were generated in older versions of HSC, you must also modify WindowRowBottom and windowColumnright to be negative numbers. This is consistent with the principle that positive numbers move to the right, and down the screen, while negative numbers move left, and up screen from the reference corner

PC or Virtual Cursor Relative Positioning.

When you choose to position relative to a cursor, HSC will offer virtual cursor or pc cursor modes automatically, based on which cursor is active at the time the hotSpot is defined. This is true even if you switch to the jaws cursor before defining the spot. The key is, which cursor will become active when you press the pc cursor key. In this section, the term, active cursor, is intended to refer to that cursor.

This mode records the distance from the JAWS cursor to the active cursor at the time you create the hotspot. There are three flavors of this mode, whether to track horizontally, vertically, or both. Depending on your choice, either, or Both horizontal and vertacal distances are recorded. In this way, the hot spot will track along with your active cursor. Window validation is very similar to TopLevelWindow mode, and that top level window serves as the context for any graphics, color, or text positioning adjustments you specify.

If Cursor relative positioning is used, your hot spot can be defined to be so many pixels away from that cursor. In this way, the hotspot can move around as the virtual, or PC cursor moves. this is good for cases such as when you want to move the PC cursor up and down a list, or a table, and you want to be able to quickly read a different column of text in the same row, or a different line in the same column. but, your hot spot doesn't have to be horizontally or vertically paralell with the active cursor. It can be up and to the right, down and to the left, or at any angle.

PC Cursor Row, means that the hot spot is assumed to be on the same row as the PC cursor. The position of the jaws cursor, relative to the PC cursor when the hotspot is defined, determines how far to the left or right the hotspot is located. An example of usage might be, if you were pressing down arrow to hear a table, one row at a time, speaking from left to right, but the information you want the hotspot to report is at the far right end of the line. You don't want to listen to all the front end stuff first. a PC Cursor row hotspot would move down along side your PC cursor, staying the prescribed distance to the left or right. In this mode, you can modify the WindowRow parameter in the definition, to create a fixed vertical offset as well.

PC Cursor Column means that the hotspot is directly above or below the PC cursor. As the PC cursor moved left or right, the hotspot would move left or right accordingly to stay positioned directly above or below the PC cursor. For example, this might be used to check a collumn heading, as you move across a row in a table. In this mode, you can modify the WindowColumn parameter in the definition, to create a fixed horizontal offset as well.

PC Cursor Both, means that your hotspot will move in both dimensions as the PC cursor moves. to help validate PC or virtual Cursor relative hotspots, HSC will expect the TopLevelWindow of the window with focus to be the same as when the hotspot was defined. If you do any text or graphics searches starting at the hotspot location, the toplevelWindow will be used as the window in which the search is performed.

Setting Focus.

Use this positioning mode when you want a hotspot to set focus on a window or control. HSC captures the attributes of the window with focus at the time the spot is defined. At activation time, HSC does a application-wide search for a window matching all those criteria and, if it is found, sets focus on that window.

Set Switching ShortCut.

use this special positioning mode when you want your hot key to cause a different hot spot set to be loaded. During the definition wizard, you are presented with a list of existing hotspot sets, from which you can select one to be activated. You can change this selection at a later time by using the definition editor, and modifying the TargetSet parameter to contain the name of the desired hotspot set.

Activate a Spot Ring

A Spot ring is a way to group selected HotSpots into a circular list which you can use special hot keys to navigate. SpotRings are discussed more in HotSpot Rings. But, they do exist, and there can be several of them. And, you can define a hotspot to simply activate a particular spot ring. If you chose this special positioning option when defining the spot, you would be presented with a list of currently existing spot rings, and be asked to choose the specific ring you want to have the spot activate. This kind of spot doesn't click anywhere, or do anything to the application. It just makes the selected spot ring become the active ring. You must define the SpotRing first, before it's name will turn up in the list of possibilities.

Starting in build 232, any spot, in addition to it's action, will also activate a spot ring if you edit the definition and add the name of your spot ring to the TargetRing parameter.

Virtual Cursor Positioning

This positioning method is good for web pages, It defines the spot to exist at a particular line number in the virtual document. And, if you are using a version of jaws wherein the routeJawsToVirtual function works correctly, you can have the spot take the mouse to the place represented by the line numberin the virtual document, where you can perform the usual complement of actions. Not all versions of JAWS perform this routing correctly.

Dynamic Window Names.


At the time the hotspot is defined, the wizard will present all window names in an edit box, allowing you to edit that information if required.

* Important: if various window names include dynamic information, such as document names or other information which may not remain constant for any number of reasons, and this information is not correctly removed, then the hotspot will fail when that dynamic information changes. you can edit the entry at definition time to leave only the information that is constant. You can also revise this information at a later time.
Incorrect assumptions about which windowname information is static and which is not, which is not always apparent, is among the most common reasons for why hotspots may begin to fail, after working perfectly immediately after their initial definition. For more information on customizing these comparison criteria, see: Customizing Comparison Criteria.

Where To Store hotSpots

If you like, you can store HotSpots in a common folder that is shared by all versions of jaws. Or, you can let HSC choose a default folder which is tied to the version of jaws you are running.

If you take no action to do otherwise, HSC will default to the latter, just as in previous versions. The base folder will be the PersonalizedSettings subfolder, which is in the user-specific settings area of JAWS.

To create a shared folder, Use Windows Explorer to creat the folder. Create one subfolder for each application, and place any hotspot files you already have in those subfolders. Note that the application subfolders must be properlay named for the application in order for HSC to find them. Focus in the application and press insert+q. Jaws will spell out the application name, followed by e x e. (ignore the . e x e part). Or, you can copy existing subfolders from a previous HSC installation. those are in the "personalizedSettings" folder in the user-specific settings area.
To tell HSC about that, open the folder where scripts are stored, and edit file HotSpotClicker.ini. In the [general] section, is a parameter called BasePath. By default, this is set to a dollar sign "$", which causes HSC to use the PersonalizedSettings folder as it's base folder. delete the dollar sign, and insert the fully qualified path to your folder. For example:
BasePath=c:\MyHSCFolder
It is a good idea to actually create the folder, and populate it with any existing hotspot sets before you tell HSC about it. If you have no existing HotSpot sets, then just create a blank folder, and HSC will do the rest.

Once HSC knows the base folder, it will create subfolders for each application it learns about, and will look in those subfolders for hotSpot information.

Note that, if you have multiple versions of jaws, you need to install the HotSpotClicker scritps into each version separately. If you want to use a shared folder, you need to edit the HotSpotClicker.ini file for each JAWS version, revising the BasePath parameter to point at the shared folder. That makes it possible to have some JAWS versions use the shared folder, and others use the local folder. You can mix and match. But, that means that, when you install a new version of jaws, not just an update, You need to tell the new version about the shared folder, as described.

Creating A file To Store Hot Spot Definitions.

After you have connected HotSpotClicker to your application, the first time you focus in that application, HSC will automatically create a subfolder for your application in the Base Folder. Inside that subfolder, named to reflect the name of your application, HSC will create a skeleton hsc file, generically named MyApp.hsc. Examples would be, notepad.hsc, or wordpad.hsc.

This type of file has a standard format, and contains one or more sections. Each section contains one or more keys. Each key is followed by an equal sign, which is followed by the value of that key. Section names are enclosed in brackets. Note that the term "key" in this file does not correspond to a key from your keyboard, but is just a term used in defining this kind of format. Think of it as the key to finding that particular piece of data. In fact, the Key can be composed of any set of printable characters including spaces.

This file contains several sections.

the [main] section.

this section contains values which apply to all hotspots, and are used to preserve your preferences. This section will be automatically updated as you use the scripts.

In addition, there are a few items which you can modify manually with a text editor, which will affect global behavior, such as verbosity settings, and whether or not to speak debug information. But, most of them are also controlled through additions to the top of your verbosity menu, accessed with jawsKey+v. In later versions of jaws, the verbosity items are accessed through the actions menu, hsc mods plus f10.

the [hotspot file list] section.

this section lists the names of the various hotSpot sets. Immediately after installation, this section contains a single line, which means that only one hot spot set is initially defined. this line is of the following form:
TopLevelWindowName=TopLevelWindowname.hsc
The characters to the left of the equal sign are the name by which you will refer to the hotspot set. Usually, it is set to the topLevelWindow name present at the time you create the set, or the name by which jaws refers to your application. You can change these set names, but if the name no longer matches the ToplevelWindow name, then automatic set switching will not work. If you intend only to activate sets manually, then you can make those names anything that seems meaningful to you, except that there must be the original line:
MyApp=MyApp.hsc
Which is HotspotClicker's way of identifying the main hotspot set.

the characters to the right of the equal sign represent an actual file name where the hot spot information for the new set is stored. This does not need to be a full path name, ut just a simple file name, which will be located in your Base Folder and, initially will refer to your MyApp.hsc file. In other words, this line of text can direct hot spot definitions to be placed in the very same file in which it resides, or in some secondary file, all based on set name. As new sets are defined, additional lines are added to this section, defining the secondary .HSC files which will contain each set.

The [slider units] section.

HSC has the ability to scan predefined areas for visual sliders or track bars which can not be read in other ways. To learn more about how to deal with sliders, read the main section on: custom functions. and, in particular, see the section on function HSCProcessVerticalSlider.

This section contains the various strings used to described the units of measurement for sliders, such as percent, db, etc. the HSC already knows about several commonly used units. But, as you create sliders, you are asked to select the units of measure from the list in this section, and are given the opportunity to create new units. When you do so, your new units names are stored in this section.

Entries here are of the form
UnitsName=comment.
The comment field can be any characters you like, or nothing at all.

The [User functions] Area.

This section contains the names of user-supplied functions which can be executed after the mouse is routed to the hotSpot location, and the configured mouse action is performed. The HSC knows about some of it's own functions which can be used in this manner. But,while those functions are presented in the dialog that lets you choose such things, they do not appear in this section. But, if you wish to write your own script functions, and have them turn up in the list in that dialog, the wizard lets you specify the name of your custom function, and will place it in this section for future use.

These lines are of the form:
Functionname=Comment.
Where FunctionName is the name of a function in your script file, and the comment is any arbitrary string of characters.
The function should be of type Void, and can optionally require parameters. However, to supply parameters, you must use the definition editor to specify the parameter values. You can only provide constant values.
For example, the JAWS Delay function is not offered as a standard HSC function. but, you could specify it as a "create_your_own" function. Once you do this, the function= parameter in your definition will look like this:
function=delay
You do not need the left and right parentheses if no parameters are being supplied. However, the Delay builtin function requires one parameter, which is the number of tenths of a second to delay. So, to delay 3 seconds, you would need to use the definition editor, and modify your function line to look like this:
function=Delay(30)
Note that you can only supply constant parameters, such as fixed numbers, or quoted strings, consistent with the parameter types required by your function. but, you can not mention jaws variable names.

For more information on user-supplied custom functions, see: Custom functions.

HotSpot Sections.

In the main .HSC file, there is one section for each hotSpot in the main set. These sections contain a number of parameters as set up by the Wizard when the hot spot is created. The name in brackets is set to the name of the hot key if one is defined, or is set to the label if not. The individual parameters which comprise the hotSpot definition are discussed in more detail in Where does That Information Get Recorded

How To Assign a Hot Spot.

first, a brief note For those users requiring multiple hotspot sets: Before assigning any HotSpots, it is important to assure that you are assigning them to the desired set. If you have created more than one hotspot set, within the one application, then double click the hotspot help key, which is defaulted to Control+Alt+Shift+f1, and use the arrow keys to choose from the currently defined sets. For those users installing hotspot clicker for the first time, If you haven't yet created any hotspot sets, then Initially, there will be only one set defined for your application, and the below cautionary instructions will not be applicable to you. However, if you do find you need multiple sets for the one aplication, it's worth remembering to check this before assigning your hotspots.
If you change your mind later, regarding which set should contain a particular hotspot, you can move, or copy, it to a different set later using the hsc mods+f5 key stroke to organize hotspots, or window prompts into sets.

Hot spot definitions will be stored in the file which is active at the time you create the hot spot. This could either be the main application's hsc file, (which we'll refer to as MyApp.HSC) file, or in one of the secondary set files. Once you have selected the name of the set to which you want to add Hot Spots, press enter. That set will now be the active set until you change it, even if you completely shut down your system. If you have automatic set switching installed, automatic set switching will be disabled, to allow your selection to remain in effect. . And, when you double click the Control+Alt+shift+f1 key to see the list of available sets, the currently active set will be the one with focus.

With the HotSpotClicker scripts linked into your application scripts as described above, Place focus in the application you are trying to adapt. Either move the JAWS cursor to the position you want to click, or have a sighted person move the mouse to that location.
Now at this initial stage ,if you do not need to worry about matching or searching for a particular graphic, color or text string, use the standard hotspot definition wizard by pressing Control+Alt+shift+A on the keyboard. JAWS will record the location of the mouse cursor, and several attributes of the window in which that spot resides. It will then present a dialog, asking which kind of positioning you want to use. use up and down arrow to select a positioning mode and press enter. Experimentation may be the only way to determine which positioning mode is most appropriate for your situation. But, Application Relative positioning would be a good first guess. By default, the choice you made in the previous hot spot will already be highlighted. Instead of the various window positioning methods, you can choose from a host of special kinds of hotSpots, such as one to switch sets, To activate a particular spot ring, to set focus on a control, or to activate an MSAA Object. You can also press escape at this point to cancel this key assignment.

The Set Focus positioning method performs no mouse click, but simply directs the application's attention to a specific control, without altering that control. this is particularly useful with sliders, where you may want to set focus on the slider without changing its value, but where clicking tends to change the value of the slider.

The MSAA Object activation is discussed in Object Navigation For more discussion on the differences between the various methods of positioning, review the section on Positioning Methods.

next, the clicker may present you with a series of various types of window titles, and ask you to remove dynamic information from those titles. As you edit these strings, remove information that will change as the application is operated at different times, or under different circumstances. Leave only that information that you are confident will remain constant. When you press enter, the reduced strings are stored as NickNames. The nickname should either be equal to the first few characters of the original string, or should be contained in the original string, so that a match can be recognized.
And, because of this, the clicker won't need to ask you to edit all these window names for every spot you define within your application. the clicker builds up a data base of nicknames as you proceed, and will thus only need to queery you when it encounters new window names for which it has no entries.
This means that defining spots will get faster and less input intensive within the one application as you proceed.

it is recommended that you leave in place only the minimum amount of information, that you are reasonably confident will always remain a part of the window name string, and which defines the purpose of that window. You will have the opportunity to edit all these attributes manually later, but to gain maximum hotspot clicking success, this is quite an important part of the process.
note: since window names for, "current," window types, can change so dynamically, you may often find it necessary to delete *all* the information in current window name strings. you can do this by hitting the delete key when the window name is highlighted, and this should delete the whole current window name at once.

For more information on removing dynamic information from window titles, see: Customizing Comparison Criteria.

next, you are presented with a dialog asking what kind of action you want to perform at this location. Use the up and down arrow keys to choose the kind of click you want to perform, and press enter. Or, press escape to cancel. You can do all forms of single or double, left or right mouse clicks, simply move the jaws cursor to a location without doing a click, or you can move to that location and say a Chunk of text. Jaws defines a "chunk" as text that was written to a location on screen in a single operation. Often, this latter mode can be used to quickly cause a piece of text to be conveniently spoken with the press of a hot key. Options for SayWord, SayToCursor, sayToEndOfLine, and SayColorField are also provided.

For more information on which cursor is active after hot spot activation, and where the cursor will be located, please see: Cursor Restoration.

Next, Jaws will ask for a label for your hot spot.
if your hotspot happens to be located on either a graphic, or a piece of text, (what is often refered to as a "text string,") then this will be offered as a default label for the hotspot. If you plan to attach a hot key, and don't wish to assign a label, , you could press delete while the default label is still highlighted, forcing the label to be blank. But, it is strongly recommended that you include a label to help keep track of the meaning of your various hot spots. However, if you omit a label, and do not attach a hot key, the operation will be canceled. You must provide either a label or a hot key. but, it is best to supply both.

If you provided a label, you will next be asked whether you would like that label to be spoken when the hot spot is activated. Use up and down arrows to make your selection, and press enter.

next, jaws will ask if you wish to attach a hot key. If you choose no, and press enter, then the operation is complete. However, if you choose yes, JAWS will prompt you to press the hot key you wish to assign, and will start playing a short beep once per second, during which time it will wait for your key stroke. You have about 30 seconds before jaws politely gives up and cancels the operation. If you decide you wish to cancel, just press escape. Otherwise, press your hot key. JAWS will speak the name of the hot key captured, record the information, and return to normal operation.

The HSC will check your existing key map to see if you have chosen a hot key which has already been assigned to a script, either in your application, or in the default scripts, or whether you have already assigned this key to an existing hot spot in the current set, and will ask you to confirm whether or not you wish to continue with this assignment. If you choose cancel, the entire hot spot definition process will be terminated. If you say no, jaws will begin beeping again, waiting for another key to be pressed. If you like, you can press escape to cancel the complete operation, or press an available hot key to continue. Remember, it is perfectly legitimate to assign the same key to different hotspots in different sets.

If you are running jaws 6.0, and perhaps other versions as well, you may find that the new hot key is not immediately functional. This is because certain versions of JAWS do not know that the key map has been modified. If this happens, you will have to alt tab away from your application, and release the alt key to focus elsewhere. Then, alt tab back into the application to force the key map to be read by jaws. The elegant solution to this problem has been tried, and has other less desireable consequences. So, until this problem is address by Freedom Scientific, we're stuck with it.

Ok! congratulations! you're done assigning your first hotspot! Your hot spot should now be ready for use. You can record as many hot spots as you like, but only one hotSpot can be associated with any one hot key in the same set. yes, multiple hot spots can reference the same exact llocation. And, your hot key can include any combination of modifiers except for the JAWSKey. Leave the JAWSKey for use by Freedom Scietific.

JAWS will differentiate between left and right modifiers, if this option is set in the default.jcf configuration file. The HotSpotClicker will capture keys according to the setting of this option, which can be accessed through the config manager, under Settings, in the keyboard dialog. However, if you change that setting, you must edit the .HSC files manually to make the necessary adjustments to key names.

HotKeys And Existing JAWS Scripts

It is possible to have a JAWS script assigned to a hotkey, but to also assign a HotSpot to that same hot key. When you create that HotSpot, HSC will notify you that the script exists. If you choose to make the assignment anyway, the name of the JAWS script is placed in a special section of the main HSC file for your application. When the key is pressed, HSC will intercept it as though it were assigned to a hotspot. If there is a spot for that key in the currently active set, then HSC will run that Hotspot. If not, it till run the JAWS script.
The name of the ssection in the file is [redirect].

HSC should manage this section itself, including removing a hot key from that section if hotspots are deleted, or entire sets are deleted, making thee redirection no longer necessary. In such a case, the jaws key map will be restored to point directly to the JAWS script.

Including String Search, Graphics And Colors In Your Hot Spot Positioning Criteria.

A more advanced hotspot wizard is attached to the Control+AltShift+g keystroke. It performs all the features of the standard hotspot assignment wizard, but also looks for a graphic in the vicinity, captures the word at the cursor, and acquires the color at the mouse. If you do not need to include the presence of a graphic, text string, or a particular color value in your hotspot positioning criteria, you will find it sufficient, and quicker to use the standard wizard attached to Control+Alt+Shift+A.
This control+alt+shift+G expanded wizard is slightly slower, but permits creation of hotspots which are only valid when a particular graphic, text string, or color, is found at, or near, the hot spot location.

If a graphic is found near the mouse location, the HSC will ask you whether you want to track that graphic. This can cause the HSC to do one of six forms of search for that graphic before performing the mouse click. This is discussed in more detail in: PrePositioning the Cursor. If no graphic is found, the HSC will capture the word at the hotspot location, and ask if you want to condition the hotspot on the presence of that text string. You can choose to ignore the string, require that it be in it's present position, search nearby for that string, or search the entire window, as identified in your positioning mode selection, either from top down, or bottom up. If you choose anything but to ignore the string, you will also be asked if you want to require a match on the foreground and/or background colors. you can allow multiple colors for either foreground or background as described in: Color Searches. But, only the present foreground and background colors are captured by the wizard.

If no graphic is found, or if you chose not to search for the graphic, and if you chose to ignore the text string, the HSC will capture the color value found at the precise ppixel of the mouse location, and ask you if this color should be required as a part of the hotspot validation. The HSC can be caused to search a small area around that location, looking for that color, before the mouse acction is applied. this is discussed more in: PrePositioning the Cursor. You can allow a list of multiple valid colors for this pixel location, as described in: Color Searches. But, only the color present at the location at definition time is captured by the wizard.

Where does That Information Get Recorded.

After discussing where the HSC data files are stored, this section links you to a complete HotSpot parameter reference. These parameters can be accessed with a text editor, or, perhaps more conveniently, through the definition editor attached to HSC mods+f4, and are used to fully define a HotSpot.

First, a clarification. When we say $jaws we mean the folder you open when you hit the start menu, programs, type j until you hear your version of jaws, then press right arrow twice to go to "explore My settings", and press enter. This is the area associated with your user name, not the all users area, and is typically a path that ends in settings\enu. By That is the folder where scripts are stored. Unless you have defined an alternative BaseFolder, Hotspot data is stored in subfolders under this $jaws folder.

In versions prior to 7.6, all information, for all applications, was stored in the $jaws\PersonalizedSettings folder. However, starting in version 7.6, a subfolder is created in the PersonalizedSettings folder, based on the application name. All hotspot data for that application is stored in that subfolder. We did that, because secondary hotspot sets, named based on topLevelWindow names, could easily conflict across applications. Separating applications into subfolders eliminates this problem. However, for backward compatibility, HSC will first check the Base Folder to see if a .hsc file exists for this application. If it does, HSC will revert to the older method. If not, it will use the new method. And, if a myApp.hsc file does not exist using the new method, one will be created.

From our example above, if you are running an application called MyApp.exe, your information is recorded in a file called MyApp.HSC in the $jaws\PersonalizedSettings\MyApp folder.

The entry called ActiveFile, located in the [main] section of MyApp.HSC, is used to determine the exact name of the file in which the hot spot will be stored, based on the set that is active at the time the recording occurs. In other words, the hot spot definition itself will either be stored in the MyApp.HSC file, or in one of the secondary files, depending on which file you have active at the moment.

Each hot spot creates a section named after that hot spot. If a hot key is attached, the key name is used as the section name. If not, then the label is used.
Section headers are enclosed in brackets at the very top of each hotspot definition.

If you need to revise a hotspot, you can edit the .hsc file manually if you like, using a text editor. but, you'll find it more convenient to use the definition editor attached to control+alt+shift+f4. discussed more in Editing HotSpot Definitions.

Click on the following link to see a complete list of values you will see as a part of the hotspot definition: HotSpot Parameter Reference

Customizing Comparison Criteria.

If you are using application, TopLevelWindow, current or Focus Window-Relative positioning, and your hotspot begins to fail, it may be because the criteria used to find the window specified in the hotspot definition is overly specific, or contains dynamic information, which was valid when the hotspot was defined, but which has become invalid due to changes in your application's environment. For example, sometimes class names, especially those very long class names which start with "afx:" will retain the first few characters over time, but will change the last few characters each time the application is invoked.
Far more typically, Application or TopLevel window names often contain the name of the document you are working on at the time. Later, you may be operating on a different document and, thus, the window name will be different. Web pages are particularly famous for changing their title information as you move around the page. In addition, quite often you may find that the name of the, current, window, surrounding a particular hotspot, may alter too often or dynamically, and perhaps too unpredictably, to form a useful criteria for validating the hotspot. For example, when seeking to make hotspots for some kinds of Tab controls, it is often the case that the current window name in which the tab control hotspot resides, may dynamically alter to be synonymous with the last tab control that had focus, or that was last clicked on. This will very quickly invalidate a hotspot, (i.e. cause a function failed message,) which relied on the current window name remaining static, when it was defined. Thus, In such cases, you may often find it most expedient to just delete the whole current window name offered, such that the clicker will not seek to use current window name criteria, as part of the validation process for that spot. This will increase chances that your hotspot will actually succeed more often, but may increase the possibility of clicking in unexpected, and possibly undesired circumstances.

Dynamic information, meaning that wich changes during the operation of your program, can be removed from the comparison in several ways.

The clicker gives you a chance to remove such dynamic information from window titles at the time the hotSpot is defined. It does this by creating a database of window titles in the current Hot Spot set, where it stores actual window titles, along with their nicknames. the nickname should be a subset of the original window title, such that the nickname is equal to the first few characters of the actual title, or is completely contained within the original title.

when you define future hot spots in that same set, the clicker will consult it's database of nicknames, to see if the current window titles are already known. if so, it will use the nickname as part of the validation criteria for that window.

To cause the clicker to forget about a nickname, you must remove that entry from the [nicknames] section of the active .HSC file.

If you are using Application or TopLevelWindow positioning modes, you can learn what attribute of the window which contains the hot spot location is not matching by turning on the debug flag through the standard jaws verbosity dialog. Then, when you try to activate the HotSpot, JAWS will speak the name of the attribute which fails the comparison. This flag is described more in: The Debug Parameter.

If you are using Application or toplevelWindow relative positioning, HSC still applies criteria related to the actual window that contained the hotspot when it was defined, to determine if the hot spot is valid. In addition, if you choose to also search from the hotspot, looking for a graphic, a text string, or a pixel color, the results of that search can remain inside the application, or topLevelWindow, but cross in to a different child window, violating your validation criteria. To eliminate consideration of the child window, and allow positioning and searching to find valid locations anywhere inside the window you have selected as your positioning method, you must eliminate those criteria which are specific to that child window, as described below. The parameters which relate only to the child window are as follows:

To ignore all child window attributes, you can disable child window validation through the verbosity menu. Press JAWSKey+v, and find Hotspot window Validation mode. Press space bar to turn it on or off. This setting is saved in the MyApp.hsc file, is applied at the time of hotspot activation, and, if off, causes HSC to ignore all these child window attributes. Normally, you should resolve the individual differences, and run with this mode turned on for the most security.

Sometimes, as you learn more about a particular application, you may wish to refine the validation criteria by manually revising the window names. To do this, you must edit the hotspot definition, either with a text editor, or from the definition editor using the control+alt+shift+f4 key stroke.

You can gain quick access to a hotspot's parameters by invoking the Hotspot definition editor, described in more detail in: Editing HotSpot Definitions.

Read through the definition, and evaluate the following to see if they might be overly specific, or contain
Information you suspect maybe altering dynamically such that it might be causing the hotspot to fail to fire as desired:

There are two ways to ignore a qualification criterion.

  1. place an asterisk in column 1 of the line containing that criterion in the definition. this allows the original value to remain in the file, so you can easily restore it later. The HSC will ignore that value, and use the special code which will cause that criterion to be ignored.
  2. Change the value to the right of the equal sign as described below.>

To Ignore integer values, set them to a negative 1, -1.

to ignore any string criterion, do the following. This discussion refers to windowName merely as an example, but should be applied generally to all string values in the comparison criteria. It does not apply to integer values. You can ignore integer values, but you can not specify multiple acceptable values, nor a range of values.

The normal string comparison mode requires that the characters listed here must be the same as the first few characters of the actual value from the window itself. For example, if the WindowName listed here is "Dog", and the actual window name found was "dog - page 1", the comparison would be satisfied, because the letters "dog" exist at the front of the actual window name. But, the "page 1" is likely to be a dynamic string, changing as the application is operated. so, we can satisfy the comparison, no matter what page we are on, by specifying only the constant portion of the window name. However, the HotSpotClicker does not know which parts of the name are dynamic, and records the entire string, relying on your manual intervention to scale it back to only constant values.

If you want to specify a string which is located somewhere in the middle of the window name, you can force that sort of comparison by inserting a caret "^" as the first character in the string. This special character is a wild card that can match any number of characters, of unknown value. But, you only need to do this if you are editing the .HSC file manually, or through the Edit Hotspot Definition dialog, to revise an existing hot spot. The assignment wizard will automatically insert this special character for you, if appropriate, when you custimize names during the creation process.

For example, if the window name was presently
"my Dog - page 1",
but later on, it might be
"your dog - page 16"
or
"Billy's dog - page 43",
we would recognize that the words
"dog - page"
remain constant. WE can force a match by making our windowName criteria look like this:
Windowname=^dog - page

There are two other special characters that can be used to control string comparisons. To use these, the string in your .HSC file must contain only one character, as defined in the following list:

Some programs are constructed in such a way that even integer values are dynamic, such as control ID's. If customizing your strings still does not resolve the issue, you may need to use HomeRow mode in JAWS, to determine if any of the integer criteria are dynamic, and eliminate them from the comparison. The HotSpotClicker knows that some ControlID's are equal to window handles, and thus are very dynamic. It checks for these cases, and, if necessary, sets the controlID to -1, which will prevent the control ID from being used as a criterion.

Customize HotSpot Creation.

If you are having frequent problems, where one of the child window attributes is causing hotspots to become invalid, you can tell the definition wizard to ignore that criteria for all newly defined hotspots. Criteria which are disabled will still be stored in the definition in the .hsc file, but will be stored with an asterisk "*" as the first character in the file key. This allows all possible values for that attribute, but allows you to use the definition editor to remove the asterisk, thus re-enabling the criterion at a later time. Note that, in the long term, to prevent clicking in the wrong place at the wrong time, it is better to correct the attribute, so that it is properly defined, than to remove it altogether.

To customize the wizard's data collection, press Control+Alt+shift+f10, and choose
Customize Child Window comparison Criteria
from the actions menu. Cursor down through the various child window attributes, and press space bar on an item to toggle it's state. Yes, means that the attribute will be recorded and used. No, means it will be recorded, but not used.

This customization is stored in the main .hsc file, and will apply to all subsequently defined hotspots. It does not affect existing hotspots.

If you want your customizations to also be applied to all new applications, choose the item that says
Save As the default for all new applications.
The current preferences will be recorded in file HotSpotClicker.hsc, which is the template from which all new main hsc files are created when connecting the clicker to new applications.

Likewise, if you change those preferences, and want to revert to what you last saved as a global setting, then choose:
Load Default Settings
The settings you last saved to the global file will be loaded, If no settings have been saved, then all criteria will be defaulted to the "on" condition, which is considered normal HSC operation.

Cursor Restoration.

This section discusses which cursor will be active after a hot spot is activated. In part, this depends on the mouse action you selected when you created the hot spot.

If parameter RestoreCursor is present in your definition, and is set to 0, HSC will not restore the cursor. This is useful when you want your custom function to determine which cursor should be active, and you don't want HSC overriding that. All new hotspots will contain this parameter, which will be set to 1. If this parameter is not present, it is defaulted to 1, which means HSC will control which cursor is left active, as described in the rest of this section.

If you chose to move to a location, rather than to say a chunk of text, or perform some kind of mouse click, then, after the hot spot is activated, the jaws cursor will always be active, and it will be parked at the location associated with this hot spot, no matter which cursor was active prior to hot spot activation. This behavior can not be customized without modifying the script source code.

However, if you choose the Say Chunk, one of the click options, or NoAction, then after the hot spot is activated, the cursor which was active before the click, will always be active afterwords as well. The default behavior is that the JAWS cursor will remain at the click location. However, There are two ways you can customize this behavior. if you would like the JAWS cursor position to be restored to the location it occupied before the click was performed, and you want that to be the new default for all hotspots, you can go to the $jaws \Personalized Settings folder under JAWS,and manually edit the main .HSC file for your application. In the [main] section, you will find a line that looks like this:
RestoreCursorPosition=0 ; set to 1 to restore to previous locaition after the click.
As indicated by the comment on this line, changing the 0 to 1, then saving and closing the file will change this behavior, so that the JAWS cursor will be restored to it's previous location. This global customization will only apply to the current application. Each time you connect the clicker to a new application, when the main .HSC file is created, this behavior will default to remaining at the click location for that new application. but, your customization will remain in effect for the old application.

If you want to make this the default for all new applications, go to the $jaws folder and edit file HotSpotClicker.hsc. This is the main template which the HSC uses to create the main hsc file for new applications. Change that RestoreCursorPosition value in this file and save your changes. Now, all new applications to which you connect the clicker will exhibit this behavior as well.

If you want a given hotspot to behave differently than the global default, use the definition editor, attached to hsc mods plus f4. In each definition is a parameter by the same name, restoreCursorPosition which can override the default behavior. The values are as follows:
0 = Use the global default behavior
1 = Restore the cursor position to the location it occupied before hotspot activation
2 = Leave the cursor at the hotspot location

Custom Mouse Clicks.

This helps deal with the occasional situation where clicking the left or right button on the physical mouse, is different from clicking the jaws left mouse button. In such cases, using one of the custom click options should allow you to simulate clicking the actual mouse.

There are two parameters in the definition which control the behavior of the custom click. Use the definition editor to alter these if you need other than default behavior>

PrePositioning The Cursor.

If you find that the actual location you want to click seems to move around slightly, you can follow the steps in this section to cause the HSC to adjust the cursor position slightly before performing the mouse click.

If you are searching for a graphic, or a pixel color, the HSC will search a small area centered around the hotspot location, looking for the criterion you specify. the mouse action will be performed only if the search is successful. The HSC will search in a special form of expanding square, centered around the hotspot location. The search Limit values shown below will limit how large that square will become in each direction. A value of 5 defines a squaere which is 10 pixels across. But, you can manually edit the search limit parameters to allow for other area shapes and sizes. Edit the following parameters:
UpLimit
DownLimit
LeftLimit
RightLimit

Text and graphics searches, can also search the positioning window, either top down, or bottom up, looking for the nth occurrence of the string or the graphic.

you can have the HSC perform one, and only one, of the following actions prior to executing the mouse action:

  1. Search for a graphic by it's graphic name,
  2. Search for a text string, possibly including foreground and background colors.
  3. Search for a single pixel color value,
  4. Just move to the hotspot location and proceed.

Graphics searches.

Before creating hotspots involving graphics, you should first label those graphics with meaninful names using the JAWSKey+g labeler. Remember that graphics often change when clicked, and may even change depending on whether the mouse cursor is on the graphic or not. The autoGraphics labeler shipped with jaws does not take all these factors into account. You may need to label the graphic once with the jaws cursor positioned on it. then, label it again, with the same name, with the invisible cursor on the graphic, and the jaws cursor parked elsewhere. then, you may need to click the graphic with the jaws cursor, and see if it changes. If it does, then repeat the process giving the graphic a new name which reflects it's new state. the hotSpotClicker will deal with these graphics using the names you provide during this labeling process.

During the hotspot definition process, the advanced wizard tells you if a graphic is found near the hotspot location, and if mor ethan one graphic is found by the same name, tells you hwo many there are, and enumerates which of them is at the hotspot, such as 4 out of 10. Then, HSC asks you if you want to use that graphic as a positioning criterion. You can choose to ignore the graphic,
require the graphic at the spot location, search nearby, or to search the entire window, either from top down, or bottom up . You can search top down for the first occurrence, or for the nth occurrence, where N represents which of the multiple graphics with the same name is closest to the hotSpot. Or, you can search bottom up, either for the first from the bottom, or the nth occurrence. For example, you could search top down for the 4th out of 10, or bottom up for the 7th out of 10. Use caution as to which of these is most likely to remain constant. Note that, if you change your mind later, you can edit the definition to search from the other end, but need to adjust the graphic count accordingly. For example, change graphicCount=4 to 7.

If you choose not to ignore the graphic, then the hotspot location is taken to be the present position of the graphic, rather than the actual mouse location. TextOffset values in the definition can be used to further offset the click location from the located item, but these must be edited manually using the Definition Editor.

If you choose "search nearby", the hsc will search an expanding area centered around the hotspot location, up to the directional search limits, looking for a graphic of the name found at definition time. Searching nearby is intended for cases where the graphic tends to move only a few pixels. This method is rather slow, and is not well suited for large area searches.

If you choose to search the entire window, either top down or bottom up, the search is much faster. The window searched is controlled by the positioning mode you choose as defined in the following list:

The GraphicCount parameter in the hotspot definition can be used for top down and bottom up searches, to look for multiple occurrences of a graphic in situations where graphics can not be uniquely named. But, if you change directions of the search, remember to also adjust the Graphic Count.

Tip: To enumerate multiple graphics, position the jaws cursor on the graphic, and use hsc mods +f8 to figure out which one you are on, and how many there are.

If the graphic is not found, then the hotspot will fail. If it is, then the location is further modified by including the TextHorizontalOffset and TextVerticalOffset values, and the click is performed at the new location.

If you have a graphic which changes names when clicked, then, you may want to search for both names. You can specify multiple graphic names by editing the hotspot definition, and adding the additional name to the Graphicname field. Multiple names should be separated by a vertical bar "|", without intervening spaces, such as "dog|cat|jam".

Note that graphics under JAWS are problematic phenomena. Graphics labeled on one machine do not always translate well to other machines, and do not always work reliably even on your own machine. Your results may vary. In fact, they probably will.

Enumerating Graphics.

This deals with situations where there are multiple graphics by the same name. By default when doing top down or bottom up graphics searches, , hsc searches for the first occurrence. but, You can search for the second or third occurrence of a graphic by setting the GraphicsCount parameter in the hotspot definition to a value larger than 1.

To find out which occurrence your jaws cursor is located on, press control_alt_shift+f7. HSC will search the positioning window for all occurrences of a graphic by the same name as the one on which the jaws cursor is located, and will report which occurrence this is, out of how many graphics. Then, you can use the definition editor to set the GraphicsCount key to the occurrence number you want.

To control which window is searched, double click control+alt+shift+f7 to cycle between the application main window, the TopLevelWindow which contains the cursor, or the child window containing the cursor itself.

The enumeration is always done top down. To figure out which occurrence that is when searching bottom up, subtract the occurrence number, from the total number of occurrences, and add 1.

Text Searches.

If a text search is specified, the HSC will move to the hotspot location, and then conduct the text search as controlled by the TextMode parameter.

The text acquired by the wizard for this purpose, will be the word at the Hotspot location. You can expand or modify that text by editing the hotspot definition after the spot is defined.

If the string is not found, the hotspot is considered to be invalid. If the string is found, the location of the first character in that string is taken to be the present photspot position. You can further modify this position by editing the definition, and placing nonzero pixel offset values in the TextHorizontalOffset and TextVerticalOffset parameters.

the search options, and associated behaviors are as follows:

The term " positioning window" refers to the position mode for the hotspot, Application, TopLevel, or Current window.

Searches can optionally also include text foreground and background color criteria. The colors are specified as RGB strings in the spot definition. Multiple colors can be specified for each criterion, by separating RGB strings with a vertical bar "|". You can learn text foreground colors, in rgb format, by double clicking jawsKey+5 on the numbers row.

If a search was required, and is successful, HSC will move the mouse to the start of the string, and apply the fixed text offsets, before performing the mouse action.

Searching For Unspecified Text

If you want to search for text of a particular foreground and/or background color, or a set of multiple foreground and/or background colors, but the text is variable, and thus can not be known ahead of time, you can do this by using the definition editor to set the text parameter to the special code caret star, ^*. This special code tells hsc that a search should be made for any text which matches the specified foreground and background colors. If you choose the "search Nearby" method, the four directional search limit parameters will limit how far the search will look from the original hotspot location. The TextCound Parameter will control how many words to look for.

Enumerating Text Strings.

Because JAWS text search is not always reliable, it is not always possible to search for multiple occurrences of a text string. Therefore, HSC defaults to only looking for the top most, or the bottom most occurrence of the string when searching top down or bottom up. But, you can try searching for multiple occurrences by setting the TextCount key in the hotSpot definition to a value larger than 1.

To learn whether a given text string is the first occurrence, or the fourth occurrence, or whatever, place your jaws cursor on the word of interest, and pres control+alt+shif+f8. HSC will grab the word at the cursor, and then search the window for all occurrences of that word. It will report how many occurrences were found, and which one your cursor is on.

To control which window is searched, double click control+alt+shift+f7 to cycle between the application main window, the TopLevelWindow which contains the cursor, or the child window containing the cursor itself.

To locate a phrase comprised of multiple words on the same line, place the cursor at one end of the phrase, and double click control+alt+shift+f8. HSC will say, marked. then, place the jaws cursor at the other end of the phrase, and double click control+alt+shift+f8 again. It doesn't matter which end you mark first. HSC will then enumerate that phrase, and the cursor will be left at the start of the phrase.

For example, If you had enumerated the word "monkey, and there were three occurrences of monkey in the selected window, and your cursor was on the middle one, HSC would say monkey is item 2 of 3, Then you could configure a hotspot to do a top down search for the word monkey, and use the definition editor to set the TextCount to 2 in order to find that occurrence of the word.

The enumeration is always done top down. To figure out which occurrence that is when searching bottom up, subtract the occurrence number, from the total number of occurrences, and add 1.

Color Searches.

You can search for text with a certain foreground and background color. but, very often, you will be searching for a pixel of a certain color, which is not part of any text. To learn more about how to manually explore for pixel colors, read the section on Color And GraphicsExploration.

The HSC searches for colors if your hotspot does any of the following actions.
Items marked with an asterisk allow specification of multiple colors. Unmarked items allow only a single color to be specified.

  1. * Track a string of text with specific foreground or background color - multiple.
  2. * Track a pixel of a certain color - multiple.
  3. speak a text phrase, or run a custom function, when a particular color is found - single.
  4. When decoding a slider - single.

To support this, the following fields exist in the hotspot definition in the active .HSC file. the keys always exist, even if they are not used, so you can always edit them with the Edit Definition Dialog accessed by the control+alt+shift+f4 keystroke.

Shown here are the keys with default values, indicating that the feature is not used. If the feature is used, then realistic RGB color values will appear in these entries.

The pixel color, and text background and foreground colors are 9 digit RGB string values. You can specify a list of acceptable colors by adding the additional RGB value to the string, separated by avertical bar. for example:
BackgroundColor=000000000|255255255
This unlikely specification indicates that the background color could either be black or white.

RGB values are 9 digit strings, where the first three digits indicate the amount of red, the second triplet indicates the amount of green, and the third triplet indicates the amount of blue. The maximum value for each triplet is 255.

To learn RGB values for text foreground and background colors, (not for individual pixel or graphics colors,) position the jaws cursor on a character of interest, and then Double click insert+5 on the numbers row.

Color And graphics Exploration

this set of hotkeys is used to explore with the jaws or invisible cursor, to look for patches of color which may not appear as text, and are thus invisible to jaws. This information is useful when you want to have a hotSpot search for a color, or when exploring the colors of a slider control.

to learn RGB or integer color values for single pixels, Activate either the JAWS or Invisible cursor, then use the standard jaws mouse movement commands, alt+shift+NumPad arrow keys to move the cursor. Be aware that some controls will change their color, depending on whether the mouse is hovering over that area or not. In such cases, you may need to specify that either of those two colors is valid, unless you can know whether the mouse will be already at the correct location or not.

To automatically speak the color upon mouse movement, use control+alt+shift+period to toggle automatic color announcement on. when this mode is enabled, HSC will look at the color at the new location each time the cursor is moved. If the color is different from the color at the previous location, a short beep is played. When you stop moving the cursor, HSC will automatically speak the color. In this way, you can rapidly cursor around, knowing that you will hear the beep when the color changes, but without having to wait for the color to be spoken.

To repeat the color at the present cursor location, use alt+shift+NumPad 5. Double click that key to copy the RGB value to the clipboard. this is useful when copying the color value into the color attribute of a hotspot in the Definition Editor.

To have HSC automatically speak the name of a graphic with each movement of the mouse, as you move through the graphic, toggle automatic announcement of graphic name, using control+alt+shift+slash. This is useful in exploring the shape and size of a graphic. Note that jaws often thinks there are dead spots inside a graphic, such that the cursor is actually on the graphic, but jaws doesn't know it.

To move jaws or invisible cursor to a known absolute pixel address, activate the desired cursor, then press control+alt+shift+f9, and type in the row and column numbers, separated by a space.

To move the JAWS or Invisible cursor to a certain number of pixels relative to the top left corner of a particular window, first use a double click of HSC mods+f7 to choose which window to use as the reference. This rotates between application main window, topLevelWindow, and current window. HSC will speak the new context, and will play a sound which is associated with that particular context. You will hear that same sound, as a reminder of the current context, when you double click alt+shift+NumPadDelete, which will report the number of pixels from the top left corner of the selected window.
Then, manually position the cursor inside the window of interest, and double click hsc mods+f9.
Note that TopLevelWindow, in this case, refers to the topLevelWindow of the child window which contains the cursor at the moment, as opposed to the TopLevelwindow which contains the window which presently has focus.

to learn the absolute coordinates of the active cursor, press alt+shift+NumPadDelete.
To learn the number of pixels down, and to the right of the top, left corner of the currently selected window, double click alt+shift+NumPadDelete. Use double click of hsc mods+f7 to select the window context

To set the number of pixels to move with each press of a mouse movement keystroke, use JAWSKey+spaceBar to enter home row mode, and then left/right arrow to choose the number of pixels. then, use JAWSKey+spaceBar to exit home row mode.

To set a bookmark at the current cursor location, press alt+shift+PageDown on the NumPad. This is an absolute pixel address, which will be remembered until you restart jaws. To return the active cursor to that location, press alt+shift+PageUp on the NumPad.

to activate the jaws cursor, and route it to the invisible cursor, press alt+shift+NumPadMinus.

to activate the invisible cursor, and route it to the jaws cursor location, press alt+shift+NumPadPlus.

To calculate the horizontal and vertical distances between two locations, Place jaws or invisible at the starting location and press alt+shift+home on the numPad. Move the cursor to the second location and press alt+shift+end. HSC will report the offset values, required to move from the starting point , to the cursor. Note that it is legal to define the start point with one cursor, and then move the other cursor to a new position before calculating the distances. In other words, one cursor can be used to mark the starting position, And a different cursor used to find a new location.

Recovery Spot.

For each Hotspot, you can define a separate HotSpot which will be executed if the original spot fails. To do this, you must use the definition editor, attached to HSC mods plus f4. Near the bottom of the definition, is an item called RecoverySpot. The characters to the right of the equal sign should be set to the name of the hotSpot which should be activated if this spot fails. Note that those characters are the characters between the brackets in the other spot, not it's label. If a hot key is attached to that spot, for example, this will be the hotkey name.

If you want the spot to fail quietly, neither taking any action, nor speaking any message, set the RecoverySpot to an asterisk "*". Setting RecoverySpot to a dollar sign "$" will cause an announcement to occur upon spot failure.

HotSpots generated with HSC versions prior to 7.6 will not have this parameter. So, it will need to be entered manually. Go to the right hand end of the last line in the definition, and press control+m to make a blank line. Then type the new item. An example would be:
RecoverySpot=control+shift+1

Audio Graphing a table Column

This feature applies to web browsers, but should also apply to spreadsheets and maybe even Microsoft Word tables. Once you have placed the virtual cursor, or a hotSpot, in a table, in a colum that you want to hear graphed, this facility will let you hear a series of audio tones whose pitch, or amplitude represents the value of each cell in the column. Place the cursor in the top most cell that contains data. HSC will travel down the column, picking up the values from each cell. It will then produce a series of audio tones for each value, proceeding down the column, with the pitch, or volume of each tone being calculated using the value in the corresponding cell. Once you get used to listening to the sequence of tones, this technique can make it much quicker and easier to scan a column of data, and look for anomalies.
Or, maybe the column is not numeric, but contains a host of well-known strings. In such cases, you can define each of the well-known strings, and associate each with a sound file that will be played, and a delay time required to let the file play.

To define a spot that will travel along with you as you move your virtual cursor, Just define an application relative spot using the jaws cursor. It doesn't matter where the jaws cursir is placed, as long as it is inside the application where the table exists. HSC too get it's current location using the virtual cursor.

Alternatively, In case you know what column you will always want to graph, and don't want to hunt around for it, you can define a hotspot in that column, using the Virtual cursor row and column position option. Place the virtual cursor in the top most cell in the column before defining the spot.

This is all done by calling one of two HSC-supplied post processing functions called ToneGraphTableDownHSC or ToneGraphTableUpHSC from your hotSpot.

Function: ToneGraphTableDownHSC
Parameter: 1 = autocalibrate, 0 = use present calibration.
Description: Start at the current cell and graph down to the end of the column.

Function: ToneGraphTableUpHSC
Parameter: 1 = autocalibrate, 0 = use present calibration.
Description: Start at the bottom of the collumn, and graph upward to the current cell.

Calibration is concerned with numeric data only, and relates to defining the relationship between the value in a cell, and the pitch or volume of the resulting tone. In the default configuration, HSC can presently select from 26 pre-stored tones. If you choose the AutoCalibration option, by supplying a parameter of 1 to the function, then HSC will scan the column, and choose the minimum and maximum values. It will then adjust it's scaling such that the smallest cell value will produce the lowest possible tone, and the largest cell value will produce the highest pitch tone. However, this means that the data will always produce the widest possible range of tones, which makes the fluctuations in the data seem equally dramatic, no matter what the data.

Altermatively, you might want to set your own 0 and 100% values manually, so the data is always presented in the same scaling, which makes it easier to spot changes in the data. You do this by calling the function with a parameter of 0, and entering the limits manually in the file described below. Each column in your table can have it's own set of limits, and the data is stored based on the URL of your table, and its index in the web page. So, each table you scan should be uniquely stored.

If you call the function with a 0, and no calibration data has been established yet, HSC will autocalibrate to the current data, even though autocalibration was not specified. However, if calibration data is available, and the table has been scanned recently, Calling with option 0 will allow the tones to be played back without having to wait for HSC to scan the data. This allows you to more conveniently repeat the scan for review, with the assumption that the table has not changed. This deals with the fact that the table must be scanned fully before the tones are played, and various computers will scan the table at different speeds. But, the tone playback must be a constant speed. So, the table is actually scanned only when necessary, and cached data is played whenever possible.

Manual Calibration

To do this, edit file HSCTables.hsc, described below, to specify the cell values that should lead to the lowest and highest tones. Then, always call ToneGraphTableDownHSC with 0 to preserve your calibration.

ToneGen Option

This section only applies to columns containing all numeric data.
Starting in build 233, there are two more options for how audio tones are generated. These are controlled by parameters in section [ToneGen], in file HotSpotClicker.ini. This is an extra DLL that HSC uses to generate a smoother series of tones, without all the gaps. You can graph using a tone of a constant volume, where the pitch is modulated to indicate the value, similar to the standard option, but without the gaps. Or, you can use a tone of a constant pitch, where the amplitude, or loudness of the tone is modulated.

this feature is not installed by default. To install it, use windows explorer to open folder c:\program files\HotSpotClicker. Locate the file called ToneGen.reg and press enter. Answer yes to the prompt. This will add the necessary entries to the registry. If you open the Tone Generator Setup, from the HSC actions menu, and the feature is not yet installed, HSC will offer to attempt to install it for you.

Tone Generator Setup

Use this feature to control how your pitch or volume graphs will be presented. Go to the HSC actions menu with hsc mods f10, choose Tone Generator Setup and press enter.
In this panel, most jaws hot keys have been disabled. Don't worry, you can always press escape to exit. Or, if somehow that doesn't work, wait 60 secondes, and this panel will close automatically.

Use the control+tab key to cycle between the three panels. Use left and right arrows to choose the parameter to be edited, and up and down arrows to choose the value for the selected parameter.

Control+Tab to the FM Frequency curve. This applies to the pitch-based graph, and lets you taylor the loudness of the tone at various frequencies. This lets you deal with the fact that your speakers, and perhaps your ears, may respond more or less to various frequencies. With this panel, you can smoothe things out, so all frequencies sound at suitable levels for you. and, you can control how low and high the graph will go in pitch. Ten frequency/volume data points are provided. Use left and right arrow to choose the pitch whose volume you want to alter. If none of the provided frequencies are the one you want to alter, choose the closest one, and then use the end and page down keys, to raise or lower the frequency of the selected data point until it matches the pitch that is really bugging you. Then, use up and down arrow to raise and lower the volume. Settings are saved automatically as you alter them.
The mimimum value encountered in the table will generate the lowest frequency of your data points, and the maximum value will generate the highest frequency. So, you can adjust the frequency span of the graph, by dragging the low and high tones up or down. Naturally, dragging is limited when you run into the nearest neighboring data point. So, you may need to drag several different points to get the curve you want.
To generate a test sweep, press f1, and press f2 when you want to stop it.

To adjust the loudest and softest tones used in the constant pitch, amplitude graph, press control+tab to select Amplitude Mode Parameters. Use left and right arrow to select the parameter you want to edit. The options are, the softest tone that will be played for the minimum value encountered, the loudest tone, used for the maximum value, and the pitch of that tone. Use up and down arrow to adjust the volumes and pitch, depending on which is selected.
To test the tone press f1.

To select which graphing method to use, press control+tab to reach Graph Mode Selections. Here, you can choose the standard frequency modulated method, or the smoother amplitude or frequency modulated methods. Probably, you will only use the standard method if, for some reason, the ToneGen.dll does not work on your system.
You can also specify the length of each tone, which is a way to cause HSC to not go through the data points so quickly.
And, you can choose where the virtual cursor will be parked after the scan. choices are to leave it at it's initial location, o the maximum value, the minimum value, or to the place where the largest change between neighboring data points was encountered. This feature only works when new data is scanned, or when the column is calibrated. It Does not work when re-running the data for review. If you have not scanned a column for over one minute, HSC will revert to scanning for new data.

List of Table-related post processors

Call these from your hot spot as needed to graph a column. All functions have no return value.

ToneGraphTableDownHSC

Parameter 1: 1 = autocalibrate, 0 = use existing calibration. Call this from a hotSpot with the cursor positioned in the top cell of a collumn you want to graph. HSC will audio graph from here on down to the bottom of the column.

ToneGraphTableUpHSC

Parameter 1: 1 = autocalibrate, 0 = use existing calibration. Call this from a hotSpot with the cursor positioned in the top cell of a collumn you want to graph. HSC will audio graph from the bottom of the column up to the currentl location.

MoveToColumnMaximumHSC

Parameters: none Once a column has been audio graphed, this function will take the cursor to the cell that contained the largest numerical value.

MoveToColumnMinimumHSC

Parameters: none Once a column has been audio graphed, this function will take the cursor to the cell that contained the lowest numerical value.

MoveToColumnBigBumpHSC

Parameters: none Once a column has been audio graphed, this function will take the cursor to the cell that differed most dramatically from it's neighbors.

Table Trackign Configuration File

Data to support this function is maintained in file HSCTables.hsc, which will reside in the folder where hotSpots for the current application are stored. This file does not exist until the first time a table is scanned. With each new table, or each new column in a table, this file is updated.

this file is a standard .INI format file, with section headers in Brackets, and key=Value pairs inside each section.

There is one section for each table, plus a [main] section.

Main section of HSCTables.hsc

This contains information to control the behavior of the scanner. the following keys exist:
Delay=1
This controls how quickly HSC scans the tones. Larger values slow the scanning down. A value of 1 is the fastest possible scan rate.

Table Headers in HSCTables.hsc

The rest of the section headers each identify a particular table, and consist of the URL to the page containing the table, followed by a semicolon, then the index to that table on the page. For example, the second table on HotSpotClicker.org will appear as the following section header:
[http://HotSpotClicker.org;2]
This means that if the page author adds, or deletes a table, this will need to be adjustted manually to preserve the data. Or, you can just scan the table again, and create a new entry.

The following keys exist:

These two are the calibration end points, and represent the cell value that will translate to the lowest and highest possible tones for each column. Increasing cell values always result in higher tones.
These two key names are prefixed with the column number. So, the calibration for column 7 would look like this:
7Minimum=4000
7Maximum=5000
This would specify that the data in column 7 should range between 4000 and 5000. Data outside this range will result in a special, percussive strike instead of an audio tone, to indicate that data went outside the expected range. At the end of the scan, when data is summarized, range violations will be announced.

Other keys in this section are used when non-numeric data is being analyzed. In that case, the key value here should be the exact cell contents of interest, and the value should specify the name of a file to be played when that value is encountered. The file should be a .WAV file, and include the extension, but no path, and the file is presumed to reside in the settings\enu\sounds folder under the user-specific settings area of jaws.
The value includes a semicolon ";" followed by the delay time in tenths of seconds that HSC should wait while the file is played.
For example, the following keys will play a file called feline.wav when the word "cat is found, and canine.wav when the word "dog" is found. HSC will wait one tenth of a second during the word Cat, and two tenths while Dog is played.
cat=feline.wav;1
dog=canine.wav;2
Note that all such entries are not column-specific. That is, you can not play a different file for the word dog depending on in which column the word is found.

HSC will play the default ding whwhen if finds non-bnumeric, non-blank cells for which it has no entry, and be silent when it finds blanks.

Object Navigation

This feature consists of two main parts:
  1. an object browsing keyboard layer, which lets you use the NumPad arrow keys to navigate between MSAA objects, plus a host of number row keys to let you query various attributes of the current object.
  2. The ability to define a hotspot which addresses the final object in your most recent browsing session. Such spots can either activate the object, or can just speak a set of aspects of the object, or can do both.

Object Browsing

By pressing the object layer activation key, control+alt+shift+LeftBracket, your keyboard is redefined to support browsing among the various objects. A small metallic sound indicates when you enter the layer. Once the layer is active, Pressing any key that is not defined for the browsing layer will result in the playing of a complimentary sounder, and the keyboard will be returned to normal. All keys described in this section are for the browsing layer only.

While in the browsing layer, press f1, to hear a list of hot keys defined for the layer. Double click f1 to take an audio tour through the various sound effects and their meanings. Or, you can also access the list of object layer hot keys from the hsc mods + h, by pressing enter on the item near the bottom, that refers to Object navigation.

The browsing layer has two primary purposes:

This browser maintains a review object, which is moved around, and equated to various objects in your system as you navigate.

In general, the numPad arrow keys are used to initialize the review object to the object with focus, and then to navigate from there by accessing peer level objects, moving to parent objects, or to the first child object. In addition, some objects contain elements, which can also be visited, using the 1 and 3 keys on the numPad, end and page down. Many buttons, and other actual controls, actually exist as elements of an object. It usually makes sense when opening the browsing layer, to press the home key to initialize your review object to the object with focus. This also routes the mouse cursor to the top left corner of that object.

Also, the numbers row contains hot keys which can be used to query the current object for the value of it's various attributes. Some of them provide additional information if double clicked. For example, the number 3, which reports the object value, when double clicked, will report the text that lies inside the physical boundaries of the object.
This set also includes a few toggle controls which represent your preferences about how the utility should operate, such as turning on or off the sound effects, filtering out apparently extraneous objects, and focus tracking.

Options are provided to allow the review object to be told to perform it's default_action, or to take the mouse to that object for experimental clicking, or to just repeat the summary of the present object.

Hierarchy Orientation

This object hierarchy is essentially a tree view, but with some slight differences. Some people like to display their tree views horizontally, with the root of the tree on the left, similar to what Windows does with file and folder structures. In that view, you would use right arrow to descend into a node, and left arrow to pop back out. As you used the up and down arrows, you would move between peer level nodes. And, like windows trees, an up or down arrow, when it hit the end of a peer group, would automatically pop back out one level.

However, HSC treats this is a vertical tree. The main root is at the top, and you press down arrow to descend to lower and lower logical peer levels. Moving between peers at the same level is done using the left and right arrows. And, when you get to the end of a peer group, you hear a short buzz, but the level is not automatically changed. Instead, you review object remains unchanged. This makes it more obvious where you are in the tree, because your nesting level doesn't change automatically. Nodes do not have open and closed statuses. So, you don't enter the node unless you specifically choose to do so.

In addition, this orientation lends itself to using stereo sound effects to answer a common question about whether or not there are peers in either direction without having to operate the arrow keys and determine the answer experimentally. But rest assured, if you are a monaural participant, the sounds are all unique, so stereo is not essential.

Initializing the Review Object

before you can browse, you need to establish the browsing starting point. You can start with the object that currently has focus, or you can acquire the object at the active cursor position. To get the object with focus, press the home key.
To get the object at the active cursor, including invisible, PC or JAWS, position the cursor, and press the numPad start, which is the right mouse button in JAWS.

Searching For Objects

If you know of some text that is contained in an object of interest, you can search the current peer level for an object that matches. The search utility does a case-insensitive search for the desired text in the object name, description and value fields, and searches only the present peer level, which is the same set of objects you get when you use left and right arrow..
press the f key to enter the search text. HSC will search starting at the first object on this level. Or, if the text has already been entered, you can use f3 and shift+f3 to search forward or backward on the current level, starting at the current object. If an object is found, it becomes the new current object.

Sound Effects

Don't be so quick to turn off the sound effects. They provide useful information about the current object, and can indicate such things as:
  1. whether the object has peers, to the right, to the left, or both. Notice the small dink sounds, or finger snap.
  2. Whether the object has children. Notice the drum sound.
  3. Whether it contains elements. Notice the rattling sound.
  4. Whetehr it is the object with application focus. Notice the old pohlaroid camera sound.
Listen in stereo, if you can, because the effects are designed to tell you stuff about peers to the left, or peers to the right, etc. Even the short buzz, that occurs when you hit the end of a group, is in stereo to remind you which wall to avoid. For example, when arrowing up to a higher peer level, you will often hear sounds that indicate which dirrections deserve further exploration. A dink on the right means you should move to the right to hear more peer level objects in that direction. Dinks on both sides, means peers to the left, and peers to the right. Here I am. Stuck in the middle with you.

To take a tour through the various sound effects, and their meanings, while in the object layer, double click the question mark. Then, press enter on a description to hear the associated sound. This dialog also has controls to enable or disable the sounds. And, there is also a layer hot key on the numbers row to turn off sounds if you really find them annoying, or just can't see the benefit. However, not all sounds are disabled. Buzzes that limit navigation are always enabled, and the mouse monitor effects also do not honor this selection, since the monitoring would be mostly unusable without them.

To hear the current setting for soundsEnabled, press the associated numbers row key once. Or, double click to toggle.

Sound Files Listing

Here is a list of the sound files played, in case you want to create your own sound scape. These are located in the settings\enu\sounds folder, in the user-specific settings area of JAWS.
  1. Children.wav - this node has children, but no peers, no elements, and is not the object in focus.
  2. ChildrenElements.wav - an object with elements, that also has children
  3. Elements.wav - an object with simple elements, but no children, peers, or focus
  4. HSCBuzzer1, hscBuzzerLeft and HSCBuzzerRight.wav - no more objects in this direction.
  5. HSCFocus.wav - This object has focus
  6. HSCLayerOpen.wav and HSCLayerClose.wav - activation and deactivation of the object navigation keyboard layer
  7. PeersBoth.wav - peers both left and right, no elements, no focus
  8. PeersBothElements.wav - this object has elements, and peers in both directions.
  9. PeersLeft.wav - to the left only
  10. PeersLeftElements.wav
  11. PeersRight.wav
  12. PeersRightElements.wav
  13. Mouse monitoring: HSCOTop.wav, HSCOBottom.wav, HSCOLeft.wav and HSCORight.wav.
  14. Buzzers: HSCBuzzer1, HSCBuzzerLeft, HSCbuzzerright, and HSCBuzzerLow

Default Action

Each object has an attribute called default_action, which means what the object will do when commanded to take an action. Usually, this is equivalent to pressing enter. But, if you query this attribute, via the numbers row, you might get a little better idea what will actually happen. A numPad key is provided to perform the default action. You can press insert+numPad5 to perform the default action.

Node Filtering

This option is switched on and off via a key on the numbers row. With this option turned off, vertical navigation will discover intermediat objects which are called windows, or clients, and which have no peers and no elements, and no default action. The only path through them is from parent to child, or visa versa. These play some important role in the operation of the application, but do not have any apparent value for purposes of HSC. With node filtering turned on, the navigation logic skips these nodes, and does not present them to the user. If you are building a path, as described below, for defining a hotspot, the node is included in the path automatically, since, even though the node may be uninteresting, it would be necessary to pass through that node on the way to the target. To hear the current setting, press the associated numbers row key once. Or, double click to toggle.

Object Focus Tracking

This mode can be switched on and off from the numbers row. If it is on, then whenever a default action is performed, HSC will wait for any resulting change of focus, and then reInitialize the review object to point to the new object with focus. So, your review object will move around as you operate your application using this method. You might turn this off if you didn't want any focus changes to be messing with where your review object currently sits. To hear the current setting, press the associated numbers row key once. Or, double click to toggle.

Speak Object Location

There is a numbers row key which will speak the row, followed by the column of the top left corner of the object. Double click to hear a more complete report, including the height and width.

Route Mouse To Object

In the navigation layer, insert+numPad Minus has been redefined to route the mouse to the top left corner of the current object. It moves to the corner of the object, not necessarily the top left corner of the text inside it.
This key exits the layer, and returns you to a mode where you can use the usual mouse controls for experimentation. To continue object navigation, you will need to re-enter the layer.

Mousing around the object

Once you locate an object of interest, You can use the arrow keys, in standard jaws mode, as described below, to explore the object. This allows you to move the mouse to a particualr location inside the object, in preparation for performing some standard mouse action, or speaking some unit of text, just as is done with traditional HotSpots.

Press the Mouse Monitor key, usually the page up key, to have HSC begin monitoring the position of the mouse relative to the edges of the current object. This key activates the jaws cursor, and exits the browsing layer, so you can mouse around.

There are two modes to this monitoring, which are controlled by a toggle assigned to the equals key in the layer. Press Equals once to hear the setting, or double click to change it. The two options are:

  1. To have HSC notice when you leave the object, and force the mouse cursor back to the edge you just left. You'll hear a short buzz, and the mouse will return along the same path it traveled when it left the object.
  2. Or, to allow exploration around the object, HSC will notice when you are outside, and periodically play a set of stereo sounds to indicate in which direction the cursor lies from the center of the object. This includes not just left, right, up or down, but also combinations of these, so you can tell if you are, for example, above and to the left of the object.

The sounds stop if you activate the PC cursor, or if the object becomes invisible. If you get lost, you can always activate the layer, and toggle the mouse restriction, with the equals key, to force the mouse to be routed back to the object. This will keep the monitoring active. Or, you can route mouse to object with insert+numPadMinus, which will route the mouse, but will terminate the monitoring.

Note that it is perfectly legitimate to explore the periphery of an object, and define a hotspot with use the corner of an object as it's reference point, but actually clicks a location that is outside the object. Simply allow the mouse to escape the object, and position it to the point of interest before defining the spot. The same parameter which controls which window corner serves as the reference for standard hotSpots applieds to object references as well.

Object HotSpots

You can define a hotSpot that will activate an object, or will speak certain aspects of the object. Spots like this use a navigation path to find the object. And, they learn that navigation path from your most recent session with the object browser. To prepare for a spot like this, do the following:

It is important to note that a single hotspot does not include do_default_action as part of it's path, but is strictly limited to simple moves. . That is, if the action you need to perform actually includes navigation to some object, doing default action on it, and then navigation to yet a different object, an operation like that can not be done in a single hotspot. It would be necessary to define two spots, and chain them together. The first would navigate to the first object, and then do default action. then, it would run the second spot, which would perform a completely different navigation. To actually set that up, you would need to manually perform the first leg of the navigation, and define the first spot to do default action. Then, you would execute that spot to set up the conditions for the second spot. Finally, perform the manual navigation required for the second leg, and then define the second spot. then, chain spot1 to spot 2.

Navigation Path Format

It seems worse than it actually is. When choosing a navigation reference, HSC drills upward in the hierarchy of objects, looking for the highest level object that is not named as the desktop. Generally, this is the top level object for the application, or for the active dialog. This object is referred to as the great ancestor.

A Navigation path represents the series of moves required to navigate from the great ancestor, down to the target object of interest. Generally, this is a series of steps involving moving down to child objects, and moving across to peer objects.

However, since the number of objects at each peer level, and even the order in which they appear, could be dynamic, HSC prefers to use object names, rather than peer indices. So, if the object we need to go through on this peer level has a name, the path will be enhanced to record the object name, and HSC will search the peer level for the nth occurrence of the name. The number n, which identifies the occurrence number is calculated automatically, based on the conditions at the time you define the spot.

path syntax

This is defined in more detail in the HSC_parameter_reference document. This is a compact syntax for describing the navigation movements that were made when traveling from the great ancestor down to the target object. The path is broken into a series of items, separated by the vertical bar. Each item represents a direction of movement. For exampel, a descent into a child would be one item. then, moving across the peer level, looking for an object, would be a second element. The latter form, the horizontal moves, often include the object names. but, vertical elements only contain an iteration count, indicating how many identical vertical moves to make.

For details about the format of a path element, consult the HSC parameter reference . Look for parameter "NavPath".

Targeted Elements

If your navigation had involved moving to one of the elements of your final object, HSC would record that element number in the spot definition, in a parameter called childID. Later, when activating the spot, HSC will start at the current great ancestor, traverse the path, and will then also institute the childID in order to access the proper element of that final object.

Activating an Object HotSpot

These spots activate just like any other spot. After executing an object hotSpot, your review object will be left pointing to the object that was touched by your most recent hotSpot activation. That will be true, even if the validation failed, which will allow you to more easily debug the failure. You can enter the object browsing layer, and will be initially located at the object that was targeted by the most recent Object Hotspot.

If you look at the hotSpot definition, lots of traditional information is missing. This is because no window matches are performed, Absolute screen cursor addressing is not used. color, graphics and text searches are not used, etc. Not all useless information has been eliminated. But, most has. However, the definition contains new information used to help qualify the object. such as the great ancestor's name, number of elements, the object name, and the object type. If these data gathered from the object that is actually found do not match the expected values, which were garnered from the object when you navigated to it manually, then the spot will fail. If debug is turned on, the first offending criterion is spoken.

the only one you can disable is the requirement that the target objectName be the same. . Some objects actually display dynamic information in the name field. If you need to disable that check, open the definition, and set the ObjectName parameter to an asterisk "*". Or, to specify that the located name must simply contain the the name in the definition, but need not be exactly equal to it, preceed the name with a caret "^". If the located object has no name at definition time, , HSC will require that the located object must have a blank name field by setting the name to a dollar sign "$".

The name comparison is case sensitive. Correct capitalization is required.

Viewing the Object As A Window

Most objects have windows associated with them, You can often learn even more about the control of interest if, after having located and inspected the object, you can also look at it as a window.
To do that, while in the object browser, press hsc mods right bracket "]". The Window Browser will be initialized to point to the window connected with this object. When prompted, press hsc mods right bracket a second time, and the Window browser will open.

UIA Support

HSC provides limited ability to explore UIA, which is Microsoft's User Interface Automation protocol As of build 242, this section is not complete. You can explore UIA. but, you can not presently define a hotSpot that makes use of it. Not all control paterns are implemented yet, and many other things are only in the concept stage. This partial solution is being posted because other things compelled a release before it was finished. AT this stage, it is very much half-baked. It is hoped that this section can be completed in the next few months. If you are in need of it, send an e-mail message to Snowman@SnowmanRadio.com and complain about what you are missing.

Exploring UIA

This is a companion to the MSAA support that is already present. Press HSC mods, plus left bracket "[", to enter object mode. Once in Objedt mode, the O key toggles between MSAA and UIA modes.

Once in UIA mode, the arrow keys move between objects in the same way as does the MSAA browser. Left arrow to reach the prior sibling, right arrow to the next sibling, up arrow to the parent, and downArrow to the first child.

Before you can navigate, you need to establish the starting point. Double click the home key. That will Set up the internalstructure for the application you are investigating. Once you have done the double click of the home key, you are ready to run with UIA. Press the home key once to move your review object to the object with focus. But, a double click is required at first to get the internal structure initialized.

Once you land on an object, the numbers row keys will speak various attributes of the object. Double click a number key if you want HSC to announce that attribute automatically as you move around. Double click again, to remove that attribute from the automatic list.

Control Patterns

UIA has the concept of a control pattern, which is just a list of things you can do to an object that supports that pattern. Some objects support more than one pattern. To explore the patterns for the current object, press shift+5 on the numbers row. That will yield a list of supported patterns. Use up and down arrow to pick a pattern, and press enter. By using the up and down arrows, you can now see what data that pattern reveals. Some items shown are data items, and others are actions. , Values are shown in the format "name: value". The colon is the cue that it is a value. Methods have parentheses following the method name. Pressing enter on a method will run that method. Press escape to return to the list of patterns. Press escape again to return back to yoru application.

Window Browser

This feature is very similar to the object browser, except that it deals with windows rather than MSAA objects. Often there is a relationship between these. Usually an MSAA object has some window associated with it. Many windows have objects, but not all do. In short, viewing your system via a windows is just another of several ways to get information from it.

As described earlier, a window is represented by an enclosed area on your screen. Behind the scenes there are several pieces of information that HSC can learn about a window, not just where it is on screen, and usually the text contained within it, but identifying information such as name, class, control ID or type. HSC uses that information to discriminate between windows..

Similar to objects, windows are linked together in a tree-like structure. Each window contains 4 pieces of linkage information, which connect it to it's prior and next peer-level windows, to it's parent window, and perhaps it's first child window. There is only a link to the first child. If there are multiple children, you get to them by going first to the first child, then following along peer linkages to get to the child you want.

At the top of the tree is a single window that you can not access directly. But, you can see all it's children. Those typically represent applications that are running on your system. You can navigate between those high-level children, and descend into them to investigate their makeup.

This utility is designed to facilitate exploration of the windows hierarchy. And, it brings along with it yet one more way to define how a hotSpot identifies it's location.

To browse windows, press the window browsing layer activation key, Control+alt+shift+right bracket "]". You will hear the sound of a window opening, meaning that the layer is active, and than your keyboard has been fully redefined for purposes of the browser. This works exactly like the object browsing layer described earlier. Left and right arrows move between peer-level windows,up arrow goes to the parent window, and down arrow to the first child.

The number row keys are defined to give you direct access to various window attributes, and also includes a set of toggle controls for customizing how the browser works.

To review the total list of hotkeys, press f1 with the window browsing layer open. Pressing a key that does not below to the layer will close the layer. You can also find a topic on this in the main HSC hot key help, control+alt+shift+h.

Window Browsing around

The firstthing to do when entering the window browser, is to establish the browser as to which window to examine. Upon entry, the browser will be looking at the last window visited. That window may or may not still exist. By pressing the home key, the browser will lock on to the window that currently has focus.

As you move around from window to window, using the arrow keys, HSC will automatically speak various attributes of each window encountered. By default, this is set to name and class. However, you can customize what is spoken automatically by double clicking most of the numbers row keys to include, or exclude each of the items in the automatic list.

Hierarchical HotSpot Positioning

This is a positioning method that uses hierarchical relationships to find the window that contains the hotSpot. It relies on a portion of the window hierarchy in your application to remain fairly constant. HSC uses these relationships to locate the window. This will work in situations where the spot of interest is in some child window, residing under the top level window with focus. This method is not intended for use in other non-focused parts of the application.

Once you find the window in which you want to create a hotspot, using the window browser, the next thing is to find exactly where inside that window the spot should reside. Hot keys are provided, just as with the object browser, to route the jaws cursor to the top left corner of the window. You can also use the Mouse Monitor, activated from inside the browser with NumPad pageUp, which will then let you mouse around with the jaws cursor, either hearing stereo indications for when you are otside the window, or using a mouse monitor mode which restricts the cursor to that window.

Once the jaws cursor is positioned, use the spot creation wizard, hsc mods+A and choose the positioning mode called, Top Level Hierarchical. Proceed to define this spot in the customary way. HSC will store a NavPath parameter in the spot definition, which contains an encoded form of the instructions for descending from the top level window above the window with focus, down to the window where your spot resides.

At activation time, HSC finds the window with focus, moves up the tree to find what jaws calls the TopLevel Window, and then use the navPath instructions to descend down to the window of interest. When possible, HSC searches for control ID numbers, or class identifiers in order to rely less on direct relationships. But, in absence of these, it relises on the number of moves in a particular direction.

Viewing the Window As An Object

Many windows have objects associated with them, You can often learn even more about the control of interest if, after having located and inspected the window, you can also look at it as an object.
To do that, while in the Window browser, press hsc mods left bracket "[". The Object Browser will be initialized to point to the object connected with this window. When prompted, press hsc mods left bracket a second time, and the Object browser will open with the object represented by that window.

Editing HotSpot Definitions.

This dialog allows you to gain quick access to the parameters for a hot spot, and make changes to existing values, or remove criteria.

Press control+Alt+Shift+f4 to bring up a list of hot spots in the current set. The top line of this buffer will indicate whether you are viewing a list of Hotspots, or a list of window Prompts. Press enter on that line to toggle to the other view. The language in the rest of this section will relate to editing hotspots, but the same principals apply if you are editing window prompts.

The second line allows you to specify a hotspot by typing it's hotkey. If you press enter on this line, HSC will start beeping once per second, awaiting the press of a hot key. When you press a key that is assigned to a hotspot in the currently active set, a dialog will open, as described below, revealing all the parameters of the associated hotspot. This is not available for window prompts, because window prompts don't have associated hotkeys. That functionality is actually provided by defining a hotspot which sets focus on the control for which a prompt is defined. Press escape to close without editing.

Once you have chosen the view you want, use your arrow keys to select the hotkey input, or the item of interest, and press enter. If you chose a hotspot or a prompt, An edit box will pop up containing all the keys and values associated with the current definition. You can use up and down arrows to examine the value of each key, use left and right arrows to examine the details of an entry, and delete or insert new characters in an existing line. However, this is not a full text editor, and thus provides somewhat limited functionality. you can change values, and even delete lines, or paste from the clipboard.

All lines in this buffer, except for the top line, are expected to be of the form:

key=value

Each Key must be unique, meaning that only one such key exists in the buffer. so, if you want to enter a remark to help document your hotspot, you could do it like this:
rem1=This hot spot is intended for personal use only.
rem2=We make no guarantees that it actually works.
Notice that the rem1 and rem2 keys are unique. This allows them to be preserved by the definition editor.

For detailed information about the parameters and their associated values, consult the HotSpot Parameter Reference

Two special hotkeys are provided to assist in editing numerical selection fields, such as mode and action, where each unique number has a special significance. Use control+alt+shift, in conjunction with f11 and f12, to move between the various valid options for that parameter.

if you press enter in this dialog, the HSC moves on to a confirmation step. So, To insert a line break, press control+m instead of the enter key

In the confirmation step, you are asked whether you want to save your revised definition, even if you did not make any changes. If you choose no, then the changes will be discarded. If you choose cancel, the editor will be re-activated showing the changes you have made so far, and You can continue editing your definition. If you choose yes, which is the default, the information will be saved, and new values will be applied. Keys that you removed will now be absent from the new definition.

To temporarily disable a criterion, place an asterisk "*" in the first character position of the line you want to disable.

If you wish to preserve all fields within the hsc editor, but still have hsc Ignore them, do not use a semicolon at the far left of the field line. If you do, it will not be saved, and will no longer show up in the hsc editor the next time that spot definition is opened. The way to do this, is to place an asterisk "*" in the left most column.

This paragraph relates only to hotspots, and not to window prompts. To change the hot key assigned to a hot spot, revise the top line of the buffer, which is enclosed in brackets, to reflect the key name, with the modifiers in the correct order, control, alt, shift, windows. When the definition is saved, the jkm file will be automatically updated. But, you might have to shake JAWS up a bit to get it to notice. Focus in another application, or on the desk top, then return to your application. This will work even if no hot key is presently attached. such hotspots have the label duplicated in the brackets. Just erase that duplicated label from between the brackets, and replace it with your keyName. Remember, specify modifiers in the order, Control, Alt, Shift, Windows. Do not use the JAWSKey.

for more information on how to revise a hot spot definition, see Customizing Comparison Criteria.

Adding A Hot Key To An Existing Hot Spot.

If you already defined a hot spot, but have not yet attached a hot key to it, you can do so by following the manual steps listed in this section.

Activate the Edit Hotspot Definition dialog with Control+alt+shift+f4, and select the hotspot to which you wish to add the hotKey. the top line of this buffer will contain the label text, enclosed in brackets. Change the characters enclosed in brackets to the name of the key you want to attach. You must include the modifiers, in a particular order, separated by plus signs, such as Control+Alt+Shift+f2. Note that the order of the modifiers is significant, and that capitalization matters. Always list them in this order, Control, Alt, Shift, Windows.

When finished, pres enter and confirm that you wish to save the new definition. Your application's JKM file will be updated automatically, and your new hot key should be in effect.

How Do I find Out what Hot Spots Are Defined.

While focused in your application, press control+alt+shift+f1, or the key you have assigned to the HSCHotSpotHelp. HSC will present a dialog listing all hot spots in the currently active set, listing the key assigned, and the label you entered when defining each hot spot. Use the up and down arrow to review the list of keys. Press escape to close the dialog. You can press enter on any of the hot spots listed to activate that spot and do the click action .

To switch to a different set of hot spots, double click the Control+Alt+Shift+f1 key, arrow to the desired set and press enter.

Fine Tuning A HotSpot Location.

This section addresses situations where your hotspot is no longer in the correct position, and you want to adjust the location. There are several distinct approaches described here.

Finding The Location Without Clicking

If you define a HotSpot that does some kind of mouse click, but you find that it doesn't cause the intended action, it may be because the mouse was not position at exactly the correct location. So, you would like to return the mouse back to that location so you can do some exploring, but you dont want to perform the mouse click, in case it has other unintended consequences.

So, with the correct HotSpot set active, press Control+Alt+Shift+f2.

This dialog looks exactly like the HotSpotHelp dialog. But, you can arrow to the item you want, and press enter. The jaws cursor will be activated, and will be moved to the location currently defined for that item, but no click will be performed. Now, you can fine tune the position by moving the mouse. then, you can redefine the HotSpot in the usual way, with the updated location, or simply adjust the position as described below.

Which Window corner to Use As A Reference.

If you believe that the correct reference window is being used, but the precise location is not quite correct, and needs to be adjusted, there are several approaches you can take.

First, consider whether the correct window edges are serving as the positioning reference. Usually, controls are placed a fixed distance from the top and left edges. However, if that is not the case, using one of the other edges as a reference may lead to more constant distances. Use the definition editor, attached to HSC mods + f4, to change the ReferenceCorner parameter to specify the edges that are more likely to remain a fixed distance from your hotspot. The Reference Corner is a numeric field, so you can use the Value Change keys, hsc mods + f11 and f12 to alter this parameter.

Here is a listing of the possible selections for this parameter, and which position parameters in the definition are used for that mode:
0 = TopLeft - WindowColumn and WindowRow
1 = TopRight - WindowColumnRight and WindowRow
2 = BottomLeft - WindowColumn and WindowRowBottom
3 = BottomRight - WindowColumnRight and WindowRowBottom

Updating Position To The Jaws Cursor.

If the referenceCorner is correct, but you still need to alter the position, you can update the definition as described in the next two paragraphs.

If a single hotspot is affected, you can place the jaws cursor at the new position, and update the hotspot position as described in this paragraph. Activate the JAWS cursor, and place it at the new location for the hotspot. Go to the HSC actions menu, hsc mods + f10, choose Adjust a Hotspot Location" and press enter. HSC will present a list of all hotspots in the currently active set, which use absolute, application, TopLevel, Current Window, or PC-relative positioning. use the arrow keys to select the hotspot to be adjusted, and press enter. The hotspot location will then be updated to the position of the jaws cursor.

Specifying temporary Offsets For Multiple HotSpots.

If many hotspots are at the wrong position, with each of them being misplaced by the same exact number of pixels, you may wish to specify a global offset, which will be applied to all selected hotspots. This is a way of moving a group of hotspots by a fixed amount. This should be used for temporary purposes, only to resolve a problem. It is best to incorporate the offsets into the affected spots, in case you need to use this feature again in the future on a different set of hotspots.

There is one set of global offsets in each hotspot set, including a horizontal and a vertical value. You can specify which of the hotspots in the current set will use these global offsets. If a hotspot is configured to use the global offsets, the global horizontal offset will be added to the horizontal position value for the spot. Likewise, the vertical global offset willb e added to the vertical position values for the spot.

To determine the offset values, Use HSC mods + f2 to move the jaws cursor to the location of a hotspot which needs to be relocated. Then, press alt+shift+PageUp on the NumPad. HSC will mark that location as a starting point. Then, move the jaws or invisible cursor to the new location, and press alt+shift+NumPad end. HSC will calculate the horizontal and vertical distances, and save those calculated results in case you want to use them later., as described below.

To specify the offset values, and to select which hotspots in the currently active set will use the offsets, Go to the actions menu, hsc mods+f10. There are three separate items there which apply. You can specify which hotspots will use the offset values, manually enter or review the offset values, or force the calculated offset values described above to be used.

To choose which of the hotspots in the currently active set will use the offsets, press
Offsets, Select Which Hotspots will Use Them
a list of all hotspots in the currently active set will be presented. At the right end of each line is a yes/no indicator, which indicates whether that hotspot will use the global offsets or not. Note that you can not choose to use the horizontal, but not the vertical offset, or visa versa. It is all or nothing.
press enter on an item to change it's state. Also, at the top of the virtual buffer, are four lines which take special actions, such as to force all hotspots to use the offsets, or to disable all of them. If you pres enter on the line that says Select By Hotkey, you can press the hotkey attached to a hotspot to change it's state.

If you want to perform a mass, global edit to adjust the position information for a group of hotspots, to reflect the current offset values, press enter on the line that reads
Permanently apply ccurrent offsets to selected Hotspots.
This will modify all hotspots which are currently set to "Yes" in the list, such that their position information will be modified by the amount specified in the global offset values. This is a way of editing the position of a set of hotspots at once. This updates the row and column information to take the offsets into account. AT the end of this operation, all hotspots will become unselected, and the offset values will have been incorporated.
press escape when you are finished.

To specify the offset amounts manually, or to review them, press
Offsets, Specify or review offset amounts.
you will be prompted to enter the horizontal and vertical offset values. Type in the values, or press enter to accept the current value for each. Positive numbers mean the hotspot new location is to the right, or down, from the old location. Negative numbers mean that the new location is above, or to the left of, the old location. Press escape to cancel the operation. HSC will attempt to return focus to the application. However, due to vagaries in the relationship between jaws and various applications, this may not always happen. But, the virtual buffer of hotspots, described below, will not be presented if you escape out of the offset solicitations.

To use the calculated results, described earlier in this section, from the actions menu, press enter on the line that reads:
Offsets, Use Calculated Values
This will preload the global offset parameters with the results calculated with the alt+shift+home key stroke described above. This is eaquivalent to typing in those numbers manually, but does not affect which hotspots are currently using the offsets.

Moving To A Screen Location Manually.

While exploring the screen to determine where a hotspot should be positioned, you may need to move the jaws or invisible cursor to a particular column and row. To do this, pres control+alt+shift+f9, and type in the absolute column, followed by the row, separated by a space. Then press enter.

To move to a location relative to the top left corner of the window containing the cursor, double click control+alt+shift+f9, and type in the horizontal offset, followed by the vertical offset, separated by a space.

You can learn the current location of jaws or invisible by pressing alt+shift+delete. Double click alt+shift+delete to learn the position relative to the left and top edges of the window containing the cursor.

to choose which window is used as a reference, either for learning or moving to a location, double click control+alt+shift+f7 to cycle between current window, topLevelwindow, and application window.

Sounds are provided to indicate the window context being used.

This is discussed in more detail in Color And Graphics Exploration

MultiClicking HotSpots

This section applies only to hotSpots being activated via a hotkey, and not to spots in the f1 list.
By default, all hotSpots are single click items. That is, each time you press the hot key, no matter how quickly you press it, or how many times, the same spot runs. However, there is a way to define that a single hot key will run one spot when pressed once, and a different spot when double clicked, and even yet a third when tripple clicked. This can significantly save keyboard real estate.
For all new hotSpots, defined after build 230, there is a new key added to the hotSpot definition, which appears as:
MultiClick=$
Older HotSpots will not have this key, but you can addit manually, using the definition editor or notepad. If the dollar sign is the only character to the right of the equal sign, then HSC will consider that this spot is a standard, single press hotSpot. As soon as you press the hotkey, the spot will run.
However, if you Change the dollar sign to the name of an existing hotspot, Then, the spot will be considered to be a double press spot. For example:
MultiClick=MyDoubleSpot|MyTrippleSpot
Replace "myDoubleSpot" etc, with your own existing spot names.
Notice the vertical bar delimited list of spots. If you are defining only a double click spot, then the vertical bar and MyTripplespot name should be omited.

Now, there will be a short delay after you press the key, during which HSC is waiting to see if a second or third press occurs. This is to avoid running the first spot inadvertently during the first press of a double or tripple click sequence. After it decides that no further key presses are coming, , HSC will select which spot to run based on the number of key presses that occurred. For a single click, the original spot will run. For second and third clicks, the MultiClick parameter will be queried for the name of the alternate spot to run. If you click more times than there are spot names listed in the DoubleClick parameter, HSC will run the last one in the list. You can define as many clicks as you need. But, recognize that any more than two or three clicks gets to be unweildy for the user.
Note that the spots referenced by this parameter are presumed to reside in the currently active set. The names used to identify the spots are the actual file section headers, the name that appears in brackets. Typically, such spots will not also have hotkeys attached, but this is permitted.

If a spot with a multiClick definition is run from the hsc mods f1 list, it will be run as though a single click occurred. And, when pressing enter on a spot from within the Chaining Browser, the only action that can be caused is a single click.

Confirmations

If you wish to cause your hotSpot to pause, and ask the user whether or not it should proceed, you can specify a confirm message in the hotSpot definition. You must add the key manually, using notepad, or the definition editor. Add a line that looks like the following: This key can be anywhere in the spot definition.
When HSC finds that key, it will put up a dialog using your confirm string as the message, along with buttons for Yes and No. If the user chooses yes, processing will proceed. If they choose no, then processing will stop, and no further chaining will occur.

Spot replicator.

This automatic procedure allows you to define one hotspot, and then to make multiple copies of it, spread out evenly over a line, or over a 2-dimensional grid. The horizontal spacing can be different from the vertical spacing. but, the distance from one hotspot to the next is required to be equal. this is handy for a paralel set of sliders, or a matrix of controls, and is much much faster than generating each hotspot manually.

To use this, you should first create a seed hotspot, at the left end of the line of controls, or at the top left corner of the grid. Then, place the jaws cursor at the right end of the line, or bottom right corner of the grid, where you want the final hotspot to reside.

next, press Control+alt+shift+f10, and choose Replicate Hotspot from the actions menu and press enter. You will be lead through a series of dialogs asking how you want the duplication to proceed.

You can choose from three methods for generating the label for each new spot:

  1. automatically generate it, based on the label of the seed spot, by appending an underline followed by a 2-digit ascending number,
  2. Grab screen text from each location to create the label,
  3. Or be prompted to tyep in each label manually.

you can also choose whether or not to be prompted for a hot key assignment for each spot, how many spots per row, and arranged in how many rows.

Once all inputs have been requested, a window appears which indicates the parameters of the replication that is about to occur. you can use the jaws cursor to examine the contents of the window without losing the location for the end spot, because that information has already been recorded. If you are not happy with the choices, press cancel to terminate the process entirely, or "no" to return to the first question, without losing any cursor position information. If you choose yes, the process will begin. Press escape at any time if you panic, and want out.

This duplication will add data the the .HSC file for the current hotspot set, and may also add entries to the key map, (jkm file) for your applicaition. If you don't like the results, you can undo the actions of the replicator by going to the actions menu, and choosing
Undo the Most Recent Hotspot Replication Process
The .HSC and .JKM files will be restored to their previous states.

Sharing HotSpot Definitions with Other users.

This section would also apply if you are installing previously defined hotspots into a new version of JAWS. For best results, perform the following steps in the order listed. This assumes that the HotSpotClicker has already been installed on the target machine. Unlike most applications, HSC must actually be installed into a particular version of jaws. There are a few common elements which are shared by all jaws installations, and several elements which are specific to a particular jaws installation. If you are running multiple versions of jaws,You need to install it into each version of jaws separately. So, when you install a new version of jaws, you need to install HSC again, selecting the new version of jaws as the target. When you merge your scripts in fromthe old jaws version, the connection will be restablished.

Start the version of jaws you will be using, and into which HSC has been installed. But, do not run the application yet. If you do, a default HSC file will be established, and you will need to overwrite it with the .HSC files you want to install.

  1. Copy the main .HSC file, and any associated secondary .hsc files for this application, to the jaws \Personalized Settings folder on the target machine. In more recent versions of HSC, those .hsc files are all contained in a subfolder, which is named according to the name of your application. In that case, just copy the entire subfolder.
  2. Unless you have moved the scripts over from a previous jaws version, and had already connected HSC to it, Use the script manager to open the application's script file, and add the line
    Use "HotSpotClicker.jsb"
    Right after the include statements. then recompile the file with control=s.
  3. Focus in the application, and wait a few seconds. HSC will detect that this is the first time the application has been run with these hotspots, and will automatically scan the .HSC file, and any associated secondary .HSC files, updating the application's key map with the necessary hot keys. You will hear a message stating that the key map has been updated.
  4. In order to force later versions of jaws to reload the new key map, you may need to focus in a different application, or on the desktop, then return focus back to the application. This is because those functions which should force a reload do not always work reliably.

To support this functionality, the HSC stores your JAWS Version and JAWS serial number in the main .hsc file. This is not confidential information, and nobody can do anything malicious with it. It is just used to detect when the .HSC file has been moved to a different installation of jaws, or when you have migrated to a new JAWS version. If the version and serial number stored in the file do not match those reported by jaws, then the key map is updated.

If you want to move to a different machine, which is running the same exact JAWS version and serial number, then you can still force the keymap update by going to the actions menu, and choosing
KeyMap - Refresh

How can I further Qualify the Hot Spot Location.

The most secure method offered by the clicker, is the Current Window relative method, which will search for the window containing the spot by name, RealWindowName, controlID, type and Class, control ID and subtype code. In addition, you can specify the presence of a text string, with optional associated foreground and background colors, or a pixel color, or the presence of a graphic.

To do further qualification, or to make further adjustments to the cursor position beyond what HSC already does for you, you will need to write a helper function in your own script file, which will be invoked by the HSC after the mouse is placed at the hotspot location, and prior to performing the mouse action. See: Pre-Positioning Callback.

Can My Scripts Automatically Activate A HotSpot Set?

Can hotspot clicker Automatically Activate each HotSpot Set for me as I navigate my application? so that when I assign new hotspots, or attempt to activate already assigned hotspots, the correct set for that focused window will be active?

yes, it can. This feature can be very helpful in situations where you have a very complex host application, containing a wide range of screen environments, each of which may require a heavy complement of hotspots, in order to become reasonably accessible. So much so that easily navigating among the sheer number of HotSpots, or assigning relevant or memorable hotkeys to them, becomes cumbersome or impractical. In such situations, it can be very convenient to create a hotspot set for each screen environment before beginning the spot definition process, and then have the clicker automatically switch hotSpot sets for you, as those environments gain focus. This feature is referred to as automatic window title set switching, and is different from automatic URL switching, discussed in Automatic URL Set Switching Note that, in many cases, TopLevel Window title switching will also load a new web page when you navigate Internet Explorer to a new web page, but it typically only applies to the main site, and not to subpages withing that site. These two features can be enabled at the same time, but, in most cases, only one mode should be enabled to prevent possible confusion

In HotSpotClicker.jss, there is a function called HSCFocusChanged, which you must call from your FocusChangedEvent in your MyApp.jss file. This code runs when focus moves from one window or control to the next.

There are two options for how to approach this, which will determine the exact modification you need to employ. In most cases, you will want to load a hotspot set based on the TopLevelWindow name. For example, in the notepad fileOpen dialog, you can tab around between the filename edit box, the combo box, etc. All of these reside under the main dialog, which is the same topLevelWindow. The same hotspot set would be loaded, regardless of which control had focus. Tabbing around would not cause a set switch. Only when the dialog closes, or a diferent topLevel window becomes active would a set switch occur.

Alternatively, in less common cases, you might want a different set to load for each individual item with focus, without regard to the topLevelWindow. Which option is appropriate will depend on your particular application. To choose which method, you can simply omit the call to function GetTopLevelWindow in the code referenced below.

In any case, to enable window title switching, you need to add a small piece of code to your application script file. to do this, open the script file for the application you are customizing, and navigate to the FocusChangedEvent function, if it contains one. Open the find dialog with control+f, and type the string
FocusChangedEvent
and hit enter. If one is present, Then copy one of the two lines exactly as it is shown below, and paste it into this FocusChangedEvent function, just above the first executable line. This will usually be the first line in the function that does not start with any of the following:
var,
int,
string,
or a semicolon ";".
Make a blank line just above that first executable line, and paste in one of the folowing lines exactly as it appears below:

For TopLevelWindow title based switching:
HSCFocusChanged (GetWindowname (GetTopLevelWindow (FocusWindow)))

For FocusWindow-based switching:
HSCFocusChanged (GetWindowname (FocusWindow))

This choice of which method to use needs to be made before you define any sets which should be automatically switched. If you have already define such sets, and change your mind about which method to use, those previously defined sets will no longer switch properly unless you change the set names to match the names of the focus windows. That means renaming the setName.hsc files, and changing the names listed in the [files list] section of the main .hsc file.

Please note that the name of the parameter to the above HSCFocusChanged function, involves a couple of calls to JAWS builtin functions, and makes use of a handle variable called FocusWindow.
Note: For those not familiar with scripting terminology, this is the parameter called FocusWindow, which is enclosed in parenthisies at the very end of the above line. If the first parameter to the FocusChangedEvent that may already exist in your application's script file, is not called FocusWindow, then you will need to change the variable referenced in the call to HSCFocusChanged, (that is, the last parameter in parenthisies at the right hand end of the above line just referred to,) so that it is the same name as the first parameter to your application's focusChangedEvent.

as an example, Say the top line of your application's FocusChangedEvent, looked like this:

Void Function FocusChangedEvent (Handle hCurWin, Handle hPrevWin)

Now notice that in this example, the second word after the first left parenthesis , the one to the right of the word "handle," the word with the comma directly after it, is not,
FocusWindow?
instead, it is,
HCurWin.
So, in this case, you would need to alter the pasted line above, such that it looked like this:

HSCFocusChanged (GetWindowname (GetTopLevelWindow (HCurWin)

Now, If your application's script file does not already have a FocusChanged event, then create one, which looks like the following:

Void Function FocusChangedEvent (handle FocusWindow, handle PrevWindow)
HSCFocusChanged (GetWindowname (GetTopLevelWindow (FocusWindow)))
; now call the version in default.jss
FocusChangedEvent (FocusWindow, PrevWindow)
EndFunction

Note: to create a function, you don't need to use the control+E new script procedure, you can simply copy and paste the entire function as shown above, into your application's script file.
Now, press control+s to recompile, then exit the script manager.

If Automatic Switching is enabled, each time focus changes to a new window, the clicker will search through the names of all hot spots sets currently defined for this application, and, if one is found matching the TopLevelWindow name which gains focus, it will activate that hotspot set, and, depending on the verbosity setting, announce the name of the new set. Controlling Verbosity is discussed in configuration Options.

Automatic switching will be disabled when you open the Hot spots Set dialog by double clicking the Control+alt+Shift+f1 key, and choose to activate a particular set from the list. this prevents the clicker from changing to a different set unexpectedly, causing new hot spots to be stored in the wrong set. To turn this feature back on, you must open the Hot Spot sets dialog, and choose
Enable Automatic Switching
and press enter.

In the default configuration, automatic switching is also disabled when you choose to create a new set, or Assign a new Hot spot. However, there is an option in the main .hsc file for your aplication, which can be changed to prevent disabling of automatic switching due to hot spot assignment, or set creation. See Configuration Options.

If your application's FocusChangedEvent is not presently set up to call the HSCFocusChanged function, the following item will appear in the Hot Spot Sets dialog:

Automatic Switching Is Not Presently Installed

To resolve this, follow the steps listed in this section for calling function HSCFocusChanged from your scripts.

Back to How To Assign a Hotspot.

There are two different methods for performing set switching when one of the automatic switching methods is enabled, but the current window title does not match any defined hotspot set:

  1. default back to the main set.
  2. Just keep the currently active set loaded
This choice is made in the HSC verbosity menu, accessed by pressing control+alt+shift+v. The default is to return back to the main set when the title is not recognized.

To switch sets upon press of a hot key, you can define a Hotspot which does not perform any mouse action, but simply activates a different hotspot set. SwitchHotspotSets is one of the options in the list of mouse actions presented when you are defining the Hotspot. However, switching using this method does not disable automatic switching, making it possible to use a mix of manual and automatic activations. When using a mix like this, it is often good to go to the verbosity menu, hsc mods+v, and tell HSC to switch only when a window title match is found. this prevents defaulting back to the main set when no match is found.

To have your own custom scripts activate a particular HotSpot set, you can call a function called HSCActivateThisSet, with the string parameter being set to the set name, which is the characters to the left of the equal sign in the [Hotspot Files List] section of the main .hsc file. That function is listed in HotSpotClicker.jss.

Automatic switching can be disabled and enabled by an individual hotSpot , by using the custom function described in DisableSetSwitchingHSC

tip: since there is no default hotkey in jaws to easily check the top level windowname at any given time, you can check that sets are being activated as expected as follows, :

after being certain that you have created hot spot sets for at least two pluggins within an application as described earlier, simply bring focus to each of these windows, then doubleClick the hotSpot help control+alt+shift+f1 keystroke. the set which is highlighted in the list, will be the currently active set. You can check this either by pressing the ReadCurrentLine, or ReadSelectedText, hotkeys in jaws.

How Can i Make JAWS Repeat The Last Hot Spot Message.

You can cause JAWS to repeat the most recent HSC message by pressing Control+Alt+Shift+apostrophe. Double click this key to open the virtual viewer, allowing you to use up and down arrow to browse the most recent HSC messages.

In addition, in the HotSpotClicker.jsh file is the definition of all global variables used by the clicker. three global strings called HSCThirdMessage, HSCSecondMessage, and HSCLastMessage contains the text of the most recently spoken messages, in case you want to make some other use of this text.

Repeating the most recent HotSpot

to simply run the most recent hotspot again, using it's configured action, you can pres control+alt+windows+grauv.

If you want the typical use of a hotspot to be to just read some text, but to allow a special use of that spot to employ a left or right mouse click, You can press hsc mods plus the left or right mouse button. The last spot will be executed again, but with the action code substituted to force a left or right single click matching the key you pressed.

Configuration Options.

This section describes a set of values in the [main] section of the main .HSC file for your application, which can be used to customize the behavior of the HotSpotClicker. Many of the items discussed here can be modified through the jaws verbosity dialog, tied to Control+alt+shift+v. In jaws versions prior to 13.0, insert+v will also work.
less common items required manual editing of the main hsc file.

To change these options only for the current application, you need to edit the .hsc file for your application in the Base Folder. If you want to customize the behavior for all future applications as well, edit file HotSpotClicker.hsc in the Settings folder for your language. That file is the template from which new hsc files are formed.

To determine the name of the .HSC file for your application. focus in the application, and press insert+q. At the end of that message, jaws will spell out the name of the application executable file. for example, if you are running Notepad, jaws would spell out:
N O T E P A D DOT E X E.
From this, you can know that your .hsc file is called
notepad.hsc

In the following subsections, we will refer to this file generically as the main .HSC file.

You can use a regular text editor, such as Notepad, to edit the appropriate file. When you switch focus back into your application, the new options should be loaded and placed in effect.

Values in the main .HSC file which are not listed in the following subsections, will be maintained automatically by the Clicker, and should not be altered manually.

Verbosity.

This value controls extra messages spoken by the clicker. If You can select any combination of options by adding up the numbers of desired options from the following list. Set this value to the sum of the numbers you have chosen.

The default value for this is 3, which is a combination of 1 and 2. this will cause set names to be spoken when autoSwitching, and will make sure dialog titles are spoken.

Expert users, who want only the minimum amount of speech, should set this option to 4 or 5, depending on whether they want set names autoSpoken.

Debug.

This section only applies to Application Relative or ToplevelWindow Relative positioning modes.

If you are having problems with hot spots failing, you can hear jaws speak the name of the attribute which is causing the first mismatch when comparing the attributes of the current window, when using application or TopLevelWindow relative positioning modes.

You can toggle this flag from the JAWSKey+v verbosity dialog.

This flag resides in the [main] section of the main .HSC file, and is of the form:
debug=0
To enable the debug messages, set this value to 1.

Allow Switch AfterAssign.

This value controls whether the act of creating a new hot spot set, or manually activating an existing set will disable automatic switching.

Restore Cursor Position.

This value controls whether the jaws cursor is return to it's original position after a click is performed, or whether it is allowed to remain at the click location.

Default restore Active Cursor

This option is in the verbosity menu, and controls how new hotspot swill be generated, with regard to whether or not the cursor which was active prior to the hotspot activation, will also be active afterword, or whether the jaws cursor will be left active. Each hotspot has it's own setting to control it's own behavior. This option only controls the default value for that parameter for all newly defined hotspots.
0 = the jaws cursor, if required by the hotspot, will remain active
1 = The active cursor will be restored.

Trap Keys.

Ideally, we wanted to trap all keys during the hot key assignment process so that, if the key you pressed is presently connected to a script, or has meaning to the application, that key would have no affect, and thus would not cause unintended consequences. And, of course, the keys would be enabled once again when the assignment process completed. However, this process is not reliable, especially under JAWS 6. therefore, it is disabled by default, and you must rely on your own knowledge of your key assignments to prevent this from happening. Of course, the HSC will examine your Key Map to prevent duplicate assignments, but we can not keep that script from running when you press the key, unless you change the default option in your main .HSC file by editing the value described here. Normally, this is not a major issue. But, do this if you are especially trouble by accidental activation. We think you'll be more troubled by the annoying behavior of losing control of your screen reader, which sometimes happens when JAWS loses focus during this process.

This value appears as:
trapKeys=0
And has the following meanings:

Set Switchnig Method

This option controls how hot spot sets are loaded based on window titles, and chooses what happens when a title is found for which there is no hotspot set defined. The choice is whetehr to default back to the main hotspot set, or to continue using the currently active set.

Technical Extras.

In this section, we note some of the extra, more esoteric features that you may want to use if you are technically knowledgeable, or at least adventurous, and wish to ring the very most flexibility out of the HotSpot Clicker.

Custom Functions.

You can customize the behavior of each hotspot by supplying the name of a post-processing function in your application script file, which should be executed after the mouse is routed to the target location, the click action, if any, is executed, and jaws has done a pause to allow the application to respond.

To attach a post-processing function to a hot spot, press the Control+Alt+Shift+f3 key. A dialog will open, which will allow you to select a hotspot from the currently active set, to which a function should be attached. Press enter on a hotspot name to open a list of functions which can be attached. The default list includes those hsc-resident functions described in the following subheadings. But, you can add your own names to the list, by clicking the _Create your Own, item near the top of the list. Type in the name of the function you intend to use, without parentheses. This function name will be added to the list, and will be offered in all subsequent sessions with this application. It is not necessary that the function actually exist at the time you attach it.

the HSC records your custom function names by adding entries to the [user functions] section of your main .HSC file. The format of the line is the function name, followed by an equal sign. Characters to the right of the equal sign are ignored, so you can enter nothing, or any comment you like. For example:

MyFunction=one of the funkiest functions I ever wrote

The function is presumed to reside in your application script file, or in the HotSpotClicker itself.

If you choose None, then no function will run in response to this hot spot.

The function you specify here will also be executed if you simply move to the Hotspot, using the Move to HotSpot dialog. this is useful for testing purposes.

Note that this feature is intended to apply to functions, and not to scripts. however, rumor has it that you can activate a script through this feature, simply by placing a dollar sign, "$", ahead of the script name in the HSC file. Some of the functions provided by the HSC itself require further information. When you choose such functions from the list on the control+alt+shift+f3 key stroke, and then press enter, any additional information required for the selected function will be requested.

The specification of which function to run appears in the hotSpot definition on a line that begins with the keyword, "function=". The characters to the right of the equal sign comprise the name of the function to run.

The hsc mods+f3 keystroke sets up a single function to run. If you already had a function defined, this dialog will disconnect that function, and replace it with the one you choose.

To run multiple functions, you must use the Definition Editor, and modify this line to list all of the functions you want to run, separated by vertical bars, "|". Each function will be run, starting with the function left most on the line. This makes it necessary for you to know the names, and parameter lists, of the functions you want to call in order to encode a complex specification correctly.

As a rediculous example, suppose you wanted your hotspot to say the word "beep, delay 3 seconds, and then say the word "bop". Your function= specification should look like this:
Function=SayString("beep")|delay(30)|SayString("bop")

Function nesting is possible, using an obscure syntax which uses "<>" "{}" and "[]" brackets to enclose function names. Nesting is a concept in which you obtain the value to be supplied in the parameter list of one function, by calling a second function first. the <> signs bound the first sublevel, {} bounds the next lower level, and [] bounds the third and lowest level. Only three levels are supported.

Some examples, using standard JAWS builtin functions, are as follows:

To say the name of the window with focus:
Function=SayString(<GetWindowName({GetFocus})>:)

Note that the parentheses are only required if the function has parameters.

To Say the name of the application main window:
Function=SayString(<GetWindowname({GetAppMainWindow([GetFocus])})>)

it is valid to combine both simpel and complex specifications, separated by vertical bars. for example, to say the word "hello, followed by the name of the window with focus:
Function=SayString("hello")|SayString(<GetWindowName({GetFocus})>)

After your custom function completes, HSC will normally control which cursor is left active. If you don't want it to do this, change the RestoreCursor parameter in the definition to 0. This parameter was added in version 7.51, and may not exist in your spot definition. If not, add one that looks like this:
RestoreCursor=0
If this parameter is absent, it will be defaulted to 1, which means, yes.

the following subsections describe predefined functions which have been provided as part of the HotSpotClicker scripts, which you can use in your own definitions.

MouseUp MouseDown

There are four functions for modifying the mouse position by a prescribed amount. The typical usage would be to jump to the hotSpot location, and then to move a certain number of pixels in a particular direction. For example, to drag a knob, a hotSpot might use the LeftButton Lock action. It would go to the location, lock the mouse, and then drag the mouse by a fixed number of pixels.

If the mouse is locked when these functions run, it will be unlocked after the movement has completed.

the following four functions perform this movement. Each accepts one parameter, which is the number of pixels to move.
MouseUpHSC (int amount)
MouseDonwHSC (int amount)< MouseLeftHSC (int amount),br. MouseRightHSC (int amount)

Move To Next Color Change

The following 4 post processing functions require no parameter, but wil move the mouse in the indicated direction until a change in color is detected. You can only move horizontally, or vertically, not at an angle. These are similar to alt+shift+windows+arrowKey.

OpenMenuHSC

Once a menu, and it's subMenus have been defined, as described in Menus, this function can be called from a hotSpot to activate a particular top level menu.
If the topLevel menu has only one submenu in it, then HSC will open the submenu directly. Parameterrs:
  1. MenuName - name of the menu to activate
  2. SubMenuname - optional, if not provided, the first subMenu in the menu specification is selected

SelectMenuHSC

This function is most useful when more than one top level menu as been defined. Once at least one menu, and it's subMenus have been defined, as described in Menus, You can call this function from a HotSpot. It will present a list of all top level menus, and allow the user to select one of them, press enter, and be taken to that menu. This allows a single hotkey to access all menus in the set.

HSCDecodeHotSpotColor.

This function will examine the color at the hot spot location, and attempt to look it up in the section for this hot spot in the HSC file. If that color is not found, HSC will prompt you for a function to run for that color, by presenting a list of known possibilities. You can write your own function to handle this color, or choose from the available set. Some of the functions offered by HSC require further information, which will be subsequently solicited in the next dialog. For example, function HSDSayPhraseByColor, will solicit a text string to be spoken when this color is encountered.

Normally, this function will prompt the user for how to handle new colors that it finds. However, you can cause jaws to remain silent, or speak a special string in this condition. To do this, open the definition editor and revise key UnknownColor. This key will be absent from hotSpots generated by earlier versions, but can be added manually.

If you want to define behavior for all hotSpots in the set, manually add this key to the [main] section of the .hsc file for the current set. Any spots with have their own local definition for the key, will use that definition, ratehr than the set-wide definition in [main].

The string to the right of the equal sign can contain one or more of the following special 2-character symbols. Most will cause HSC to replace the special code with related information from the environment:
%n Insert the name of the Hotspot
%c insert the RGB color value
%s be silent %p play sound file.

The %p code must be in the first 2 characters, followed immediately, by the name of a .wav file to play when this event occurs. You can specify the full path to the file. Or, if only a file name is listed, HSC will look in the same folder where the .HSC files are located. But, the %p directive, can not be accompanied by any spoken text. All text other than the %p itself is assumed to be part of the filename.

To cause jaws to remain silent, add the key:
UnknownColor=%s
The special %s represents a blank string to HSC.
Or, if you want jaws to include the color number in the message, for debug purposes, you can insert the special code "%c" in your string. For example, if the test spot is positioned on color white, and This function does not have a specification for what to do when white is encountered, you could add the following key to your definition:
UnknownColor=Color %c is not recognized by Hotspot %n
JAWS would say:
Color 255255255 is not recognized by hotSpot test

In order to tell HSCDecodeHotSpotColor what to do when a color is recognized, you should not define the UnknownColor key listed above. Or, if you have define dit, use the verbosity menu to set debug mode to detailed. This will overide the UnknownColor key, if it exists. Then, activate the hotspot to see a list of functions you can use to respond to the current color.

In general, the supplied functions allow you to do the following for each unique color:

Note that you can defined unique actions for each color, such as speak a predefined phrase when one color is found, or speak a frame of on screen text for a different color , or activate a different hotspot for yet a third color, which, if you like, might even activate a completely different hotspot set.

If you choose to play a sound, sounds are presumed to reside in the same folder that holds the .HSC files. However, full path names are accepted, though not likely to be portable.

If you change your mind about what should happen when a given color is found, then you will need to learn the RGB color value of the location. Once the location is set to the color you want to modify, Use control+alt+shift+f2 to move to that hotspot location, and use alt+control+NumPad1 to hear the 9-digit RGB value. use the definition editor, control+alt+shift+f4, to modify the hotspot definition. Near the bottom of the definition, There are two keys for each color. the key is composed of the 9-digit RBG string for that color. A second key is composed by adding the letter "f" to the end of the RGB value. This latter key will contain the name of the function to run when this color is found. The other key, which is just the RGB value by itself, contains information required by the function you have selected. delete the key with the f attached, and you will be prompted to redefine the action for that color the next time it is encountered. In simple cases, such as where you want to simply modify the text spoken, that text will be stored in the key without the f. You can simply modify the text, and then save the definition.

The color numbers recorded will depend on the color depth presently selected in the settings tab, under display options in your control panel. So, if you change color depth, your colors will not be recognized any longer. If you redefine the colors again, under your new color depth, the HSC will still retain the settings for your old color depth. Now, both color depths will be recognized. But, other than manually redefining the colors again, there is no convenient way of automatically mapping between color depths.

HSCProcessVerticalSlider.

There is also a function called HSCProcessHorizontalSlider. This discription will apply to both of these very similar functions. When we talk about the bottom of the vertical slider, we would also be referring to the left end of a horizontal slider.

When you first establish a hotspot corresponding to a slider, find a point which, when clicked, will set focus on the slider, but will not change it's value. This allows you to define a left single click action for this hot spot, in order to set focus on the slider. This is not really necessary, but provides a convenient way to set focus, in case the page up and page down keys actually move the slider. As an alternative, you could define that hotSpot with a positioning mode set to SetFocus.

Once you define this hot spot, you will need to use Control+Alt+Shift+f3 to associate the HSCProcessVerticalSlider function with this hot spot.

The first time you activate the hot spot with this function connected, the function will lead you through a series of steps required to determine the parameters which define the slider. Each time you activate the hot spot, you will receive new instructions. Once you position the mouse as instructed, then activate the hot spot again to record the information and perhaps receive further instructions.

The data gathered is as follows:

When specifying the minimum and maximum units, you can even include a minus sign for negative numbers, for such cases where, for example, you might want your slider to operate between minus 50 and plus 50 percent.

Once the slider is fully defined, activating the hot spot will result in the value of the slider being calculated, and then spoken. The mouse cursor will be left on the pointer of the slider, in case you feel like locking the left mouse button and having a drag. If the arrow keys, or the page up and page down do not change the slider, locking the mouse, and using alt+shift in combination with the appropriate arrow keys, may be the only way to manipulate the slider.

The hot spot definition in the active .HSC file will now contain the information gathered during the definition process. You can edit the hotspot definition and manually adjust the end points to fine tune the accuracy. To do this, you should adjust the left and right, or top and bottom positions by one or two pixels at a time. If you have an upDown slider, and dragging as low as possible does not quite produce a readout of the minimum expected value, then decrease the SliderBottom value. this is equivalent to raising the lower end point. However, if you raise it too much, then the HSC might report that the slider bar can not be found when the slider is at that extreme end of travel. this is because the HSC only searches the area between SliderBottom and Slider top. so, if the slider is outside that range, then it will not be found. Likewise regarding sliderTop. If pushing the slider all the way up does not quite reach the maximum number expected, then increase the sliderTop value slightly. this equates to lowering the top end point. The same problem of the slider not being found can occur here as well, if you increase the number too far.

Remember the minimum and maximum position values are pixel addresses. For horizontal sliders, these are column numbers. for vertical sliders, they are row numbers. Column numbers increase from left to right. Row numbers increase from top to bottom.

The following definitions apply to the values in the .HSC file. If you want to redefine a slider, remove all these keys from the HotSpot definition with The Edit Hotspot Dialog, , but leave the rest of the hot spot in tact.

HSCSaySpecialStrings

This function can be used to cause a specified string of text to be spoken. It requires additional input, which is the text to be spoken.
By default, the entered text is placed in a file key called "string". Starting in build 239, a second file key called "advString" will also be added, and will contain the same text. When HSC verbosity is set to beginner, the text in "string" is spoken. When HSC verbosity is set to Advanced, the text in "advString" will be spoken. Use the definition editor to alter the text in the two strings as needed. When older hotspots are processed using build 238, the text in "string" is spoken, regardless of verbosity.

ChainToNext>/a>

This function can be used to activate a different hotspot. In this way, you can chain hotspots together, causing a series of readouts, or actions to be taken, from the activation of a single hotspot. This function identifies the HotSpot that should run next, after this one completes. For information on how toidentify HotSpots that should run before this one, see ChainToPrior.

You can chain up to ten hotspots in a series. HSC is watching out for you, in case you inadvertently cause a hotspot to be chaned back to itself, there bye causing an infinite loop. The chain will be stopped, and a polite diagnostic message will be spoken. Specifying this function requires additional input, which is the selection of the name of the hotspot to chain to.

To remove a chain link from a spot, Use HSC mods + f3, and add the ChainToNext function. In the secondary dialog that asks you for the spot to chain to, choose "none" and press enter.

Chain To Prior

In cases where you need to run a different hotSpot first, such as when you need to set up the conditions under which the current hotSpot will be successful, you can establish a ChainToPrior attribute which causes a different hotspot in the current set to run first. That hotspot can even be a chain of hot spots in it's own right. When that spot, or chain of spots finishes, the current hotSpot will run.

Note that ChainToPrior, and ChainToNext are not mutually exclusive. Both can be used at the same time. If so, the prior link will be executed first. when that prior spot, or chain of spots finishes, the current spot will run, and then any ChainToNext spots that are attached to it. Again, a total chaining limit of ten sequential spots is imposed, in order to detect and prevent looping.

To add a ChainToPrior, Just choose chainToPrior from the function list. In the next dialog that appears, select the hotSpot that should run first.

To remove a ChainToPrior from an existing hotSpot, simply add the ChainToPrior function to the HotSpot, even though it is already there. In the secondary dialog that asks for the spot to be chained to, choose None, and press enter.

H3>KeyboardLockHSC and KeyboardUnlockHSC If you create a long chain of hotspots, such that you start the first spot in the chain, and they execute serially, one after the other, confusion can arrise if an impatient user presses keys while the chain is executing
To prevent this, assign custom functions to the first and last spots in the chain. The first spot should have the line
function=KeyboardLockHSC
Which will entirely lock the keyboard.
The last spot in the chain should have the follwoing custom function:
function=KeyboardUnlockHSC
Don't worry, it will unlock automatically in 5 seconds if you don't quite get this right.

DisableSetSwitchingHSC

This function allows you to stop HSC from automatically changing which set is active. To enable automatic switching again, call function EnableSetSwitchingHSC.

HSCSayFrame

This function can be used to cause the text in a frame to be spoken. You should define the frame, using the frames manager, before attaching this function to the hotspot. Selecting this function requires additional input, which is a selection from the list of presently defined frames for this applicaition.

SpeakTextInHSCFrame

In cases where you can not define a new JAWS frame, such as when you are working under scripts that were provided by somebody else, and can not be modified, this function allows you to define a region around your hotspot in which text should be spoken. In addition, you can choose only text with certain attributes, foreground and/or background color.

To use this, define your hotspot anywhere in the block of text you want spoken, on a word which has the attributes and color of the text you want to speak.
Use hsc mods+f3 and assign function SpeakTextInHSCFrame to that hotspot. If you then activate the spot, HSC will instruct you how to proceed with the setup process. The mouse exploration reference position, and bookmark, will be established at the hotspot location. This will help you find the spot again if you lose it, by pressing alt+shift+numPad3 to return to bookmark. Do not change the reference position during this process.
To establish the top left corner of the frame, place the jaws cursor there, and double click alt+shift+numPad1. Then activate the spot to record the corner, and to receive next instructions.
Next, place the jaws cursor on the right end of the longest line of text. If no text is in the window at the moment, you will need to use alt+shift and the numPad arrow keys to find the pixel location where the longest text would stop. the vertical position is irrelevant in this step. Then, activate the spot again to capture the right edge.
Finally, place the jaws cursor on the bottom line of text, or use alt+shift+ numPad arrow keys to move to the bottom line. The horizontal position is irrelevant in this step. Run the spot again
Now, the spot is ready for use.

In some cases you may need to fine-tune the parameters of the function to get exactly what you want. Use the definition editor to edit the function= line.

The parameters are listed below. But, if you want to redefine part of the frame boundaries, you can set the corresponding edge coordinate to 9999, and rerun the spot. Then, follow the directions to define that edge. That technique works for the bottom, or right edge, but not the top left corner. In the latter case, you might want to take the guessing route, or just delete the function and start over.

For example, If you need to move the right edgeout further, you can just edig the definition, and make a guess. Or, you can set the third parameter to 9999 and save the definition. Run the spot, and get instructions for defining the right edge. Move the jaws cursor to the new location, double click alt+shift+numPad 1 to record the location, and run the spot to incorporate the new location. The bottom edge is still there as before, and the spot now runs with your new right edge, and the old bottom edge.

This 3 step teqnique of defining the frame as top left corner, right edge, and bottom edge is preferred over the typical 2-step process because it is hard to get the bottom corner correct when the bottom line of text is not the longest line. So, it is difficult to establish the propr right edge.

The parameter names are listed as follows, from left to right on the "function =" line in the definition. Each of the first 4 are the distances in pixels from the actual hotspot location to the corresponding edge. Negative values denote edges that are above, or to the left of the hotspot. Strictly speaking, it is not necessary that the hotspot be inside the rectangle. But, that would be a typical use.

  1. horizontal pixel distance of the left edge from the hotspot.
  2. Vertical pixel distance to the top edge.
  3. Horizontal pixel distance to the right edge.
  4. Vertical pixel distance to the bottom edge.
  5. attributes, these numbers come from file HJConst.jsh which is part of jaws. These are set to match the attributes of the character at the hotspot location at the time you run the setup. but, you can change this to -1 to include all text, 64 for highlighted. Other values are shown in HJConst.jsh for bold, strikeout, italics etc.
  6. Text foreground color, set to -1 to ignore
  7. Text background color, set to -1 to ignore.

SayWord.

This function will simply speak the single word found at the hotspot location, after the mouse action has been performed. This is simply the JAWS builtin function for SayWord.

SayChunk.

This is the JAWS builtin by the same name, and can be used to speak a block of text which was written to the screen in a single operation. Usually, it yields a group of words which are logically related.

SayField.

This function speaks all text in the vicinity of the hotspot, which is of the same color as the hotspot location itself. This can be useful, similar to sayChunk, in reporting a group of words which are logically related. This option is also provided as one of the mouse action choices.

SpeakTextBetween

This function speaks a portion of the text on the line containing the hotSpot. If you want to speak text on more than one line, consider the use of a JAWS frame. Remember, HSC can also speak frames by frame name. This function requires two parameters, which indicate the number of pixels from the hotSpot location where text should be spoken. A negative number indicates the number of pixels to the left of the hotSpot, while positive numbers move to the right. For example, the following function
function=SpeakTextBetween(-30,20)
would speak text from 30 pixels left of the hot spot, to 20 pixels right of the hotSpot.

To use this:

  1. create a hotSpot in the middle of some block of text you want spoken.
  2. For the mouse action where no click is necessary, choose Say Text Between, or noAction, which will instruct you to add a post processing function. If you actually need to perform a mouse action first, choose that mouse action here, and just add the post processing function later.
  3. After the spot is created, Add post processing function SpeakTextBetween.
  4. When you activate the spot, HSC will remind you that the function still does not know where to speak, and will establish the mouse exploration reference point at the HotSpot location.
  5. Activate the jaws cursor, and find the first letter of the text you want spoken. Press alt+shift+end on the numPad to learn the distance to the reference location, and write down the number. If HSC says the cursor is left of the reference, write down a negative number.
  6. Move the jaws cursor to the last character to be spoken, and press alt+shift+end again. Write down the second number, if HSC says you are left of the reference, write down a negative number.
  7. Open the definition editor for the hotSpot, and go to the bottom of the definition where you will see the following line:
    function=SpeakTextBetween(0,0)
    Replace the 0,0 with the start and end numbers you wrote down earlier. Then, press enter to save the definition.

HSCCancelOriginatingSpot

The most common use for this is when you attach a custom function to a spot which is preChained to by another spot, in order to determine whether or not the originating spot is in the correct situation to run.

For exampel, spot x has a hot key attached, and is the spot the user wishes to run. Spot y is a validation spot, which is linked to spot x as a preChain, so that y will actually run before x. Write a custon function in your applications script file, and specify it as the post-processing function for spot y. In that function, perform whatever logic is required to decide if spot x should be allowed to run. If it should not, call HSCCancelOriginatingSpot to terminate the chain, and prevent spot x from running.

Other Post Processing Functions.

Other jaws built in functions are also offered, such as saySentence, SayToCursor, SayfromCursor, plus HSCSayWindowTypeAndText, which is equivalent to the JAWS builtin function sayWindowTypeAndText. Experimentation is the best way to determine which of these will do what you need in your particular situation.

SpeechOff and SpeechOn are also offered. These are useful when you chain hotspots together, so jaws does not chatter excessively as the hotspots are performing their actions. Typically, you would turn speech off in the first spot in the chain, and then turn it back on in the last spot. Be aware that, if you execute speechOff, jaws will no longer speak, until a speechOn is encountered.

If jaws stops speaking, it may be because you have executed a SpeechOff call without a subsequent speechOn(). If this happens, pressing inser+v will turn speech back on.

HSCBuildHotSpotList

If you are writing your own scripts, and you want to acquire a list of Hotspots in the currently active set, call this function. It resides in HotSpotClicker.jss, and returns a list of all hotspotsin two separate forms. the parameters are as follows:
  1. SectionNames - byRef, returns a vertical bar delimited list of the actual section names from the .hsc file. If a hot key is attached, this will be the hotKey name, else it will be the label.
  2. View - integer set to 0 for hotspots, or 1 for window prompts.
  3. Suffix, a user-supplied string which will be appended if there is no hotKey.
  4. function returns a string, a vertical bar delimited list, comprised of entries, which are either of the form

Speak Top Level Window Name.

There is a short script, called SpeakTopLevelWindowname, which will speak the top level window name for debug purposes. To use this, you can open your applications JKM file with a text editor. Add the following line to the [common keys] section of the JKM file.

HotKeyname=SpeakTopLevelWindowName
Where HotKeyName represents a valid key name, such as Control+alt+w.

Tip: you may have to restart jaws to get it to reread the JKM file in order to have your key become effective.

Pre-Positioning Callback.

After the HSC moves to the cursor position defined by the hotspot, you can additionally modify the cursor position by instructing the HSC to search for a graphic, or a color. If you do not choose either of these options, a function called HSCPrePositioningCallback will be called, after the cursor is positioned, but prior to the mouse action. A default version of this function resides in HotSpotClicker.jss, and does nothing. But you can write a function by the same name in your script file. If your function exists, it will be called, instead of the version in HotSpotClicker.jss.

Declare the function like this:

int Function HSCPrePositioningCallback ()

At the time this function runs, the JAWS cursor is active, and is parked at the hotspot location. To do your further processing, you may wish to access global HSC variables located in file HotSpotClicker.jsh. The name of the hotspot which is calling your function is in variable HSLastSpot. Because this is a single, common function, which runs for all hotspots, you will need to incorporate logic in your function to examine HSLastSpot, and take action specifically for your particular hotspot, and not for all others. Variable HSLastSpot will be set to the section name which contains your hotspot in the active .HSC file. Typically this is the hot key name. The strings must match exactly, so it is important that the modifiers are in the correct order, but capitalization is not required.

This function should perform any necessary logic to adjust the cursor position, or to determine if the hotspot is valid, based on the construction of your application.

This function should return a value of 1 if processing should continue, or 0 if there is a problem, and processing should stop. If a value of 1 is returned, the HSC will proceed to perform the mouse action at the new cursor position.

HSCLookupKey.

This function can be called to activate a hotspot based on the hotspot name. This is useful if you want scripts in your application scrip file to automatically activate a hotspot. It is declared like this:
Void Function HSCLookupKey (string keyName)
The parameter is the name of the hot key to which the hot spot is connected. if no hotkey is connected, then it is the label of the hot spot. In any event, this string equates to the bracketted name of the section in the .hsc file which defines this hotspot.

HSCActivateThisSet.

This function can be called from your scripts or custom functions to cause a particular HotSpot set to be loaded. If this name exists, then this will become the active set.

The function is declared like this:
void Function HSCActivateThisSet (string setName)
Where setname is the name of the hotspot set. These are the same characters as appear to the left of the equal sign in the entry for this set in the [Hotspot files List] section of the main .hsc file. These are also the same characters which you used to name the set when it was created. Note, it is not the hotspot set file name, but is the name of the hotspot set.

Sound Files.

All sound files for the clicker are located in the Sounds folder, under the "Explore My Settings" area of jaws. The names either begin with the word "HotSpot", or with the prefix "HSC".

HotSpot Rings.

One of the ways we have come to think of a program being accessible, is when you can repeatedly press the tab key, and hear jaws speak relevant information as focus moves from one control to the next. Repeated presses of the tab key typically move around a ring of locations such that, if you keep pressing tab, focus will return to the original location. Thus, you can think of this as a ring of controls, since the tab key eventually wraps back to the original location. While arguably inefficient, because one must move around the ring tabbing and tabbing, until the desired control is found, it is a familiar paradigm, and thus one you might like to recreate. However, many programs either do not tab to the locations you need most, or ignore the tab key altogether. In some cases, the tab key actually works, but not in a way jaws can detect, so no speech is produced.

HotSpotClicker allows you to create a list of hotspots which can be treated like a ring, with hotkeys provided which will activate the next, or prior, spot in the list. The list wraps around so that, when you get to the end of the list, HSC jumps back to the start of the list, in much the same way as the tab key usually works. Likewise, if you activate the prior spot, when you are at the start of the list, hsc jumps down to the last spot in the list, and starts working it's way up.

We call these spot rings, but don't confuse them with spot chains. A chain of spots means that once the first hotspot in the chain is activated, the rest of the spots in the chain will also be automatically activated, one at a time. Hotspots in spot rings, on the other hand, do not activate one another. The ring is simply a way of telling hsc where to go the next time you press one of the ring navigation keys.

Any type of hotspot can be included in the ring, including those which don't set focus anywhere, but simply speak information. But, a typical usage would be where you actually wanted to move focus around, just as the tab key would do.

Caution, it is usually not a good idea to put hotSpots which toggle items, such as checkboxes, on a spot ring. This is because, as you move around the ring, from one spot to the next, each Hotspot is automatically firing, and thus is performing it's function. So, a hot spot which actually makes a change, such as ticking a checkbox, will actually make changes as you navigate the spot ring. This can lead to confusing results.

Originally, there was only one spotRing per hotspot Set. But, in build 195, HSC was enhanced to allow you to define as many spot rings as you want, each with a unique name. A particular hotSpot can exist on more than one ring.

Even cooler, you can organize all your rings into a super ring of rings. The ring of rings is another circular list, containing all the names of the existing spot rings, in a particular order. This 2-layer structure allows you to activate a particular ring in one of two ways:

  1. You can press a hot key to rotate around the ring of rings to find the one you want, or
  2. You can define a Special hotspot which activates a particular ring
The rotation keys for the ring of rings are assigned to alt+control+windows+tab. Add the shift key to rotate backwards. To move around the ring, use alt+control+tab, or add the shift key to mvoe backward. So, first you decide which ring is active, then you rotate around that ring, activating hotSpots as you go. The main idea is that different spot rings are applicable to different parts of your application. The Spot ring is really analogous to the tab order in an application, where you move from one control to the enxt. Likewise, the super ring of rings is analogous to the control+tab rotation in dialogs, where you move from page to page.

The typical order of creation is:

  1. Define your hotspots, and make sure they all work.
  2. Define individual rings, choosing spots to occupy them.
  3. Define the ring of rings, choosing which of your rings should appear in the list.
However, you can add spots to rings later, or revise the ring order using the ring editor, discussed later.

Creating a SpotRing

To create a ring, which would simulate a desired tab order, you must first create the necessary hotspots, each of which can set focus on a desired control. Test the spots individually, and make sure they work as expected. They do not need to have hotkeys attached.

next, go to the HSC Actions menu, and choose "Build Spot Ring For This Hotspot Set". The first dialog lets you create a new ring, delete an existing ring, or look at the spot assignments for existing rings.

Once you create a ring, type in a unique name for the ring, and press enter, a virtual viewer will open, showing all the hotspots defined in the current set. Use up and down arrow to explore the list of hotspots in the current set. Each line will indicate if that hotSpot is currently on this ring or not. Use left and right arrows to choose whether or not the curren spot is part of this ring.
Press escape when you are finished, and indicate whether you wish to save your changes.

If you delete a spot from the middle of the ring, then press enter again, the hotspot will be added back to the ring, but will be added at the end of the growing list. While you are editing this, the ring, actually looks like a list, with new additions being placed at the end of the list.

Because of this simplified editing method, deleting and then re-adding hotspots can mess up the order of the ring. If the order is not what you want, you will need to use the ring editor, also in the actions menu, to edit the list into the correct order.

Setting Up The Ring of Rings

Go to the actions menu, with hsc mods +f10, choose Edit Ring Order and press enter. A specialized HSC dialog opens which shows the names of all the rings on the master ring of rings. This editor has no visual interface, so sighted people are at your mercy. Sorry, it doesn't do braille either
While in this dialog, and also while in it's descendent dialogs, most standard jaws keys are disable. No applications scripts will run. You can not, and should not try to alt tab out of this dialog, use the escape key to return to normal mode.
Specialized hot key help is available on control+alt+shift+h, and key describer mode is available by pressing insert+1 on the numbers row. Consult that help for details about which hot keys to use with your keyboard layout. But, in general use left and right arrows to move around the ring of rings. HSC will speak the names of each of the rings as you move. A beep indicates that the super ring has wrapped around to the start again.

For a given slot on the ring of rings, you can use up and down arrow to review the list of rings that are available. A special hot key is provided to force the current slot to be updated to the ring you have selected with the up and down arros. You can even insert new entries, or delete existing entries. In this way, you can fully define the order in which the rin names appear in the ring of rings.

Establishing The Initial Spot Ring

To determine which Spot ring will initially become active when the set loads,go to the HSC actions menu with hsc mods f10, and choose Edit Spot Ring Order. Use left and right arrow to locate the name of the ring you want to be initially active, and press the end key on the numPad. The currently selected ring will become the initial ring for this set.

Managing the Order of Spots On A SpotRing

Choose Edit Ring Order, from the hsc actions menu, and examine the list of spot rings. To open a particular ring so you can manage the order in which spots appear, arrow to the desired ring name and press alt+enter. A second speech-only dialog opens which shows the names of all the hotSpots that exist on that ring. Again, HSC hotkey help, control+alt+shift+h, and key describer JAWSKey+1, specific to this editor, is available. Consult that help for specific hot keys. But, in general, use left and right arrows to travel around the ring. HSC will speak the name of each of the hotspots on the ring. A short beep will sound when you wrap around to the start of the ring.
Hot keys are provided to allow you to copy and paste spot names from one slot to another, to delete a slot, or to allow you to insert new slots, either before or after the current item, or replacing the current item. When inserting a new slot, a list of all hotSpots in the current set is provided, so you can choose a spot name that is not already on the ring. In this way, you can expand or contract the ring, and can rearrange the order in which spots appear.

To actually run a hotSpot for test purposes, arrow around the ring to a desired spot name and press enter.

This dialog actually consists of two panels. The one that is active when you enter is the panel that shows the spots on the ring that you selected in the master ring of rings prior to opening the ring for editing.
The second panel shows all rings currently defined in the hotspot set. When in that panel, Use up and down arrows to move between rings, and left/right arros to move around the currently selected ring. Pres tab to cycle between panels.

This arrangement makes it convenient for you to reorganize which rings contain which hotspots. For example, suppose you had an old spotRing, from the days before build 195 where there was only one ring. That spotRing will show up as one of your rings. Create the new rings as desired via Build Spot Ring in the actions menu. Then, in the ring of rings, choose SpotRing and press enter. The ring editor will open, showing spotRing on one panel, and all rings, including SpotRing, in the other panel. Using the tab key, you can easily move spots from the old SpotRing to any of the new rings using the cut and paste techniques available.

for new files, the pane labeled as, from, which contained the old spot ring is no longer of importance.
When finished with editing, press escape, and choose whether or not to save your changes. You will return to editing the ring of rings. Press escape again to return to the application.

Navigating A Spot Ring.

Once you get the ring defined, and in the order you want, you need a way to move from one spot to the next in the ring. There are two ways to do this.

The default method is to use the HSC-assigned keys for this purpose. Alt+control+tab moves forward in the ring. Add the shift key to move backward. A handy way to think of this is to hold down alt and control with your right hand. Then, use your left hand to press tab and shift+tab, just as you would normally do.

As you move to each item, the corresponding hotspot is activated. if there is no spot ring defined for the currently active hotspot set, these keys take no action.

The other method might be where you actually want to connect these services into the tab and shift+tab keys, for a more familiar look and feel. Doing this requires some rudimentary scripting on your part. The important thing is that you are careful about when the tab key should not navigate the ring, which may require some application-specific logic. A basic example is shown below. But, in any event, once you have connected these to the tab key, you can still temporarily disable ring navigation using the hsc mods plus comma key. Wehn navigation is disabled, the tab and shift+tab will pass through to the application like normal.

Using the hsc mods plus the comma key, you can tell HSC whether or not it should redirect the tab and shift+tab keys to now become ring navigation keys.

You can also implement tab redirection to ring navigation at a scripting level, as described below. If you're not a scripter, and don't care about this, skip to the next heading.

Scrip interface for Spot Ring Navigation

To use this feature, you must toggle tab key ring navigation on using hsc mods plus comma. Once it is enabled, and you have done the steps described below, the tab and shift+tab keys will move arount the currently active ring, activating each spot as you go. In addition, you can make the control+tab and shift+control+tab keys switch between active rings, and the insert+tab key activate the current spot on the currently active ring.

To attach ring navigation to the tab and shift+tab, define two scripts in your application script file, one for each key. In the script manager creation wizard, you can not specify the tab key as a hot key. so, temporarily assign them to an unused key. then, you can edit the application's jkm file, find the name of your two scripts, and change the hotkey manually. Or, you can use the keyboard manager to do this. But, in the keyboard manager, you must first go to the options menu, choose hot keys, and set the checkboxes to allow tab and shift tab to be specified as hot keys. then, find your scripts in the list, and change the keystroke appropriately.

Back in the script manager, you are now ready to write the code for your scripts. HotspotClicker provides a set of functions that will be used to accomplish the navigation. These functions reside in module HSCRings.jss. Your scripts can call these functions. Each function returns an integer value which indicates whether or not HSC took any action. If the value return is 0, then no action was performed, and your script should default to the standard behavior for the affected hot keys.

Tab Key Ring navigation

Call these from scripts that handle the tab and shift+tab keys in your script file. To activate the next item in the ring, call function TabNextSpotInRingHSN()
If this function returns a value of 0, there is no ring defined for this set, or ring navigation is disabled. A returned value of 1 means that a hotspot was activated.

To activate the prior item in the ring, call function TabPriorSpotInRingHSN() To start the ring at the first item, call function SetRingIndexHSN(1). Likewise, if you want to jump the ring to item 5, call SetRingIndexHSN (5) This does not activate the item, just positions the index so that, when you activate the next spot in the ring, it would be item 5. If you do not call this function, the first press of either of these keys may not have any effect, but the ring index will get initialized at the start of the list.

Here is a sample tabKey script, which will attempt to navigate the ring only of the name of the top level window is FunkyMonkey. If funkyMonkey is not in focus, the tab key will be passed through. Likewise, if no ring exists, or if ring navigation is disabled, the tab key will be passed through as well.

Script TabKey()
var
handle hTopLevelWindow
; find out if we are focused somewhere in funkyMonkey
Let hTopLevelWindow = GetTopLevelWindow (GetFocus())
if (GetWindowName(hTopLevelWindow) == "FunkyMonkey") then
if (TabNextSpotInRingHSN()) then
; the next spot was activated ok, so we are done
return
endif
endif
; if we get here, we did not activate a hotspot, so pass tab on through
TypeCurrentScriptKey()
EndScript
the shift+tab script would be identical, except that it would call function TabPriorSpotInRingHSN

Tip: if you have an existing script for the tab key, and you want to override it when a ring is available, You need to change the entry in the JKM file for the tab key, specifying the name of your script in place of the original script. This will cause the key to invoke your script instead. you can use a script very much like the example above, but, instead of TypeCurrentScriptKey, you can invoke the original script with a line like this:
PerformScript MyOriginalScript()
Where "myORiginalScript" is the name of your script.

Selecting a ring with Control+tab

JAWS has default scripts for handling control+tab and shift+control+tab. You can intercept these keys simpy by specifying scripts in your file that are named exactly like the default scripts for the purpose, and adding logic to your version of those scripts that will decide whether or not to pass control on to the default script. When you add these scripts, don't specify hot keys for them. Jaws will use the key assignments in the default file, and will find your script by virtue of the fact that your script is named the same as the default version. If you already have handlers for these keys, you can simply add the logic to those handlers.

To activate the next ring in the ring of rings, call function ControlTabNextRingHSN. If HSC performed an action, because this feature is enabled, and a ring exists, the function returns a value of 1, otherwise, 0 is returned.

To activate the prior ring in the ring of rings, call function ControlTabPriorRingHSN. If HSC performed an action, because this feature is enabled, and a ring exists, the function returns a value of 1, otherwise, 0 is returned.

Below are two scripts, which demonstrate replacing the default scripts for control+tab and shift+control+tab:

Script PreviousDocumentWindow ()
if (ControlTabPriorRingHSN() == 0) then
; HSC did not service this key
; default to standard jaws handling
PerformScript PreviousDocumentWindow ()
endif
EndScript

Script NextDocumentWindow ()
if (ControlTabNextRingHSN() == 0) then
; HSC did not service this key
; default to standard jaws handling
PerformScript NextDocumentWindow ()
endif
EndScript

Run Current Spot with Insert+tab

If the tab key ring navigation feature is enabled, insert+tab can be made to run the current HotSpot on the currently active ring.

To run the current spot on the current ring, call function InsertTabHSN. If the feature is enable, and such a spot exists, this function returns a value of 1, otherwise 0 is returned.

The following script can be used to intercept the insert+tab key. Use this script name, which matches the same script in the default scripts, so that no hot key needs to be attached to this script.

Script SayWindowPromptAndText (),br> if (InsertTabHSN() == 0) then
; HSC did not service this key
performScript SayWindowPromptAndText()
endif
EndScript

Ring Tracking.

You can force the ring position to be automatically updated as you activate hotspots by turning on the Ring autoTracking flag, by pressing hsc mods plus the grave accent key. When tracking is enabled, and you activate a hotspot that is presently in the ring, the ring pointer will be updated so that, the next time you attempt to navigate forward in the ring, the hotspot which appears in the ring, right after the one most recently activated, will be next in the list. Press hsc mods plus grave accent again to turn this feature off.

Context Lists

A context list is a list of HotSpots that can be executed once an associated Hotspot has been executed. Once a different hotspot is executed, the original context list is no longer active. Typically, the original hotspot sets up all the conditions under which all the spots in the associated context list will make sense. The way you would use it is to execute the original Hotspot. then, use hsc mods right mouse button to get a list of context spots that can then be executed. Choose one, and press enter to execute it.

Note, this applies to the most recent hotSpot executed. If you chain two spots together, the only one to which a context list could be reasonably attached is the final spot in the chain. A context list attached to the first spot would never become available, since that spot will always be folowed by the second spot in the chain.

Context lists are implemented using the same mechanism that manages spot rings. They are stored in the same way, but do not actually behave like rings. A context list is not available to be included in the ring of rings, and you can't tab around a context list. Likewise, spot rings are not availabe as context lists. But, you use the ring management functions, located in the actions menu, under Build a spot ring to manage the list, such as choosing which spots reside on the list, and the order in which they appear.

If you examine the .hsc file, you will see that context lists are stored exactly like rings. A new parameter has been added called "scope". This will indicate if the data is a context list, or a standard spot ring. If the parameter is not present, the data is assumed to be an old-style spot ring.

To define and use a context list, generally follow these steps:

  1. Define the main spot that sets up the conditions, and make sure it works.
  2. Define the hotspots that will make up the context list. Usually, these are spots that will only work once the main spot has run, and set up the conditions. It might be useful to encode some reference to the main spot in the names of each of the context spots, just to help you keep track of what belongs to what.
  3. Define the context list, give it a name, and assign the context spots to the list.
  4. Modify the original HotSpot to tell it that it has a context list attached.

To use it:

  1. Run the original hotspot.
  2. Press hsc mods right mouse button, choose a context spot from the list, and press enter. The context spot will be executed.

Creating the Context list

From the actions menu, hsc mods f10, choose Build Spot Ring For this HotSpot Set, and press enter. Choose Create A Context List, and press enter. From here on, steps are identical to creating a spot ring, give it a name, and then choose which spots reside on the list. Press escape when done.

To modify the list later, the context list will turn up in the list of spot rings shown under Built Spot Ring For this HotSpot set in the actions menu. Press enter on the name of the context list, and edit the contents just as you would a spot ring. Right arrow to put a spot on the list, left arrow to take it off.

Connecting A Context List To A HotSpot

Press HSC mods f6, and choose the name of the main hotspot from the list. The list will be initially focused on the most recent spot executed. Press enter to open the list of known context lists. Choose the Context list you want to connect and press enter. Done.

Note, it is possible to have any number of HotSpots share a common context list.

Deleting A Context List

Delete a Context List just like you would delete a spot ring, from the Build Spot Ring item in the actions menu.

Note, HSC does not scan your .HSC file, and remove references to the context list. So, if you delete the list, you will want to use notepad, or other text editor, to check for references to the context list, and remove those. The only problem caused if you fail to remove those hanging references is that the hsc mods right mouse button will not work when the most recently executed hotSpot referred to an unknown context list. A warning message is spoken, so you can go remove the reference.

Just as with rings, if you delete a spot that resides on a context list, HSC does not automatically update the list.

Menus

This feature allows you to implement a two-layer menu structure, similar to those typically seen in application menus. The concept is that a SubMenu consists of a list of HotSpots. A menu consists of a list of subMenus. And the activator Hotspot opens the menu, with a particular subMenu selected, but not opened. You can define as many separate menus as you like, and each menu can contain an unlimited number of subMenus. Since they don't turn up on screen, the sky is the limit. So, that means that different activators can open different menus, or the same menu, with a different subMenu selected.

A subMenu is implemented as a special kind of spotRing, with the Scope field set to SubMenu. You build, modify or delete subMenus similarly to building a spot ring, or a context list, by accessing the associated item in the Menu Management section of the HSC actions menu. There, you can create, delete, or edit menus and submenus.

If you only want a single level menu, just consisting of a set of HotSpots, and dont' need to select between multiple submenus, you still need to defined that submenu, as well as a topLevel menu to contain it. But, since the top level menu contains only one submenu, HSC will skip the main menu at activation time, and open the submenu directly.

Just as with rings, if you delete a spot that resides on a submenu, HSC does not automatically update the submenu list. Or, if you delete a subMenu, the menus that refer to it are not automatically updated. Use the File Auditor, found in the HSC actions menu, to identify and correct dependency issues like that.

The general process for forming a menu structure is as follows. Support for most of these can be found in the Menus Management section of the HSC actions menu:

  1. Using the HotSpot creation wizards, generate each of the HotSpots reqquired for each subMenu
  2. Create the subMenus, specifying which HotSpots reside on each.
  3. Create the menu, and specify which subMenus reside on it.
  4. Using the HotSpot creation wizard, generate the HotSpot that will activate the menu. It can perform the customary set of actions, or you can specify that it take no action at all.
  5. Assign the post-processing function -- A new post-processing function called OpenMenuHSC must be added to the activator spot, specifying the menu name, and optionally, the name of the subMenu to select.

Once the activator spot opens the menu, you can use the followign keys to move around in the menu:

Menu Sounds

By default, HSC plays a small sound when a menu is opened, and another sound when it is closed by making a selection and pressing enter, or it is canceled by pressing escape. However, in file HotSpotClicker.ini, in the [General] section, there are three keys that allow you to customize the sounds.
The keys are:
MenuOpen
MenuClose
MenuCancel
Each of these is followed by a file name, including the .WAV extension. The files are presumed to reside in the Sounds subfolder under the user-specific settings area of JAWS.

To customize those sounds place new files in that sounds folder, and revise HotSpotClicker.ini accordingly.

To prevent a sound, set the corresponding file key to a dollar sign. For example:
MenuClose=$

Auditing A HotSpot Set

For several reasons, HSC does not clean up entirely after itself when you delete a Hotspot or a spot ring. Mostly, this is due to a major performance problem with very large files. But, it also relates to the damage you can do when you delete something you didn't mean to delete. The result is that hanging references are left hanging. For example, if hotSpot x is being chained to by another spot, and you delete hotSpot x, then that other spot will be chaining to a spot that no longer exists. Likewise, if spot X was in a spot ring, that spot ring will still have a slot that refers to x, even though it does not exist.

This tool, activated from the HSC actions menu, HSC mods f10, scans the current hotspot set, and checks the various references to see that all is as it should be. Go to the actions menu, and choose "Audit The Current Set For Missing Links".

The initial screen is explanatory. Toward the bottom of that opening screen, there are two links which can be used to start the analyzer. You can just cause HSC to analyze the file, and make a report, but not perform any actual modifications, or you can let HSC go ahead and remove the hanging references automatically. If you choose the latter, HSC makes a backup copy of your current set before performing the edits. Those edits are performed with the idea that all hanging references should be removed. If, on the other hand, you have been editing your .hsc file manually, as some do, and have created references before filling them in later, the analysis only flavor of this tool will give you a listing of the references you have not filled in yet.

HSC window prompt creator, "spot prompter."

This feature is useful in cases where you tab to a window, but jaws does not properly speak the name and/or value of the item that gains focus. It allows you to specify a name for that control, a custom string, a tutor message, and the name of a custom function which will speak the value of the control.

To use this feature, You need to make some small changes to further integrate the HSC with your application script file. If you have a function called HandleCustomWindows, you can add a few lines of text to the top of that function. If not, then write one which looks like the following. Notice the semicolons at the start of some of these lines. Those are comments, simply for explanatory purposes, and can be included in your source code, because the jaws cscript compiler will ignore any line that starts with a semicolon.

Int Function HandleCustomWindows (handle FocusWindow)
; if you already have this function, then add the following few lines.
if (HSCCheckForPrompt (FocusWindow)) then
; a prompt exists for this window
; if you specify a processing function for the prompt, it will say the window contents. So we are done.
return(1) ; indicate that we took care of it
Endif
;*** end of the few lines to add to your existing function
; include any other logic you need for other purposes
; return 1 if you don't want jaws default processing to do any more speaking
return(0) ; means we did not handle this window, so jaws should take care of it itself
EndFunction

NOTE, as in the HscFocusChanged event situation, if you already have a HandleCustomWindows function, then the parameter to that existing function, (i.e. the second word after the left Parenthesis directly to the right of the word "handle," on the top line of the function,) may not be called FocusWindow, as it is in our example. If it is not, then You will need to change the word
FocusWindow
in the new lines you are adding, to match the name of the parameter specified in your existing function.

Once you have added this special logic to your application script file, press control+s to recompile it.

the name HandleCustomWindows is a special name which is known to JAWS. JAWS calls a function by that special name whenever focus moves from one control to the next. Most aplication script files have a function by that name. The function called HSCCheckForPrompt is an HSC function wich does the actual checking as to whether a special HSC prompt has been defined for the window gaining focus.

Back to, "how to assign a hotspot.

Defining Special Prompts.

To define a special spoken prompt for a control, tab to the control that is not speaking correctly, and press control+alt+shift+p. If the special processing function described above has not been installed, HSC will detect the fact, and give you a summary of the instructions provided above. You can copy the text of the default version of function HandleCustomWindows from the virtual buffer, for pasting into your jss file.

If the processing has been installed and is working properly, you are asked to complete a series of entries required to define the prompt. You may be asked to remove dynamic information from the window name and real window names, similar to hotspot creation. This general process, and the reasons behind it, are discussed more in: Customizing Comparison Criteria.

After any potentially dynamic window names have been resolved, you are prompted for a text string which will be spoken when this control gains focus, or when you press insert+tab to see what item has focus at the moment. Tyep in a suitable string, and presss enter.

next, you are prompted for the name of a function which will speak the value of the control. You are provided with a list of several functions, internal to HSC, which will decode most standard controls, along with an option to specify the name of your own function. Most standard windows will be handled adequately by JAWS without special processing. For that reason, one of the options provided is called JAWSDefaultProcessing. Use this setting when jaws speaks the value correctly, but gets the name wrong. Specify your own function when JAWS doesn't get the value correct either.

The HSC provided functions can be found near the bottom of HotSpotClicker.jss, near a comment that reads:
;*** example window processing functions for the HSC prompt Creator
If you choose to type in the name of one of your own functions, that name will be added to the list of options, and will now be available for selection from the list when working on the current application. That function should reside in your own application script file. the construction of such a custom function is discussed in more detail in Custom Prompt Processing Functions

The following prompt processing functions are listed in the HotSpotClicker.jss file, and can be used for most situations by simply selecting one from the list:

Depending on which function you select, additional input may be solicited.

There are two strings which are placed in the definition which are defaulted to blank, as indicated by the presence of a single dollar sign "$". These are:

String=$

and

Tutorial=$

These are not solicited in the promp creator, but can be filled in by using the definition editor attached to control+alt+shift+f4. Just erase the dollar sign, and replace it with the text you want. The dollar sign is necessary to represent a blank string in order for jaws 6 to preserve the entry.

In order to change the hotSpotClicker, so that it will solicit these items automatically, open the HotSpotClicker.jss file, and change the constants located near the top of the file to 1, the recompile. The constants to be changed are:

cn_PromptMeForCustomStrings = 0, ; change this to 1
and

cn_PromptMeForTutorMessages = 0

The Custom string can be spoken after your custom prompt function decodes and speaks the value of the control. The default functions will always speak this string if it is present. For example, if your control yields a number, and you know the number is in terms of minutes, you could set the custom string to the word "minutes". If you don't want anything spoken, just leave this field set to the dollar sign "$". It is"$" by default.

The tutor message is provided, in case you would like to provide additional information about this control. That string will be spoken if tutor messages are enabled, and the string is not set to "$".

Finally, you are asked whether you wish to attach a hot key to this prompt. If you choose yes, HotSpotClicker will start beeping, once per second, awaiting the press of a hot key, exactly as it does when defining a hotspot. When a key is detected, then a new hotspot is defined, by the same name as the prompt, which is designed simply to set focus on the control associated with this prompt.

After these fiels are filled out, and any necessary custom prompt function has been written, the prompt is complete and is ready for use.

Editing Custom Prompt Definitions.

Window prompts appear in the active HSC file in sections, which look very much like hotspots, but which have fewer items. You can edit these definitions, just as you do hotspots, with the control+alt+shift+f4 key stroke. The top line in that list allows you to choose between HotSpot, and Window Prompt views. Press enter on that line to go to the other view.

use up and down arros to browse the list of window prompts in the current hotspot set. the text of the spoken prompt will appear in the list, followed by an obscure string which is a window identifier. The window identifier appears where a hot key would normally appear for a hot spot. Press enter to edit the definition.

the text between the brackets is the window identifier, which is an encoded form of information used to uniquely identify the control being customized. The format of this string is described in the HotSpotClicker.jss file, in function HSCComposeWindowID. In most cases, this information should not be modified. However, the other fields in the definition can be edited as needed, using the control+alt+shift+f4 definition editor. Use this editor just as you do with standard hotspots. . Press enter to save the definition, or escape to exit without saving.

The following text fields exist in the definition:

Delete a prompt in the same way as you delete a hotspot. Use the tripple click of control+alt+shift+f1, select the prompt view, then locate the name of the spoken prompt, and press enter to delete it.

Custom Prompt Processing functions.

If you want to write your own function, your script file must include the HotSpotClicker.jsh file in order to gain access to a global variable which contains the handle of the window with focus. This handle is contained in global variable HSGlobalHandle. Open the HotSpotClicker.jss file, and Examine the source code of the functions listed above for examples as to how to do this.

the following HSC global variables are useful in writing custom prompt processing functions:

To speak the custom string, once your function has spoken the value of the control, call function HSCSpeakSpecialStrings. It will look up the custom string from your prompt definition and, if one is specified, wil speak it.

Prompter Limitations.

This feature relies on JAWS receiving an indication as focus moves from one window to the next. Some applications simply move a graphical highlight around a large, common window to indicate focus. However, JAWS will not detect that movement. It needs to see focus moving from one window to the next. In other words, the FocusChangedEvent needs to run in order to invoke the processing required to support this feature.

If your application has already been customized, and frames have been employed, with an event defined for the frame gaining focus, be aware that the function associated with that frame event will run, instead of the FocusChangedEvent. Such a scenario will bypass your special prompt processing, unless steps are taken to also include those event functions.

A second limitation involves situations where a dialog can be optionally made to look different by disabling certain controls. If those controls completely disappear from the window, then a window prompt in that dialog, defined prior to the alteration, may cease to function.

An example of such as the Windows volume control, where the user can select which controls actually appear in the window. This changes the hierarchical relationship between windows. HSC depends on a knowledge of that relationship in order to uniquely identify a window. It does this, in part, by constructing a window identifier, which is a concatenation of several facts about the window. Included in that identifier, are numberws which indicate the number of windows from the first peer window on each level, moving up to the real window. If the structure changes, such that those numbers are no longer valid, then the prompt will fail.

A prompt can also fail if you have not correctly removed dynamic information from the window name and real window name. You can find out if this has happened by turning on HSC debug mode in the insert+v verbosity menu. With debug turned on, if the window locator string is correct, but the control id, window name, or real window name is wrong, the HSC will inform you of the mismatch. You can then bring up the definition in the definition editor to revise the offending entry.

ToolTips.

A ToolTip is a string of text which shows up on screen when the mouse is made to hover over an item. In some cases, a graphical image of a button, or other control, is painted on the screen in a way that is invisible to JAWS. Sighted people who do not recognize the control, and wonder what it is for, will place the mouse cursor over the item, and then read the text which pops up. These toolTips can give us meaningful clues about how to control the application, if we could only find them.

HotSpotClicker gives you a way to scan a window, and build a list of toolTips for later use. Press control+Alt+Shift+f10 to go to the HSC Actions menu, choose ToolTip Scanner and press enter. A dialog will open listing the Tooltip scanning options. Choose from one of the activities listed there. Each item in that dialog will open a new dialog for that purpose.

With this facility, you can perform the following major functions:

Scanning for ToolTips.

Once you press enter on this item, HSC will determine which control has focus, and link from that window, to the TopLevelWindow, which is typically the larger window that has a title, and which contains the control with focus. Depending on which window you have chosen to scan, It is either this topLevelwindow, or the application main window which will be scanned. Because applications vary in terms of how their window hierarchy is arranged, it is not always apparent which window needs to be scanned. Experimentation is recommended.

Depending on the size of the window, this operation can take several minutes. HSC announces the minimum amount of time required for a full scan. However, as ToolTips are encountered, and the scanning slows down, the time extends. so, it is not possible to know exactly how long the scan will take. Expect this to be a slow, time-consuming, extended process. But, it is a process you invoke as a part of adapting the application, not as a part of normal operation. This is something you do when you have no other means of finding those controls. It is necessarily a very thorough, slow and ponderous operation, and must be that way in order for detection to be successful.

Still, you do have some ability to drive the scanning process, as described more below. But, be aware that, by altering the scanning process, you may miss toolTips that you did not know existed. Understanding the scanning method will help you to control that process more effectively.

Scanning starts at the top left corner of the window, and moves the jaws cursor in steps, toward the right edge. Between steps, it pauses and waits for a toolTipEvent to occur. When it reaches the right edge of the window, if no toolTips were found on that line, it jumps down by a fixed number of pixels, and starts again at the left edge, moving in steps toward the right.

Once it reaches the right edge, if a toolTip was found on the current line, HSC will retrace it's steps, scanning back to the left on that same line. This is necessary in order to determine both the left side, and the right side of the tool. This means that, in empty regions, HSC is only scanning left to right. but, in populated regions, it will be scanning both directions. When it predicts the minimum scanning time, HSC is assuming that no retracing, right to left, will be necessary.

The speed of scanning, and the number of pixels between both vertical and horizontal jumps, are all controlled by constants near the top of the HotSpotClicker.jss file. So, you can change the scanning speed, and step sizes, for both modes of operation, if necessary to achieve reasonable toolTip detection on your system. However, scanning too rapidly will easily cause hsc to miss toolTips. When the first toolTip is found, hsc does a test to determine how rapidly it can scan. Typically, this settles in at about ten pixels every half second.

Controlling the Scan.

While scanning is in progress, you should not operate your application, nor alt tab to another window. However, jaws reading functions are allowed, such as SayLine, or reading the time of day with JAWSKey+f12.

To stop the scanning, press numPad 5. AnytoolTips found so far will remain in the temporary data file.

During scanning, you can cause HSC to skip the present line, and move to the next line, by pressing leftshift+leftControl+ExtendedDownArrow. Use that key combination, even if you do not have left/right differentiation enabled. This will allow you to skip rapidly down the window if you know the toolTips are near the lower portion of the window.

To move up one line, press LeftControl+LeftShift+ExtendedUpArrow.

When scanning toward the right, you can cause HSC to reverse direction, and scan back toward the left by pressing LeftControl+LeftShift+ExtendedLeftArrow. This is handy if you become familiar with the layout, and are certain that no ToolTips of interest lie to the right of the current scan location. Be ware, however, that you can cause hsc to skip over toolTips which you did not know were present.
Likewise, you can force a left moving scan to reverse direction, and start moving to the right again with control+shift+ExtendedRightArrow.

where toolTips are Stored.

As toolTips are identified during the scanning process, an entry is placed in the [ToolTips] section, in file hsc_temp.hsc in the Personalized Settings folder. there is one entry for each ToolTip, The characters to the left side of the equal sign are composed of the ToolTip text. the Characters to the right of the equal sign are pairs of x/y coordinates for all the points at which the toolTip edges were discovered. These are absolute screen coordinates.

Browsing and Moving To toolTip Locations.

Once you have performed a scan, and are focused somewhere in the same TopLevelWindow, you can browse an alphabetized list of the toolTips that have been collected. Press enter on an entry to activate the jaws cursor and move it to that location.

This process looks up the entry for the selected toolTip, and summarizes all the x/y coordinant pairs to determine an estimated geometric center of the control. It then moves the jaws cursor to that location. Once there, you can press left mouse button to test the accuracy of the location, and learn the effect of activating the control, or perhaps, if you like, define a hotspot there in the customary way. But, there are other ways to generate hotspots as well, as described below.

Please note, these boolTip locations are based on absolute coordinates at this point. So, any changes in screen layout can invalidate these numbers. Even if you close the application, and intend to continue work at a later time, be aware that these locations may not still be valid when you reopen the application. These are not intended for permanent use. Rather, they are an interim means of determining where real HotSpots should be established. And, in the long term, it should be hotspots, not toolTip records that give you access to these controls. Hotspots will be more likely to track along as the screen is rearranged.

ToolTip Explore Mode

When this mode is turned on, you can mouse around with the jaws cursor, looking for toolTips. When one is encountered, the toolTip collection sound will be played, and it's name and location will be added to the hsc_temp.hsc file. Be sure to mouse around sufficiently to find left, right, top and bottom edges of the toolTip area, so that the center can reasonably be calculated by the other utilities.
To turn this mode on or off, go to the actions menu, choose ToolTip Scanner and press enter, then choose Explorer Mode.

Making a HotSpot from A Single ToolTip.

In addition to just routing the jaws cursor to the location, and defining a hotspot through the wizard, One good, quick way to make a hot spot from a single toolTip, is done with this dialog. use the up and down arrow keys to browse the list of toolTips in the temporary file. Press enter on a item to create a hotspot based on that toolTip location. HSC makes some assumptions about the kind of toolTip, forcing it to be current window relative positioning, left single click action. The label is set to the ToolTip text. Some window names might be presented, asking for dynamic information to be removed. You will be asked whether or not you would like to attach a hot key, and, if yes, you can press the hot key just as you do in the normal hotspot assignment wizard. You can then use the Definition editor, control+alt+shift+f4, to modify the entry as needed.

Making HotSpots From All toolTips.

To just convert all known toolTips to hotspots, you can use this dialog. A list of all toolTips in the database is shown, so you can arrow up and down the list to see if there are any in here you definitely do not want to generate. If there are, then, you need to press escape to close this dialog, and edit the hsc_temp.hsc file manually to remove the unwanted entries. You can not select infividual toolTips from this dialog. It is all or nothing.

Once you press enter to proceed, you are asked if you want to attach a hot key, with the options being:

  1. Yes To All - as each hotspot is generated, you will be prompted to press a hot key.
  2. Ask Individually - as each hotspot is generated, you will be asked whether a hotkey should be attached or not. If you say yes, then the hotkey is solicited. If not, the hotspot is generated with no hotkey solicited.
  3. No To All - All hotspots are generated without soliciting a hotkey.

Just as with standard hotspots, some window names may be presented in order that dynamic information can be removed.

Undoing the most recent tooltip generation.

When you generate multiple hotspots from the known toolTips, a backup file is made of your active HSC file, along with the application key map. You can undo the results of the most recent automatic generation by accessing the Undo option in the actions menu, attached to control+alt+shift+f10. This menu item will disappear once you restore to a backup version, or if you generate another hotspot manually, or edit a hotspot.

Sounds for ToolTip Scanning.

AS the scanning proceeds, HSC uses special sounds to keep you informed of progress. You will hear a repetitive tap tap tap sound, as the cursor is being stepped across the screen. This sound has one characteristic when moving left to right, and changes to a slightly different tone when the cursor is moving right to left. Additional sounds are provided when the scanner advances to the next row, and when a ToolTip event is detected.

These files are located in the Sounds folder under the $jaws folder. The file names, and when they are played is as follows:

ToolTip Trouble shooting.

If toolTips are not being detected, but you know they are being displayed on screen, then there are three possibilities. Each is discussed in more detail below:
  1. The TooltipEvent function is not being called due to custom script implementations.
  2. HSC is scanning too rapidly, or taking too large a steps during the scanning process.
  3. JAWS is not capable of detecting these toolTips at all. This has been known to happen, and has no known solution. Come to this conclusion only after having addressed items 1 and 2 above.

ToolTipEvent.

If your application script file does not have a function called ToolTipEvent, then This feature should work without any additional steps on your part. However, if such a function does exist, then that function must also call ToolTipEvent, providing the same parameters with which it was called. This is similar to the situation we discussed earlier, during installation, when discussing additions to The KeyPressedEvent, and will pass control to the HotSpotClicker version of ToolTipEvent.

Controlling ToolTip Timing and Step Size.

We think these parameters have been optimally adjusted for best performance. But, if you still feel like adjusting them, In file HotSpotClicker.jss, near the top, are listed several constants. One group is dedicated to controlling the ToolTip scanner. There are three items for each of the two modes, slow, and fast. you can control: If toolTips are not being detected, you might use slower scan rates, with smaller jumpts. Both will lead to longer scan times.

Licensing Proprietary HotSpot Sets

If you have invested considerable effort in creating a complex set of HotSpots, you may well wish to sell those hotspots to help put a little food on your table. You can encode files for a particular serial number.
Do do this, loadeach of the files involved in the set. This would include manually loading the main set, and each of the subsets, if any. for each file, go to the actions menu, by pressing hsc mods f9, and choose the item called, license a hotspot set for a particular jaws serial number, and press enter. You will need to enter your client's jaws serial number, and your e-mail, in case your client wants to contact you. That e-mail also gets spoken if someone with an unauthorized serial number tries to run your sets.

HSC will create a subfolder for that serial number, located under the folder for the current application, under the Base Folder where all the other .hsc files for this application are stored, and deposit the encoded files in that folder. Your client can import the files as usual, and need not be concerned with the licensing at all. And, your cliebnt doesn't need to use the same Base Folder as you. But, they will want to be aware of their choice, so they can know where to place your files.

Chaining Browser

When a hotSpot set has been developed, and employs any of several forms of chaining, which is any method of passing control from one spot to the next, it can become confusing as one tries to puzzle out all the relationships. This utility, accessible from the HSC actions menu, can be used to identify such relationships for maintenance purposes. For example, maybe you want to modify a particular spot, and want to know all the hotSpots that use that spot, so you can make sure your modifications will be compatible. Or, maybe you want a convenient way to look at all the ways in which a given spot will pass control to other spots, and determine the list of spots on which your spot depends.

To use the chaining browser, first make sure that the HotSpot set you want to analyze is the currently active set. This is because the analysis is confined to the current set, since chaining across set boundaries is not supported. A spot which activates another set is not considered to be using chaining, since it does not activate a particular destination spot.

To activate the set of interest, double click HSC mods f1, and select that set from the list, followed by enter. Next, go the HSC actions menu with hsc mods f10, and press c to select the chaining browser, followed by enter.

This utility has no visual interface, but is accessible only through speech and or Braille. Logically, there are three panes, and you use left and right arrow keys to move between panes. JawsKey+tab will remind you which pane has focus. Notice the stereo sound effects that also convey focus information as you move around. Make sure you don't have your speakers reversed, or your headphones on backwards.

Initially, the center pane has focus, which will contain a list of all hotSpots in the current set, including hidden spots. Use up and down arrow to select a spot that you want to analyze. Or, you can type it's name or description, or even press it's hot key in order to conduct the search.
Once you start typing, hsc will collect the characters you type into a buffer. If you have not pressed a key in one second, HSC will stop collecting, and will search for that text in the list of spot names. If your entered string starts with a period, ".", then a search will be satisfied if HSC finds a spot name that contains your text anywhere in the name. If your string did not start with period, then the comparison starts at the beginning of the name, and is applied for the number of characters you typed.

The search starts at the current position in the list, and proceeds downward. If HSC reaches the bottom of the list without finding amatch, it will return to the top of the list, and search downward until the current position, or a match is found.

Once a spot is selected, you can then investigate that spot. Press enter to run the spot. Or, press alt+enter to open that spot in the definition editor, where you can change the parameters if desired.

You can run the spot in several different ways, depending on whether you want to inhibit chaining for diagnostic purposes. Pressing enter by itself runs the spot with all chaining enabled.
To disable preChaining, use shift+enter.
To disable post-chaining, including color chaining and recovery spots, press control+enter.
To disable all chaining, press control+shift+enter.

From the main spot list then, press right arrow to access the outBound chain list. This is a list of spots to which this spot passes control. Such chains might be post chains, or preChains, chaining that is conditional depending on a certain color, or even a recovery spot. In short, these are spots to which control will be passed, either before your spot runs or after word. Use up and down arrow keys to browse this list of forward chains. The destination spotName is listed, followed by the type of chaining that will be performed. To follow a chain, press alt+rightArrow. Focus will move back to the spots list, the center pane, and the destination spot will be selected. To return back to the original spot, press backspace.

Or, to view a list of spots that reference this spot, press left arrow from the center pane, to move to the InBound chains list. If your set is very large, this can take a few seconds to open, because the entire set must be scanned for various forms of reference to your spot. Once the InBound list is populated, use up and down arrow to review the results. This is simply a list of spots that reference your spot. If you forget which spot you were analyzing, you can briefly right arrow back to the center pane to hear the name of that spot, then left arrow back into the InBound list without causing a reScan. HSC remembers the most recently generated Inbound list, and the name of the spot it references.

The inBound list is just a list of spots that refer to your spot. It does not contain information about the manner of that reference. To obtain that information, select one of the spots listed there, and follow the chain backward using alt+leftArrow. Focus will move back to the center panel, with the referring spot selected. Now, you can right arrow into that spots outBound chain list, and find your original spot in there to see how and why it refers to you.
Again, you can return to your original spot with backspace.

The backspace key can be used to undo an unlimited number of moves. However, that history is discarded if you up and down arrow in the center panel, the main spots list, or exit the browser. Essentially, the history is cleared if you leave the chain, even if you then return back to the chain.

HotKey help is provided via hsc mods+h when in the chaining browser.

While in the browser Most ordinary keys are not honored. However, you can repeat the current item with jawsKey+upArrow, or double click that key to spell the item. JawsKey+f12 speaks the time.

If you activate the jaws cursor, the browser is suspended, and you can explore the screen with jaws or invisible cursors. In this mode, all standard jaws keys are honored. This is useful for exploring the affect of running a hotSpot, or quantifying some change that you wish to make.
Pressing the PCCursor key will return to the chaining browser as you left it.

to exit the chaining browser, press escape. Or, leave the keyboard alone for 5 minutes, and the browser will close automatically.

State Designer

This utility is a very simplified design tool, which may be useful to anyone wishing to design a logical work flow, or procedure. It has nothing to do with accessibility, was not in demand, but is included here just because. If you can't figure out what anybody would ever do with it, then the tool is not for you. But, if you need to plan the process you would go through to do something, or the way data entry screens in an application would work, the rules governing a game, or anything that relates to a logical sequence of events and conditions, then perhaps this tool will be useful to you. Let us know if you actually used it. It is located in the actions menu, hsc mods f10. Documentation is located in file StateDesigner.htm, along with the other HSC docs in your programs group. Or, if you're lucky, you'll be able to Click the link below to Read About The State Designer

version History.

Here is where you can learn the additions and corrections applied for recent versions.

What's New In Build 242.

This is the most recent version.
This build simply fixes an omission reported by users, which prevent spots of certain types from being offered in the actions menu, Adjust A Hotspot Location dialog. Application Plus Current Relative spots were omitted, and could not be adjusted.

Build 241 Build 241 fixes a problem that only applied to very long processing tasks and was an issue only with very large hotspot sets. Such processes as licensing a file, applying offsets, and converting from application to application plus window relative positioning, where each spot in the set must be edited, take a long time to complete. Starting in Jaws 16, a safety timeout was added to keep jaws from locking up in certain situations. These long processes were looking like a lockup to jaws, and so the process was being terminated. These processes will now be allowed to complete.

build 240

Nothing is new, except that the ability to assign hotspots to a hot key that is already assigned to a JAWS script has been refined and now works more completely. With previous versions, when importing a set, the key overrides were not also being installed.

Build 239

Build 239 simply addresses issures relating to the order in which things are spoken when you are using special functions, like HSCSaySpecial Strings, and HSCDecodeHotSpotColor. Things were spoken out of order. That's all.

build 238

Build 237

Build 236

The only change in 236 is attempted corrections to the logic that installs the ToneGen library, which is used to support the table tone graphing capability. Indications are that this worked in XP, but did not work pro9perly in Windows 7. We still don't know about Windows 8, and maybe you can help there. When you first try to use the table tone graphing capability, described in Audio Graphing a table Column, HSC tells you to answer yes to a query from the registry editor. However, the registry editor never woke up and asked the question, so the dll did not get installed. This would imply that very few people know the pleasure of using this utility. Plese give it a try and report your results to: Snowman@SnowmanRadio.com

Build 235

Build 234

Build 232

The only item is documentation corrections, and a change to how HSC activates a spot ring from a HotSpot. If the parameter called TargetRing in the spot definition is set to the name of an existing spot ring in the currently active set, that ring will be activated, even if the action parameter is not set to activate a spot ring. This lets a spot perform some ordinary action, and activate a particular spot ring as well.

Build 231

Build 230

Changes listed below.
Tip: If you already have HSC installed, if the old installer asks you if you want to remove any old version of HSC, just say no. Tell it you don't want to create a backup, but it will do it anyway. But, that should avoid unnecessary reboots.
Additions in build 230:

Build 229

Bug fixes, nothing more.

Build 228

build 227

build 226

What's new? Nothing. Only bug fixes.

Build 225

More Bug fixes.

Build 224

Build 223

Build 222

Build 221

Build 220

Build 219

Build 218

Added the follwoing post processing functions, which can be selected from the hsc mods f3 list:

Build 217

Having a hard time getting it right. Build 214 was short lived, included all of the following. Build 215 simply corrected a bug that caused the toolTip scanner to not work. And 216, restores the messsage history, which was broken by 214, and adds the ability to check for updates online from the actions menu.

Build 213

Build 212

build 211

  • JAWS 13.0 nudged us out of the insert+v quick settings list, and we can't figure out a good way to get back in. Doing so makes connecting an application much more complicated. So, the verbosity settings are now accessed from the actions menu, hsc mods plus f10.
  • Added logic to control how automatic set switching is performed when a window title is found for which there is no hotspot set defined. The default is to revert back to the main set. This new option in the verbosity dialog allows HSC to just stay with the currently loaded set.
  • HSCDecodeHotSpotColor was still losing track of which spot was actually being fired when the spot was part of a chain.
  • The hsc mods plus left or right mouse button keys, which do a mouse click at the last spot executed also lost track of which spot was last when a chain was executed.
  • Ring tracking, which forced a spot ring to track along as spots on that ring are fired was not working. This is an optional feature, controlled by hsc mods plus grauv.
  • HSC mods plus f11 and f12 in the definition editor were skipping the value of 0 for noAction in the rotation

Build 209

  • Fixes bugs related to speaking of tutorial messages and special strings when activated via spot rings. Some issues also found regarding activating spots from the f1 list.
  • Fixes problems with color detection, using the HSCDecodeHotSpotColor function, for spots in chains, or when activated from a spot ring.
  • Deleting a hotSpot will now purge all existing spot rings of the deleted spot. Previous, spots remained as entries on the ring, even though the spot no longer existed

Build 207

  • Function HSCFocusChanged contained a line to always enable speech, which was causing problems with user scripts that wanted to keep speech turned off while focus was changing.
  • Post processing function HSCDecodeHotSpotColor did not assign new colors to the correct section in the .hsc file if the spot was placed on a new color, and was activated from the hotSpot list, rather than a hot key.
  • Added new post processing function SpeaktextBetween for speaking a portion of the horizontal line containing the HotSpot.

Build 207

  • Adds the ability to chain to a prior spot before executing the current spot
  • Some non-hotSpot items were turning up in the dialogs that select a hotSpot.
  • Get the version number right.

Build 206

Builds between 200 and 205 were private betas. Lucky you. You didn't get one. In fact, build 206 still claims to be build 205, because the version number did not get changed.. Build 205 fixes a number of issues surrounding spot rings, but adds no new features. And build 206 fixes a small bug that made the wizard generate the incorrect code when choosing the mouse action when defining new spots.

Build 200

  • Extended the tab key ring navigation feature, enabled with hsc mods plus comma, which allowed the tab and shift tab keys to navigate the current spot ring. Build 199 added the ability to use control+tab and shift+control+tab to switch between active spot rings, and for insert+tab to run the current hotSpot on the curretnly active ring.
  • When defining a hotSpot, specifying a hot key that is already assigned to a script, HSC will let you override the script for the current set so that, when the current set is active, your hotSpot runs. When another set is active, in which there is no HotSpot assigned to that hot key, the original application script will run. Likewise, when you delete that hotSpot, the original application script will be restored.
  • Several minor bug fixes regarding spot rings.

Build 198

  • Removed a piece of code that was preventing the jaws builtin function DLGSelectItemInList from working on later versions of jaws. This caused scripts that display stuff in the virtual viewer to not be able to do so.
  • HSC had refused to run a recovery spot when the debug option in the verbosity menu was switched on, and a hotSpot with a recovery spot specified, failed. As of build 198, the recovery spot will always be attempted except when you have debug mode set to "detailed". If you need to use detailed mode when debugging a recovery spot, give it it's own hot key, so you can execute it separately.

build 197

  • When importing HotSpot sets, HSC was not parsing the set file for top level window titles to determine a true set name. So, automatic widnow title switching was not working in some cases.
  • Fixed an unknown function call issue that occurred when initially loading a set.

Build 196

  • Fixed a minor bug that prevented one module, hscStrings.jss, from compiling successfully in JAWS 11.
  • Added top level support for a control right click action. The underlying logic is not yet available. You can specify it, but it won't do it yet.

Build 195

  • You can now create multiple spot rings, and even form a ring of rings.
  • Added a step to Build Spot Ring in the actions menu to allow for ring creation
  • Reworked the spot listing that appears after you creat a spot ring in the actions menu. No longer uses spacebar or enter to toggle the spot in or out of the ring, but uses left and right arrow keys.
  • Added hot keys for moving around the ring of rings, to select which ring is active.
  • Defined a new type of hotSpot which can activate a particular ring.
  • Added ability to define which spot ring is active when a set loads.
  • added Edit Ring Order utility to the actions menu for managing the order in which rings appear in the ring of rings, and the order of hotSpots on each ring.
  • HSC mods semicolon now speaks a tutorial message for the most recent spot. The Repeat last spot key is moved to control+alt+windows+grauv.
  • Added hsc mods plus left or right mouse button to repeat the most recent hotspot, but with a forced left or right click action.
  • Added support for licensed HSC files.
  • Added hot keys for altering a jaws place marker location, and to return to a temporary jaws place marker.
  • A new positioning mode, virtual line number, for html pages.

Build 194

Nothing is new. A bug related to incorrect spot ring navigation when more than 10 spots were in the ring has been fixed.

build 193

  • Changes to PCCursor relative positioning modes -- If the virtual cursor is active, when a pc-relative spot is defined, HSC will require that the virtual cursor also be active when the spot is activated, and will position relative to the virtual cursor. This will not function properly in versions of jaws where the RouteJawsToVirtualCursor function does not work correctly, such as jaws 7 and 8. Likewise, if the PC cursor is active when the spot is defined, the pc cursor will be required at activation time, and positioning will occur relative to the PC cursor.
    To force pc-cursor mode, use JawsKey+z to temporarily turn off the virtual cursor when defining a spot.
    Older spots, defined by earlier versions, will continue to assume pc-cursor behavior.
  • Added a new hot key, hsc mods plus q, for defining a new spot, using the selections made in the most recent hotspot definition. This is handy if you are defining a lot of spots that are very similar.
  • A problem where fs-supplied key maps were not properly inherited when HSC is connected to an application, such as internet explorer, where Freedom Scientific has supplied scripts, was addressed. HSC failed to copy the fs-supplied jkm file first, before adding it's own keys, thus disconnecting the fs-supplied hot keys.
  • HotSpotClicker.jss will now compile under jaws 10.

Version 192

  • Added a few helper functions which developers can call from their HSC-ready scripts to learn whether HSC is installed and, if so, what version it is. These were also added to the HSCStubsForDevelopers.zip file.
  • .
  • Improved the debug information provided when a hotspot fails, and you have debug mode enabled, as found in the verbosity menu.
  • Took steps to reduce the chattiness when operating the wizard. The basic problem is that, while the wizard dialogs are coming and going, jaws notices brief returns of focus to the application. This is improved, but will probably never totally addressed.

Version 191

  • Fixed problems when relating to the keymap refresh, and keymap remove all HSC Keystrokes utilities, which did not properly handle certain hotkeys.

build 190

  • Got realistic about how to label new releases. Instead of using standard major and minor version numbers, things will be named simply by an ascending build number. You get to decide for yourself what changes are major, and which are minor.
  • Various internal adjustments to accomodate jaws 9.0
  • Added an option to allow importing of all sets in the list, to the double click hsc mods+f1 dialog.
  • Added a new positioning mode, FocusWindow, which allows your hotSpot to move around, tracking the window with focus.
  • Added automatic loading of hotSpot sets based on a web page address in Internet Explorer.
    Loading A Set Based On A Web Page URL
  • Now you can remove dynamic information from set names when creating a new hotSpot set. IN the past, the set would not load automatically, unless it was unchanged. Now, it uses nicknames.
  • Added logic to restore multiple key navigation in HSC lists. Type the first few letters of the item you are looking for. This was broken by recent versions of JAWS.
  • Improved the information provided in detailed debug mode to help figure out why the item your hotSpot is searching for cannot be found.
  • You can now press a single space, for HSDSayPhraseByColor, which will cause nothing to be spoken for the current color.
  • Added logic to get rid of the virtual viewer when linking from a custom help file. The virtual viewer seemed to hang around for a bit if showVirtualViewerOnScreen was checked in jaws basics.

Version 7.72

  • If a hot key is assigned to a hotspot, but not in the currently active set, that key will now be passed through to the application, and no HSC message will be spoken.
  • HotSpot processing is now disabled while the Definition Editor is open, for cases where you have hotSpots attached to printable characters. so, you can enter those keys into the definition.

Version 7.71

  • Fixed a bug that allowed HSC to miss certain conflicts in your jaws keyMap when scripts were assigned in the Desktop Keys section.
  • Added a new key to the definition, failMsg, which can be set to a custom string which will be spoken when the hotspot fails.
  • Added a new option to the toolTip scanner, which lets you mouse around manually, collecting toolTips as you go. ToolTip Explore Mode

Version 7.70

  • Added the ability to define custom help for each hotSpot set, useful for sharing hotSpot sets with others, accessible through double click of control+alt+shift+h. Read about it here: Custom Documentation
  • Added the ability to Import, copy, or delete, a hotSpot Set, in the double click of hsc mods +f1 menu.
  • If you have a hotspot search for multiple strings of text, or one of a list of graphics, you can now make HSC speak which of those was actually found. This involves manual manipulation of a new key in the definition called SpeakLocatedItem.
  • Switched over to using an improved, more reliable HSCSRVR.DLL, based on ATL rather than MFC.
  • Added a sounder to replication monitor, for cases where people replicate massive amounts of spots without any prompting. Long periods of silence were disconcerting.
  • Same for generating all spots from toolTips.

Version 7.63

  • Add a PassKeyThrough option in the mouse action field, which allows the hotkey assigned to the hotSpot to be passed on to the application.
  • Added an entry to new hotspot definitions called SliderWidth, which can be used to make HSC scan a strip, rather than a single line when scanning for sliders. Older hotspots will continue to scan a single line, unless the new key is added manually.
  • In previous versions, color, text and graphics searches were all mutually exclusive. Starting in version 7.63, you can do a color search after you do a text or graphics search. The text or graphics search establishes the starting point for the color search.
  • ToolTip scanner, scan control keys did not work unless differentiate between NumPad and extended keys was turned on. This has been corrected, but you can also use control+shift in conjunction with the numPad keys as well.
  • Color exploration keys did not necessaryly honor the color format setting. Also, when pc cursor is active, alt+shift+NumPad5 did not report jaws cursor color. This has been corrected.
  • HotSpotOrganizer, when selecting a hotSpot, the "press escape to close this window" message was not sorted to the bottom of the list. This has been corrected.

Version 7.62

Nothing is new. Only Minor bug fixes,

  • Fixed Installer issues which caused compile failures on two script files, HSCAdjustment.jss and HSCRings.jss.
  • Changed a message to recommend hitting the space bar, rather than enter, on one dialog where conflicts were posed by JSonar scripts. This was the actions menu, Offsets-choose which hotspots will use them, when applying offsets to all selected hotspots.

Version 7.61

  • Added the ability to delete an entire secondary hotspot set from within the HSC menu structure.
  • Improved reliability of a keymap file copy operation which takes place when creating the original hotspot set, when the original JKM file is in the jaws shared settings area.
  • One of the drag and drop operations, where a hotspot is activated while the mouse button is locked, did not work correctly.

Version 7.6

  • Added new actions to lock and unlock left or right mouse buttons.
  • Added a Custom Click option for mouse actions, which can help work around cases where the physical mouse buttons produce results in some applications, which the default jaws mouse button emulation keys, simply do not produce.
  • Added the ability to fine tune the location of an existing hotspot. Described in Fine Tuning a Hotspot Location
  • Added Global hotspot Position Offsets for use in debugging positioning errors, and facilitating the temporary adjustment of a number of spots at once, before committing new position coordinates permanently to the spot definitions. Temporary Pisition Offsets.
  • Added the ability to position a hotspot relative to any of the four corners of a window, and even to position outside that window. Choosing A Reference.
  • Added ability to define a RecoverySpot, which will be executed if the current spot fails. Convenient if a troublesome spot constantly shifts between a couple of static locations, that you wish the clicker to check for at the press of a single hotkey. Read about it heer: Recovery Spots.
  • Added an option to override, on a spot by spot basis, the global option which controls whether the jaws cursor is left at the hotspot location, or return to it's original location after spot activation. New spots created with version 7.6 will contain the new parameter,
    RestoreCursorPosition. But to use this parameter with any other setting than it's global default, with previously defined spots, You must add this parameter manually to spots created prior to version 7.6.
    Values for this parameter are:
    0 = useGlobal setting,
    1= Restore Mouse to it's previous location before the spot was executed,
    2 = do not restore to previous location. i.e. leave the mouse at the position of the last executed hotspot.
    When new spots are created, this parameter defaults to the global setting, which by default is set to leave the mouse at the location of the most recently executed hotSpot.
  • Added a new, "SpotRings," feature, which allows the handy ability to quickly and easily activate hotspots in a totally customizable tab order. This can allow you to customize tab key navigation in cases where the tab key doesn't behave as you would like. By default, This feature is attached to controlAltTab, and controlAltShiftTab keystrokes, but one handed tab and shiftTab navigation of SpotRings is also possible.
    Read more about it here: HotSpot Rings
  • added 2 new Keymap related features to the hotSpotClicker actions menue:
    1. KeyMap refresh, ; when This feature is activated, hotSpotClicker will check that all the HotSpot key definitions listed in the application's main, and subset hsc files, are loaded into the jaws keymap file for that application, ready for use.
    2. KeyMap, remove all hsc keystrokes from the jkm file; as it's name suggests, This feature conveniently strips an application's keymap file, of all hotSpotClicker related keys. including hsc master keys, and any shortcut keys assigned to hotspots within that application.
  • revised window validation criteria to allow deliberate positioning outside the window.
  • Enhanced text searches to allow searching for unspecified text with particular foreground and background colors.
  • Provided a totally new hotspot clicker installation program, sporting several enhancements and changes to the installation and uninstallation process. hsc will now properly recognize versions of jaws above 7.0 during installation, and will now create it's own entry in the start menue. For more information regarding the new installer, please see: Installer changes from 7.51 to 7.6
  • Added a new hotkey, hsc mods+f5, which allows hotSpots, or window prompts, to be copied, or moved, between hotspot sets.
  • Previously, all hotspot set files were created directly within the personalized settings folder, within the enu folder of the user profiles area of jaws.
    Beginning with version 7.6, HotspotClicker will now create each newly connected application set file, plus any other subset files defined within that application, inside it's own individually named application folder within the personalized settings folder.
  • fixed a bug with handling of multiple post-processing functions, when the spot was chaining to another spot.
  • Fixed a bug with color autoAnnounce and the invisible cursor.
  • Fixed a bug which caused the non-successful release of an hsc related component upon manually quitting jaws, which subsequently prevented jaws from restarting correctly in certain situations. This could sometimes happen when jaws was mqnually manually exited from a non-hsc connected application.

Version 7.51

  • Added mouse and color exploration utility key strokes, used for exploring the screen for pixel colors, and graphics locations, useful especially in determining the colors and pixel addresses which define sliders. See Color And Graphics Exploration
  • Slightly enhanced the position cursor utilities on the f9 key to remember and default to the coordinates which were entered the last time the utility was used. Also added the ability to move the jaws cursor, even though the PC cursor is presently active. The cursor which was active prior to invoking this utility, will also be active afterword.
  • ToolTip Scanner - Added a hot key, control+shift+rightArrow to force the scanner to start moving to the right. This matches the existing control+shift+LeftArrow, which forces the scanner to move left.
  • Speed improvements for custom functions, and chaining to hotspots.
  • Added the ability to specify multiple, or even nested, custom functions. See custom functions.
  • Added ObjectName as an attribute for all new hotSpots and Window prompts, to provide more precise identification.
  • When defining a hotKey for a new hotspot, if the hot key is already assign , and you choose to override the key assignment, that existing hotspot will now be saved, using it's label as the identifier, and with no hot key attached, instead of being deleted entirely.
  • Added a new key to all new hotspot definitions, RestoreCursor, defaulted to 1. Set this to 0 if you don't want hsc to change which cursor is active after your custom post-processing function runs. For all new hotspots, you can control the default value of this parameter from the verbosity menu.
  • Fixed a problem where HSC was not detecting the active keyboard layout in jaws 6 and later.
  • Fixed a problem that could lead to long prompt processing delays if the window name was blank
  • Removed a problematic workaround which used object name when window name was blank. Now, object name is included as an additional, independent attribute.
  • .

What Was New In Version 7.50

  • Scanning for ToolTips -- an automatic means of systematically moving the mouse slowly around your application in an effort to identify clickable locations which yield toolTips, but which are totally invisible to JAWS. Access a list of known toolTips, in order to move to and activate them, or to generate hotspots from one, or all of them.
  • HotSpot replicator - Clone a hotSpot, and automatically make several copies of it, spread evenly over a line, or over a grid, great for accessing information from multiple coloumns, or for dealing with a large group of evenly spaced controls, including sliders.
  • Customize which current window criteria will be recorded in newly defined hotspots
  • Disable child window Validation - Temporarily turn off child window validation criteria to allow the hotspot to work, even though some aspect of the window containing the hotspot has changed.
  • HotSpots can now search for multiple occurrences of identical text or graphics, plus utilities to help you determine which occurrence of the item your cursor is on. You can enumerate a word or phrase, or a graphic, and can control which window to search.
  • A utility hotkey for moving the JAWS or invisible cursor to a given pixel address, either relative to the edges of the screen, or to the borders of the current window, the topLevelWindow, or the application main window.
  • Associate hotkeys withwindow prompts -- you can automatically create a hotspot, with hot key attached, for returning focus to the control which has focus when you create a window prompt.
  • Chaining hotspots - one spot can activate another spot. Infinite Loop protection is provided.
  • A spot prompt can activate a hotspot.
  • Color and graphics search algorithm has been significantly improved, including the ability to define unique search limits in all four directions.
  • If searching for a pixel color, Specify multiple colors as possibilities.
  • A special form of quasi-hotspot can be defined to activate a different set of hotspots. So, you can load a hotspot set at the touch of a key.
  • New positioning modes to track along with the PCCursor
  • More options have been added to the Actions list, such as sayToCursor and SayColorField.
  • More options have been added to the list of predefined post-processing functions, which run after your mouse action has been performed. These include the ability to speak a predefined string of text, or speak the contents of a frame. Plus, you can always add your own.
  • One post-processing function, HSCDecodeHotSpotColor, can now, not only speak a color-specific string of text, but can call other functions based on color.
  • JAWS INI services, which are used to read and write the .HSC files have been replaced for improved reliability.
  • Two hot keys were added for use in the definition editor, to allow you to modify numeric selection fields in ways that actually tell you waht the number means, rather than having to look it up.
  • In the opening dialog for the Definition Editor, you now have the option to press a hot key in order to edit the hotspot associaited with that hotkey.

Appendix I, List Of Hot Keys.

The following table lists the hot keys assigned to the HotSpotClicker to support its internal operations. In an attempt to reduce the likelyhood of key conflicts with commonly applied key assignments, the combination of all three modifiers, control, alt and shift has been used.

Information on how to change keyboard assignments is listed in the next section: Changing Hot Key Assignments.

Function

HotKey

Hot Key Help,

Control+Alt+Shift+H.

Assign a new hotspot,

Control+Alt+Shift+A.

Assign a new hotspot including graphics and color,

Control+Alt+Shift+G.

Create Spot Prompt, ,

Control+Alt+Shift+P.

Execute a hot spot from a list,

Control+alt+Shift+f1 single click.

Switch to, or create, a different hot spot set,

Control+Alt+Shift+f1 double click.

Delete a hot spot from the current set,

Control+Alt+Shift+f1 triple click.

Move to location - Choose hotspot from a list, and move the cursor to that location,

Control+Alt+Shift+f2.

Assign a user function to a hotspot,

Control+alt+Shift+f3.

Edit Definition choose from a list and press enter to modify,

Control+Alt+Shift+f4.

Organize HotSpots into Sets

Control+Alt+Shift+f5.

Speak Tutor Message for Most recently activated hotspot,

Control+Alt+Shift+semicolon.

Repeat most recently spoken message,

Control+Alt+Shift+apostrophe.

Enumerate Graphic, double click to select enumeration window,

Control+Alt+Shift+f7.

Enumerate Text, double click to mark and enumerate a phrase,

Control+Alt+Shift+f8.

Go to Absolute Screen Location

Control+Alt+Shift+f9.

HSC Actions Menu,

Control+Alt+Shift+f10.

Decrease numeric selection Item when in the definition editor,

Control+Alt+Shift+f11.

Increase Numeric selection Item when in the definition editor,

Control+Alt+Shift+f12.

Move mouse or invisible to explore for colors and graphics,

alt+shift with numPad arrow keys.

repeat color at active cursor,

Alt+Shift+NumPad5.

Toggle auto speaking of color upon mouse movement,

Control+Alt+Shift+period.

toggle auto speaking of graphic name upon mouse movement,

Control+Alt+Shift+slash.

Set bookmark at active cursor location,

Alt+Shift+PageUp.

Return to most recently set bookmark,

Alt+Shift+PageDown.

Route Jaws to Invisible,

Alt+Shift+NumPadMinus.

Route Invisible to Jaws,

Alt+Shift+NumPadPlus.

Set Anchor Point,

Alt+Shift+NumPadHome.

Distance From Anchor to cursor,

Alt+Shift+NumPadEnd.

enable/disable tab key navigation of spot ring,

Control+Alt+Shift+Comma.

enable/disable spot ring autoTracking,

Control+Alt+Shift+Grauv.

Appendix I.1, Changing Hot Key Assignments.

This section applies to the hot keys which are used to control HSC operation, and not to those which are connected to your hot spots. To change hotspot key assignments, read section: Editing HotSpot Definitions.

If you wish to change the hot keys assigned to the HotSpotClicker itself, You must follow the steps in this section. Simply revising your application's jkm file is not sufficient.

Use the script manager to edit file
HotSpotClickerKeys.jsh.
which is located in your $jaws folder.

This file contains a series of constant definitions, which are of the form
SymbolicName="HotKeyName."
Do not change the symbolicName, as this name is referenced in the JSS file. However, you can change the HotKeyname portion of the line to reflect the key you wish to assign to that function. Notice that the HotKeyName is in quotation marks. The quotes are required.

If you use modifier keys, keep them in the following order: Control, Alt, Shift Windows. do not use the JAWSKey, keep that for FreedomScientific.

After editing all the entries you wish to change, save and close the HotSpotClickerKeys.jsh file.

next, use the script manager to open file HotSpotClicker.jss. recompile this file by pressing control+s. This will cause your revised jsh file to be read and incorporated. Now, you can close the jss file.

To change the color and graphics exploration hotkeys, You must edit file
HSCMouseKeys.jsh
Then, recompile module HSCMouse.jss.

Next, you will need to manually remove the previous hotspot clicker key assignments, from the jkm file of any applications for which the hotspot clicker has been previously installed, prior to your key assignment alterations. You can do that with the script manager fairly easily, or you can use the keyboard manager.

When you focus back in your application, the new key assignments will be added to your application's jkm file. but, with jaws 6, or later, you may need to focus elsewhere briefly, and then focus back in your application for jaws to realize the change has taken place. Once yu have done all these steps, the hot key help will be automatically updated, and your new keys should be in effect. But, of course, your new keys will no longer be consistent with this document.

*** end of HotSpotClicker ***