keys.rst 10 KB
Newer Older
mathieui's avatar
mathieui committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
.. _keys-page:

Keys
====

This file describes the default keys of poezio and explains how to
configure them.

By default, most keys manipulating the input (where you type your
messages and commands) behave like emacs does.

.. note:: Keys are case sensitive. Ctrl-X is not the same than Ctrl-x

Key bindings listing
--------------------
Some key bindings are available only in some tabs, others are global.

mathieui's avatar
mathieui committed
18 19
.. _global-keys:

mathieui's avatar
mathieui committed
20 21 22 23
Global keys
~~~~~~~~~~~
These keys work in **any** tab.

mathieui's avatar
mathieui committed
24
**Ctrl-p** or **F5**: Go to the previous tab.
mathieui's avatar
mathieui committed
25

mathieui's avatar
mathieui committed
26
**Ctrl-n** or **F6**: Go to the next tab.
mathieui's avatar
mathieui committed
27 28 29 30 31 32 33 34 35 36

**Alt-number**: Go to the tab with that number.

**Alt-j**: Waits for you to type a two-digits number. Go to tab number xx.

**Alt-e**: Go to the tab with a higher priority (private message >
highlight > message > non-empty input).

**Alt-z**: Go to the previously selected tab.

mathieui's avatar
mathieui committed
37
**Alt-r**: Go to the contact list tab.
mathieui's avatar
mathieui committed
38

mathieui's avatar
mathieui committed
39 40
**F4**: Toggle the left pane.

mathieui's avatar
mathieui committed
41 42 43 44 45 46 47 48 49 50
**F7**: Shrink the information buffer.

**F8**: Grow the information buffer.

**Ctrl-l**: Refresh the screen.

**Alt-D**: Scroll the information buffer up.

**Alt-C**: Scroll the information buffer down.

mathieui's avatar
mathieui committed
51 52
.. _input-keys:

mathieui's avatar
mathieui committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
Input keys
~~~~~~~~~~
These keys concern only the inputs.

NOTE: The clipboard is common to all inputs. This lets you cut a text
from one input to paste it into an other one.

**Ctrl-a**: Move the cursor to the beginning of line.

**Ctrl-e**: Move the cursor to the end of line.

**Ctrl-u**: Delete the text from the start of the input until the cursor
and save it to the clipboard.

**Ctrl-k**: Delete the text from the cursor until the end of the input
and save it to the clipboard.

**Ctrl-y**: Insert the content of the clipboard at the cursor position.

**Ctrl-Enter**: Insert a line break. Since the input is only one line,
the line break is represented by the character ``|`` in it but will be
sent as the real ``\n`` character.

louiz’'s avatar
louiz’ committed
76 77 78 79 80 81
**Alt-k**: Escape the next key pressed. For example if you press Alt-k,
followed by Ctrl-q, this will enter “^Q” into the text input. This is useful
for example in conjunction with the bind command, to help you know how to
bind something to a key combination without having to remember how to write
them by hand.

mathieui's avatar
mathieui committed
82
.. _chattab-keys:
mathieui's avatar
mathieui committed
83 84 85

Chat tab input keys
~~~~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
86

mathieui's avatar
mathieui committed
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
These keys work in any conversation tab (MultiUserChat, Private or
Conversation tabs).

**Key Up**: Use the previous message from the message history.

**Key Down**: Use the next message from the message history.

**Page Up**: Scroll up in the conversation by x lines, where x is the
height of the conversation window - 1.

**Page Down**: Like Page Up, but down.

**Ctrl-b**: Go one line up in the buffer.

**Ctrl-f**: Go one line down in the buffer.

**Ctrl-s**: Go half a screen up in the buffer.

**Ctrl-x**: Go half a screen down in the buffer.

