Ways to Make Supernova Do Something When You Press a Key

Ways to Make Supernova Do Something When You Press a Key

Ways to make Supernova do something when you press a key.

Introduction

There are various ways to make the Dolphin Access Software do something when you press a key. This article reviews these methods and discusses the advantages of each one.

This article assumes you are already familiar with and have a basic knowledge of mapping and scripting. The article is based on version 10.02 of Supernova, but the methods discussed apply equally to Hal and other versions of the Access Software.

In all the following methods, we assume you are already running the application for which you wish to program the key.

The example action we program is simply to say the word "Hello", purely for demonstration.

Ways to make something happen when you press a key

Following are the main ways to make something happen when you press a key.

1. Define a custom action in the map file actions.

This method uses mapping alone.

Method

  1. Open the Access Software Control Panel by pressing Ctrl + Space.
  2. From the Map menu, choose Map File Management.
  3. In the Map File Management dialog that appears, press the General Settings button.
  4. In the General Settings dialog, press the Custom Action Definitions button.

This brings you to the Action List dialog, where you can manage any actions which are specific for this map.

To create a new custom action:

  1. Select the category for the new action, from the Category list. In this case, select Custom Application.
  2. Press the New button to create a new action.
  3. You will be prompted which action you wish to define; select it from the list and choose OK.

This brings you to the Action Editor where you can create the list of operations that make up the action.

  1. Enter a name for the action, in the Name box.
  2. Press the New button to create a new operation.
  3. In the New Operation dialog, select the operation Speak Text and press OK.
  4. When prompted, enter the word "Hello" and press OK.
  5. Finally, press the OK or Close buttons in all the dialogs until you return to the application window.

To test the new hot key, press the key that corresponds to the action you defined.

For example, if you chose to define custom application action 1 and are using the default desktop (number pad) hot key set, the hot key is Left Shift + Numeric Keypad 7. The equivalent hot key for the default laptop (function key) hot key set is Left Ctrl + Left Shift + F5.

If all goes well, the speech should say - rather unsurprisingly - "Hello".

Advantages

The advantages of using this method are that the hot keys can be kept consistent in different applications and the key should be familiar to the user.

The custom application action hot keys are defined in the Hot Keys dialog in the Configure menu; so if a user chooses to redefine their hot keys, the custom action will still work with the new hot key. The hot key is also discoverable in Key Describe mode.

Note that this method is not just restricted to being able to define custom application actions: you can also redefine what a standard action does by picking it from the list in the Define Action Dialog. For example, if you want to make the Read Status action do something different, choose this action from the Speech category.

This method uses mapping to create the action. Writing actions in maps can be an effective way to quickly code simple tasks.

2. Define a dynamic hot key in a map file rule.

This method uses mapping alone.

The technique is similar to the previous method, but embeds the action in the filter for a rule in the map file. We also use a Dynamic Action which means the action itself can define the hot key to use.

Method

  1. Open Training Mode by pressing Left Ctrl + Left Shift + Semicolon.

Note that this key combination may not be available. If not, set up the hot key for the action Train Windows (in the Actions category), using the Configure Hot Keys dialog.

The Training Mode dialog should appear.

  1. Proceed to create a new rule or edit an existing rule as necessary. Be sure that the rule is in the map for the application.
  2. When you get to defining the filter for the target of the rule, press the Custom Actions button.

This calls up a dialog very similar to the one for defining general actions in the map.

  1. Select the Dynamic Actions category from the list of actions.
  2. Press the New button to create the new dynamic action.
  3. In the Create Action dialog, enter a name for the action.
  4. In the list of operations, press the New button, select Speak Text and then enter the word "Hello" when prompted. The process for defining the operation list is exactly the same as for the previous method.

Before closing the Action Editor dialog, notice that there is an extra button, Hot Keys, that isn't present when defining a custom action as shown in the previous method.

  1. Press the Hot Keys button and define the hot key you want to trigger the action.
  2. Finally, OK or close all the dialogs and return to the main application.

Test the action by pressing the hot key you defined. If all goes well, as expected, the speech should say "Hello".

Advantages

The advantages of this method are that the hot key will only be available in the circumstances when the mapping rule applies. For example, if you added the rule for a particular dialog box, the dynamic hot key will only work when in that dialog and not in the rest of the application.

