NAME
IUP::Manual::06_HandlingKeyboard - Handling keyboard in IUP applications
IUP MANUAL
IUP::Manual::06_HandlingKeyboard <<< this document
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 characterIUP->isXkey($key)function informs if a given key is an extended codeIUP->isShiftXkey($key)function informs if a given key is an extended code using the Shift modifierIUP->isCtrlXkey($key)function for the Ctrl modifierIUP->isAltXkey($key)function for the Alt modifierIUP->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