A4 configuration file

configuration file location

The configuration file is read from $XDG_CONFIG_HOME/a4/a4.ini by default. If $XDG_CONFIG_HOME is not set, it reads from $HOME/.config/a4/a4.ini. Alternatively, the user can specify the configuration file path using the -c command line parameter. If neither of these is available, the default a4.ini file is read from the installation directory, usually /usr/local/etc/a4/a4.ini.

$ a4 -c ./foo.ini

[Default]

specifying color and style attributes

To specify the appearance of an element, give the foreground color, followed by the background color, followed by the font attributes. Specifying any of these is optional, but if you do specify any of them they must be in this order.

titlebar_normal = 7 -1 italic
titlebar_urgent   = 0xffffff 0xaaaaaa reverse,italic

Colors may be either an indexed color number, 0-255, or a specific 24-bit RGB color (see 8-bit, 256-color table). Indexed colors are the 8 standard colors (0-7), 8 bright colors (8-15), 216 extended colors (16-231), and 24 gray scale colors (232-255). Note that the actual color displayed when specifying an indexed color number is determined by how the underlying terminal defines the color for each index number. 24-bit RGB colors must be defined as a six digit hexadecimal number 0xRRGGBB where each of RGB is a hexadecimal digit 0-9, A-F, a-f. If supported by the underlying terminal, these colors will appear as specified. You may also specify a color as -1 to use the underlying terminal's default color.

Font attributes may be one or more of the following, although their implementation depends on the underlying terminal on which you are running a4. In order to combine any of attributes, separate them by a command with no space.

bold italic reverse strike blink

You may also use one of these three underline types.

single double curly

titlebar elements

Each terminal window has a one line title bar at the top that displays the title text and the window number assigned by a4. The window number is used for navigating using the focusn action. The title text is set by the shell and is used by a4 to match optional color rules to implement different color schemes for logging into different hosts, switching to different user IDs, or anything else that is useful. The settings for titlebar_selected are used for the color and style of the title bar of the currently focused window (or group of windows). All other windows use the settings for titlebar_normal, with two exception: if the bell has been triggered in a terminal then the titlebar_urgent settings are used, and if a terminal window has been set to read-only then the titlebar_readonly settings are used.

The title bar text is typically kept up-to-date by setting the PROMPT_COMMAND environment variable in your .bashrc file, or other shell .profile or rc file. For example,

PROMPT_COMMAND='echo -ne "\e]0;${USER}@${HOSTNAME}:${PWD/$HOME/\~}\a"'

It can also be useful to change the title bar text in some scripts, in order to help you keep track of different aspects of your work.

$ echo -ne "\e]0;Custom Title Text\a"

statusbar text elements

There is a one line status bar available in a4 that may be displayed at the top or bottom of the screen, or may be turned off. It has four sections from left to right: the tag names, the current layout symbol, action keys being evaluated, and the status bar text.

The status bar text is generated by one or more commands, statusbar_cmd, at a set interval, statusbar_interval. By default, there are two commands set to alternately run every 10 seconds, first the date command and then the uptime command. Be very careful when setting commands that they do not take a significant amount of time to run as that can have an impact on the performance of the a4 application. In order to have more complex status text, best practice is to have an external process update a text file, and then set the a4 statusbar_cmd to cat that file out.

statusbar_cmd = cat ~/.cache/status/statusbar.txt

To not have any status bar text, either do not set any statusbar_cmd or set statusbar_interval = -1. When statusbar_interval = 0, the status bar command will run once and will not update automatically. It can be triggered to update with the statusnext action, and by default this is assigned to click-1 on the status text.

The settings defined for statusbar are used for the color and style of the status bar text. You may specify optional statusbar_begin and statusbar_end characters to surround the status bar text. The initial position for the status bar, top or bottom, is set by statusbar_top, and whether or not it is visible by statusbar_display. The position of the status bar can be changed using statusbarpos and whether it is displayed or not using statusbarvis. These are set on a per-tag basis.

tag elements

