AG_STYLESHEET(3)

NAME
AG_StyleSheet - agar cascading style sheets

SYNOPSIS

    #include <agar/core.h>
    #include <agar/gui.h>

DESCRIPTION
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.

TYPOGRAPHY
Typographical style attributes include:

font-family
    "Courier", "DejaVu Sans", "foo.woff2", "my.bmp"
font-size
    "10pts", "10.5pts", "80%"
font-weight
    "normal", "bold" or "!parent"
font-style
    "normal", "italic", "upright-italic" or "!parent"
font-stretch
    "normal", "condensed", "semi-condensed" or "!parent"

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).

COLORS
Color-defining style attributes include:

color
    Foreground primary
background-color
    Background primary
text-color
    Text and vector icons
line-color
    Lines and filled shapes
high-color
    Shading (top and left)
low-color
    Shading (bottom and right)
selection-color
    Selection primary

Colors allow an optional state selector (e.g., "color#focused"). If no selector is given then the given color is assigned to all states.

#unfocused
    Widget is not focused (default state).
#focused
    Widget is focused (see AG_WidgetFocus(3)).
#disabled
    Widget is disabled (see AG_WidgetDisable(3)).
#hover
    Cursor is over the widget (MOUSEOVER is set).

Color values can be specified using any one of the representations below. See AG_ColorFromString(3) for details.

8-bit Device RGB
    "r,g,b[,a]" or "rgb(r,g,b[,a])"
16-bit Device RGB
    "rgb16(r,g,b[,a])"
Hue, Saturation and Value
    "hsv(h,s,v[,a])"
16-bit hex
    "#rgb[a]"
32-bit hex
    "#rrggbb[aa]"
64-bit hex
    "#rrrrggggbbbb[aaaa]"
Color keyword
    "AliceBlue", "antiquewhite"

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:

padding
    "<Number>", "<T> <R> <B> <L>" or "inherit"
spacing
    "<Number>", "<H> <V>" or "inherit"

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).

INITIALIZATION
void AG_InitStyleSheet(AG_StyleSheet *ss)

void AG_DestroyStyleSheet(AG_StyleSheet *css)

AG_StyleSheet * AG_LoadStyleSheet(void *obj, const char *path)

int AG_LookupStyleSheet(AG_StyleSheet *css, void *widget, const char *key, char **rv)

The AG_InitStyleSheet() function initializes the given AG_StyleSheet as an empty style sheet. AG_DestroyStyleSheet() releases all resources allocated by a style sheet.

The AG_LoadStyleSheet() function loads a style sheet from path. On success, a newly allocated AG_StyleSheet is returned. If path begins with a "_" character, AG_LoadStyleSheet() will search for a statically-compiled stylesheet (i.e., "_agStyleDefault" is always available).

The AG_LookupStyleSheet() routine searches the style sheet for the specified attribute (identified by key). If the style sheet defines an attribute applicable to the specified widget instance (the widget argument), its value is returned into rv.

EXAMPLES
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:

    AG_Button {
    	font-family: league-gothic;
    	font-stretch: condensed;
    	font-size: 120%;
    	color: AntiqueWhite;
    	text-color: #000;
    	color#disabled: rgb(200,200,200);
    	text-color#disabled: rgb(125,125,125);
    	high-color#hover: red;
    	low-color#hover: darkred;
    	padding: 5 4 5 4;      /* TRBL */
    }

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:

    	font-size: 50%;			# Half of parent font size
    	color: hsv(100%,50%,100%);	# Half of parent saturation
    	color: hsv(100%,100%,75%);	# 3/4 of parent value

SEE ALSO
AG_Intro(3), AG_Widget(3), AG_Window(3)

HISTORY
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".