Enabling keyboard support

Users frequently interact with host applications using special keys on the physical keyboard, such as F1, Attn, Reset, and Clear. There are different ways in which the users of your HATS applications can send keystrokes to the host:

• By pressing keys on the physical keyboard. The term keyboard support, as used in this chapter, refers to this activity.
• By using buttons or links for function keys that are rendered by HATS default rendering. The user clicks on the button or link to send a host key to the host.
• By using the host keypad or buttons or links you individually insert. The user clicks on the button or link to send a host key to the host.

This chapter explains how to define keyboard support in your HATS project and contains tips for documenting keyboard support for your users.

To use keyboard support in HATS Web projects, you must have a supported Web browser. For a list of supported Web browsers and limitations, see "System Requirements for Host Access Transformation Services" at http://www.ibm.com/support/docview.wss?uid=swg27011794 and "Host Access Transformation Services 9.7 - Known issues and workarounds" at http://www.ibm.com/support/docview.wss?uid=ibm10876092.

Defining keyboard support

If not enabled by default, you can enable keyboard support and select available options on the Other tab of your Project Settings. For more information, see Keyboard support.

You can also define a host keypad and an application keypad. See Host keypad and Application keypad for more information.

Changing the appearance of the keypads

For HATS Web projects, use the Host Keypad and Application Keypad settings on the Rendering tab of your Project Settings to define which keys to display and whether to display them as buttons or links. See Host keypad and Application keypad for more information.

To change the style of a keypad for a specific HATS Web project, change the cascading style sheet (.css file) that corresponds to the keypad. This will be the style sheet you are using when you build your project. In the Rational® SDP workbench, go to the HATS Projects view of the HATS Toolkit and expand the project name. Expand Web Content/Common/Stylesheets. For more information, see Using style sheets.

To modify the style sheet, double-click on the .css file to open the editor. Keep in mind that templates can override your style sheet changes. For more information about cascading style sheets, go to http://www.w3.org/Style/CSS/.

If not already defined, the style sheet can define any of the following HATS styles:

table.HostKeypad

Host keypad background

table.ApplicationKeypad

Application keypad background

input.HostPFKey

Host keypad PF buttons

input.HostButton

Host keypad buttons

input.ApplicationButton

Application keypad buttons

a.HostKeyLink

Host keypad links

a.ApplicationKeyLink

Application keypad links

For HATS rich client projects, use the Host Keypad settings on the Rendering tab of your Project Settings to define which keys to display and whether to display them as buttons or links. See Host keypad for more information. Use the Application Keypad settings on the Rendering tab of your Project Settings to define which application-level buttons to display. Use the Toolbar settings on the Rendering tab to define whether the application-level buttons will display text, an image, or both. See Application keypad and Toolbar  RCP-only  for more information.

Providing documentation for users

To facilitate use of your HATS application, you may want to document the keyboard settings for your users--either in the application's graphical user interface or in some other easily displayed form (perhaps a link in your template). Your documentation should describe:

• How to turn keyboard support on and off, using Turn Keyboard On/Off.
• The HATS keyboard mapping, as shown in Table 5.
• How the Enter key works with HATS tabbed folders. Keyboard support must be off when the user presses the Enter key to display the contents of a different tab, after using the Tab key to move to a new tab. If keyboard support is not turned off, the Enter key goes to the host.
• For a list of the required level of Web browsers and limitations for using keyboard support with HATS Web applications, see "System Requirements for Host Access Transformation Services" at http://www.ibm.com/support/docview.wss?uid=swg27011794 and "Host Access Transformation Services 9.7 - Known issues and workarounds" at http://www.ibm.com/support/docview.wss?uid=ibm10876092.

Special 5250 field key support

Default field keypress combinations

The default field keypress combinations for HATS Web applications are listed below. For information about how to remap the keyboard, see Remapping the keyboard in a HATS application.

• Quick Field Exit: Ctrl + Enter.
• Field Exit: Shift + Enter.
• Quick Field Minus: Shift + Numpad minus.
• Field Minus: Ctrl + Numpad minus.
• Field Plus: Ctrl + Numpad plus.

Quick Field Exit

The Quick Field Exit keypress can be used with HATS Web applications to speed the entry of numeric data for 5250 screens. This keypress clears the current field from the current caret position to end of the field, and advances the cursor position to the next field. Although this keypress can be used on any field, it is especially useful where users might otherwise use a Field Exit. A true Field Exit keypress sends the screen of data to the host and causes the HATS transformation to be redrawn. Therefore, screens requiring many Field Exit aids before being submitted may cause usability issues. The Quick Field Exit keypress, combined with the Field Exit Emulation feature, increases the speed of such applications considerably.

