Showing changes from revision #6 to #7:
Added | Removed | Changed
An application using the Wimp should always perform all of its input handling using the Wimp_Poll routine, rather than the olderWimp_Poll routine, rather than the older OS_ReadC or OS_Byte calls directly.
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.
# | Description |
---|---|
1 | If the mouse pointer is clicked using Select or Adjust over a writeable icon. The caret is positioned and sized automatically by the Wimp. |
2 | By calling the Wimp_SetCaretPosition. The application has control of the caret settings. Positioning of the caret must be calculated using window position, scroll offsets and pointer position. |
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.
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.
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 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:
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.
h2(#escape Key). 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.
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.
Enable Escape Key | *FX 299,0 |
Disable Escape Key | *FX 229,1 then OS_Byte 124 |
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…
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.