Introduction

What is Agar?

Agar is a software library that allows developers to implement powerful, high-performance GUIs (Graphical User Interfaces) for their applications. Agar can be compared to other portable GUI toolkits such as GTK+, QT or wxWidgets, but it is released under a more permissive license (MIT / revised BSD). Due to its own unique set of strengths, Agar has been used to implement a number of complex editors, large engineering applications and visualization programs. Since Agar has a small memory footprint and can be easily integrated into existing OpenGL or SDL-based applications, it has also been used by games and emulators.

Portability

In addition to being compatible with a wide array of operating systems (including Linux, Windows, MacOS X, MacOS Classic, FreeBSD, NetBSD, OpenBSD SGI IRIX, AmigaOS), Agar is also compatible with different graphical interfaces and window systems. While most major GUI libraries are cross-platform, they are generally limited to a given window system. For example, a GTK+ program on Linux will always interface with the X Windows system. On the other hand, an Agar program on Linux, as of this writing, can be made to interface with:

The "glx" driver: The X Windows system using hardware acceleration.
The "sdlgl" driver: A SDL display, with hardware acceleration (if SDL is available).
The "sdlfb" driver: A traditional framebuffer via SDL (if SDL is available).
Your own custom driver.

In the case of the "glx" driver, multiple "native" windows are supported. With the "sdlgl" and "sdlfb" drivers, the application is limited to a single native window. Without the need for recompiling, an Agar program can select a driver at run-time. An Agar program need not to be aware of the presence of an underlying window system; if there isn't any (as it is the case with embedded devices or SDL-based drivers), Agar provides a minimal "built-in" window manager.

Installing Agar

Under Unix-based platforms

On Unix-based platforms, the process of installing Agar from source is straightforward:

Download the source package (see Download page), and unpack to a temporary directory.
Run ./configure (see ./configure --help for available options).
Run make to build the library.
Run make install, as root.

Depending on your exact platform, pre-compiled binary packages may be available from your ports / packages system. If the binary package is behind the latest Agar stable release, it is best to stick to the source.

Under Windows

On the Windows platform, installing any library can be a difficult process, but we've made the process as simple as it can be made. A number of pre-compiled Windows packages are available from the Agar Download page. The .zip version of the Agar source package also contains generated "project files" for a number of IDEs.

For step-by-step guides to installing Agar, compiling it from source, or using it in specific IDEs in Windows, refer to the Agar Wiki articles:

First steps in Agar programming

Hello World!

We'll start with the canonical "Hello World":

Example 1-1: Hello world (source)

#include <agar/core.h>
#include <agar/gui.h>
 
int
main(int argc, char *argv)
{
	AG_Window *win;
 
	/* Initialize Agar. */
	if (AG_InitCore("hello", 0) == -1 ||
	    AG_InitGraphics(NULL) == -1)
		return (1);
 
	win = AG_WindowNew(0);
	AG_LabelNew(win, 0, "Hello, world!");
	AG_WindowShow(win);
 
	AG_EventLoop();
	AG_Destroy();
	return (0);
}

The AG_InitCore() call initializes Agar's software utility library, Agar-Core (it implements non-GUI-specific features such as the Agar object system). The first argument to AG_InitCore() is an arbitrary program name string.

AG_InitGraphics() initializes the Agar GUI system. The argument to this function is an Agar "driver specification" string, which is a comma separated list of video/input drivers to try in order. For example, "sdlfb" selects frame-buffer video via SDL. The special string "<SDL>" tries all available SDL-based drivers, and "<OpenGL>" tries all drivers with OpenGL support. We'll pass a NULL argument, so Agar will try to select the "best" available driver for the current platform.

We create a standard Agar window by invoking AG_WindowNew(), which returns a pointer to the AG_Window object. The next call creates a simple text label using AG_LabelNew(), and attaches it to the window. AG_LabelNew(), like every other widget constructor routine in Agar, accepts a pointer to the parent widget or window as its first argument.

Agar windows are initialized as hidden. AG_WindowShow() displays the window now that it contains all of the GUI elements we want.

AG_EventLoop() enters Agar's default, general-purpose event loop. The call to AG_EventLoop() will only return when the application will terminate. AG_EventDestroy() releases all resource allocated by Agar.

Using the Agar API Reference

The Agar API Reference documents in detail every public function, structure, object and data type in the Agar API; it also features some code examples. Unless Agar was installed without manual pages (e.g., --without-manpages), the API reference is installed in Unix manual page format. Downloadable versions of the documentation in HTML format are available from the Documentation page.

A number of manual page sections are standard throughout the documentation:

DESCRIPTION - A description of the main topic covered by the manual page.
INHERITANCE HIERARCHY - The list of superclasses leading up to this one (for Agar object classes).
INITIALIZATION - Constructor, destructor, and general configuration-related routines.
EVENTS - Agar events processed, or generated by instances of this class (for Agar object classes).
EXAMPLES - Example code fragments.
SEE ALSO - Links to related manual pages.
HISTORY - Historical details

Since some developers have the habit of looking at the C include files as a form of documentation, it is worth mentioning that as new Agar releases are issued, compatibility is guaranteed only for those functions and data types that are officially documented in the API Reference.

Adding an Exit Button

Let's add an "Exit" button strengths strenghts