UIOverview

Irssi Text UI Overview

Irssi is deliberately designed to allow most of the actual text and formatting to be customised by themes and scripts. This is achieved by a combination of expandable markup templates, and special escape codes to generate colour and other formatting features.

• Internals documents the underlying mechanism for how these features are implemented, but this page in intended to give an overview for people looking to write or customise their theme files.

• Irssi::UI::Theme also contains details of the functions available to script writers who wish to use themes and formats within their code.

• Formats describes the various markup syntax used within the theme templates for colour and other formatting.

• Complete Format List categorises the available internal formats and themes in a way that can be easily searched for those trying to customise a specific aspect.

See also Theme Editing for practical details on writing or modifying a theme file.

Templates

Templates are the main workhorse of Irssi the display customisations. In use, they take the form '{template_name arg1 arg2 ...}, or are used in the [[printformat $msg_level, $format, @params`|Irssi#Printing]]

In construction, they are typically written as

# bold the first argument, followed by a space and then all subsequent args.
some_format = "%_$0%_ $1-";

Named arguments are not possible, they exand only based on positional arguments, so it is often necessary to read the code or comments surrounding them to determine the positional value of each argument.

They are subject to various rules of expansion before display, as will be outlined below.

Templates are often built on top of other templates, to make global changes easier. For example, the format notify_join has the following definition:

notify_join = "{nick $0} [$1@$2] [{hilight $3}] has joined to $4";

This format takes 4 arguments. The first, $0, is passed to the {nick} format, which is defined as an abstract. The second and third and rendered directly, whilst $3 is also a recursively expanded pattern {hilight}.

Replaces

Replaces are a special case of "not-quite-templates", but rather global mappings which are applied to rendered templace once everything else is complete.

By default, their only function is to darken the [] brace characters, as shown by the line in Format List#Replacements.

Replaces are generally applied, but there are some special cases, such as being evaluated using the format_expand() using the EXPAND_FLAG_IGNORE_REPLACES flag, they are not.

Abstracts

Abstracts are the core contents of each theme file, and define the basic templates which are built upon by formats.

In order to decouple the actual display syntax from the internal formats, abstracts are used as a bridge, and define such templates as:

hilight = "%_$*%_";

Abstracts are used not only in the construction of formats, but also play a significant role in the renderng of window items, such as status bars.

Formats

Formats are special, top-leve flavours of templates, in that they are exposed to the use via the /FORMAT <module> <key> <value> command.

Generally, modifying these formats directly is a bad iedea, since they are easy to break, especially if you place the arguments in the wrong order, and a /SAVE command will save them to the theme file where they will persist.

Unlike abstracts and replaces, formats each reside in a particular namespace, as defined by their module identifiers.

Those identifiers are (assuming core modules are loaded:)

• fe-common/core
• fe-common/fe-text
• fe-common/irc/dcc
• fe-common/irc/notifylist
• fe-common/irc
• fe-common/perl

Internals/Formats has a more in-depth desccription of these modules, and how the formats are used internally with irssi.