Because rich client applications have a different architecture than Web applications, a Quick Field Exit keypress in rich client applications is not necessary. There is no round-trip delay for a true Field Exit in rich client applications.

Quick Field Minus

The Quick Field Minus keypress can be used with HATS Web applications to speed the entry of negative numeric data for 5250 screens. This keypress clears the current field from the current caret position to end of the field, prepends the field value with a minus sign character (-), and advances the cursor position to the next field. Although this keypress can be used on any field, it is only useful on 5250 signed numeric fields where users might otherwise use a Field Minus. A true Field Minus keypress sends the screen of data to the host and causes the transformation to be redrawn. Therefore, screens requiring many Field Minus aids before being submitted may cause usability issues. The Quick Field Minus keypress, combined with the Alternate way to input negative numbers feature, increases the speed of such applications considerably. Using the Quick Field Minus keypress on fields other than 5250 signed numeric fields may cause improper data entry.

Because rich client applications have a different architecture than Web applications, a Quick Field Minus keypress in rich client applications is not necessary. There is no round-trip delay for a true Field Minus in rich client applications.

Alternate way to input negative numbers

To enter a negative number in a 5250 signed numeric field, users can enter a minus sign character (-) in the first position of the field, instead of using a Field Minus and incurring a round trip to the server. This allows for faster entry of large quantities of negative numbers into 5250 signed numeric fields. The HATS server emulates a Field Minus keypress for each 5250 signed numeric field entered with a leading minus sign character. Any unwanted prefilled data must be cleared from the field before tabbing to another field. Users should not enter a minus sign in the first position and also press Field Minus, Field Plus, or Field Exit.

Field Exit Emulation

This feature automatically supplies a Field Exit aid key for the user, when required. A Field Exit aid key is required when certain types of 5250 fields are modified.

For example, if a user is using the Quick Field Exit keypress to advance from field to field, and submits the screen with an Enter key or some other non-field aid key, a Field Exit might be required for the field containing the cursor when the screen is submitted.

In this case, if a required Field Exit is not supplied, the host might respond with the error message, Enter key not allowed in field. With this HATS feature, the HATS server sends a Field Exit to the host before sending the Enter, avoiding the error message.

If you want to disable this feature, add the following statements to the application.hap file:

<class name="com.ibm.hats.common.RuntimeSettings">
        <setting name="emulateFieldExit" value="false"/>
</class>

If there is already a <class> section by this name, just add the <setting> line inside the section.

Remapping the keyboard in a HATS application

Concepts to understand before remapping HATS keys

Every HATS application embeds code from the Host On-Demand product to handle the connection to the Telnet server on behalf of the client. Therefore, this guide uses Host On-Demand terminology for mnemonic keywords which may be sent to the host computer to represent the user pressing keys in the host session.

Mnemonic keywords

HATS-supported 3270 mnemonic keyword table

Table 6. Mnemonic Keywords for SendKeys

Function	Mnemonic Keyword
Attention	[attn]
Alternate View	[altview]
Clear	[clear]
Enter	[enter]
F1	[pf1]
F2	[pf2]
F3	[pf3]
F4	[pf4]
F5	[pf5]
F6	[pf6]
F7	[pf7]
F8	[pf8]
F9	[pf9]
F10	[pf10]
F11	[pf11]
F12	[pf12]
F13	[pf13]
F14	[pf14]
F15	[pf15]
F16	[pf16]
F17	[pf17]
F18	[pf18]
F19	[pf19]
F20	[pf20]
F21	[pf21]
F22	[pf22]
F23	[pf23]
F24	[pf24]
Home	[home]
PA1	[pa1]
PA2	[pa2]
PA3	[pa3]
Reset	[reset]
System Request	[sysreq]

HATS-supported 5250 mnemonic keyword table

Table 7. Mnemonic Keywords for SendKeys

