The graphical appearance (typography, colors, paddings and spacings) of Agar
widgets is controlled by the style engine.
Style properties can be either applied to individual widgets with
AG_SetStyle(3) or defined as part of blocks of attributes in an Agar stylesheet.
The AG_StyleSheet language makes no attempt at compatibility with HTML CSS (GUI elements are not DOM-oriented), but we've adopted some of its syntax and keywords in order to ease the learning curve for new users.
Note: The rendering code of Agar widgets has no conception of style attributes. It uses a compact binary representation generated by the style compiler, which itself runs on demand only when properties are changed.
Typographical style attributes include:
The font-family attribute selects the type face. Agar will scan system fonts (via fontconfig), Agar core fonts as well as user-installed fonts (according to the FONT_PATH setting of AG_Config(3)). Matching is case-insensitive with fontconfig but case-sensitive with core and user fonts.
font-size sets the font size either in points ("10pts", "10.5pts") or in percentage of the parent font size ("80%"). In general font sizes should be specified in "%" so that AG_ZoomIn(3) and AG_ZoomOut(3) (which trivially sets "font-size" on the window) may work as expected.
font-weight sets the font weight to "normal", "bold" (bold variant) or "!parent" (opposite of parent's setting).
font-style sets the font style to "normal", "italic" (italic / oblique), "upright-italic" or "!parent" (opposite of parent's setting).
font-stretch sets the width variant of the font to "normal", "semi-condensed", "condensed" or "!parent" (opposite of parent's setting).
Color-defining style attributes include:
Colors allow an optional state selector (e.g., "color#focused"). If no selector is given then the given color is assigned to all states.
Color values can be specified using any one of the representations below. See AG_ColorFromString(3) for details.
RGBA and HSV components may be expressed in "%" (in relation to the same color entry in the parent widget's palette).
Color keywords are matched case-insensitively.
PADDING AND SPACING
Paddings and spacings are specified in pixels:
When padding is given as a single number, it applies to all (Top, Right, Bottom and Left) sides. If spacing is a single number, both horizontal and vertical spacings are set.
Different widget classes will handle padding and spacing differently. Some widgets can handle negative padding and negative spacing values (as a way to indicate condensing of separated items or features).
Agar's default stylesheet is compiled from
gui/style.css. It is a good starting point for writing new stylesheets.
The stylesheet fragment selects a condensed font, tweaks the color scheme and sets padding values for the AG_Button(3) class:
By default, a widget instance inherits its style attributes from its parent. The syntax allows certain attributes, such as "font-size" and "color" to be specified in relation to the parent. For example:
|AG_Intro(3), AG_Widget(3), AG_Window(3)|
|A very basic AG_StyleSheet language first appeared in Agar 1.5.0. Agar 1.6.0 improved parsing and validation, introduced a new color scheme, added typography features as well as "padding" and "spacing".|