This is the abbreviated quick start guide for HotSpotClicker, referred to as HSC. If you want complete information on the entire feature set, or If you find that you need more guidance on how to perform the steps required, please consult the link below. this file just provides the basics to get you up and running, and presumes nominal familiarity with the script manager. The revision history is at the end of the detailed documentation. Read detailed HSC documentation here
Here is a quick and gratifying way to start using HotSpotClicker if you have a sighted friend nearby. You must first have HotSpotClicker installed and connected to the application where you want the hotspot to be defined. Just ask your friend to place the mouse on the graphic you want to assign a hotspot to, without clicking on it. Press control alt shift A to start defining the hotspot there, and follow each prompt as it appears. It is important to remove what HotSpotClicker calls dynamic information from all Window names. This information is often the name of the document Which is currently opened in your application. After the hotspot has been defined, you can check if it's there by typing all control shift F1, and start using it right away. Or, you can just press it's hot key. This is only a start and I encourage you to read the rest of the manual as you can do much more with HotSpotClicker.
If you have a location on the screen where you want to perform some kind of action, this utility lets you identify that location, and specify the action to be performed, and even a hot key to be used to initiate the action. The actions to be performed can include all types of mouse clicks, acquiring and speaking various units of text, and several specialized behaviors. Before the action is performed, HSC will position the mouse cursor at the starting point specified by the HotSpot definition, and can be caused to adjust the location by searching near that initial location for text strings, graphic names, or pixel colors.
HotSpotClicker is a set of JAWS scripts, along with a .dll file which is installed onto your coputer. The DLL file does nothing unless it is called upon by HSC to interact with the HSC data files. Unlike most scripts on your computer, HSC does not belong to any particular application. It takes no action on it's own, and can not even be seen until you connect it to one or more applications, as described below.
If you already have scripts for an application, you can modify them very slightly to cause HSC to operate in conjunction with those scripts. If you don't have any custom scripts, you will need to create a bare skeleton script file to allow the HotSpotClicker to be activated. This is discussed more in the installation section.
In it's simplest form, HSC allows you to place the jaws cursor in some location where you want to do a mouse click, or read some text, and then to connect that location to a hot key so that, when you press the hotkey, the jaws cursor is taken to that location, and a desired action is performed. The action can be any kind of mouse click, or speaking of on-screen text, through various methods such as sayword, sayLine, say all text of the same color, SayFrame, and many other options.
The location can be identified by it's absolute screen coordinates, or through the use of several different window border-based positioning methods which allow the hotspot to move around as your application is resized, or relocated.
Optionally, you can specify a series of one or more post-processing functions, either from a list of standard offerings, or a custom function in your script file, which will be automatically executed After the specified action is performed, making this a very extensible tool.
HotSpots can have hot keys attached, or can be left unassigned. You can activate a hotspot by pressing it's hot key, or by choosing it from a list.
Hotspots can be organized into sets. Each set can be activated manually, or automatically as your application changes focus. Only one set is active at any one time. But, the same physical hotkey can be attached to multiple hotspots, depending on which set is active.
You can group a subset of hotspots into one or more hotSpot rings, which can be used to create your own tab order, overriding the tab order provided by the application. This means that, each time you press the tab key, the next hotspot in the ring is activated. Hot keys are provided to choose which ring is active, and to move around the active ring, in either direction.
HSC also includes the ability to define custom prompts for controls whose labels, or values, are not properly spoken. You can define the prompt to be spoken, and can specify alternative methods for obtaining and speaking the current value.
Several handy screen exploration utilities are included, including a toolTip scanner which automatically explores the screen for toolTips, and builds a list of such locations, so you can explore their uses, and can generate hotspots from any or all of them.
Once you install HotSpotClicker, and are focused in an application to which you have it connected, press control+alt+shift+h for a list of HSC hot keys.
Second, you must connect HSC to each application with which you want to use it. This connection is specific to the version of jaws that is running at the time. HSC's connection to that same application will not exist for other jaws versions until you open that version of jaws, and perform the steps required.
Installing HSC is easy, as described in the next paragraphs. But, uninstalling it is a bit more involved. This is because, each time you connect HSC to an application, changes are automatically made to the jaws keymap for that application. Plus, you have to make a few small additions to the jaws script source file. The uninstaller doesn't know about all those changes. So, Before you actually uninstall HSC, you need to undo those manual steps you took for each application. Failure to unhook HSC from all applications prior to actually removing HSC will result in annoying error messages each time you focus in the offending application. Read the details here: Manual Uninstallation Instructions
Download the executable installer here download HotSpotClicker build 242 Executable Installer Run the installer, and follow on-screen prompts as usual. If you already have HSC installed, and the installer asks if you want to uninstall a previous version first, answer no. Life is just simpler that way.
The installer will make a backup copy of your settings\enu folder in the user-specific settings area, which can serve as a safe repository of unmodified script files, in case your manual modifications go arye.
In addition, the installer will place a small set of files into the settings\enu folder of your user-specific settings area, and will also create a HotSpotClicker folder in the Program files folder, and create a HotSpotClicker group in the Start menu, from which you can access documentation files in that folder.
If there are no custom scripts for your application, you can create the necessary skeleton script file by copying all of the text in a file called
HscConnectionCodeForBlankJssFiles.HTML
Which, after HSC Installation, is located in the HotSpotClicker folder in the Program Files folder.
Focus in the application, and open the script manager, and make sure the file is blank. If it is, then paste the copied text into that blank script file, and then recompile.
Note that if you have purchased scripts from a vendor which does not supply the script source, in the .jss file, you can not connect HSC to those scripts, unless the vendor has chosen to make the scripts HSC-ready.
If the file is not blank, add the following statement near the top of the file:
Use "HotSpotClicker.jsb"
typed exactly as shown here. This is required for basic functionality. Do the next two items if you want to enable window prompts, and automatic hhotspot set switching. when you are done modifying your application scripts, press control+s to recompile.
To enable automatic set switching, add the following line as the first executable line of your focus ChangedEvent:
HSCFocusChanged (GetWindowName (GetTopLevelWindow (FocusWindow)))
Replace the word "FocusWindow" with the actual parameter name of the first parameter to your FocusChangedEvent.
If you don't have a focusChangedEvent, then make one that looks like this:
Function FocusChangedEvent (handle focusWindow, handle prevFocus)
HSCFocusChanged (GetWindowName (GetTopLevelWindow (focusWindow)))
FocusChangedEvent (focusWindow, prevFocus)
EndFunction
To enable HSC custom prompt processing, add the following 3 lines as the first executable statements in your HandleCustomWindows function:
if (HSCCheckforPrompt (focusWindow)) then
return(1)
Endif
Where focusWindow should be replaced with the name of the actual parameter in the top line of your HandleCustomWindows function.
If you do not have a HandleCustomWindows function, make one that looks like this:
Int Function HandleCustomWindows (handle focusWindow)
if (HSCCheckforPrompt (focusWindow)) then
return(1)
Endif
Return (HandleCustomWindows (focusWindow))
EndFunction
If, when you try to assign a prompt, HSC says that the functions required are not installed, or if custom prompts never are detected, then you may need to move the three lines listed above, over to the FocusChangedEvent. This is because, depending on choices made by the author of your application scripts, HandleCustomWindows may not be called as expected. If this is necessary, make sure you change "focusWindow" to match the first parameter in the top line of your FocusChangedEvent.
When you have finished editing, recompile the script file and return focus to your application. HSC will detect that it is running in a new application, and will install it's keyboard assignments, and create an original, empty hotspot file, with a default HotSpot set named according to your application.
note: if upon defining hotspots, you find that hsc is not excepting your keystrokes during the final beeping key assignment phase of the definition process, don't pannic! Just allow the 30 second timeout to elapse, and check the section in the main documentation pertaining to the KeyPressedEvent function. Minor script modifications must be applied to the KeyPressedEvent for Internet Explorer running under versions of jaws after 6.2.
In order to use the HotSpotClicker, you need to be focused in an application to which it is connected.
Most HotSpotClicker master keys use the modifiers, control+alt+shift, all three held down at once. We call these HSC mods. But, when you define your own hotspots, you can use other combinations as you wish.
Use HSC mods plus h to get a list of hotkeys assigned to the clicker itself.
Use up and down arrow to explore that list, and escape when finished, or press enter on an item to execute it.
Before defining a spot, you need to put the jaws cursor, which is the same as the mouse pointer, in the correct location. you can use any of the normal cursor navigation keys to do this, however you may find that traditional character, word, or line navigation commands,
will cause the mouse to totally jump over the locations you want to click.
in these cases, use shift+alt in conjunction with the numPad arrow keys to move the mouse, or jaws cursor, a few pixels at a time. Enter home row with insert+space, then use left and right arrows to choose how many pixels to move with each key press. then, exit home row mode with insert+space. The default increment is 3 pixels.
Alternatively, you can also have a sighted person place the physical mouse in the correct location before starting the HotSpot creation process.
To jump to a set of absolute screen coordinates, use hsc mods plus f9.
To jump to a given number of pixels down, and to the right, of the top left corner of a window, use a double click of hsc mods +f7 to choose which window will serve as the positioning reference for your mouse movement. Application, means that the main application window is the reference. topLevel, means whatever window has a title, and contains the window or control that currently has focus. Current Window, means the window that contains the mouse. When using Current Window mode, you first need to place the mouse anywhere inside that window, then proceed to the next step. Mouse pre-positioning is not required for the other two modes.
Once the mode is chosen, double click hsc mods+f9, and type in the pixel column and row, separated by a space.
Toggle automatic speaking of color or graphic name upon small mouse navigation, with hsc mods plus period, or slash.
Repeat the RGB value of the color at the current location using alt+shift+NumPad 5. double click to copy color to clipboard.
Set a bookmark with alt+shift+PageUp, and return to that bookmark with alt+shift+pageDown.
To create a HotSpot, Once your mouse is positioned, press hsc mods+A to start the hotSpot creation wizard.
Every hotspot belongs to a set.
The default set is named after your application, and the definitions in that set are stored in the main HSC file along with some other general purpose information. but, you can create additional sets. The default name offered for each new set is the topLevelWindow name which contains the window which presently has focus inside your applicaition. But, you can override that to specify any name you like, as long as it is unique. The definitions for the new set will be stored in a file generically named setName.hsc in the PersonalizedSettings folder.
But, you should accept the default set name if you want to activate the new set automatically upon changes in application focus.
To choose which set is presently active, or to create a new set,use hsc mods plus a double click of f1.
In that same dialog, you can enable or disable automatic switching. If automatic switching is enabled, then each time your application changes focus, HSC will look at the name of the top level window which contains the control with focus. If it has a set by that same name, it will activate it.
Manually activating a set disables automatic switching.
If the dialog says automatic set switching is not presently installed, then your addition to the focusChangedEvent was not done correctly.
If they don't provide scripts as well, then you will need to connect HSC to that application as described elsewhere in this guide. Once HSC is connected, you can double click hsc mods+f1, and choose the item called Import a HotSpot Set, and press enter. You can then choose which set to import, or to import all sets. HSC will set up the required keyboard associations to allow your hotspots to be activated.
This will create a new hotspot in the currently active set. Once you have the jaws cursor position on the location of interest, press hsc mods plus A, and follow the wizard, using up and down arrows to choose your answers, and pressing enter to advance. there is no back button. If you change your mind, just escape and start over.
If you want to create a spot on a graphic, or a string of text, and you want HSC to search around for that item first, in case it has moved slightly, then use the hsc mods plus g wizard instead.
HSC will ask what kind of positioning mode you want to use. There is an extensive discussion on positioning modes in the main documentation file. But, for most purposes:
Application mode positions relative to the top and left edges of the application, and is good for most non-dialog controls.
For controls inside dialogs, topLevel positioning is usually good, and will compute the position relative to the edges of the dialog.
Current Window mode does an application-wide search for a window matching the smallest window containing the cursor at definition time. While a very powerful method, this can be trickier to get working, because if the window is not unique, then HSC will probably find the wrong window. In addition, some of the window criteria can change over time without it being apparent, and can invalidate the search unless those criteria are disabled. Debugging this type of hotspot is significantly more difficult than those of other modes.
SetFocus mode is used to set focus on the control that had focus when the wizard was started.
If you are asked to remove dynamic information from a window name, use your editing keys to remove any portion of the name that will change, such as document names. Leave only the characters that will remain constant as your application is operated.
If you chose to attach a hot key during spot definition, simply press that hot key. If the set to which that spot belongs is active, the spot will be activated. Or, press hsc mods +f1, choose the spot from the list for the currently active set and press enter.
To revise the parameters that make up a spot definition, use hsc mods plus f4. If the top line says !Promptiew, then you are looking at window prompts. press enter on that line to switch to !hotSpotView. Choose a spot from the list for the currently active set, and press enter. or alternatively, hit enter upon the, "select by hotkey" list entry, then press the hotkey assigned to the hotspot, to enable you to select the spot for editing via it's assigned hotkey.
An edit box opens showing all the parameters. Use standard editing keys to revise values.
Use hsc mods plus f11 and f12 to modify numeric fields.
A complete list of all parameters and their associated meanings is located in file
HotSpot Parameter Reference.html
which is also listed in the HotSpotClicker start menu item.
Control+A cannot be used to select all within the editor. If you want to copy the definition to the clipboard, , move to the top of the definition with control+home, to the start of the line with home, then use control+shift+end to select the entire definition.
Use control+m, instead of the enter key, to place a line break in the buffer.
Press the real enter key when you are done editing, and then answer the confirmation dialog.
Or, press escape to cancel and discard your edits.
If you're hotspot used to work, but it doesn't any more, the most likely reason is that some of the criteria you used to define the spot have now changed.
Access the jaws verbosity settings with JawsKey+v, and enable the HotSpotClicker Debug Mode. Then activate the hotspot again.
HSC will speak the offending criterion, indicating what was found, versus what was expected. You can then use the definition editor to alter the offending criterion.
For more information, read the section on Customizing Comparison Criteria in the
Detailed HSC documentation
You can use the Homerow utilities in JAWS to examine the various aspects of the window to determine which criteria no longer match those listed in the definition editor for the broken spot. This will allow you to appropriately generalize those criteria. Completely eliminating criteria, by placing an asterisk in the first column of the line containing an offending criterion can make the spot succeed again, or it can cause HSC to find the wrong window, depending on the application. Experimentation is often the only way.
This is an optional function that can run after your spot has been activated, and any necessary mouse click has been performed. You can write your own function in your application script file, and provide the name to HSC, or you can choose from a list of predefined functions.
One very handy predefined function is HSCDecodeHotSpotColor, which causes HSC to evaluate the pixel color at the spot location, and look up a string of text to be spoken when that color is found. If a string is already stored, it will speak that string. If it has no text string for that color, it will ask you to enter the string you want spoken when that color is found. Enter a space to ignore the color. It is also possible to assign additional custom functions for each color detected.
Another handy function is HSCChainToHotSpot, which will ask for the name of a hotspot to be activated, when this hotspot finishes. In this way, you can chain hotspots together. If you accidentally chain them in a circle, HSC will rescue you.
To assign a post-processing function, use hsc mods plus f3, pick the spot to which you want to add the function, and press enter. then, choose the function you want to assign. Only one function can be assigned to a hotspot in this way. But, you can use the definition editor, hsc mods+f4, to add additional function names to the "function=" line. Separate multiple functions by the vertical bar "|". For exmaple:
function=MyFunction|YourFunction
The functions will be executed in the order they are listed.
A special exception is HSCChainToHotspot, which can be added through the hsc mods+f3 key, even though another function is already attached. This function is automatically invoked last, if the ChainToSpot parameter in the hotspot definition is present, and is not blank.
You can write a function in your application script file, and provide it's name to HSC, using the "create your own" option, to cause HSC to invoke your own custom function. This function will now be offered as an option for all subsequent hotspots in this application.
you can remove the function by repeating the function assignment process described here, and choosing "none".
To remove a chain, use the definition editor, and delete the characters to the right of the equal sign in the ChainToSpot parameter.
Use hsc mods plus a tripple click of f1. This dialog lets you delete hotspots, or window prompts. If the top line says !PromptView, then you are looking at window prompts. Press enter on that line to make it say !HotSpotview. Pick a hotSpot from the currently active set, press enter to delete it, and answer "yes" to the confirmation question that follows.
Focus on a troublesome control and press hsc mods plus p. Type in the label you want spoken when focus lands on that control.
Choose a function which will report the value of the control. HSC provides several predefined possibilities, including jaws default processing. Or, you can write your own function in your application script file, and specify the name of that function to HSC.
You can specify a hotspot which will be executed when this control gains focus.
You can also specify a hot key which will place focus on this control, if it is visible. This actually creates a separate hotSpot, whose job is to set focus on the control of interest.
To alter some parameter in a prompt definition, use hsc mods plus f4, and choose !Promptview. then, pick a prompt to be edited and press enter. The definition editor for the selected window prompt will open. This is just like the hotspot editor. Press enter to save changes, or escape to quit.
If your window prompts used to work, but stop working after a while, there are two likely possibilities.
First, use jaws home row mode to learn the attributes of the control for which your prompt is assigned. then, use the definition editor to check the window validation attributes that are recorded for that prompt. Some of them may have changed. Perhaps they are not really required, and can be temporarily eliminated by placing an asterisk in column 1. Or perhaps, they contain dynamic information, and need to be generalized. Read the Customizing Comparison Criteria. section of the Detailed HotSpotClicker Documentation
The second possibility relates to changes in the windows hierarchy, which is the relationship between individual windows, arranged in a tree-like hierarchical structure.
HotSpotClicker's spot prompt functionality, relies on a static position in the hierarchy, and if this alters, it may cause inaccuracies in your spot prompts. an example of this can be seen in windows volume control. if you define prompts for the many tab stops within this application, but then you alter how many actual controls are displayed in the application, through the properties for the play control, then, you will find that some of your prompts no longer speak. If the prompt just stops firing altogether, then you can probably deal with it by defining another prompt for the same control in the new context.
Then, you will have two prompts, one for each context.
However, if the original prompt still fires, but on the wrong control, life is a bit more complicated. One solution is
to consider the prompt criteria in the definition editor to see if any of them are more generic than is appropriate, such as considering only part of a window name.
Another option may be to create a hotspot set for each configuration, and then define all necessary prompts and hotspots in one of those sets, leaving the other set empty.
When you do this, for each new set, HSC will create a new file in the PersonalizedSettings folder generically called setName.hsc. It is legitimate to use Windows Explorer to delete the empty set file right after creation, and then to copy an existing set file, and rename it to match the new set name, including the .hsc extension.
This will import all hotspots and prompts from the populated set, into the second set. then, you can delete, and then redefine, prompts that do not work for that configuration.
If you want to import hotspots or prompts from the default set, you should not copy the default set, since the main hsc file has a different format from the secondary sets.
Use HSC mods+f5 to move or copy hotSpots, or window prompts, from one set to another.
As a last resort, if possible, you may need to settle on a context, such as deciding which controls you want to have show up in your volume control, and just leav it that way. Then define the prompts for that context. Meanwhile, we're looking at other ways to do this.
If a hot key was associated with a window prompt, there will then be a corresponding hotspot for that hotkey which must be deleted separately.
HSC can slowly move around your application, looking for regions on the screen which, when the mouse hovers there, will produce a ToolTip. this is a very slow, methodical process.
Once the ToolTip locations have been learned, you can view a list of known toolTips, and can have the jaws cursor moved to a ToolTip by choosing it's name in the list and pressing enter.
You can generate a hotspot from a single toolTip location, or can automatically generate spots from all known toolTips.
the toolTip scanner is located in the HSC Actions menu, accessed through hsc mods plus f10.
For more information on all things HSC, see the Detailed HotSpotClicker Documentation
*** end of document