1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
.. vim: set fileencoding=utf-8:
.. _user-input:
**************
User Input
**************
.. currentmodule:: urwid
All input from the user is parsed by a display module, and returned from either
the :meth:`get_input() <raw_display.Screen.get_input>` or
:meth:`get_input_nonblocking() <raw_display.Screen.get_input_nonblocking>` methods as a list.
Window resize events are also included in the user input.
The :class:`MainLoop` class will take this input and pass each
item to the widget methods :meth:`keypress() <Widget.keypress>` or
:meth:`mouse_event() <Widget.mouse_event>`. You may
filter input (possibly removing or altering it) before it is passed to the
widgets, or can catch unhandled input by passing functions into the
:class:`MainLoop` constructor. If the window was resized
:class:`MainLoop` will query the new display size and update
the screen.
There may be more than one keystroke or mouse event processed at a time, and
each is sent as a separate item in the list.
.. _keyboard-input:
Keyboard Input
==============
Not all keystrokes are sent by a user's terminal to the program, and which keys
are sent varies from terminal to terminal, but Urwid will report any keys that
are sent.
============= =================
Key pressed Input returned
============= =================
H ``'h'``
SHIFT+H ``'H'``
SPACE ``' '``
ENTER ``'enter'``
UP ``'up'``
PAGE DOWN ``'page down'``
F5 ``'f5'``
SHIFT+F5 ``'shift f5'``
CTRL+SHIFT+F5 ``'shift ctrl f5'``
ALT+J ``'meta j'``
============= =================
With Unicode :ref:`text encoding <text-encodings>` you will also receive
Unicode strings for any non-ASCII characters:
=========== ==============
Key pressed Input returned
=========== ==============
é ``u'é'``
Ж ``u'Ж'``
カ ``u'カ'``
=========== ==============
With non-Unicode :ref:`text encoding <text-encodings>` characters will be sent
as-is in the original encoding.
=========== =========================================
Key pressed Input returned (each in its own encoding)
=========== =========================================
é ``'é'``
Ж ``'Ж'``
カ ``'カ'`` (two bytes)
=========== =========================================
Urwid does not try to convert this text to Unicode to avoid losing any
information. If you want the input converted to Unicode in all cases you may
create an input filter to do so.
.. _mouse-input:
Mouse Input
===========
Mouse input is sent as a (*event*, *button*, *x*, *y*) tuple. *event* is a string
describing the event. If the *SHIFT*, *ALT* or *CTRL* keys are held when a mouse
event is sent then *event* may be prefixed by ``'shift '``, ``'meta '`` or
``'ctrl'``. *button* is a number from 1 to 5. *x* and *y* are character
coordinates starting from ``(0, 0)`` at the top-left of the screen.
Support for the right-mouse button and use of modifier keys is poor in many
terminals and some users don't have a middle mouse button, so these shouldn't
be relied on.
``'mouse press'`` Events
------------------------
A mouse button was pressed.
=============== ======================
`button` number Mouse button
=============== ======================
1 Left button
2 Middle button
3 Right button
4 Scroll wheel up [#first]_
5 Scroll wheel down [#first]_
=============== ======================
.. [#first] typically no corresponding release event is sent
``'mouse release'`` Events
--------------------------
Mouse release events will often not have information about which button was
released. In this case *button* will be set to 0.
``'mouse drag'`` Events
-----------------------
In the rare event that your user is using a terminal that can send these events
you can use them to track their mouse dragging from one character cell to the
next across the screen. Be aware that you might see *x* and/or *y* coordinates
one position off the screen if the user drags their mouse to the edge.
|
