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_Colors interface manages a global array of standard colors which are shared between visible widgets. Note that a given theme may or may not use these values at all (see AG_Style(3) for details), but it is customary for themes to use the standard colors, at least as general guidelines for the user's color preferences.

INTERFACE

void AG_ColorsInit (void)

int AG_ColorsLoad (const char *path)

int AG_ColorsSave (const char *path)

void AG_ColorsSaveDefault (void)

int AG_ColorsSetRGB (int color, Uint8 r, Uint8 g, Uint8 b)

int AG_ColorsSetRGBA (int color, Uint8 r, Uint8 g, Uint8 b, Uint8 a)

int AG_ColorsGetRGB (int color, Uint8 *r, Uint8 *g, Uint8 *b)

int AG_ColorsGetRGBA (int color, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)

The AG_ColorsInit() function (re)loads the default Agar color scheme. It is rarely invoked directly because it is implied by AG_InitGraphics(3).

The AG_ColorsLoad() function loads the color scheme from the given Agar color scheme (*.acs) file. AG_ColorsSave() saves the current color scheme to the given *.acs file. AG_ColorsSaveDefault() saves the current color scheme to the default location, assuming save-path is set in AG_Config(3).

The AG_ColorsSetRGB() and AG_ColorsSetRGBA() functions change the specified standard color based on RGB and RGBA components. AG_ColorsGetRGB() and AG_ColorsGetRGBA() return the RGB/RGBA components representing the specified color. These functions return 0 on success, -1 if the given index is invalid.

COLOR INDICES

The widget rendering functions read the colors from the global agColors[] array. Although many widget-specific color slots may be added to, or removed from the array, the following constants are standard and not subject to change between Agar releases:

enum {
	BG_COLOR,			/* Global background */
	FRAME_COLOR,			/* Standard container background */
	LINE_COLOR,			/* Lines (eg. in tables) */
	TEXT_COLOR,			/* Text */
	WINDOW_BG_COLOR,		/* Window background */
	WINDOW_HI_COLOR,		/* Window highlight #1 */
	WINDOW_LO_COLOR,		/* Window highlight #2 */
	TITLEBAR_FOCUSED_COLOR,		/* Focused titlebar color */
	TITLEBAR_UNFOCUSED_COLOR,	/* Unfocused titlebar color */
	TITLEBAR_CAPTION_COLOR,		/* Titlebar text color */
	BUTTON_COLOR,			/* For button-like controls */
	DISABLED_COLOR,			/* For "disabled" controls */
	MENU_UNSEL_COLOR,		/* Non-selected menu item */
	MENU_SEL_COLOR,			/* Selected menu item */
	MENU_OPTION_COLOR,		/* Boolean option for menu item */
	MENU_TXT_COLOR,			/* Text of menu item */
	MENU_SEP1_COLOR,		/* Menu separator #1 */
	MENU_SEP2_COLOR,		/* Menu separator #2 */
	TEXTBOX_COLOR,			/* Text control background */
	TEXTBOX_TXT_COLOR,		/* Text control foreground */
	TEXTBOX_CURSOR_COLOR,		/* Text cursor */
	TRANSPARENT_COLOR,		/* Always (0,0,0,0) */
	PANE_COLOR,			/* Movable pane separators */
	TABLE_COLOR,			/* Background of table widgets */
	TABLE_LINE_COLOR,		/* Lines of table widgets */
	LAST_COLOR			/* Last index */
};

EXAMPLES

The following code fragment sets the window background color to black:

AG_ColorSetRGB(WINDOW_BG_COLOR, 0,0,0);

HISTORY

The AG_Colors interface first appeared in Agar 1.0. Colors were previously configurable on a per-widget basis, but this was changed to reduce memory consumption.