Why Do HotSpots Fail

One of the most common problems with HotSpots, is that they work when you initially define them. But later, they may stop working, for no apparent reason. This article discusses some of the more common reasons why this happens, and suggests ways to make your HotSpots more reliable.

Trimming Dynamic Information

This has to do with window names that change over time, and no longer match the titles that were learned at the time of hotspot creation. Whether or not this is the problem can be determined by turning debug mode on. Go to the HSC actions menu, choose verbosity settings, and set debug to either detailed or summary. If HSC is failing to identify the proper window, a message will indicate the fact. In any case, this problem usually results in HSC saying HotSpot Failed.

In the hotSpot creation wizards, you are often asked to remove dynamic information from various strings that are obtained from the application. Typically, these are used as window names, or object names, when HSC attempts to insure that it is clicking in the correct location. It is therefore quite important to edit these strings to remove information that will change over time. This is covered pretty well in the main documentation. Clearly, a document name is one such example. For example, if the window name is:
Untitled - Notepad
you would not want to use that as a window name, unless you only wanted your spot to work when notepad is opened with a blank, default document. If you used notepad to open a specific file, like MyText.txt, then the window name will change to:
MyText.txt - notepad.
To have the spot work for all documents, the string, when offered in the wizard, should be edited down to simply:
- Notepad
totally removing the filename. HSC would then change its strategy to not require an exact match, but to simply require that any window title it finds must contain the string "- Notepad" as a part of the name. Or, if you blank the string entirely, HSC will conclude that no match is required at all, and will accept anything for that field.

However, a less obvious example is where an application version number is part of the window title. You may, or may not, wish to include that. But, the key is to be conscious of what will change, and what will not.

In some cases, the string obtained by the wizard is so long, that it can even impair the ability of JAWS to speak the prompt, which instructs you to remove the dynamic information. If you find yourself in the wizard, but focused in an edit box with a bunch of text that seems like it may have come from your application, then you are probably at a dynamic information removal step. And, it is now important to consider the string offered, and do this editing.

Again, because some strings are quite long, depending on your application, the operation of the edit box can be confusing. This is outside the control of HSC. Some versions of JAWS behave quite oddly when the edit box is populated with more text than will fit on screen. Just pressing control+shift+end, followed by delete, may or may not be enough to entirely blank the string. Be more assertive with the home and end keys to make sure you have seen the entire string, before dismissing it.

If you have defined a spot incorrectly, and wish to repair it manually, you can actually edit the .hsc file with a text editor, and correct relevant fields. Typically, these are the windowname, application window name, topLevelWindow name, and object name. If you are deleting characters from any of these strings, HSC can no longer look for exactequality, but needs to just require that the string it finds contains the characters listed in your .hsc file, as a subset. To make HSC realize that, you need to put a caret "^" just to the right of the equal sign.

To allow HSC to accept any title, no matter what, delete all characters to the right of the equal sign, and replace with an asterisk "*".

To require that the title must be blank, replace all characters with a dollar sign "$".

Positioning Method

The second most common reason why hotSpots fail is that the location you need to click has moved, relative to the location identified by HSC. it is not always clear, when you are creating spots, whether the location of interest will stay in the same place, or if it will move, and when. Until you fully and precisely understand that behavior, it is difficult to instruct HSC how to accomodate it.

Usually, HSC will not say "hotSpot failed". It will happily perform the requested action, just at the wrong place. Usually, unexpected actions will result, or nothing at all will happen.

The problem usually derives from the fact that the hotSpot is basing it's position reference on the wrong reference item. By default, HSC uses the top left corner of a window as it's positioning reference. This means that the windowColumn and WindowRow attributes of the spot are actually distances in pixels from that top left corner. But, as the window is resized, minimized, or maximized, it is stretched, and the distances between items inside the window can change. In cases like that, it might be necessary to use a different corner as the reference. Or, perhaps, you can instruct the hotSpot to search for an item, such as a string of text, a graphic name, or pixel of a certain color first, and then to move x pixels in some direction from there to find the actual click location.