Another advantage is that, because you have to specifically define the hot key, you can be sure of exactly what keys to press, no matter how the user has their hot key set configured.

However, there is a disadvantage that the user will not be able to disable or change the hot key unless they go through the mapping process as described above. Again, in order to make the change, you have to know where you are looking. Further, the hot key cannot be discovered using Key Describe mode.

3. Define a hot key to call a script function.

This method uses both mapping and scripting.

Method

First, we'll write a script function called Test.

  1. From the Map File Management dialog in the Control Panel, press either the Create Script or Edit Script button as appropriate. This calls up the Script Editor.
  1. Move to the end of the displayed script, by pressing Ctrl + End.
  2. Enter the following script code:

function Test()

Speak.Text("Hello")

end

  1. Save the script and exit the editor using the commands on the File menu.

Now, we'll create the action to call this script. You can define the action either as a custom application key (Method 1, above), or as an action embedded in a map file filter (Method 2, above) - the choice is yours.

In either case, when you get to defining the sequence of operations that make up the action:

  1. Enter a name for the action, as previously.
  2. Press the New button to create a new operation.
  3. Choose the operation Call Script Function.
  4. When prompted, enter the name of the function in the script that you want to call. All the functions currently in the script will appear in a list, so you can just pick the Test function from this list instead of typing the full name.
  5. OK all the remaining dialogs to return to the application.

Test the key in the usual way.

Advantages

The advantage of this method is that it allows you to benefit from a fully featured programming language, allowing you to make more complex decisions, use a wider range of commands and perform detailed queries on the application or the access software.

4. Use System.RegisterScriptKey in a script to call a script function.

This method uses scripting alone.

Method

  1. Open the access software control panel and from the Map menu choose Map File Management.
  1. Press the Create Script or Edit Script button as appropriate.

This calls up the Script Editor where you can write your script code.

  1. Write the Test function, as shown in Method 3, above. The code is exactly the same.
  2. If the script does not yet contain an EventScriptStartup function, add one as shown below. If it does, then add the System.RegisterScriptKey line as shown:

function EventScriptStartup()

System.RegisterScriptKey(KEY_T, MODIFIER_CUSTOM, "Test", "Test function")

end

  1. Save the script and exit the Script Editor to return to the Control Panel.
  2. Close the remaining dialogs to return to the application.

Test the hot key in the usual way. As shown, the hot key will be the Dolphin key + T.

Advantages

This method has all the advantages of method 3, above, using the scripting language to perform the task but also has the advantage that it does not require any modifications to the map file. This means that this technique is equally usable for the main script file or any extension scripts.

The disadvantage is that currently, keys defined with the script function System.RegisterScriptKey cannot be discovered in Key Describe mode. A user also cannot change them without editing the script itself.

Note that, in common with the other methods discussed above, the key press is passed to the script first, before it is passed to the application.

We recommend that any keys that may change in different language versions of the access software should be defined in a script prompt file and these prompts be used to register the key, rather than hard-coding the key constant in the script. For details, see the Scripting Manual.

5. Use EventApplicationKeyPress in script to call a script function.

This method uses scripting alone.

Method

  1. Open the Control Panel and the script editor as described in Method 4, above.
  1. Enter the Test function as shown in Method 3 above. The code is exactly the same.
  2. Enter the following event function:

function EventApplicationKeyPress (scancode, modifier)

if scancode == KEY_T and modifier == MODIFIER_CUSTOM then

Test()

return EVENT_HANDLED

end

return EVENT_PASS_ON

end

  1. If you still have the EventScriptStartup function from Method 4, remove it so that the registered hot key from Method 4 will no longer be operational.
  2. Save the script and exit the editor to return to the Control Panel.
  3. Close the remaining dialogs to return to the application.

Test the script as before. The hot key is the Dolphin Key + T.

Advantages

Again we have the advantages of scripting, but this method might be useful in particular situations when you need to monitor for a wide range of keys where registering dozens of hot keys would not be appropriate.

This method also lets the key press through to the application itself before calling the script. You can therefore check to see what has happened onscreen as a result of pressing the key.

The disadvantage is that keys handled in this way cannot be discovered in Key Describe mode. Again we recommend, if necessary, that such keys are defined in the script prompt file so they can be changed on a per language basis.

Top View