Function	Mnemonic Keyword
Attention	[attn]
Alternate View	[altview]
Clear	[clear]
Enter	[enter]
F1	[pf1]
F2	[pf2]
F3	[pf3]
F4	[pf4]
F5	[pf5]
F6	[pf6]
F7	[pf7]
F8	[pf8]
F9	[pf9]
F10	[pf10]
F11	[pf11]
F12	[pf12]
F13	[pf13]
F14	[pf14]
F15	[pf15]
F16	[pf16]
F17	[pf17]
F18	[pf18]
F19	[pf19]
F20	[pf20]
F21	[pf21]
F22	[pf22]
F23	[pf23]
F24	[pf24]
Field Exit	[fldext]
Field+	[field+]
Field-	[field-]
Help	[help]
PA1	[pa1]
PA2	[pa2]
PA3	[pa3]
System Request	[sysreq]
Page Up	[pageup]
Page Down	[pagedn]
Quick Field Exit	[qfldext]
Quick Field Minus	[qfld-]
Reset	[reset]
System Request	[sysreq]
Test Request	[test]

Determining keycode values

To determine the keycode value for a given key on the keyboard, save the following HTML code in a file and open it in an Internet Explorer browser window. The keycode value is displayed for any key pressed in that browser.

<html>
<head>
<script>
document.onkeydown = keydownhandler;
function keydownhandler()
{
	document.testform.displayField.value = "Keycode: " + window.event.keyCode;
}
</script>
</head>
<body>
	<center>
		<form name="testform">
			<input type="text" name="displayField" value="Hit any key">
		</form>
	</center>
</body>
</html>

Remapping keys for HATS Web applications

In every HATS Web application is a file named KBS.js which determines how the keycode values generated by the users keyboard are mapped to key signals sent to the host session. To remap the HATS keyboard, you must edit the KBS.js file. To locate KBS.js, go to the Navigator view then look in the project_name/Web Content/Common directory. There are three values in KBS.js which determine the relationship between any key on the keyboard being pressed and what signal is then sent to the host. These three values are:

1. The keycode value for the pressed key, represented as an integer variable in the KBS.js file. For example,

   var CODE_F2 = 113; 

   for the F2 key,
2. The combination of the keycode value and the Alt, Ctrl, and Shift states of the keyboard, and
3. The Host On-Demand mnemonic keyword sent for the keycode combination value and Alt, Ctrl, and Shift states. For example,

   [CODE_F2, 0, 0, 0, '[pf2]']

   sends the pf2 key signal to the host when the F2 key is pressed on the user's keyboard.

To change key mappings in your HATS Web application, you can change or add combinations allowing new or existing keys to send the mnemonic keyword.

To remap keys in HATS Web applications, you only need to modify the keycode and defaultKeyMappings variables at the top of the KBS.js file.

1. Keyboard support can be set using project-level settings to specify whether it should follow HATS V5, or earlier, rules or if it should support all mapped keys, regardless of what buttons or links are displayed. To modify these settings, go to the HATS Projects view and double click the Project Settings of your HATS project, select the Other tab and click Keyboard Support. For more information, see Keyboard support.
2. By default, HATS shows the application keypad but does not display the host keypad. In order for HATS to display the host keypad, you need to go to the HATS Projects view and double click the Project Settings of your HATS project, select the Rendering tab and click Host Keypad. You will then have the option of enabling the check box to display the host keypad as well as selecting which keys to display.

Example

The following example shows how to map the Ctrl+Home key combination on the keyboard. To send the Home key to the host session and also place a button for this function in your transformation, two steps are required: Edit KBS.js and then modify your transformation as described in Adding additional keypad buttons to a transformation.

To specify the key combination that sends the host key, modify the KBS.js file by adding the lines specified in bold italic below:

var CODE_BACKSPACE = 8;
 var CODE_TAB       = 9;
 var CODE_ENTER     = 13;
 var CODE_PAUSE     = 19;
 var CODE_ESC       = 27;
 var CODE_PAGEUP    = 33;
 var CODE_PAGEDOWN  = 34;
 var CODE_END       = 35;
 var CODE_HOME      = 36;
 var CODE_INSERT    = 45;
 var CODE_DELETE    = 46;
 var CODE_A         = 65;
 var CODE_B         = 66;
 var CODE_C         = 67;
 var CODE_D         = 68;
 var CODE_E         = 69;
 var CODE_F         = 70;
 var CODE_G         = 71;
 var CODE_H         = 72;
 var CODE_I         = 73;
 var CODE_J         = 74;
 var CODE_K         = 75;
 var CODE_L         = 76;
 var CODE_M         = 77;
 var CODE_N         = 78;
 var CODE_O         = 79;
 var CODE_P         = 80;
 var CODE_Q         = 81;
 var CODE_R         = 82;
 var CODE_S         = 83;
 var CODE_T         = 84;
 var CODE_U         = 85;
 var CODE_V         = 86;
 var CODE_W         = 87;
 var CODE_X         = 88;
 var CODE_Y         = 89;
 var CODE_Z         = 90;
 var CODE_HOSTHOME = 36;
 var CODE_F1        = 112;
 var CODE_F2        = 113;
 var CODE_F3        = 114;
 var CODE_F4        = 115;
 var CODE_F5        = 116;
 var CODE_F6        = 117;
 var CODE_F7        = 118;
 var CODE_F8        = 119;
 var CODE_F9        = 120;
 var CODE_F10       = 121;
 var CODE_F11       = 122;
 var CODE_F12       = 123;
 var HostKey        =1;
 var ApplicationKey =2;