You can use HSC mods f2 to just move the jaws cursor to the spot location without performing the action. If you like, bookmark the location with alt+shift plus numPad home. Now, mouse around and find the proper location. You can use Adjust HotSpot Location, in the actions menu, to correct the spot for now. But, the problem will reoccur until it's root cause it understood. The key question to be answered is:
what item, that jaws can find, is a constant distance from the location you want to click?
If it's a different corner of the same window, you can use the definition editor to alter the item called ReferenceCorner. Remember, hold down the hsc mods, and press f11 or f12, then release all keys to change, and hear the meaning of, numeric fields like that.

In some cases, it might mean that you have specified the incorrect positioning method when you created the spot. Application relative is the most commonly used. But, sometimes, the location you want is actually inside some child window. As the child window moves, so to does the location of interest. But, if your hotSpot is always relative to the application at large, it does not track the movements of the child window. Current Window Relative positioning may work in a case like that.
When you define the spot initially, specifying current window relative positioning, HSC will perform a test, to see if the window can be uniquely located. If there are other windows with the same identifying information, then identification is ambiguous, and HSC will tell you that. Cases have been seen where, for some reason, HSC gets it wrong, and thinks the window is not unique, when it actually is. So, it's worth a screen refresh, and a retry. But, if the same error is reported, then current window relative is not an option.

TopLevel positioning is typically good for spots inside a dialog. But again, experimentation may be the only way to find what is best.

To change the positioning method, the best way is to just delete the spot, and redefine it from scratch.

Use Text Or Graphics as a reference

Sometimes, you can use the mouse exploration keys to find a text string, or a graphic, that is near the location of interest. HSC mods plus the slash key on the bottom row will enable autoGraphics reporting, so your mouse exploration keys will announce the presence of graphics, even those that are not labeled. If you find one near bye that you want to use, use the jaws graphics labeler to create a graphic label. Again, this graphic, or text string must always be a fixed distance from the location of interest.

Put the Jaws cursor on the reference graphic or text, and use the hsc mods plus g advanced wizard to define the spot. Tell it to search near bye for that item. Now, the spot will track along as the reference item moves. Then, use the hsc mods plus numPad home and end to set a reference on the hotspot location. then, move the jaws cursor to the spot you actually want to click, and use hsc mods plus NumPad end to find out how far that location is from the reference. All that remains, is to use the definition editor to set the horizontal and vertical text offset items to the distance numbers you learned with the mouse exploration keys.
this makes HSC search for the reference item, and then move a fixed distance to the actuall spot.

Reference Items

If you are searching for a specific color or a text string, are those things changing as you operate the application? Is the color the same, regardless of which cursor is over that color? Or, does the color change as the mouse cursor hovers there. Usually, when you activate a hotspot, and it searches for a color, the mouse cursor is not already at that location, meaning that it is the non-hovering color that is of interest. You can use the invisible cursor with the mouse exploration keys. The invisible cursor will not affect colors over which it hovers, and will more accurately report the colors you should search for.


Some times, when you label a graphic with the jaws cursor, then move the jaws cursor away, and try to find the graphic with the invisible cursor, you won't find it. This is because the graphic changes in appearance, depending on whether the mouse is hovering over it or not, and JAWS considers that to be a completely different graphic. So, with the jaws cursor elsewhere, if you do a search for the graphic by it's jaws cursor labeled name, the search will fail.
The solution is to label the graphic twice, with the same name, once with each cursor.

Multiple HotSpot Sets

If you are using multiple sets, is the new set loading when you dont' expect it to? If so, then the spot you think is failing is actually not running, because it is not defined for the current set. Double click hsc mods f1 to see if this is the case. If so, then the set name needs to be more narrowly defined, in order to only switch when appropriate. Changing a set name can be done by editing the main .hsc file, the [hotspot file list] section, changing the characters to the left of the equal sign.