DESCRIPTION

Agar is a graphical application toolkit. It provides all types of graphical applications, written in different languages, with consistent interfaces across a wide array of platforms.

This document summarizes the various interfaces provided by the standard libraries included in the official Agar source distribution (such as ag_core, ag_gui, etc.) These libraries share the same version number and release cycle, but they are separate and can be packaged and distributed independently.

USING THE AGAR API REFERENCE

Since the Agar API Reference is also intended as a detailed specification (defining function prototypes, structures and function behavior in detail), the content can become repetitive and difficult to read, so the API Reference uses a number of conventions:

The return value for functions returning int, unless otherwise documented, represents an error code (where 0 = success, -1 = failure). On failure, the error message can be retrieved using AG_GetError(3).
Every function prototype described in the documentation has some associated text, except for those function "variants" that are trivial and obvious by looking at the function prototype (for example, AG_LabelNew(3) accepts a printf-style format string, and AG_LabelNewS(3) accepts a plain C string).
When Agar is compiled with threads support, functions are thread-safe unless documented otherwise (see CONVENTIONS section of AG_Threads(3) for important details related to thread safety).

There is generally one manual page per Agar object class. A number of manual page sections are standard throughout the documentation, this includes:

INHERITANCE HIERARCHY	List of parent (inherited) classes. See AG_Object(3) for details on inheritance with the Agar object system.
EVENTS	List of events defined by this object (and optionally, a list of events potentially raised by this object). See AG_Event(3) for details on Agar events.
STRUCTURE DATA	List of public structure members which are safe to access directly (in the specified way). Function interfaces are always available so developers who prefer to use them exclusively can ignore these sections. Note: Multithreaded applications must use AG_ObjectLock(3) prior to accessing this data (although the object can be assumed locked in some contexts, see AG_Event(3) for details).

AGAR-CORE

Agar's general utility library is named ag_core. It implements the AG_Object(3) object system which is used extensively by all other Agar libraries. It also provides cross-platform interfaces to operating system services (e.g., filesystems, network services, threads).

To use this library, link against agar-config --libs (non-graphical applications can also link against agar-core-config --libs to avoid the GUI library).

AG_Config(3)	Manage Agar configuration settings.
AG_Core(3)	Core Agar library initialization.
AG_DataSource(3)	Generic interface to different data sources.
AG_Db(3)	Interface to key/value databases (e.g., Berkeley DB).
AG_DbObject(3)	Database-bound Agar object class.
AG_DSO(3)	Cross-platform interface to dynamic linkers.
AG_Error(3)	Error handling in Agar.
AG_File(3)	Portable interface to filesystems.
AG_Object(3)	The Agar object system.
AG_Event(3)	Event handling for objects.
AG_Limits(3)	Interface to platform-dependent limits.
AG_Threads(3)	Portable threads interface.
AG_Timeout(3)	Timer system (object and event-bound).
AG_Time(3)	Low-level time interface.
AG_Variable(3)	Primitiive data variables and bindings.
AG_Version(3)	Datafile versioning functions.

AGAR-GUI

The ag_gui library implements the Agar GUI system. It also includes a set of standard, built-in widgets. The Agar GUI is implemented in a fashion independent of the underlying graphics API (i.e., direct-video, OpenGL), and is designed to provide the highest performance and efficiency achievable with any given graphics system.

To use this library, link against agar-config --libs.

AG_BlendFn(3)	Pixel blending functions.
AG_Color(3)	Color structure.
AG_Colors(3)	Color scheme interface.
AG_Cursor(3)	Cursor configuration.
AG_Driver(3)	Driver (backend) interface.
AG_GlobalKeys(3)	Global keyboard shortcut table.
AG_GuiDebugger(3)	GUI debugging tool.
AG_KeySym(3)	Keyboard definitions.
AG_KeyMod(3)	Keyboard modifier definitions.
AG_MouseButton(3)	Mouse button definitions.
AG_Style(3)	The high-level themeing API.
AG_Surface(3)	Graphics surfaces.
AG_Text(3)	Interface to font engine (i.e., FreeType or bitmap fonts).
AG_Units(3)	Conversion between different unit systems.
AG_View(3)	Low-level interface to the graphics display.
AG_Widget(3)	Generic widget interface.
AG_WidgetPrimitives(3)	Widget rendering primitives.
AG_Window(3)	Basic window widget; interface to built-in window manager.

AGAR-GUI: STANDARD WIDGETS

The standard Agar widget set provides the basic GUI functionality useful to the widest range of applications. Note that the implementation of more specialized and application-specific widgets (made simple by the AG_Object(3) interface) is encouraged, as demonstrated by the other standard Agar libraries which include a few of them.