You can define up to 9 alphanumeric tagnames. (In theory, you can define more than 9, but it will be difficult to define keyboard mappings to use them.) By default they are set to the digits 1-9, but using words or mnemonics might be useful. Keep in mind that these are displayed at the left end of the status bar, so it is best to keep the names short. The setting for tag_printf defines how each tag name is printed on the status bar (see printf for details). The default is " %s ", but you might like to use surrounding characters, for example "[%s]".

The settings for tag_selected are used for the color and style of each tag that is currently selected to be viewed. Tags that have terminal windows assigned to them, but are not currently selected for viewing, use the settings for tag_occupied. If any of those tags have a terminal window with the urgent flag set then the tag_urgent settings are used. All other tags, those not selected and without any terminal windows assigned to them, use the tag_normal settings.

zoom settings

For layouts that are split between a zoom area and a stack, you set the default number of terminal windows in the zoom area with zoomnum, which defaults to 1. The amount of the screen taken up by the zoom area is set in zoomsize with a number between .1-.9 to specify the percentage of the screen, which defaults to .5.

[Layouts]

There are eight layouts defined in a4. The order in which they are listed in the [Layouts] section of a4.ini determines the order they are cycled through. You can comment some out if you will never use them, and they won't be included in your cycle. You can also specify the symbol that is displayed on the status bar when each layout is active.

[...Actions]

Actions are functions in a4 that may be assigned to keyboard and mouse sequences. This section describes how to specify action command mappings in the a4.ini file as well as some special keyword mappings. The actions themselves are described on the Actions page.

There is a [KeyboardActions] section and six separate [Mouse...Actions] sections for clicking on six separate parts of the screen: one of the terminal window areas [MouseTermwinActions], one of the terminal window title bars, including those that are minimized [MouseTitlebarActions], one of the tag names [MosueTagActions], the layout symbol [MouseLayoutActions], the status bar text [MouseStatusTextActions], or one of the vertical frame lines [MouseFrameActions].

specifying key combinations for actions

There will be a command line option to run a4 and get the keyboard and mouse text needed for the a4.ini file. Keyboard commands can have a key combination of up to three keys assigned to them. A key can be on its own or can incude the Meta or Alt key, M-, with the Control key, C-, with the Shift key, S-, or with any combination of those. In the a4.ini file, any modifier keys must be put in the order of M-C-S-. Two special keys that must be fully spelled out are "Space" and "Hyphen", otherwise simply use the actual key.

A mouse click is the combination of a press followed by a release in the same location. As a convenience, you may use the word click and a4 will expand that out appropriately. Typically, the left mouse button is 1 and the right is 3. For example, to specify a Control left click, use C-click-1 (you must use all lowercase click at this time). At this time, double click is not supported in a4.

special keyword actions

There are a few special action keywords.

startup: Any actions that are assigned to the special keyword startup are run when a4 is first started up. You can use this keyword more than once and the actions will be run in the order they are defined in a4.ini.
viewkeys: The viewkeys optional keyword expands to assign the specified key binding, followed by digits 1‑9, to the action view for up to the first 9 tags. By default, viewkeys = C‑g v expands to C‑g v 1 = view 1, C‑g v 2 = view 2, etc.
tagkeys: The tagkeys optional keyword expands to assign the specified key binding, followed by digits 1‑9, to the action tag for up to the first 9 tags. By default, tagkeys = C‑g t expands to C‑g t 1 = tag 1, C‑g t 2 = tag 2, etc.
viewtogkeys: The viewtogkeys optional keyword expands to assign the specified key binding, followed by digits 1‑9, to the action view_tog for up to the first 9 tags. By default, viewtogkeys = C‑g V expands to C‑g V 1 = view_tog 1, C‑g V 2 = tag 2, etc.
tagtogkeys: The tagtogkeys optional keyword expands to assign the specified key binding, followed by digits 1‑9, to the action tag_tog for up to the first 9 tags. By default, tagtogkeys = C‑g T expands to C‑g T 1 = tag_tog 1, C‑g T 2 = tag_tog 2, etc.

https://waxandwane.org