User Input

All input from the user is parsed by a display module, and returned from either the get_input() or get_input_nonblocking() methods as a list. Window resize events are also included in the user input.

The MainLoop class will take this input and pass each item to the widget methods keypress() or 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 MainLoop constructor. If the window was resized 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 text encoding you will also receive Unicode strings for any non-ASCII characters:

Key pressed

Input returned

é

u'é'

Ж

u'Ж'

カ

u'カ'

With non-Unicode text encoding 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 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 [1]

5

Scroll wheel down [1]

'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.