.\" Copyright (c) 2014-2023 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd February 18, 2023 .Dt AG_STYLESHEET 3 .Os Agar 1.7 .Sh NAME .Nm AG_StyleSheet .Nd agar cascading style sheets .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION .\" MANLINK(AG_Style) .\" IMAGE(/widgets/AG_Style.png, "Alternate style sheet") The graphical appearance of Agar widgets (including typography, colors, paddings, spacings and decorations) is determined by the stylesheet of their parent .Xr AG_Window 3 . .Pp An .Nm defines a set of attribute .Em blocks . Each block has a .Em selector associated with it. Selectors allow widgets to be targeted based on their class (E), the class of their parent (E > F) or their instance names in relation to the class of their parent (E > "F"). .Pp Selector conditions allow widgets to be styled based on their current geometry ("width", "height") or the zoom level of their windows ("zoom"). .Pp Attributes defined by a stylesheet can be overridden on a per widget instance basis with the .Xr AG_SetStyle 3 family of functions. .Pp Agar stylesheets allow C-style comments. .Sh TYPOGRAPHY Style attributes are case-insensitive. The following are available: .Pp .Bl -tag -width "font-stretch " .It Va font-family The name of the font face or the exact filename of a font (e.g., "DejaVu Sans", "agar-ideograms.agbf", "foo.woff2"). .It Va font-size The font size (e.g., "80%", "10pts", "10.5pts", "12px"). Fonts of GUI elements are normally expressed in "%". .It Va font-weight The font weight ("Thin", "ExtraLight", "Light", "Regular", "SemiBold", "Bold", "ExtraBold", "Black" or "!parent"). .It Va font-style The font style ("Normal", "Italic", "Oblique" or "!parent"). .It Va font-stretch Width variant ("Normal", "UltraCondensed", "Condensed", "SemiCondensed", "SemiExpanded", "Expanded", "UltraExpanded" or "!parent"). .El .Pp The .Va font-family attribute selects the type face. Agar will look up system fonts (via fontconfig), Core Fonts as well as user-installed fonts (under .Xr AG_Config 3 .Dv AG_CONFIG_PATH_FONTS ) . Matching is case-insensitive except for fonts which are referenced by filename. .Pp The .Va font-size attribute sets the font size either in points ("10pts", "10.5pts") for vector fonts, pixels ("12px") for bitmap fonts, or in percentage of the parent widget font's size ("80%"). Generally, the font sizes of GUI elements should be given in "%" so that the zoom function may work as expected (the .Xr AG_ZoomIn 3 and .Xr AG_ZoomOut 3 functions work by simply increasing or decreasing the target window's "font-size"). .Pp The .Va font-weight attribute sets the weight of the font: .Pp .Bl -tag -width "ExtraLight " -compact .It Thin Wt#100 Thin .It ExtraLight Wt#200 Extra Light / Ultra Light .It Light Wt#300 Light .It Regular Wt#400 Regular / Normal .It SemiBold Wt#600 Semi Bold / Demi Bold .It Bold Wt#700 Bold .It ExtraBold Wt#800 Extra Bold .It Black Wt#900 Black / Heavy .It !Parent (opposite of parent) .El .Pp The .Va font-style attribute selects the style of the font: .Pp .Bl -tag -width "Oblique " -compact .It Italic Italic style (with Oblique fallback) .It Oblique Oblique style (with Italic fallback) .It !Parent (opposite of parent) .El .Pp The .Va font-stretch attribute selects the width variant: .Pp .Bl -tag -width "UltraCondensed " -compact .It UltraCondensed 50.0% - Ultra Condensed .It Condensed 75.0% - Condensed .It SemiCondensed 87.5% - Semi Condensed / Demi Condensed .It SemiExpanded 112.5% - Semi Expanded / Demi Expanded .It Expanded 125.0% - Expanded .It UltraExpanded 200.0% - Ultra Expanded .It !Parent (opposite of parent) .El .Sh COLORS Color-defining style attributes include: .Pp .Bl -tag -compact -width "background-color " .It Va color Foreground primary .It Va background-color Background primary .It Va text-color Text and vector icons .It Va line-color Lines and filled shapes .It Va high-color Shading (top and left) .It Va low-color Shading (bottom and right) .It Va selection-color Selection primary .El .Pp Colors allow an optional state selector (e.g., "color#focused"). If no selector is given then the given color is assigned to all states. .Pp .Bl -tag -compact -width "#unfocused " .It "#unfocused" Widget is not focused (default state). .It "#focused" Widget is focused (see .Xr AG_WidgetFocus 3 ) . .It "#disabled" Widget is disabled (see .Xr AG_WidgetDisable 3 ) . .It "#hover" Cursor is over the widget (MOUSEOVER is set). .El .Pp Color values can be specified using any one of the representations below. See .Xr AG_ColorFromString 3 for details. .Pp .Bl -tag -width "Real hue/saturation/value " -compact .It "8-bit Device RGB" "r,g,b[,a]" or "rgb(r,g,b[,a])" .It "16-bit Device RGB" "rgb16(r,g,b[,a])" .It "Hue, Saturation and Value" "hsv(h,s,v[,a])" .It "16-bit hex" "#rgb[a]" .It "32-bit hex" "#rrggbb[aa]" .It "64-bit hex" "#rrrrggggbbbb[aaaa]" .It "Color keyword" "AliceBlue", "antiquewhite" .El .Pp RGBA and HSV components may be expressed in "%" (in relation to the same color entry in the parent widget's palette). .Pp Color keywords are matched case-insensitively. .Sh PADDING AND SPACING Paddings, margins and inner spacings are specified in pixels: .Pp .Bl -tag -compact -width "padding " .It Va padding "", " " or "inherit" .It Va margin "", " " or "inherit" .It Va spacing "", " " or "inherit" .El .Pp The .Va padding attribute sets the inner padding amount in pixels. If given as a single "", the same amount is applied to all sides. Negative values are allowed, and may be used to condense content. .Pp The .Va margin attribute sets the outer margin amount in pixels. If given as a single "", the same amount is applied to all sides. The margin amounts must be positive. .Pp The .Va spacing attribute sets the horizontal and vertical spacings between inner elements of a widget. If given as a single "", the same amount is used for both horizontal and vertical spacings. Negative values are allowed, and may be used to condense content. .Pp Margin is handled generically by container widgts. Padding and inner spacings are implemented in a widget-specific way. Different widget classes will handle padding and spacing differently. .Sh C INTERFACE .nr nS 1 .Ft "void" .Fn AG_InitStyleSheet "AG_StyleSheet *ss" .Pp .Ft "void" .Fn AG_DestroyStyleSheet "AG_StyleSheet *css" .Pp .Ft "AG_StyleSheet *" .Fn AG_LoadStyleSheet "void *obj" "const char *path" .Pp .Ft int .Fn AG_LookupStyleSheet "AG_StyleSheet *css" "void *widget" "const char *key" "char **rv" .Pp .nr nS 0 The .Fn AG_InitStyleSheet function initializes the given .Nm as an empty style sheet. .Fn AG_DestroyStyleSheet releases all resources allocated by a style sheet. .Pp The .Fn AG_LoadStyleSheet function loads a style sheet from .Fa path . On success, a newly allocated .Nm is returned. If .Fa path begins with a "_" character, .Fn AG_LoadStyleSheet will search for a statically-compiled stylesheet (i.e., "_agStyleDefault" is always available). .Pp The .Fn AG_LookupStyleSheet routine searches the style sheet for the specified attribute (identified by .Fa key ) . If the style sheet defines an attribute applicable to the specified widget instance (the .Fa widget argument), its value is returned into .Fa rv . .Sh EXAMPLES Agar's default stylesheet is compiled from .Pa gui/style.css . It is a good starting point for writing new stylesheets. .Pp The following stylesheet fragment selects a condensed font, tweaks the color scheme and sets padding values for the .Xr AG_Button 3 class: .Bd -literal .\" SYNTAX(agarcss) 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 */ } .Ed .Pp The following example uses an E > F (children of class) selector to set the color of all buttons embedded in the .Xr AG_Numerical 3 widget: .Bd -literal .\" SYNTAX(agarcss) AG_Numerical > AG_Button { color: blue; } .Ed .Pp The following example uses an E > "F" (children named) selector to set the color of specific button instances embedded in the .Xr AG_Numerical 3 widget: .Bd -literal .\" SYNTAX(agarcss) AG_Numerical > "increm" { color: red; } AG_Numerical > "decrem" { color: green; } .Ed .Pp The following example switches to a condensed font when the width of the widget is below a given threshold: .Bd -literal .\" SYNTAX(agarcss) AG_HSVPal { font-family: league-gothic; font-size: 140%; } AG_HSVPal (width < 90) { font-family: league-gothic-condensed; font-size: 120%; } .Ed .Pp 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: .Bd -literal .\" SYNTAX(agarcss) 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 .Ed .Pp .Sh SEE ALSO .Xr AG_Intro 3 , .Xr AG_Widget 3 , .Xr AG_Window 3 .Sh HISTORY A very basic .Nm 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". Agar 1.7.0 added "margin" and extended "font-weight" and "font-stretch" to include all standard weights and width variants. The selectors E > F (children of class) and E > "F" (children named) appeared in Agar 1.7.0.