Color and Font Attribute Themes

Each of the elements of the screen has color and font attributes defined in a4.ini. Often, these are defined in a separate theme.ini file, which is included in the a4.ini file.

specifying color 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_unselected = 7 -1 italic
titlebar_urgent = 0xffffff 0xaaaaaa reverse,italic

Colors may be an indexed color number, 0-255, a specific 24-bit RGB color (see 8-bit, 256-color table), or one of the defined color names. 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.

specifying font attributes

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 comma with no space.

bold italic reverse strike blink

You may also use one of these three underline types.

single double curly

titlebar theme

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. Using different terminal color schemes is useful for logging into different hosts, switching to different user IDs, or any number of other purposes.

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_unselected. If the alert, or bell, has been triggered in an unselected terminal then the titlebar_urgent settings are used. If a terminal window has been set to read-only then the titlebar_readonly settings are overlaid on the regular titlebar settings. For this overlying of attributes to work, you optionally set additional font attributes, and optionally set only a new foreground or background color, not both, and leave the other set to -1.

statusbar theme

The settings defined for statusbar are used for the color and style of the status bar text.

tags theme

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_unoccupied settings.


tags 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]".

scroll back history

Each terminal has a scroll back history buffer. Set the number of lines with scroll_history, defaults to 5000.

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.

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.

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.

cursor settings

The selected terminal has the cursor focus. The cursor can be set to be visible or hidden with cursorvis and blinking or solid with cursorblink. The cursor shape can be 1 for block, 2 for underline, or 3 for vertical bar with cursorshape.

startup actions

Any number of actions assigned to the optional 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 specified. For organizational purposes, it is helpful to put all your startup actions in a separate file, such as ~/.config/a4/startup.ini, and then include that in your a4.ini file with include = startup.ini. An example of a useful set of actions to put in a startup.ini file are to create a terminal window on tag 2, ssh to a remote server, and change to the projects directory:

startup = view 2
startup = create_term
startup = keysequence ssh\n
startup = keysequence cd projects\n

Terminal Color Rules

titlebar elements

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"


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.

Action Types

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.