[[!redirects The Window Manager Keyboard Input And Text Handling]] h6. [[WindowManager]] h6(. » [[WindowManager Technical Details|Technical Details]] h6((. » Keyboard Input and Text handling h2(#overview). 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|OS_ReadC]] or [[OS_Byte|OS_Byte]] calls directly. h2(#input_focus). 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. |_<^. # |_<^. 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|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. | h4. Notification The Wimp notifies applications when windows gain and lose focus using the [[Gain_Caret|Gain_Caret]] and [[Lose_Caret|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. h2(#key_presses). 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. h4. Notification The Wimp notifies applications about key presses through the [[Key_Pressed|Key_Pressed]] event code via [[Wimp_Poll|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. h2(#function_keys_and_hot_keys). 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|Wimp_ProcessKey]] so that other applications (that have bit 12 of its [[Window Flags|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|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|Window Flags]] should be set so that the window can be displayed off screen. h2(#special_characters). 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. h2(#escape_key). Escape Key As the Wimp continually loops round [[Wimp_Poll|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. h4. 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|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|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|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… h4. See also * [[Gain_Caret|Gain_Caret]] * [[Key_Pressed|Key_Pressed]] * [[Lose_Caret|Lose_Caret]] * [[OS_Byte|OS_Byte]] * [[OS_Byte 124]] * [[OS_ReadC|OS_ReadC]] * [[Wimp_CloseDown|Wimp_CloseDown]] * [[Wimp_Poll|Wimp_Poll]] * [[Wimp_ProcessKey|Wimp_ProcessKey]] * [[Wimp_SetCaretPosition|Wimp_SetCaretPosition]] * [[Window Flags|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|Style Guide]]. [linkStyle]Style+Guide