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
|
.. _user-input:
User Input
==========
All input from the user is parsed by a display module, and returned from either
the :meth:`get_input` or :meth:`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` or :meth:`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
--------------
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 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 at (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.
.. vim: set ft=rst fenc=utf-8:
|
