NAME

IUP::Manual::06_HandlingKeyboard - Handling keyboard in IUP applications

IUP MANUAL

INTRODUCTION

This manual deals with keyboard handling in IUP based applications.

Keyboard

The application can control the focus using the functions GetFocus and SetFocus. When the focus is changed the application is notified trough the callbacks GETFOCUS_CB and KILLFOCUS_CB.

Keyboard navigation in the dialog uses the "Tab" and "Shilf+Tab" keys to change the keyboard focus from one control to another. The exception is when the focus is at a multiline IUP::Text control, to change focus the combination "Ctrl+Tab" must be used, because "Tab" is a valid input for the text. All IUP interactive controls have Tab stops, but the navigation order is related to the order the controls are placed in the dialog and can not be changed. The order is the same implemented by the functions NextField and PreviousField. To remove the Tab stop from a control use the CANFOCUS attribute.

Arrows can also be used for navigation between buttons and toggles. This is necessary because when an IUP::Toggle is inside an IUP::Radio the "Tab" keys will navigate only to the selected toggle.

In Windows, the focus feedback only appears after the user presses a key (except for the IUP::Text where the feedback is the caret). Before pressing a key if you click in a control the focus feedback will be NOT be shown although it will be in focus. IUP::Matrix and other additional controls will always show their focus feedback. In GTK and Motif the focus feedback is always shown for the control that has the focus.

Two keys are also important in keyboard navigation: "Enter" and "Esc". But they are only effective if the application register the attributes DEFAULTENTER and DEFAULTESC of the IUP::Dialog. These attributes configure buttons to be activated when the respective key is pressed. Again "Enter" is a valid key for the Multiline so the combination "Ctrl+Enter" must be used instead. If the focus is at a button then the Enter key will activate that button independent from the DEFAULTENTER attribute.

Usualy the application will process keyboard input in the IUP::Canvas using the KEYPRESS_CB callback. But there is also the K_ANY callback that can be used for all the controls, but it does not have control of the press state, it is called only when the key is pressed. Both callbacks use the key codification explained in Keyboard Codes. These codes are also used in the ACTION callbacks of IUP::Text and IUP::Multiline, and in shortcuts using the KEY attribute of IUP::Item and IUP::Submenu. Finally all the keyboard codes can be used as callback names to implement application hot keys.

Keyboard Codes

The table below shows the IUP codification of every key in the keyboard. Each key is represented by an integer value, defined in the "iupkey.h" file header, which should be included in the application to use the key definitions. These keys are used in K_ANY and KEYPRESS_CB callbacks to inform the key that was pressed in the keyboard.

IUP uses the US default codification this means that if you installed a keyboard specific for your country the key codes will be different from the real keys for a small group of keys. Except for the Brazilian ABNT keyboard which works in Windows and Linux. This does not affect the IUP::Text and IUP::Multiline text input.

Notice that somes key combinations are not available because they are restricted by the system.

  • IUP->isprint($key) function informs if a key can be directly used as a printable character

  • IUP->isXkey($key) function informs if a given key is an extended code

  • IUP->isShiftXkey($key) function informs if a given key is an extended code using the Shift modifier

  • IUP->isCtrlXkey($key) function for the Ctrl modifier

  • IUP->isAltXkey($key) function for the Alt modifier

  • IUP->isSysXkey($key) function for the Sys modifier

In the table bellow there are the most common definitions. Change the definition to K_s*, K_c*, K_m* and K_y* when the respective modifier is pressed (Shift, Control, Alt and Sys). Sys in Windows is the Windows key and in Mac is the Apple key. Check the "iupkey.h" file header for all the definitions. To detect the combination of two or more modifiers use global attribute "MODKEYSTATE".

Note: GTK in Windows does not generates the Win modifier key, the K_Print and the K_Pause keys (up to GTK version 2.8.18).

 KEY            KEYCODE CONSTANT (from IUP::Constants)
 -------------- ---------------------------------------
 Space          K_SP
 !              K_exclam
 "              K_quotedbl
 #              K_numbersign
 $              K_dollar
 %              K_percent
 &              K_ampersand
 '              K_apostrophe
 (              K_parentleft
 )              K_parentright
 *              K_asterisk
 +              K_plus
 ,              K_comma
 -              K_minus
 .              K_period
 /              K_slash
 0              K_0
 1              K_1
 2              K_2
 3              K_3
 4              K_4
 5              K_5
 6              K_6
 7              K_7
 8              K_8
 9              K_9
 :              K_colon
 ;              K_semicolon
 <              K_less
 =              K_equal
 >              K_greater
 ?              K_question
 @              K_at
 A              K_A
 B              K_B
 C              K_C
 D              K_D
 E              K_E
 F              K_F
 G              K_G
 H              K_H
 I              K_I
 J              K_J
 K              K_K
 L              K_L
 M              K_M
 N              K_N
 O              K_O
 P              K_P
 Q              K_Q
 R              K_R
 S              K_S
 T              K_T
 U              K_U
 V              K_V
 W              K_W
 X              K_X
 Y              K_Y
 Z              K_Z
 [              K_bracketleft
 \              K_backslash
 ]              K_bracketright
 ^              K_circum
 _              K_underscore
 `              K_grave
 a              K_a
 b              K_b
 c              K_c
 d              K_d
 e              K_e
 f              K_f
 g              K_g
 h              K_h
 i              K_i
 j              K_j
 k              K_k
 l              K_l
 m              K_m
 n              K_n
 o              K_o
 p              K_p
 q              K_q
 r              K_r
 s              K_s
 t              K_t
 u              K_u
 v              K_v
 w              K_w
 x              K_x
 y              K_y
 z              K_z
 {              K_braceleft
 |              K_bar
 }              K_braceright
 ~              K_tilde
 Esc            K_ESC
 Enter          K_CR
 BackSpace      K_BS
 Insert         K_INS
 Del            K_DEL
 Tab            K_TAB
 Home           K_HOME
 Up Arrow       K_UP
 PgUp           K_PGUP
 Left Arrow     K_LEFT
 Middle         K_MIDDLE
 Right Arrow    K_RIGHT
 End            K_END
 Down Arrow     K_DOWN
 PgDn           K_PGDN
 Pause          K_PAUSE
 Print Screen   K_Print
 Context Menu   K_Menu
 acute          K_acute
 cedilla        K_ccedilla
 F1             K_F1
 F2             K_F2
 F3             K_F3
 F4             K_F4
 F5             K_F5
 F6             K_F6
 F7             K_F7
 F8             K_F8
 F9             K_F9
 F10            K_F10
 F11            K_F11
 F12            K_F12