Command Map

class urwid.CommandMap

dict-like object for looking up commands from keystrokes.

Default values:

tab, ctrl n

'next selectable'

shift tab, ctrl p

'prev selectable'

ctrl l

'redraw screen'

esc

'menu'

up, down, left, right

'cursor up', 'cursor down', 'cursor left', 'cursor right'

page up, page down

'cursor page up', 'cursor page down'

home, end

'cursor max left', 'cursor max right'

space, enter

'activate'

Only containers created with select_navigation=True handle 'next selectable' and 'prev selectable', see Moving the Focus with Tab.

Edit also handles these readline-style commands, which no key is mapped to by default: 'cursor word left', 'cursor word right', 'cursor line start', 'cursor line end', 'delete word left', 'delete word right', 'delete space word left', 'delete char right', 'delete to start of line' and 'delete to end of line'. A word is a run of letters, digits and underscores, and a line ends at a newline. bind_readline() maps the usual readline keys to them. An Edit with an undo history handles 'undo' and 'redo', see Edit.undo_limit. An Edit with a kill buffer handles 'yank', see Edit.kill_buffer. An Edit with a text completer handles 'complete next' and 'complete previous', which no key is mapped to by default either; see Edit.text_completer. Tabs handles 'next tab' and 'previous tab', and no key is mapped to them by default.

• 'delete word left' stops at punctuation, as readline’s backward-kill-word (meta backspace) does, except that an underscore is part of a word here.

• 'delete space word left' deletes back to the previous whitespace, as bash’s ctrl w (unix-word-rubout) does.

• 'cursor line start', 'cursor line end', 'delete to start of line' and 'delete to end of line' work on lines that end at a newline. 'cursor max left' and 'cursor max right' move to the edge of the screen row instead, so on a wrapped line they stop earlier.

• 'delete char right' deletes the character under the cursor, as delete does.

>>> cm = CommandMap()
>>> cm.bind(Command.WORD_LEFT, "meta b")
>>> cm.bind(Command.DELETE_TO_LINE_START, "ctrl u")
>>> cm.bind(Command.COMPLETE_NEXT, "ctrl f")
>>> cm.bind(Command.NEXT_TAB, "meta right")

Initialize the command map with the class’s default key-to-command bindings.

bind(command: str | Command, *keys: str) → None

Bind keys to command, refusing a key that is already bound to a different command.

A key already bound to command is accepted. Item assignment (command_map[key] = command) remains the way to rebind a key on purpose.

>>> cm = CommandMap()
>>> cm.bind("quit", "q", "ctrl c")
>>> cm.bind("quit", "ctrl l")
Traceback (most recent call last):
...
ValueError: Key 'ctrl l' is already bound to 'redraw screen', cannot also bind it to 'quit'

Parameters:

• command – the command to bind.

• keys – keystrokes to bind to command, added to those it already has.

Raises:

ValueError – a key in keys is already bound to a different command; the command map is left unchanged.

bind_readline() → None

Bind the readline editing keys to the commands Edit handles.

keys	commands
ctrl a, ctrl e	'cursor line start', 'cursor line end'
meta b, meta f	'cursor word left', 'cursor word right'
meta backspace, meta d	'delete word left', 'delete word right'
ctrl u, ctrl k	'delete to start of line', 'delete to end of line'
ctrl w	'delete space word left'
ctrl d	'delete char right'
ctrl _	'undo'
ctrl y	'yank'

No other widget handles these commands, so the keys reach the containers above an Edit unchanged, and the shared command map can take them.

>>> cm = CommandMap()
>>> cm.bind_readline()
>>> cm["ctrl a"]
<Command.LINE_START: 'cursor line start'>
>>> cm["ctrl k"] = "kill"
>>> cm.bind_readline()
Traceback (most recent call last):
...
ValueError: Key 'ctrl k' is already bound to 'kill', cannot also bind it to 'delete to end of line'

Raises:

ValueError – one of the keys is already bound to a different command; the command map is left unchanged.

clear_command(command: str | Command) → None

Remove every keystroke currently mapped to command.

copy() → Self

Return a new copy of this CommandMap, likely so we can modify it separate from a shared one.

restore_defaults() → None

Reset the command map to the class’s default key-to-command bindings.