**Alt-/**: Complete what you’re typing using the "recent" words from the
current conversation, if any.

**Alt-v**: Move the separator at the bottom of the tab.

**Alt-h**: Scroll to the separator, if there is one.

**Ctrl-c**: Insert xhtml formatting.

    You have to press Ctrl-c then a character listed below:
        - 1: Red
        - 2: Green
        - 3: Yellow/Orange
        - 4: Blue
        - 5: Pink
        - 6: Turquoise
        - b: Bold
mathieui's avatar
mathieui committed
124
        - u: Underlined
mathieui's avatar
mathieui committed
125 126
        - o: Stop formatting

mathieui's avatar
mathieui committed
127 128
.. _muctab-keys:

mathieui's avatar
mathieui committed
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
MultiUserChat tab input keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These keys work only in the MultiUserChat tab.

**Alt-u**: Scroll the user list down.

**Alt-y**: Scroll the user list up.

**Alt-p**: Scroll to the previous highlight.

**Alt-n**: Scroll to the next highlight.

**tabulation**: Complete a nick.

mathieui's avatar
mathieui committed
144 145
.. _muclisttab-keys:

mathieui's avatar
mathieui committed
146 147
MultiUserChat List tab input keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
148

mathieui's avatar
mathieui committed
149
These keys work only in the MultiUserChat List tab (obtained with :term:`/list`).
mathieui's avatar
mathieui committed
150 151 152 153 154 155 156

**Up**: Go up one row.

**Down**: Go down one row.

**j**: Join the MultiUserChat currently selected.

mathieui's avatar
mathieui committed
157
**J**: Join the MultiUserChat currently selected, without giving focus to its tab.
mathieui's avatar
mathieui committed
158

mathieui's avatar
mathieui committed
159
**Ctrl-M**: Join the MultiUserChat currently selected (same as ``j``.
mathieui's avatar
mathieui committed
160 161 162

**PageUp**: Scroll a page of chats up.

mathieui's avatar
mathieui committed
163
**PageDown**: Scroll a page of chats down.
mathieui's avatar
mathieui committed
164 165


mathieui's avatar
mathieui committed
166 167
.. _rostertab-keys:

mathieui's avatar
mathieui committed
168 169
Contact list tab input keys
~~~~~~~~~~~~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
170

mathieui's avatar
mathieui committed
171
These keys work only in the Contact list tab (the tab number 0).
mathieui's avatar
mathieui committed
172 173 174 175 176 177 178 179 180 181 182 183 184

**/**: Open a prompt for commands.

**s**: Start a search on the contacts.

**S**: Start a (slow) search with approximation on the contacts.

**Alt-u**: Move the cursor to the next group.

**Alt-y**: Move the cursor to the previous group.

**Ctrl-c**: Cancel the input (search or command)

185
**Enter** on a contact/resource: open a chat tab with this contact/resource
mathieui's avatar
mathieui committed
186

187
**Enter** on a group: fold/unfold that group
mathieui's avatar
mathieui committed
188 189 190 191 192 193 194 195 196

**Up**: Move the cursor down one contact.

**Down**: Move the cursor up one contact.

**PageUp**: Scroll a page of contacts up.

**PageDown**: Scroll a page of contacts down.

197 198 199 200 201 202 203 204 205 206 207 208 209
.. note:: The following will not work if you can still write things in the
                input (meaning you previously typed ``s`` or ``/``)

**Space**: Fold/Unfold the current item.

**o**: Show the offline contacts.

