.\" Copyright (c) 2006-2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" 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 August 29, 2006
.Dt AG_COLORS 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Colors
.Nd agar standard GUI color manager
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
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
.Xr 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.
.Sh INTERFACE
.nr nS 1
.Ft "void"
.Fn AG_ColorsInit "void"
.Pp
.Ft "int"
.Fn AG_ColorsLoad "const char *path"
.Pp
.Ft "int"
.Fn AG_ColorsSave "const char *path"
.Pp
.Ft "void"
.Fn AG_ColorsSaveDefault "void"
.Pp
.Ft "int"
.Fn AG_ColorsSetRGB "int color" "Uint8 r" "Uint8 g" "Uint8 b"
.Pp
.Ft "int"
.Fn AG_ColorsSetRGBA "int color" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a"
.Pp
.Ft "int"
.Fn AG_ColorsGetRGB "int color" "Uint8 *r" "Uint8 *g" "Uint8 *b"
.Pp
.Ft "int"
.Fn AG_ColorsGetRGBA "int color" "Uint8 *r" "Uint8 *g" "Uint8 *b" "Uint8 *a"
.Pp
.nr nS 0
The
.Fn AG_ColorsInit
function (re)loads the default Agar color scheme.
It is automatically invoked by
.Xr AG_InitVideo 3 .
.Pp
The
.Fn AG_ColorsLoad
function loads the color scheme from the given Agar color scheme (*.acs) file.
.Fn AG_ColorsSave
saves the current color scheme to the given *.acs file.
.Fn AG_ColorsSaveDefault
saves the current color scheme to the default location, assuming
.Va save-path
is set in
.Xr AG_Config 3 .
.Pp
The
.Fn AG_ColorsSetRGB
and
.Fn AG_ColorsSetRGBA
functions change the specified standard color based on RGB and RGBA components.
.Fn AG_ColorsGetRGB
and
.Fn AG_ColorsGetRGBA
return the RGB/RGBA components representing the specified color.
These functions return 0 on success, -1 if the given index is invalid.
.Sh COLOR INDICES
The widget rendering functions read the colors from the global
.Va 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:
.Bd -literal
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 */
};
.Ed
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_View 3 ,
.Xr AG_Widget 3 ,
.Xr AG_Window 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.0.
Colors were previously configurable on a per-widget basis, but this was
changed to reduce memory consumption.