/***********************************************************
 * NOTICE: DO NOT MODIFY THE ABOVE VARIABLES!!
 ***********************************************************/

 var defaultKeyMappings = [
 // KEYCODE,       ALT, CTRL, SHIFT, MNEMONIC
 //============ command key mappings ================
   [CODE_ENTER,      0,    0,     0, '[enter]'     ],
   [CODE_PAUSE,      0,    0,     0, '[attn]'      ],
   [CODE_ESC,        0,    0,     0, '[clear]'     ],
   [CODE_ESC,        0,    0,     1, '[sysreq]'    ],
   [CODE_PAGEUP,     0,    0,     0, '[pageup]'    ],
   [CODE_PAGEUP,     1,    0,     0, 'refresh'     ],
   [CODE_PAGEDOWN,   0,    0,     0, '[pagedn]'    ],
   [CODE_HOSTHOME, 0,    1,     0, '[home]'    ],
   [CODE_PAGEDOWN,   1,    0,     0, '[pa3]'       ],
   [CODE_END,        1,    0,     0, '[pa2]'       ],
   [CODE_INSERT,     1,    0,     0, 'default'     ],
   [CODE_DELETE,     1,    0,     0, '[pa1]'       ],
   [CODE_D,          0,    1,     0, 'disconnect'  ],
   [CODE_H,          0,    1,     0, '[help]'      ],
   [CODE_P,          0,    1,     0, '[printhost]' ],   
   [CODE_J,          0,    1,     0, 'printjobs'   ],
   [CODE_ENTER,      1,    0,     0, 'reverse'     ],   
   [CODE_K,          0,    1,     0, 'toggle'      ],
   [CODE_S,          0,    1,     0, 'ResetButton' ],   
 //============ function key mappings ===============
   [CODE_F1,         0,    0,     0, '[pf1]'       ],
   [CODE_F1,         0,    0,     1, '[pf13]'      ],
   [CODE_F2,         0,    0,     0, '[pf2]'       ],
   [CODE_F2,         0,    0,     1, '[pf14]'      ],
   [CODE_F3,         0,    0,     0, '[pf3]'       ],
   [CODE_F3,         0,    0,     1, '[pf15]'      ],
   [CODE_F4,         0,    0,     0, '[pf4]'       ],
   [CODE_F4,         0,    0,     1, '[pf16]'      ],
   [CODE_F5,         0,    0,     0, '[pf5]'       ],
   [CODE_F5,         0,    0,     1, '[pf17]'      ],
   [CODE_F6,         0,    0,     0, '[pf6]'       ],
   [CODE_F6,         0,    0,     1, '[pf18]'      ],
   [CODE_F7,         0,    0,     0, '[pf7]'       ],
   [CODE_F7,         0,    0,     1, '[pf19]'      ],
   [CODE_F8,         0,    0,     0, '[pf8]'       ],
   [CODE_F8,         0,    0,     1, '[pf20]'      ],
   [CODE_F9,         0,    0,     0, '[pf9]'       ],
   [CODE_F9,         0,    0,     1, '[pf21]'      ],
   [CODE_F10,        0,    0,     0, '[pf10]'      ],
   [CODE_F10,        0,    0,     1, '[pf22]'      ],
   [CODE_F11,        0,    0,     0, '[pf11]'      ],
   [CODE_F11,        0,    0,     1, '[pf23]'      ],
   [CODE_F12,        0,    0,     0, '[pf12]'      ],
   [CODE_F12,        0,    0,     1, '[pf24]'      ]
 ];

var CODE_HOME = 36;

