Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

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

DESCRIPTION

The AG_Style structure describes a "style" (or "theme") to be associated with GUI widgets, using a set of functions which we refer to as "style operations". Different widgets in a same display can be linked with different themes.

While the low-level AG_Widget(3) primitives (i.e., the AG_Draw*() functions) are mainly concerned with generic entities such as lines, rectangles and circles, AG_Style is concerned with high-level cosmetic operations, such as rendering "the background of a button in a given state". Style operations tend to target specific classes of widgets, but many of them are generic. For example, TableBackground() is used by all widgets displaying tabular data.

Widget implementors are encouraged to use style operations for all rendering operations that are purely cosmetic. New style operations can be added without breaking previous themes.

Style operations generally perform vector drawing operations or blit fixed pixmaps in specific patterns. The default theme uses vector drawing exclusively. Vector drawing is recommended when resolution independence is a requirement.

INTERFACE

void AG_SetStyle (void *object, AG_Style *style)

The object argument of AG_SetStyle() may be a AG_Driver(3), an AG_Widget(3) or an AG_Window(3). If the argument is a AG_Driver(3), all AG_Window(3) objects attached to it will inherit the style by default. If the argument is a widget or window, any child widget attached to it will also inherit the new style setting.

STYLE OPERATIONS

init (AG_Style *style)	Initialization function.
destroy (AG_Style *style)	Destructor function.
WindowBackground (AG_Window *window)	Draw background for windows (that do not have the AG_WINDOW_NOBACKGROUND flag set).
WindowBorders (AG_Window *window)	Draw borders around windows (the `wBorderSide` and `wBorderBot` members of `window` determine the size of the borders in pixels).
TitlebarBackground (AG_Widget *widget, int isPressed, int isFocused)	Draw background of a titlebar widget.
ButtonBackground (AG_Widget *widget, int isPressed)	Draw background of a button.
ButtonTextOffset (AG_Widget widget, int isPressed, int x, int *y)	Return an offset to assign to button labels into `x` and `y`.
BoxFrame (AG_Widget *widget, int depth)	Draw background for generic box-style containers, where `depth` is given in pixels.
CheckboxButton (int state)	Draw a checkbox button.
ConsoleBackground (AG_Widget *widget, AG_Color bgColor)	Draw background for text console display widgets.
FixedPlotterBackground (AG_Widget *widget, int showAxis, Uint32 yOffs)	Draw background for single-axis plots.
MenuRootBackground (AG_Widget *widget, AG_Rect r)	Draw background for root menu displays.
MenuRootSelectedItemBackground (AG_Widget *widget, AG_Rect r)	Draw background for selected root menu items.
MenuBackground (AG_Widget *widget, AG_Rect r)	Draw background for menu views.
MenuItemBackground (AG_Widget widget, AG_Rect r, int xIcon, AG_Widget iconObj, int icon, int isSelected, int boolState)	Draw background for an individual item in a menu view. `xIcon` is the x-coordinate of the icon to display. `iconObj` is the widget that contains the icon mapping.
MenuItemSeparator (AG_Widget *widget, int x1, int x2, int y, int h)	Draw a horizontal separator between menu item. `x1` and `x2` are the line endpoints, `y` is the y-coordinate of the line and `h` is the total height of the separator.
NotebookBackground (AG_Widget *widget, AG_Rect r)	Draw the background for AG_Notebook(3) style widgets.
NotebookTabBackground (AG_Widget *widget, AG_Rect r, int idx, int isSelected)	Draw the background for a notebook tab. `idx` indicates the index of the tab. `isSelected` is 1 if this is the currently active tab.
PaneHorizDivider (AG_Widget *widget, int x, int y, int w, int isMoving)	Draw the background for a horizontal divider. `isMoving` indicates whether the user is currently moving the divider.
PaneVertDivider (AG_Widget *widget, int x, int y, int w, int isMoving)	Draw the background for a vertical divider. `isMoving` indicates whether the user is currently moving the divider.
RadioGroupBackground (AG_Widget *widget, AG_Rect r)	Draw the background for a group of radio buttons.
RadioButton (AG_Radio *radio, int x, int y, int selected, int overlap)	Draw an individual AG_Radio3 button. `x` and `y` are the upper-left coordinates of the button. `selected` is 1 if the button is currently selected. `overlap` is 1 if the cursor is over the button.
ScrollbarBackground (AG_Widget *widget)	Draw the background for scrollbar widgets.
ScrollbarVertButtons (AG_Scrollbar *scrollbar, int y, int h)	Draw the three buttons of vertical AG_Scrollbar(3) widgets. `y` is the upper coordinate of the center (slider) button and `h` is its height.
ScrollbarHorizButtons (AG_Scrollbar *scrollbar, int x, int w)	Draw the three buttons of horizontal AG_Scrollbar(3) widgets. `x` is the left coordinate of the center (slider) button and `w` is its width.
SliderBackgroundHoriz (AG_Widget *widget)	Draw the background for a horizontal slider.
SliderBackgroundVert (AG_Widget *widget)	Draw the background for a vertical slider.
SliderControlHoriz (AG_Widget *widget, int x, int w)	Draw the control for a horizontal slider. `x` is the x-coordinate of the left edge of the control, and `w` is the width of the control in pixels.
SliderControlVert (AG_Widget *widget, int y, int h)	Draw the control for a vertical slider. `y` is the y-coordinate of the top edge of the control, and `h` is the height of the control in pixels.
SeparatorHoriz (AG_Widget *widget)	Draw horizontal AG_Separator(3) widgets.
SeparatorVert (AG_Widget *widget)	Draw vertical AG_Separator(3) widgets.
SocketBackground (AG_Socket *socket)	Draw the background of AG_Socket(3) widgets. The function must repect the `bgType` value of the socket.
SocketOverlay (AG_Socket *socket, int highlight)	Draw over AG_Socket(3) widgets. Usually, a rectangle or circle is drawn when `highlight` is 1.
TableBackground (AG_Widget *widget, AG_Rect r)	Draw background for tabular displays such as AG_Table(3).
TableColumnHeaderBackground (AG_Widget *widget, int idx, AG_Rect r, int isSelected)	Draw background for a column header cell. `idx` is the index of the column. `isSelected` is 1 if the column is selected.
TableSelectedColumnBackground (AG_Widget *widget, int idx, AG_Rect r)	The background for a selected column. `idx` is the index of the column.
TableRowBackground (AG_Widget *widget, AG_Rect r, int isSelected)	Draw the background of an entire table row. `isSelected` is 1 if the row is selected.
TableCellBackground (AG_Widget *widget, AG_Rect r, int isSelected)	Draw the background of an individual table cell. `isSelected` is 1 if the cell is selected.
ListBackground (AG_Widget *widget, AG_Rect r)	Draw the background of list displays such as AG_Tlist(3).
ListItemBackground (AG_Widget *widget, AG_Rect r, int isSelected)	Draw the background of individual list items. `isSelected` is 1 if the item is selected.
TreeSubnodeIndicator (AG_Widget *widget, AG_Rect r, int isExpanded)	Draw a symbol (typically a "+" inside of a square) to indicate that the given tree item contains child items `isExpanded` is 1 if the child items are visible.

EXAMPLES

See demos/widgets for an example of a custom theme.

The easiest way to start a new theme is to simply copy gui/style_default.c from the Agar source distribution, remove the static initializer for agStyleDefault and use an initialization function that overrides individual operations instead, so that the theme will continue to work as new operations as added:

AG_Style myStyle;
void
InitMyStyle(AG_Style *s)
{
	*s = agStyleDefault;
	s->name = "MyStyle";
	s->version.maj = 1;
	s->version.min = 1;
	s->init = NULL;
	s->destroy = NULL;
	s->WindowBackground = MyWindowBackground;
	s->WindowBorders = MyWindowBorders;
	...
}

HISTORY

The AG_Style interface first appeared in Agar 1.3.

BUGS

This manual page should be divided into categories.