During a search
"""""""""""""""

**Enter**: end the search while keeping the selected contact under the cursor
(tip: press **Enter** a second time to open a chat window)

mathieui's avatar
mathieui committed
210 211
.. _forms-keys:

mathieui's avatar
mathieui committed
212 213
Data Forms tab keys
~~~~~~~~~~~~~~~~~~~
mathieui's avatar
mathieui committed
214

mathieui's avatar
mathieui committed
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
**Ctrl+y**: Validate the form, send it and close the tab.

**Ctrl+g**: Cancel that form (do not send your changes) and close the
tab.

**Up**: Select the next field.

**Down**: Select the previous field.

**Right/Left**: Switch between possible values, in a jid-multi,
 list-multi, list-single or text-multi field.

**Space**: Select that option

XML tab input keys
~~~~~~~~~~~~~~~~~~

These keys only work in the XML tab (obtained with :term:`/xml_tab`)

**Ctrl+k**: Freeze or un-freeze the display in order to have a clear view of
 the stanzas.


.. _key-conf:

Key configuration
-----------------

Bindings are keyboard shortcut aliases. You can use them
to define your own keys to replace the default ones.
where ``^x`` means *Control + x*
and ``M-x`` means *Alt + x*

To know exactly what the code of a key is, just run

.. code-block:: bash

252
    python3 poezio/keyboard.py
mathieui's avatar
mathieui committed
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294

And enter any key.

Turn Alt-i into a tab key (completion, etc):

.. code-block:: ini

    M-i = ^I

Actions
-------

Mapping actions on keys
~~~~~~~~~~~~~~~~~~~~~~~

One may want to add keyboard shortcuts on actions that were not mapped already
in poezio. To this effect, you can map the keys on actions using the
:ref:`key-conf` seen in the previous section.


The actions are pseudo-keystrokes, and have to be treated the same way.
They all begin with an underscore to prevent any possible collision with things
already defined.

Actions list
~~~~~~~~~~~~

.. note:: Even if some of these actions are labelled as similar to other
        keystrokes, remapping the keystrokes will not remap the actions defined here.

**_bookmark**

    Bookmarks the current room.

    Similar to :term:`/bookmark`.

**_bookmark_local** Bookmarks the current room, locally.

    Similar to :term:`/bookmark_local`

**_close_tab**: Closes the current tab.

mathieui's avatar
mathieui committed
295 296
    This is the same as :term:`/close`. The first tab (the contact list) can
    not be closed.
mathieui's avatar
mathieui committed
297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327

**_disconnect**: Disconnects poezio from the server.

**_quit**: Exits poezio.

    Similar to :term:`/quit`.

**_reconnect**: Disconnects then reconnects poezio, if possible.

    This is similar to :term:`/reconnect`.

**_redraw_screen**: Redraws the screen.

    This isn’t normally useful, similar to Ctrl-l.

**_reload_theme**: Reloads the theme.

    Similar to :term:`/theme`.

**_remove_bookmark**: Removes the bookmark on the current room.

    Similar to :term:`/remove_bookmark`.

**_room_left**: Goes to the room on the left.

    Similar to the default Ctrl-p action.

**_room_right**: Goes to the room on the right.

    Similar to the default Ctrl-n action.

mathieui's avatar
mathieui committed
328
**_show_roster**: Goes to the contact list
mathieui's avatar
mathieui committed
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347

    Similar to Alt-r action.

**_scroll_down**: Scrolls down in the current buffer.

    Similar to PAGEDOWN.

**_scroll_up**: Scrolls up in the current buffer.

    Similar to PAGEUP.

**_scroll_info_down**: Scrolls down in the info buffer.

    Similar to Alt-c.

**_scroll_info_up**: Scrolls up in the info buffer.

    Similar to Alt-d.

348
**_server_cycle**: Cycles in the current chatroom server.
mathieui's avatar
mathieui committed
349

350 351
    Similar to :term:`/server_cycle` in a chatroom. If you are not in a
    chatroom, you will get an error.
mathieui's avatar
mathieui committed
352 353 354 355 356 357 358 359 360

**_show_bookmarks**: Shows the current bookmarks.

    Similar to :term:`/bookmarks`.

**_show_important_room**: Goes to the most important room.

    Similar to Alt-e.

361
**_show_invitations**: Shows all the pending chatroom invitations.
mathieui's avatar
mathieui committed
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417

    Similar to :term:`/invitations`.

**_show_plugins**: Shows the currently loaded plugins.

    Similar to :term:`/plugins`.

**_show_xmltab**: Opens an XML tab.

    Similar to :term:`/xml_tab`.

**_toggle_pane**: Toggles the left pane.

    Similar to F4.

Status actions
~~~~~~~~~~~~~~

**_available**: Sets the status to *available*.

    Similar to ``/status available``.

**_away**: Sets the status to *away*.

    Similar to ``/status away``.

**_chat**: Sets the status to *chat*.

    Similar to ``/status chat``.

**_dnd**: Sets the status to *dnd*.

    Similar to ``/status dnd``.

**_xa**: Sets the status to *xa*.

    Similar to ``/status xa``.

Command execution
~~~~~~~~~~~~~~~~~

With that kind of actions, you can also execute arbitrary commands, with the
``_exc_`` keyword.


You only have to prefix your command line with ``_exc_``, and without the  ``/``.


**/kick Partauche bound on Ctrl-w**:

.. code-block:: ini

    ^W = _exc_kick Partauche


That key binding will only work in the tabs defining the command (here, the
418
chatroom tab), and will show an error message in the others.
mathieui's avatar
mathieui committed
419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443

Examples
~~~~~~~~

**Config with user-defined actions**

.. code-block:: ini

    [bindings]
    ^W = _close_tab
    M-x = _show_xmltab
    M-i = _show_important_room
    M-p = _toggle_pane

**Config with commands mapped**

.. code-block:: ini

    [bindings]
    M-c = _exc_configure
    ^Q = _exc_part RAGE QUIT
    ^J = _exc_join
    ^F = _exc_load figlet
    ^R = _exc_load rainbow
    ^S = _exc_say llollllllllllll