Remapping keys for HATS rich client applications

In the rich client environment, default keyboard mappings are defined in the plugin.xml file of the HATS RCP Runtime Extension plug-in and apply to all HATS rich client applications running in the same environment.

An Eclipse keyboard context is used to influence what commands are available to the user at any given moment. When a user is using a HATS transformation view, the HATS keyboard context is used. This context is registered in the plugin.xml file of the HATS RCP Runtime Extension plug-in. The following example shows how this appears:

<extension 
      point="org.eclipse.ui.contexts">
   <context
         name="%KEYBOARD_CONTEXT_NAME"
         description="%KEYBOARD_CONTEXT_NAME"
         id="com.ibm.hats.rcp.transformationContext"
         parentId="org.eclipse.ui.contexts.window">
   </context>
</extension>

The default keyboard mappings are also defined in the plugin.xml file. The following example shows how a key mapping for a HATS application running in Eclipse RCP or Lotus® Expeditor appears in this file:

<extension
      point="org.eclipse.ui.commands">
   <category
         name="%COMMAND_CATEGORY_NAME"
         description"%COMMAND_CATEGORY_NAME"
         id="com.ibm.hats.rcp.transformationCategory"
   </category>
   <command
         name="[pf1]"
         category="com.ibm.hats.rcp.transformationCategory"
         id="com.ibm.hats.rcp.send_[pf1]">
   </command>
     ...
 </extension>

<extension
      point="org.eclipse.ui.bindings">
   <key
         commandId="com.ibm.hats.rcp.send_[pf1]"
         contextId="com.ibm.hats.rcp.transformationContext"
         configuration="org.eclipse.ui.defaultAcceleratorConfiguration"
         sequence="F1"
   </key>
     ...
 </extension>

The key bindings for running in Lotus Notes® are separate from the other key bindings. The equivalent key binding for the previous example would be:

   <key
         commandId="com.ibm.hats.rcp.send_[pf1]"
         contextId="com.ibm.hats.rcp.transformationContext"
         schemeId="com.ibm.workplace.notes.hannoverConfiguration"
         sequence="F1"
   </key>

Example

The following example shows how to map the Ctrl+Home key combination on the keyboard for a rich client application running in Eclipse RCP or Lotus Expeditor. First, add the command tag for [home], and key tag for Ctrl+Home, to the plugin.xml file in the HATS RCP Runtime Extension plug-in as shown below:

<extension
      point="org.eclipse.ui.commands">
     ...
   <command
         name="[home]"
         category="com.ibm.hats.rcp.transformationCategory"
         id="com.ibm.hats.rcp.send_[home]">
   </command>
     ...
 </extension>

<extension
      point="org.eclipse.ui.bindings">
     ...
   <key
         commandId="com.ibm.hats.rcp.send_[home]"
         contextId="com.ibm.hats.rcp.transformationContext"
         configuration="org.eclipse.ui.defaultAcceleratorConfiguration"
         sequence="Ctrl+Home"
   </key>
     ...
 </extension>

Next, update the transformation view code so that the view is aware that a new key mapping is registered in the plugin.xml file. To do this, edit the MainView.java file in your project. This file is located in the \Source\<project name>\views folder under your project in the HATS Projects view. Double-click on the MainView.java file to open it in the editor. Add the createKeyboardActions method following the MainView method as shown below:

protected void createKeyboardActions() {
    super.createKeyboardActions();
    addKeyboardAction("[home]", "com.ibm.hats.rcp.send_[home]");
}

You can provide a way for your users to configure the default Eclipse keyboard preferences. This is normally configured from the menu bar using Window > Preferences > Workbench > Keys. If you provide this for your users, they will be able to override the key mappings defined in the HATS RCP Runtime Extension plug-in.

Adding additional keypad buttons to a transformation

You can add a new button or link into the default Host Keypad. The control for this is in Project Settings on the Rendering tab, Host Keypad settings. The new button or link will appear whenever the default Host Keypad is used. You can add a new button or link to a single transformation using the Insert Host Keypad > Individual Key function when editing the transformation. See Individual Key for more information. The GUI for adding your own button or link requires a Caption and a Mnemonic. In this example, the Caption is Home, and the Mnemonic is [home]. If you want keyboard support for this new button, you must add it to the KBS.js defaultKeyMappings table (for Web applications) or the plugin.xml file of the HATS RCP runtime extension plug-in (for rich client applications).