WindowManager Keyboard Input And Text Handling

WindowManager

» Technical Details

» Keyboard Input and Text handling

Overview

An application using the Wimp should always perform all of its input handling using the Wimp_Poll routine, rather than the older OS_ReadC or OS_Byte calls directly.

Input Focus

Only one window within the Wimp can have the input focus at any given time. In other words, only one window will accept user input via the keyboard. The term used for this is input focus.

The window with input focus should be highlighted so that it is easy for the user to see which window has the focus. This is usually achieved by a highlighted Title Bar, and a caret to show the current input focus position in the window’s work area or icon, whichever has the focus.

A window can gain the input focus by the following methods.

Notification

The Wimp notifies applications when windows gain and lose focus using the Gain_Caret and Lose_Caret respectively. This allows for an application to respond to the change in caret position. It also is very important if an application is drawing its own caret and not relying on the Wimp’s caret.

Key Presses

The Wimp handles the majority of key presses if a writeable icon has the focus. The left and right cursor keys work as expected and the text, caret position and index are all updated. Other key presses, and all keys pressed while the input focus is not in a writeable icon must be managed by the application.

Notification

The Wimp notifies applications about key presses through the Key_Pressed event code via Wimp_Poll.

The Wimp provides information about the keys pressed as well as the standard Wimp caret.

It is the responsibility of the application to decide what actions to perform based on the keys pressed. i.e. pressing on the down cursor key, usually means to moves focus to the next item within the window.

Function Keys and Hot Keys

Function keys and ‘hot’ keys must be handled by the application itself. They are reported via the standard notification (see above), but are passed as special codes with bit 8 set.

Applications should pass the value of unknown or unwanted function and hot keys back to the Wimp using Wimp_ProcessKey so that other applications (that have bit 12 of its Window Flags) can deal with the key press if they so desire. They are called in the order they appear in the window stack, top most first.

An application should return via Wimp_Poll once it has carried out any actions.

Notes:

• If a function key is passed back to the Wimp and the input focus is a writeable icon, then the Wimp will expand the function key definition and insert as much as possible of the string into the icon
• Function key F12 and any key-press combination is reserved by RISC OS, so applications must not respond to this key press
• If an applications purpose is to grab hot keys, bit 6 of Window Flags should be set so that the window can be displayed off screen.

Special Characters

Special key combinations can be created by the use of the Alt key. The use of these combinations is common within international keyboards. To ensure that these combinations are permitted, applications should allow for the use of the top-bit-set characters.

Escape Key

As the Wimp continually loops round Wimp_Poll, applications can easily detect if the escape has been pressed by checking for the escape button character code 27 (&1B). However, if an application is to perform an action that will take a considerable amount of time then another option is available.

Handling Escape Keys Manually

If an application is going to perform an action that will take a considerable amount of time before it calls Wimp_Poll, then it may be wise to enable its own Escape key trapping.

Note: It is important that an application disable Escape key trapping before it calls Wimp_Poll.

It is also a good idea to display the mouse pointer as an hourglass during actions that will take a considerable amount of time, as the user is less likely to interrupt if progress is visible. You should not, however, attempt to change the pointer while the hourglass is still showing.

Upon an application closing down via Wimp_CloseDown, the Wimp restores the Escape key to its previous state, along with all other settings changed by the application. i.e. cursor keys, function keys etc…

See also

• Gain_Caret
• Key_Pressed
• Lose_Caret
• OS_Byte
• OS_Byte 124
• OS_ReadC
• Wimp_CloseDown
• Wimp_Poll
• Wimp_ProcessKey
• Wimp_SetCaretPosition
• Window Flags

RISC OS has many guidelines on the appropriate use of Keys presses and Character handling. For a complete detailed guide, please see the RISC OS Style Guide.