Enabling keyboard support in projects

Users frequently interact with host applications using special keys on the physical keyboard, such as F1, Attn, Reset, and Clear. There are two different ways in which the end users of your HATS projects 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 a keypad--a graphical table of HTML buttons or links that represent keys on the physical keyboard. The end user clicks on the desired key in the keypad to send that 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 end users.

To use keyboard support in HATS projects, have a supported Web browser. For a list supported Web browsers and limitations, refer to HATS Getting Started

Note:

In earlier versions of HATS, Ctrl+R was used in bidirectional sessions to reverse the screen. In HATS V6 Ctrl+R is mapped to a host RESET for both bidirectional and non-bidirectional sessions, and Alt+Enter is mapped to reverse for bidirectional sessions.

Defining keyboard support

To configure keyboard support in a HATS project, you need to enable keyboard support in your project. Keyboard support can be enabled by going to the Other tab of your Project Settings and selecting the available options. For more information, see Keyboard support

You will also need to define the host keypad as well as which application keypad keys to include. See Application keypad and Host keypad for more information.

Changing the appearance of the keypads

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

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

The cascading style sheet defines seven 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

Providing documentation for end users

To facilitate use of your HATS project, we recommend that you document the keyboard settings for your end 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 4

• How the Enter key works with 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 for using keyboard support, refer to HATS Getting Started

Table 4. Key mapping in HATS

Button on button bar	Default physical key mapping
F1 - F12	F1 - F12
F13 - F24	Shift + F1 - F12
ENTER	Enter
CLEAR	Esc
RESET	Ctrl + R
SYSREQ	Shift + Esc
ATTN	Pause/Break
PAGEUP	Page Up
PAGEDN	Page Down
PA1	Alt + Delete
PA2	Alt + End
PA3	Alt + Page Down
PRINT	Ctrl + P
HELP	Ctrl + H
Enable/disable keyboard	Ctrl + K
Default	Alt + Insert
Refresh	Alt + Page Up
Reset HTML Form	Ctrl + S
Disconnect	Ctrl + D
View print jobs	Ctrl + J
Reverse	Alt + Enter
Field Exit	Ctrl + Enter
Field+	Ctrl + Plus
Field-	Ctrl + Minus

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 web browser client. Therefore, this guide references Host On-Demand documentation for key mnemonics which may be sent to the host computer to represent the user pressing keys in the host session.

In every HATS application is a file called KBS.js which determines how the keycode values generated by the users keyboard are mapped to key signals sent to the host session. You will edit the KBS.js file and then rebuild your HATS application to remap the HATS keyboard. 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 HOD 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 application, you can change or add combinations so new or existing keys send the mnemonic keyword. Note that to remap keys in HATS, you only need to modify the keycode and defaultKeyMappings variables at the top of the KBS.js file.

Note:

There are dependencies between the keys listed in the KBS.js file, the Keyboard Support state of the Project Settings, and the presence or absence of any key buttons listed on the screen. The rules governing these dependencies are listed below.

1. Keyboard support can be determined at a project-level setting to choose 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 Project 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 Project 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.

If you consider remapping some of the keys on your keyboard (browser keyboard support), be aware that you cannot remap the Ctrl, Alt, and Shift keys. HATS uses JavaScript and JavaScript does not consider these keys to be keypresses, but rather modifiers.

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>

Determining mnemonic keywords

:

HATS-supported 3270 mnemonic keyword table

Table 5. 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 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]
Field exit	[fldext]
Field+	[field+]
Field-	[field-]
Help	[help]
PA1	[home]
PA2	[pa1]
PA3	[pa2]
System Request	[pa3]
Page Up	[pageup]
Page Down	[pagedn]
Reset	[reset]
System Request	[sysreq]
Test Request	[test]

Example

The following is an example on 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 shown below.

Specifying the key combination that sends the host key

Modify the KBS.js file by adding the lines specified in bold and 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]'      ]
 ];

Note:

The name given to any new keycode variable (CODE_HOSTHOME in this example) is not important except that it be unique and match the corresponding entry in the defaultKeyMappings variable list. Also note in this example that adding a new keycode variable for the Home key is not actually necessary since the

var CODE_HOME = 36;

entry already exists for the Home key's keycode. However, if you are mapping a keyboard key that is not associated with a keycode variable already defined in KBS.js, such an entry would be necessary.

Adding additional keypad buttons to a transformation

You can add a new button or link into the default Host Keypad with the Project Settings. The control for this is 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 JSP using the Insert Individual Host Key item from the HATS Tools menu when editing the JSP. 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, add it to the KBS.js defaultKeyMappings table as shown above.