# Usage

This page is the main page of the documentation for poezio, explaining how to use it and describing its interfaces.

Poezio is composed of tabs which can be of various types. Each tab type has a distinct interface, list of commands and list of key shortcuts, in addition to the global commands and key shortcuts.

## Tab list

There are two ways of showing the open tabs:

### Horizontal list

This is the default method.

On all tabs, you get a line showing the the list of all opened tabs. Each tab has a number, each time you open a new tab, it gets the next available number.

### Vertical list

On all tabs, you get a pane on the left side of the screen that shows a list of the opened tabs. As stated above, each tab has a number, and each time you open a new tab, it gets the next available number.

This mode is enabled by setting the enable_vertical_tab_list option to `true` in the configuration file.

### Options for the tab list

The following options are used to configure the behavior of the tab list:

- enable_vertical_tab_list
- vertical_tab_list_size
- vertical_tab_list_sort
- show_tab_names
- show_tab_numbers
- show_inactive_tabs
- use_tab_nicks

## Generalities

Global commands

Global shortcuts

The tab numbered 0 is always the roster tab, the other tabs can be of any type.

The status of a tab is represented by its color:

- Blue (tab 0): an inactive tab of any type, nothing new to see there.
- Purple (tab 1): a MultiUserChat tab with at least one new unread message.
- Green (tab 2): a tab of a private conversation (Private tab or Conversation tab) with a new message to read.
- Cyan (tab 3): the current tab.
- Red (tab 4): a MultiUserChat tab with at least one new highlight message.

You can go from one tab to another in many ways:

- `Ctrl+n` and `Ctrl+p`
- /win command
- /next and /prev commands
- `Alt` + a number
- `Alt+j` followed by a two-digits number
- `Alt+e`, this will jump to the next tab with the highest priority. Priority applies in this order: private message > highlight message > normal message.

## Roster tab

Specific commands

Specific shortcuts

This is a unique tab, always numbered 0. It contains the list of your contacts. You can add (/add, /accept), remove (/remove) and search contacts from there, and you can open a conversation with them (`Enter` key).

Use the direction arrows (↑↓) to browse the list, the `Space` key to fold or unfold a group or a contact.

1. Area where information messages are displayed.
2. Actual list of contacts. The first level is group, the second is the contacts and the third is the resources of your online contacts.
3. More informations about the selected contact.

## MultiUserChat tab

Specific commands

Specific shortcuts

Chat shortcuts

This tab contains a multi-user conversation.

1. The conversation window, this is where all the messages and events related to the muc will be displayed. It can be scrolled up and down with `PageUp` and `PageDown`.

2. The participant list. Participants are listed by their role first, and then alphabetically. The status of each participant is symbolized using the color of the character on the left of its nick. That character also shows the chatstate of each participant:

   - `|`: inactive
   - `X`: composing
   - `A`: active
   - `p`: paused

   The roles and affiliations of the participants are symbolized by the char before the nick and its color. The characters define the affiliations, and they mean:

   - `~`: Owner
   - `&`: Admin
   - `+`: Member
   - `-`: None

   And their color define their roles, and they mean:

   - Red : moderator
   - Blue: participant
   - Grey: visitor

   The nicks have a random color given by poezio (which can be changed with /recolor)

3. Your information in that MUC (the name of the room, your nick, your role and affiliation).

4. The topic of the room.

You can configure the room (if you have the rights to do it) using the /configure command, open a private conversation with someone using the /query command, change or view the topic using the /topic command…

## Private tab

Specific commands

Chat shortcuts

This is the tab opened with the /query command in a MultiUserChat tab, letting you talk in private with a participant of a multi-user chat.

This is just a simple one to one conversation, with a line showing the status, name and chatstate of the participant.

## Conversation tab

Specific commands

Chat shortcuts

A tab opened from the roster or /message, to talk in private with one of your contacts.

This is also just a simple one to one conversation, with a line showing the status, name and chatstate of the participant, as well as a line at the top showing the status message of the contact. Plugins may add some elements to the status line.

## Dataforms tab

Specific shortcuts

This tab lets you view a form received from a remote entity, edit the values and send everything back. It is mostly used to configure MUCs with the /configure command but can actually be used for almost anything.

Use the `Up` and `Down` keys to go from one field to the other, and edit the value using the `Space`, `Left` or `Right` keys, or by entering text.

You can then send the completed form using `Ctrl+y` or cancel using `Ctrl+g`.

## List tab

Specific shortcuts

This tab lists all public rooms on a MUC service (with the /list command). It is currently very limited but will be improved in the future. There currently is no way to search a room.

Use the `Up` and `Down` or `PageUp` and `PageDown` keys to browse the list, and use `Enter` or `j` to join the selected room.

You can sort the rooms by moving the direction arrows (`←` or `→`) and pressing `Space` when you are on the appropriate column.