NAME

AG_Intro —

agar introduction

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

The Agar API Reference is intended as a detailed specification explaining Agar's functions and structures in sufficient detail. To avoid the content becoming repetitive, the API Reference uses a number of important conventions regarding error handling and thread-safety:

The return value for functions returning int, unless otherwise documented, represents an error code, where 0 indicates success and -1 indicates failure. On failure, an error message string can be retrieved using AG_GetError(3).
Some functions have variants differing only in argument format. For example, AG_LabelNew(3) accepts a format string, and AG_LabelNewS(3) accepts a plain C string. Since the difference is shown in function prototype, it is customary to omit mentioning those variants in the following paragraph describing the function.
Some functions have variants differing only in error-handling style. Those may also be omitted from the description paragraph. For example, AG_MutexInit(3) has no return value. If the function fails, an AG_FatalError(3) is raised. The AG_MutexTryInit variant, however, returns 0 on success or -1 on failure.
When Agar is compiled with threads support, Agar functions are thread-safe (free-threaded), 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). Multithreaded applications must use AG_ObjectLock(3) prior to accessing this data (although in some contexts, such as inside event handler routines, objects can be presumed locked; see AG_Threads(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): Database access methods.
AG_DSO(3): Cross-platform interface to dynamic linkers.
AG_Error(3): Error handling in Agar.
AG_Event(3): Virtual functions (at the Agar object level).
AG_EventLoop(3): Main application event loop. General event sources and sinks.
AG_Execute(3): Cross-platform interface to program execution.
AG_File(3): Portable interface to filesystems.
AG_Limits(3): Interface to platform-dependent limits.
AG_Net(3): Interface to network I/O facilities.
AG_Object(3): The Agar object system.
AG_String(3): Functions for manipulating C strings.
AG_TextElement(3): Dynamically-allocated multilanguage text buffer.
AG_Threads(3): Portable threads interface.
AG_Timer(3): Timer facility.
AG_Time(3): Interface to time sources.
AG_User(3): Cross-platform interface to user accounts.
AG_Variable(3): Primitive 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_Anim(3): Animated graphics surfaces.
AG_BlendFn(3): Pixel blending functions.
AG_Color(3): Color structure.
AG_Cursor(3): Cursor configuration.
AG_Driver(3): Driver (backend) interface.
AG_GlobalKeys(3): Application-wide keyboard shortcuts.
AG_GL(3): OpenGL-specific functions.
AG_GuiDebugger(3): GUI debugging tool.
AG_KeySym(3): Keyboard key definitions.
AG_KeyMod(3): Keyboard modifier definitions.
AG_MouseButton(3): Mouse button definitions.
AG_StyleSheet(3): Agar's version of cascading style sheets.
AG_Surface(3): Graphics surfaces.
AG_Text(3): Interface to font engine / text rendering facilities.
AG_Units(3): Conversion between different unit systems.
AG_Widget(3): Generic widget interface.
AG_WidgetPrimitives(3): Widget rendering primitives.
AG_Window(3): Basic window / window manager interface.

AGAR-GUI: STANDARD WIDGETS

The standard Agar widget set provides the basic GUI functionality useful to the widest range of applications. Developers are encouraged to implement more specialized and application-specific widgets (this is made simple by use of the AG_Object(3) system).

AG_Box(3): Horizontal/vertical widget container.
AG_Button(3): Push-button widget.
AG_Checkbox(3): Checkbox widget.
AG_Combo(3): Canned text input/drop-down menu widget.
AG_Console(3): Scrollable text console widget.
AG_DirDlg(3): Directory selection 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_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.

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-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_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^2 and R^3.
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_String(3): Math-specific extensions to the AG_Printf(3) formatting engine.
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^3.
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^2 and R^3.
M_Quaternion(3): Basic quaternion arithmetic.
M_Rectangle(3): Routines specific to rectangles in R^2 and R^3.
M_Triangle(3): Routines specific to triangles in R^2 and R^3.
M_Vector(3): Basic linear algebra routines specific to vectors. In addition to vectors in R^n, specialized operations are provided for vectors in R^2, R^3 and R^4.

AGAR-AU

The ag_au library provides a basic cross-platform interface to audio hardware.

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

AU(3): Audio library initialization.
AU_Wave(3): Structure containing an audio stream.
AU_DevOut(3): Interface to audio output device.