diff options
Diffstat (limited to 'doc/en/weechat_user.en.adoc')
| -rw-r--r-- | doc/en/weechat_user.en.adoc | 1067 |
1 files changed, 538 insertions, 529 deletions
diff --git a/doc/en/weechat_user.en.adoc b/doc/en/weechat_user.en.adoc index d435972a2..bd9c412a0 100644 --- a/doc/en/weechat_user.en.adoc +++ b/doc/en/weechat_user.en.adoc @@ -631,6 +631,53 @@ Some environment variables are used by WeeChat if they are defined: | WEECHAT_EXTRA_LIBDIR | An extra directory to load plugins (from the "plugins" directory in this path). |=== +[[colors_support]] +=== Colors support + +WeeChat can use up to 32767 color pairs to display text in bars and chat area +(your terminal must support 256 colors to use them in WeeChat). + +According to value of _TERM_ environment variable, you may have following limits +for colors in WeeChat: + +[width="75%",cols="8,>3,>3",options="header"] +|=== +| $TERM | Colors | Pairs +| "rxvt-unicode", "xterm", ... | 88 | 32767 +| "rxvt-256color", "xterm-256color", ... | 256 | 32767 +| "screen" | 8 | 64 +| "screen-256color" | 256 | 32767 +| "tmux" | 8 | 64 +| "tmux-256color" | 256 | 32767 +|=== + +You can run `weechat --colors` or use command `/color` in WeeChat to +display limits for your environment. + +Some recommended values for _TERM_ if you want 256 colors: + +* under screen: _screen-256color_ +* under tmux: _screen-256color_ or _tmux-256color_ +* outside screen/tmux: _xterm-256color_, _rxvt-256color_, _putty-256color_, ... + +[NOTE] +You may have to install package "ncurses-term" to use these values in _TERM_ +variable. + +If you are using screen, you can add this line to your _~/.screenrc_: + +---- +term screen-256color +---- + +If your _TERM_ variable has wrong value and that WeeChat is already running, +you can change it with these two commands: + +---- +/set env TERM screen-256color +/upgrade +---- + [[files_and_directories]] === Files and directories @@ -959,151 +1006,6 @@ kbd:[!] In irc plugin, you can remap these colors using option <<option_irc.color.mirc_remap,irc.color.mirc_remap>>. -[[colors]] -=== Colors - -WeeChat can use up to 32767 color pairs to display text in bars and chat area -(your terminal must support 256 colors to use them in WeeChat). - -According to value of _TERM_ environment variable, you may have following limits -for colors in WeeChat: - -[width="75%",cols="8,>3,>3",options="header"] -|=== -| $TERM | Colors | Pairs -| "rxvt-unicode", "xterm", ... | 88 | 32767 -| "rxvt-256color", "xterm-256color", ... | 256 | 32767 -| "screen" | 8 | 64 -| "screen-256color" | 256 | 32767 -| "tmux" | 8 | 64 -| "tmux-256color" | 256 | 32767 -|=== - -You can run `weechat --colors` or use command `/color` in WeeChat to -display limits for your environment. - -Some recommended values for _TERM_ if you want 256 colors: - -* under screen: _screen-256color_ -* under tmux: _screen-256color_ or _tmux-256color_ -* outside screen/tmux: _xterm-256color_, _rxvt-256color_, _putty-256color_, ... - -[NOTE] -You may have to install package "ncurses-term" to use these values in _TERM_ -variable. - -If you are using screen, you can add this line to your _~/.screenrc_: - ----- -term screen-256color ----- - -If your _TERM_ variable has wrong value and that WeeChat is already running, -you can change it with these two commands: - ----- -/set env TERM screen-256color -/upgrade ----- - -[[colors_basic]] -==== Basic colors - -Basic colors in WeeChat are: - -[width="75%",cols="1m,4",options="header"] -|=== -| Name | Color -| default | Default terminal color (transparent for background) -| black | Black -| darkgray | Dark gray -| red | Dark red -| lightred | Light red -| green | Dark green -| lightgreen | Light green -| brown | Brown -| yellow | Yellow -| blue | Dark blue -| lightblue | Light blue -| magenta | Dark magenta -| lightmagenta | Light magenta -| cyan | Dark cyan -| lightcyan | Light cyan -| gray | Gray -| white | White -|=== - -[[colors_extended]] -==== Extended colors - -WeeChat dynamically allocates color pairs when colors are used on screen (to -display buffers and bars). - -In addition to basic colors, you can use a color number between 1 and the limit -of your terminal. - -Use command `/color` to see current colors and limits. With kbd:[Alt+c] you can -temporarily switch to terminal colors to choose a color. - -For example if you want to display time in orange in buffer, do: - ----- -/set weechat.color.chat_time 214 ----- - -Or if you want a very dark green background for status bar: - ----- -/set weechat.bar.status.color_bg 22 ----- - -[[colors_aliases]] -==== Aliases - -You can add color aliases with command `/color alias` and then use this alias -in any color option. - -For example: - ----- -/color alias 214 orange -/set weechat.color.chat_delimiters orange ----- - -[[colors_attributes]] -==== Attributes - -It is possible to use some attributes for colors. One or more attributes can be -added before color name or number: - -* `+*+`: bold text -* `+!+`: reverse video -* `+/+`: italic -* `+_+`: underlined text -* `+|+`: keep attributes: do not reset bold/reverse/italic/underlined when - changing color - -For example if you want self nick as white underlined, do: - ----- -/set weechat.color.chat_nick_self _white ----- - -Or if you want time in status bar as orange underlined with bold: - ----- -/set weechat.color.status_time *_214 ----- - -To use an attribute with default terminal color (-1), you must use a number -greater than last terminal color, for example max color in WeeChat: 99999. - -Example of bold with terminal foreground color: - ----- -/set weechat.color.status_time *99999 ----- - [[buffers_and_windows]] === Buffers and windows @@ -1426,233 +1328,6 @@ By default WeeChat and its default plugins interpret these variables: [NOTE] External plugins and scripts can define and use other local variables. -[[bars]] -=== Bars - -A _bar_ is an area beside the chat that can contain any type of text. - -The bar options can be set with options `weechat.bar.name.option` where `name` -is the name of the bar and `option` the option for this bar. - -List of bar options: - -[width="100%",cols="2m,2,10",options="header"] -|=== -| Option | Values | Description - -| type | `root`, `window` | - A bar with type `root` is displayed exactly one time on screen, outside all - windows. The default bar _buflist_ has type `root`. + - A bar with type `window` is displayed in each window, for example if you - split one time the screen (with `/window splith` or `/window splitv`), you - will have one bar in each window. The default bars _title_, _status_, - _input_ and _nicklist_ have type `window`. - -| position | `top`, `bottom`, `left`, `right` | - Position of the bar: above/below chat, on the left/right. - -| priority | integer ≥ 0 | - Priority for display of bar: this is used for ordering the bars on screen when - many bars have same type and position. + - The bars are displayed from the edge of the screen to the center. A higher - priority will display bar at the beginning, so closer to the edge. + - Example: _input_ bar has priority 1000, so it is displayed before the _status_ - bar, which has priority 500. - -| size | integer ≥ 0 | - The size of the bar: number of columns for position left/right, number - of lines for position top/bottom. A size of `0` means automatic, so the size - will be computed according to content displayed in bar. - -| size_max | integer ≥ 0 | - The maximum size for a bar, `0` = no limit (this option is used only if - `size` = `0`). - -| color_bg | color | - The default background color for the bar. - -| color_fg | color | - The default text color for the bar. - -| color_delim | color | - The color for delimiters in bar. - -| hidden | `on`, `off` | - When option is `on`, the bar is hidden. + - Note: instead of changing this option, the command `/bar` is preferred, for - example: `/bar toggle nicklist` (see command <<command_weechat_bar,/bar>>). - -| separator | `on`, `off` | - When option is `on`, a separator (line) is displayed between this bar and - other bars (or chat). - -| items | string | - A list of _items_ (see <<bar_items,items>> for more info). - -| filling_left_right | `+horizontal+`, `+vertical+`, `+columns_horizontal+`, `+columns_vertical+` | - Type of filling for a bar which has position `left` or `right` (see - <<bar_filling,filling>> for more info). - -| filling_top_bottom | `+horizontal+`, `+vertical+`, `+columns_horizontal+`, `+columns_vertical+` | - Type of filling for a bar which has position `top` or `bottom` (see - <<bar_filling,filling>> for more info). - -| conditions | string | - The conditions to display the bar (see <<bar_conditions,conditions>> for more - info). -|=== - -[[bar_items]] -==== Items - -The option _items_ is a string with a list of bar items, separated by a comma -(space between items on screen) or `+++` (glued items). - -The list of bar items is displayed with command `/bar listitems`. - -Before or after item name, you can use chars (that are not alphanumeric, `+-+` -or `+_+`). They will be displayed before/after item with the delimiters color -defined in bar (option _color_delim_). - -Example of bar with items "[time],buffer_number+:+buffer_plugin+.+buffer_name": - -.... -┌───────────────────────────────────────────────────────────────────────────┐ -│[12:55] 3:irc/libera.#weechat │ -└───────────────────────────────────────────────────────────────────────────┘ -.... - -A special syntax can be used to force the buffer used when displaying the bar -item: "@buffer:item" (where "buffer" is the full name of buffer and "item" is -the name of a bar item). - -This is useful in root bars, to display item for a specific buffer which is -not displayed in the current window (or even not displayed at all). - -Example: nicklist of bitlbee in a root bar (if the bar is called -_bitlist_ and if bitlbee server is called _bitlbee_): - ----- -/set weechat.bar.bitlist.items "@irc.bitlbee.&bitlbee:buffer_nicklist" ----- - -[[bar_filling]] -==== Filling - -There are four types of filling: - -* `+horizontal+`: the items are displayed horizontally, from left to right. If - there are new lines in items, a space is used to separate lines. -* `+vertical+`: the items are displayed from top to bottom. If there are new - lines in items, a new line is used to separate lines. -* `+columns_horizontal+`: items are displayed using columns, where text is - aligned on the left. The first item is on top left, the second is on same - line, on the right. -* `+columns_vertical+`: items are displayed using columns, where text is aligned - on the left. The first item is on top left, the second is one line below. - -Default bars _title_, _status_ and _input_ have _horizontal_ filling, and -default bar _nicklist_ has _vertical_ filling. - -Some examples of filling for bar _nicklist_: - -.... -┌───────────────────────────────────────────────────────────────────────┐ -│Welcome to #test, this is a test channel │ -│12:54:15 peter | hey! │@carl │ -│12:55:01 +Max | hello │@jessika│ -│ │@maddy │ -│ │%Diego │ -│ │%Melody │ -│ │+Max │ -│ │ celia │ -│ │ Eva │ -│ │ freddy │ -│ │ Harold^│ -│ │ henry4 │ -│ │ jimmy17│ -│ │ jodie ▼│ -│[12:55] [6] [irc/libera] 3:#test(+n){24} │ -│[@carl] █ │ -└───────────────────────────────────────────────────────────────────────┘ - filling_left_right = vertical ▲ - -┌───────────────────────────────────────────────────────────────────────┐ -│Welcome to #test, this is a test channel │ -│12:54:15 peter | hey! │@carl lee │ -│12:55:01 +Max | hello │@jessika louise │ -│ │@maddy mario │ -│ │%Diego mark │ -│ │%Melody peter │ -│ │+Max Rachel │ -│ │ celia richard│ -│ │ Eva sheryl │ -│ │ freddy Vince │ -│ │ Harold^ warren │ -│ │ henry4 zack │ -│ │ jimmy17 │ -│ │ jodie │ -│[12:55] [6] [irc/libera] 3:#test(+n){24} │ -│[@carl] █ │ -└───────────────────────────────────────────────────────────────────────┘ - filling_left_right = columns_vertical ▲ - -┌───────────────────────────────────────────────────────────────────────┐ -│@carl %Diego celia Harold^ jodie mario Rachel Vince │ -│@jessika %Melody Eva henry4 lee mark richard warren │ -│@maddy +Max freddy jimmy17 louise peter sheryl zack │ -│───────────────────────────────────────────────────────────────────────│ -│ │ - filling_top_bottom = columns_vertical ▲ - -┌───────────────────────────────────────────────────────────────────────┐ -│@carl @jessika @maddy %Diego %Melody +Max celia Eva │ -│ freddy Harold^ henry4 jimmy17 jodie lee louise mario │ -│ mark peter Rachel richard sheryl Vince warren zack │ -│───────────────────────────────────────────────────────────────────────│ -│ │ - filling_top_bottom = columns_horizontal ▲ -.... - -[[bar_conditions]] -==== Conditions - -The option _conditions_ is a string which is evaluated to know if the bar -must be displayed or not. - -The string can be: - -* _active_: the window must be active -* _inactive_: the window must be inactive -* _nicklist_: the buffer displayed in window must have a nicklist -* an expression: it is evaluated as boolean (see command - <<command_weechat_eval,/eval>>) - -For the expression, following variables are available: - -* `+${active}+`: true if window is active -* `+${inactive}+`: true if window is inactive -* `+${nicklist}+`: true if buffer displayed in window has a nicklist - -Following pointers are available: - -* `+${window}+`: the window where condition is evaluated -* `+${buffer}+`: the buffer of window where condition is evaluated - -Example to display nicklist bar in all buffers with a nicklist, and only if -width of terminal is > 100: - ----- -/set weechat.bar.nicklist.conditions "${nicklist} && ${info:term_width} > 100" ----- - -Same condition, but always display nicklist on buffer _&bitlbee_ -(even if terminal is small): - ----- -/set weechat.bar.nicklist.conditions "${nicklist} && (${info:term_width} > 100 || ${buffer.full_name} == irc.bitlbee.&bitlbee)" ----- - [[bare_display]] === Bare display @@ -1740,155 +1415,17 @@ The screen will look like that in bare display: So you can click the URL from _joe_ without any problem in your terminal (of course this supposes that your terminal supports click on URLs). -[[notify_levels]] -=== Notify levels - -[[setup_notify_levels]] -==== Setup notify levels - -Four levels are possible in messages displayed in buffers, from lower to higher: - -* _low_: message with low importance (for example irc join/part/quit) -* _message_: message from a user -* _private_: message in a private buffer -* _highlight_: message with highlight - -Each buffer has a notify level, which is used to decide what messages will add -buffer in hotlist. - -The default notify level can be set using option -<<option_weechat.look.buffer_notify_default,weechat.look.buffer_notify_default>>, -default is _all_. - -[width="75%",cols="2m,7",options="header"] -|=== -| Notify level | Level of messages added to hotlist -| none | (none) -| highlight | _highlight_ + _private_ -| message | _highlight_ + _private_ + _message_ -| all | _highlight_ + _private_ + _message_ + _low_ -|=== - -Notify level can be defined for a set of buffers, for example all buffers of -irc server "libera": - ----- -/set weechat.notify.irc.libera message ----- - -Set notify level _highlight_ on channel "#weechat" only: - ----- -/set weechat.notify.irc.libera.#weechat highlight ----- - -The notify level for a buffer can be set with command `/buffer`: - ----- -/buffer notify highlight ----- - -[[max_hotlist_level_nicks]] -==== Max hotlist level for nicks - -It is possible to set max hotlist level for some nicks, per buffer, or per group -of buffers (like IRC servers). - -The buffer property "hotlist_max_level_nicks" can be set with a list of nicks -and for each nick the max hotlist level to trigger, possible levels are: - -* -1: no hotlist changes for nick -* 0: low priority (like join/part messages) -* 1: message -* 2: private message -* 3: highlight (in fact useless, since it's already the default max for all messages) - -For example to disable highlights from "joe" and "mike" on current buffer: - ----- -/buffer set hotlist_max_level_nicks_add joe:2,mike:2 ----- - -[NOTE] -The buffer property "hotlist_max_level_nicks" is not saved in configuration. + -You can easily save it with the script _buffer_autoset.py_: you can install it -with `+/script install buffer_autoset.py+` and get help with -`+/help buffer_autoset+`. - -[[highlights]] -=== Highlights - -[[highlights_words]] -==== Add words to highlight - -By default, WeeChat highlights messages from other users containing your nick, -therefore the highlight depends on the buffer (the nick can be different from -one buffer to another). - -You can add other words to highlight with the option -<<option_weechat.look.highlight,weechat.look.highlight>>, for example to -highlight your nick and "word1", "word2" and all words beginning with "test": - ----- -/set weechat.look.highlight word1,word2,test* ----- - -If you need a more specific rule for the word, you can use regular expressions -with the option <<option_weechat.look.highlight_regex,weechat.look.highlight_regex>>, -for example to highlight words "flashcode", "flashcöde" and "flashy": - ----- -/set weechat.look.highlight_regex flashc[oö]de|flashy ----- - -The delimiters around words to highlight can be customized with the option -<<option_weechat.look.word_chars_highlight,weechat.look.word_chars_highlight>>. - -[[highlights_tags]] -==== Add tags to highlight - -Lines displayed can contain "tags", which give some info about the origin of -message or the message itself. + -You can display tags with the command `/debug tags` (same command to hide them). - -You can add specific tags to highlight with the option -<<option_weechat.look.highlight_tags,weechat.look.highlight_tags>>. -Tags are separated by commas, and multiple tags can be separated by `+++` to do -a logical "and" between them. - -For example to highlight all messages from nick "FlashCode" and all notices -from nicks beginning with "toto": - ----- -/set weechat.look.highlight_tags "nick_flashcode,irc_notice+nick_toto*" ----- - -[[highlights_regex_buffer]] -==== Set extra highlights on buffer - -You can force highlight using a regular expression with the buffer property -"highlight_regex". - -For example to force the highlight on all messages in the current buffer: - ----- -/buffer set highlight_regex .* ----- - -[NOTE] -The buffer property "highlight_regex" is not saved in configuration. + -You can easily save it with the script _buffer_autoset.py_: you can install it -with `+/script install buffer_autoset.py+` and get help with -`+/help buffer_autoset+`. - [[key_bindings]] -=== Default key bindings +== Key bindings + +WeeChat provides a lot of default key bindings, listed in the following chapters. + +They can be changed and new ones can be added with the <<command_weechat_key,/key>> command. [[key_bindings_cmdline]] -==== Command line +=== Command line [[key_bindings_cmdline_cursor_movement]] -===== Cursor movement +==== Cursor movement [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -1908,7 +1445,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_cmdline_editing]] -===== Editing +==== Editing [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -1936,7 +1473,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_cmdline_color_codes]] -===== Color codes +==== Color codes [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -1950,7 +1487,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_cmdline_history]] -===== Command history +==== Command history [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -1962,7 +1499,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_buffers]] -==== Buffers +=== Buffers [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -2000,7 +1537,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_windows]] -==== Windows +=== Windows [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -2019,7 +1556,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_bars]] -==== Bars +=== Bars [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -2043,7 +1580,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_hotlist]] -==== Hotlist +=== Hotlist [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -2056,7 +1593,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_toggle_keys]] -==== Toggle keys +=== Toggle keys [width="100%",cols="^.^3,.^8,.^5",options="header"] |=== @@ -2068,7 +1605,7 @@ with `+/script install buffer_autoset.py+` and get help with |=== [[key_bindings_search_context]] -==== Search context +=== Search context These keys are used in context "search" (when kbd:[Ctrl+r] is pressed to search text in buffer). @@ -2088,7 +1625,7 @@ text in buffer). |=== [[key_bindings_cursor_context]] -==== Cursor context +=== Cursor context These keys are used in context "cursor" (free movement of cursor on screen). @@ -2117,7 +1654,7 @@ These keys are used in context "cursor" (free movement of cursor on screen). |=== [[key_bindings_mouse]] -==== Mouse +=== Mouse These mouse actions are possible only if mouse is enabled with key kbd:[Alt+m] (command: `+/mouse toggle+`). @@ -2170,7 +1707,7 @@ These mouse actions are possible only if mouse is enabled with key kbd:[Alt+m] ^(1)^ kbd:[▲] and kbd:[▼] are wheel up and down. [[key_bindings_fset_buffer]] -==== Fset buffer +=== Fset buffer These keys and actions are used on the fset buffer (see <<fset_plugin,Fset plugin>>). @@ -2216,7 +1753,7 @@ These keys and actions are used on the fset buffer (see <<fset_plugin,Fset plugi ^(1)^ The action must be entered as input on the command line, followed by kbd:[Enter]. [[key_bindings_script_buffer]] -==== Script buffer +=== Script buffer These keys and actions are used on the script buffer (see <<scripts_plugins,Script plugin>>). @@ -2239,6 +1776,251 @@ These keys and actions are used on the script buffer (see <<scripts_plugins,Scri [NOTE] ^(1)^ The action must be entered as input on the command line, followed by kbd:[Enter]. +[[configuration]] +== Configuration + +[[colors]] +=== Colors + +[[colors_basic]] +==== Basic colors + +Basic colors in WeeChat are: + +[width="75%",cols="1m,4",options="header"] +|=== +| Name | Color +| default | Default terminal color (transparent for background) +| black | Black +| darkgray | Dark gray +| red | Dark red +| lightred | Light red +| green | Dark green +| lightgreen | Light green +| brown | Brown +| yellow | Yellow +| blue | Dark blue +| lightblue | Light blue +| magenta | Dark magenta +| lightmagenta | Light magenta +| cyan | Dark cyan +| lightcyan | Light cyan +| gray | Gray +| white | White +|=== + +[[colors_extended]] +==== Extended colors + +WeeChat dynamically allocates color pairs when colors are used on screen (to +display buffers and bars). + +In addition to basic colors, you can use a color number between 1 and the limit +of your terminal. + +Use command `/color` to see current colors and limits. With kbd:[Alt+c] you can +temporarily switch to terminal colors to choose a color. + +For example if you want to display time in orange in buffer, do: + +---- +/set weechat.color.chat_time 214 +---- + +Or if you want a very dark green background for status bar: + +---- +/set weechat.bar.status.color_bg 22 +---- + +[[colors_aliases]] +==== Aliases + +You can add color aliases with command `/color alias` and then use this alias +in any color option. + +For example: + +---- +/color alias 214 orange +/set weechat.color.chat_delimiters orange +---- + +[[colors_attributes]] +==== Attributes + +It is possible to use some attributes for colors. One or more attributes can be +added before color name or number: + +* `+*+`: bold text +* `+!+`: reverse video +* `+/+`: italic +* `+_+`: underlined text +* `+|+`: keep attributes: do not reset bold/reverse/italic/underlined when + changing color + +For example if you want self nick as white underlined, do: + +---- +/set weechat.color.chat_nick_self _white +---- + +Or if you want time in status bar as orange underlined with bold: + +---- +/set weechat.color.status_time *_214 +---- + +To use an attribute with default terminal color (-1), you must use a number +greater than last terminal color, for example max color in WeeChat: 99999. + +Example of bold with terminal foreground color: + +---- +/set weechat.color.status_time *99999 +---- + +[[notify_levels]] +=== Notify levels + +[[setup_notify_levels]] +==== Setup notify levels + +Four levels are possible in messages displayed in buffers, from lower to higher: + +* _low_: message with low importance (for example irc join/part/quit) +* _message_: message from a user +* _private_: message in a private buffer +* _highlight_: message with highlight + +Each buffer has a notify level, which is used to decide what messages will add +buffer in hotlist. + +The default notify level can be set using option +<<option_weechat.look.buffer_notify_default,weechat.look.buffer_notify_default>>, +default is _all_. + +[width="75%",cols="2m,7",options="header"] +|=== +| Notify level | Level of messages added to hotlist +| none | (none) +| highlight | _highlight_ + _private_ +| message | _highlight_ + _private_ + _message_ +| all | _highlight_ + _private_ + _message_ + _low_ +|=== + +Notify level can be defined for a set of buffers, for example all buffers of +irc server "libera": + +---- +/set weechat.notify.irc.libera message +---- + +Set notify level _highlight_ on channel "#weechat" only: + +---- +/set weechat.notify.irc.libera.#weechat highlight +---- + +The notify level for a buffer can be set with command `/buffer`: + +---- +/buffer notify highlight +---- + +[[max_hotlist_level_nicks]] +==== Max hotlist level for nicks + +It is possible to set max hotlist level for some nicks, per buffer, or per group +of buffers (like IRC servers). + +The buffer property "hotlist_max_level_nicks" can be set with a list of nicks +and for each nick the max hotlist level to trigger, possible levels are: + +* -1: no hotlist changes for nick +* 0: low priority (like join/part messages) +* 1: message +* 2: private message +* 3: highlight (in fact useless, since it's already the default max for all messages) + +For example to disable highlights from "joe" and "mike" on current buffer: + +---- +/buffer set hotlist_max_level_nicks_add joe:2,mike:2 +---- + +[NOTE] +The buffer property "hotlist_max_level_nicks" is not saved in configuration. + +You can easily save it with the script _buffer_autoset.py_: you can install it +with `+/script install buffer_autoset.py+` and get help with +`+/help buffer_autoset+`. + +[[highlights]] +=== Highlights + +[[highlights_words]] +==== Add words to highlight + +By default, WeeChat highlights messages from other users containing your nick, +therefore the highlight depends on the buffer (the nick can be different from +one buffer to another). + +You can add other words to highlight with the option +<<option_weechat.look.highlight,weechat.look.highlight>>, for example to +highlight your nick and "word1", "word2" and all words beginning with "test": + +---- +/set weechat.look.highlight word1,word2,test* +---- + +If you need a more specific rule for the word, you can use regular expressions +with the option <<option_weechat.look.highlight_regex,weechat.look.highlight_regex>>, +for example to highlight words "flashcode", "flashcöde" and "flashy": + +---- +/set weechat.look.highlight_regex flashc[oö]de|flashy +---- + +The delimiters around words to highlight can be customized with the option +<<option_weechat.look.word_chars_highlight,weechat.look.word_chars_highlight>>. + +[[highlights_tags]] +==== Add tags to highlight + +Lines displayed can contain "tags", which give some info about the origin of +message or the message itself. + +You can display tags with the command `/debug tags` (same command to hide them). + +You can add specific tags to highlight with the option +<<option_weechat.look.highlight_tags,weechat.look.highlight_tags>>. +Tags are separated by commas, and multiple tags can be separated by `+++` to do +a logical "and" between them. + +For example to highlight all messages from nick "FlashCode" and all notices +from nicks beginning with "toto": + +---- +/set weechat.look.highlight_tags "nick_flashcode,irc_notice+nick_toto*" +---- + +[[highlights_regex_buffer]] +==== Set extra highlights on buffer + +You can force highlight using a regular expression with the buffer property +"highlight_regex". + +For example to force the highlight on all messages in the current buffer: + +---- +/buffer set highlight_regex .* +---- + +[NOTE] +The buffer property "highlight_regex" is not saved in configuration. + +You can easily save it with the script _buffer_autoset.py_: you can install it +with `+/script install buffer_autoset.py+` and get help with +`+/help buffer_autoset+`. + [[mouse]] === Mouse support @@ -2358,6 +2140,233 @@ any gesture made using left button. You can find an event name with command `+/input grab_mouse+` then doing event with mouse. This will insert event name on command line. +[[bars]] +=== Bars + +A _bar_ is an area beside the chat that can contain any type of text. + +The bar options can be set with options `weechat.bar.name.option` where `name` +is the name of the bar and `option` the option for this bar. + +List of bar options: + +[width="100%",cols="2m,2,10",options="header"] +|=== +| Option | Values | Description + +| type | `root`, `window` | + A bar with type `root` is displayed exactly one time on screen, outside all + windows. The default bar _buflist_ has type `root`. + + A bar with type `window` is displayed in each window, for example if you + split one time the screen (with `/window splith` or `/window splitv`), you + will have one bar in each window. The default bars _title_, _status_, + _input_ and _nicklist_ have type `window`. + +| position | `top`, `bottom`, `left`, `right` | + Position of the bar: above/below chat, on the left/right. + +| priority | integer ≥ 0 | + Priority for display of bar: this is used for ordering the bars on screen when + many bars have same type and position. + + The bars are displayed from the edge of the screen to the center. A higher + priority will display bar at the beginning, so closer to the edge. + + Example: _input_ bar has priority 1000, so it is displayed before the _status_ + bar, which has priority 500. + +| size | integer ≥ 0 | + The size of the bar: number of columns for position left/right, number + of lines for position top/bottom. A size of `0` means automatic, so the size + will be computed according to content displayed in bar. + +| size_max | integer ≥ 0 | + The maximum size for a bar, `0` = no limit (this option is used only if + `size` = `0`). + +| color_bg | color | + The default background color for the bar. + +| color_fg | color | + The default text color for the bar. + +| color_delim | color | + The color for delimiters in bar. + +| hidden | `on`, `off` | + When option is `on`, the bar is hidden. + + Note: instead of changing this option, the command `/bar` is preferred, for + example: `/bar toggle nicklist` (see command <<command_weechat_bar,/bar>>). + +| separator | `on`, `off` | + When option is `on`, a separator (line) is displayed between this bar and + other bars (or chat). + +| items | string | + A list of _items_ (see <<bar_items,items>> for more info). + +| filling_left_right | `+horizontal+`, `+vertical+`, `+columns_horizontal+`, `+columns_vertical+` | + Type of filling for a bar which has position `left` or `right` (see + <<bar_filling,filling>> for more info). + +| filling_top_bottom | `+horizontal+`, `+vertical+`, `+columns_horizontal+`, `+columns_vertical+` | + Type of filling for a bar which has position `top` or `bottom` (see + <<bar_filling,filling>> for more info). + +| conditions | string | + The conditions to display the bar (see <<bar_conditions,conditions>> for more + info). +|=== + +[[bar_items]] +==== Items + +The option _items_ is a string with a list of bar items, separated by a comma +(space between items on screen) or `+++` (glued items). + +The list of bar items is displayed with command `/bar listitems`. + +Before or after item name, you can use chars (that are not alphanumeric, `+-+` +or `+_+`). They will be displayed before/after item with the delimiters color +defined in bar (option _color_delim_). + +Example of bar with items "[time],buffer_number+:+buffer_plugin+.+buffer_name": + +.... +┌───────────────────────────────────────────────────────────────────────────┐ +│[12:55] 3:irc/libera.#weechat │ +└───────────────────────────────────────────────────────────────────────────┘ +.... + +A special syntax can be used to force the buffer used when displaying the bar +item: "@buffer:item" (where "buffer" is the full name of buffer and "item" is +the name of a bar item). + +This is useful in root bars, to display item for a specific buffer which is +not displayed in the current window (or even not displayed at all). + +Example: nicklist of bitlbee in a root bar (if the bar is called +_bitlist_ and if bitlbee server is called _bitlbee_): + +---- +/set weechat.bar.bitlist.items "@irc.bitlbee.&bitlbee:buffer_nicklist" +---- + +[[bar_filling]] +==== Filling + +There are four types of filling: + +* `+horizontal+`: the items are displayed horizontally, from left to right. If + there are new lines in items, a space is used to separate lines. +* `+vertical+`: the items are displayed from top to bottom. If there are new + lines in items, a new line is used to separate lines. +* `+columns_horizontal+`: items are displayed using columns, where text is + aligned on the left. The first item is on top left, the second is on same + line, on the right. +* `+columns_vertical+`: items are displayed using columns, where text is aligned + on the left. The first item is on top left, the second is one line below. + +Default bars _title_, _status_ and _input_ have _horizontal_ filling, and +default bar _nicklist_ has _vertical_ filling. + +Some examples of filling for bar _nicklist_: + +.... +┌───────────────────────────────────────────────────────────────────────┐ +│Welcome to #test, this is a test channel │ +│12:54:15 peter | hey! │@carl │ +│12:55:01 +Max | hello │@jessika│ +│ │@maddy │ +│ │%Diego │ +│ │%Melody │ +│ │+Max │ +│ │ celia │ +│ │ Eva │ +│ │ freddy │ +│ │ Harold^│ +│ │ henry4 │ +│ │ jimmy17│ +│ │ jodie ▼│ +│[12:55] [6] [irc/libera] 3:#test(+n){24} │ +│[@carl] █ │ +└───────────────────────────────────────────────────────────────────────┘ + filling_left_right = vertical ▲ + +┌───────────────────────────────────────────────────────────────────────┐ +│Welcome to #test, this is a test channel │ +│12:54:15 peter | hey! │@carl lee │ +│12:55:01 +Max | hello │@jessika louise │ +│ │@maddy mario │ +│ │%Diego mark │ +│ │%Melody peter │ +│ │+Max Rachel │ +│ │ celia richard│ +│ │ Eva sheryl │ +│ │ freddy Vince │ +│ │ Harold^ warren │ +│ │ henry4 zack │ +│ │ jimmy17 │ +│ │ jodie │ +│[12:55] [6] [irc/libera] 3:#test(+n){24} │ +│[@carl] █ │ +└───────────────────────────────────────────────────────────────────────┘ + filling_left_right = columns_vertical ▲ + +┌───────────────────────────────────────────────────────────────────────┐ +│@carl %Diego celia Harold^ jodie mario Rachel Vince │ +│@jessika %Melody Eva henry4 lee mark richard warren │ +│@maddy +Max freddy jimmy17 louise peter sheryl zack │ +│───────────────────────────────────────────────────────────────────────│ +│ │ + filling_top_bottom = columns_vertical ▲ + +┌───────────────────────────────────────────────────────────────────────┐ +│@carl @jessika @maddy %Diego %Melody +Max celia Eva │ +│ freddy Harold^ henry4 jimmy17 jodie lee louise mario │ +│ mark peter Rachel richard sheryl Vince warren zack │ +│───────────────────────────────────────────────────────────────────────│ +│ │ + filling_top_bottom = columns_horizontal ▲ +.... + +[[bar_conditions]] +==== Conditions + +The option _conditions_ is a string which is evaluated to know if the bar +must be displayed or not. + +The string can be: + +* _active_: the window must be active +* _inactive_: the window must be inactive +* _nicklist_: the buffer displayed in window must have a nicklist +* an expression: it is evaluated as boolean (see command + <<command_weechat_eval,/eval>>) + +For the expression, following variables are available: + +* `+${active}+`: true if window is active +* `+${inactive}+`: true if window is inactive +* `+${nicklist}+`: true if buffer displayed in window has a nicklist + +Following pointers are available: + +* `+${window}+`: the window where condition is evaluated +* `+${buffer}+`: the buffer of window where condition is evaluated + +Example to display nicklist bar in all buffers with a nicklist, and only if +width of terminal is > 100: + +---- +/set weechat.bar.nicklist.conditions "${nicklist} && ${info:term_width} > 100" +---- + +Same condition, but always display nicklist on buffer _&bitlbee_ +(even if terminal is small): + +---- +/set weechat.bar.nicklist.conditions "${nicklist} && (${info:term_width} > 100 || ${buffer.full_name} == irc.bitlbee.&bitlbee)" +---- + [[secured_data]] === Secured data |