=pod
=head1 NAME
IUP::Manual::06_HandlingKeyboard - Handling keyboard in IUP applications
=head1 IUP MANUAL
=over
=item * L<IUP::Manual::01_Introduction|IUP::Manual::01_Introduction>
=item * L<IUP::Manual::02_Elements|IUP::Manual::02_Elements>
=item * L<IUP::Manual::03_Attributes|IUP::Manual::03_Attributes>
=item * L<IUP::Manual::04_Callbacks|IUP::Manual::04_Callbacks>
=item * IUP::Manual::06_HandlingKeyboard E<nbsp>E<nbsp>E<nbsp>E<nbsp>E<nbsp> B<E<lt>E<lt>E<lt> this document>
=item * L<IUP::Manual::05_DialogLayout|IUP::Manual::05_DialogLayout>
=item * L<IUP::Manual::07_UsingImageLibrary|IUP::Manual::07_UsingImageLibrary>
=back
=head1 INTRODUCTION
This manual deals with keyboard handling in IUP based applications.
=head1 Keyboard
The application can control the focus using the functions
L<GetFocus|IUP/"GetFocus()"> and L<SetFocus|IUP::Manual::02_Elements/"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 L<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 L<NextField|IUP::Manual::02_Elements/"NextField()"> and L<PreviousField|IUP::Manual::02_Elements/"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 L<IUP::Toggle|IUP::Toggle> is inside an L<IUP::Radio|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 L<IUP::Text|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. L<IUP::Matrix|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 L<IUP::Dialog|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 L<IUP::Canvas|IUP::Canvas>
using the L<KEYPRESS_CB|elem/iupcanvas.html#Callbacks> callback. But
there is also the L<K_ANY|call/iup_k_any.html> 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 L<Keyboard Codes|attrib/key.html>.
These codes are also used in the ACTION callbacks of L<IUP::Text|IUP::Text> and
L<IUP::Multiline|IUP::Multiline>, and in shortcuts using the KEY attribute of L<IUP::Item|IUP::Item>
and L<IUP::Submenu|IUP::Submenu>. Finally all the keyboard codes can be used as
callback names to implement application hot keys.
=head1 B<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
L<IUP::Text|IUP::Text> and L<IUP::Multiline|IUP::Multiline> text input.
Notice that somes key combinations are not available because they are
restricted by the system.
=over
=item * C<IUP-E<gt>isprint($key)> function informs if a key can be directly used as a printable character
=item * C<IUP-E<gt>isXkey($key)> function informs if a given key is an extended code
=item * C<IUP-E<gt>isShiftXkey($key)> function informs if a given key is an extended code using the Shift modifier
=item * C<IUP-E<gt>isCtrlXkey($key)> function for the Ctrl modifier
=item * C<IUP-E<gt>isAltXkey($key)> function for the Alt modifier
=item * C<IUP-E<gt>isSysXkey($key)> function for the Sys modifier
=back
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
=cut