AG_Box(3)	Horizontal/vertical widget container.
AG_Button(3)	Generic push-button widget (boolean bindings).
AG_Checkbox(3)	Generic checkbox widget (boolean bindings).
AG_Combo(3)	Text input/drop-down menu widget.
AG_Console(3)	Scrollable text console widget.
AG_Editable(3)	Low-level text edition widget (string bindings, UTF-8 supported).
AG_FileDlg(3)	File selection widget.
AG_Fixed(3)	Container for fixed position/geometry widgets.
AG_FontSelector(3)	Font selection widget.
AG_GLView(3)	Low-level OpenGL context widget.
AG_Graph(3)	Graph display widget.
AG_FixedPlotter(3)	Plotter for integral values.
AG_HBox(3)	Alternate interface to AG_Box(3).
AG_HSVPal(3)	Hue/saturation/value color picker widget.
AG_Icon(3)	Drag-and-droppable object that can be inserted into AG_Socket(3) widgets.
AG_Label(3)	Display a string of text (static or polled).
AG_MPane(3)	Standard single, dual, triple and quad paned view.
AG_Menu(3)	Menu widget.
AG_Notebook(3)	Notebook widget.
AG_Numerical(3)	Numerical input / spinbutton widget for floating-point and integer values.
AG_Palette(3)	Edit a RGB color value (Uint32/AG_PixelFormat bindings). Obsoleted by AG_HSVPal(3).
AG_Pane(3)	Dual paned view.
AG_Pixmap(3)	Displays arbitrary surfaces.
AG_ProgressBar(3)	Progress bar widget.
AG_Radio(3)	Simple radio group widget (integer bindings).
AG_Scrollbar(3)	Scrollbar (integer or floating-point bindings).
AG_Scrollview(3)	Scrollable view.
AG_Separator(3)	Cosmetic separator widget.
AG_Slider(3)	Slider control (integer or floating-point bindings).
AG_Socket(3)	Placeholder for drag-and-droppable AG_Icon(3) objects.
AG_Statusbar(3)	Specialized statusbar widget.
AG_Table(3)	Table display widget.
AG_Treetbl(3)	Tree-based table display widget.
AG_Textbox(3)	Text edition widget (string bindings, UTF-8 supported).
AG_Tlist(3)	Tree/list widget (either static or polled).
AG_Toolbar(3)	Specialized button container for toolbars.
AG_UCombo(3)	Variant of AG_Combo(3) which displays a button instead of a text input.
AG_VBox(3)	Alternate interface to AG_Box(3).

AGAR-VG

The ag_vg library is a simple 2D vector graphics library which allows developers to specify hierarchical sketches consisting of elements such as lines, curves and text. It uses linear transformations to define the placement of geometrical entities, which the best approach for most applications.

Following the same design philosophy as the Agar-GUI, ag_vg only provides the entity classes (e.g., lines, arcs) useful to the widest range of applications, and allows specialized and application-specific entities to be implemented easily in separate libraries. For specialized applications such as CAD systems, the placement of entities might be best described through geometrical constraints (e.g., distances and angles) as opposed to linear transformations. This functionality is implemented, notably, by the FreeSG library (see http://freesg.org).

To use this library, link against agar-vg-config --libs.

VG(3)	Vector drawing object.
VG_View(3)	Agar widget for visualization and edition of drawings.
VG_Arc(3)	Arc entity.
VG_Circle(3)	Circle entity.
VG_Line(3)	Line entity.
VG_Polygon(3)	Polygon entity.
VG_Text(3)	Text entity.

AGAR-RG

The ag_rg library is useful at generating and manipulating raster graphics (either static or animated) by compositing a set of graphical elements. It implements a composite image format which allows directives, transformations and instancing of discrete graphical elements.

To use this library, link against agar-rg-config --libs.

RG(3)	Container for graphics, animations and textures.
RG_Tile(3)	Surface generated from a set of instructions.
RG_Texture(3)	Tile reference with texturing settings.
RG_Anim(3)	Animation generated from a set of instructions.
RG_Pixmap(3)	Graphical surface used internally.
RG_Feature(3)	Generic graphical operation framework.
RG_Tileview(3)	Widget for graphics edition, generic tool framework with undo.

AGAR-MATH

ag_math is a general-purpose math library focused on providing consistent structures and highly optimized routines. In addition to linear algebra, ag_math also provides useful computational geometry structures and methods (e.g., intersections, tesselations), portable complex-number/quaternion routines and some useful Agar-GUI widgets and extensions.

To use this library, link against agar-math-config --libs.

M_Intro(3)	Math library initialization and primitive types.
M_Matrix(3)	Routines specific to matrices. This includes general m-by-n matrices (frequently encountered in scientific applications and usually solved with sparse-matrix optimizations), as well as a specialized interface for 4x4 matrices (usually countered in computer graphics).
M_Circle(3)	Circles in R² and R³.
M_Color(3)	Mapping between different color spaces.
M_Complex(3)	Complex-number arithmetic not reliant on compiler extensions.
M_Coordinates(3)	Mapping between different coordinate systems.
M_Sort(3)	Sorting algorithms (qsort, heapsort, mergesort, radixsort)
M_IntVector(3)	Vector operations for vectors with integer elements.
M_Line(3)	Routines related to lines, half-lines and line segments.
M_Matview(3)	Agar-GUI widget for viewing the contents of M_Matrix(3) objects numerically or graphically.
M_Plane(3)	Routines related to planes in R³.
M_Plotter(3)	General-purpose plotting widget for Agar-GUI, with support for M_Real, M_Vector and M_Complex types.
M_PointSet(3)	Set of points and related operations (e.g., convex hull).
M_Polygon(3)	Operations related to polygons in R² and R³.
M_Quaternion(3)	Basic quaternion arithmetic.
M_Rectangle(3)	Routines specific to rectangles in R² and R³.
M_Triangle(3)	Routines specific to triangles in R² and R³.
M_Vector(3)	Basic linear algebra routines specific to vectors. In addition to vectors in Rⁿ, specialized operations are provided for vectors in R², R³ and R⁴.