API Documentation

An extension is provided that you can import:

  (require-extension agar)

In addition, foreign types used by the library can be included:

  (include "agar-types.scm")

Error Handling

All the procedures do automatic error checking and may throw exceptions of the kind (exn agar). Note that some errors put the native library into an inconsistent state.

procedure: `(agar-condition? ANY) → BOOLEAN`

Checks whether the given object is a condition of kind (exn agar).

procedure: `(make-agar-condition MESSAGE) → CONDITION`

Creates a new condition of kind (exn agar) with the given error message.

parameter: `current-agar-condition`

Synthetic parameter holding the current error state of Agar as a condition object. Returns #f or a condition of kind (exn agar) when called without arguments. Turns any argument into an error message that is set as the Agar error state.

procedure: `(check-agar-condition [STATUS]) → STATUS`

Checks if status is #f or negative. If that is the case, or if status is not given at all, checks the values of current-agar-condition. If there is an error state, it is raised as a continuable exception.

If there is no error state, the status (or an unspecified value) is returned.

Library Initialization

procedure: `(init-agar! [program: STRING] [verbose?: BOOLEAN] [create-datadir?: BOOLEAN] [soft-timers?: BOOLEAN] [graphics: BOOLEAN|STRING]) → UNSPECIFIED`

Initializes the Agar library, passing various flags as specified. If the graphics keyword argument is given and either #t or a driver name, the graphics subsystem is also initialized.

Object System

procedure: `(object? ANY [CLASS]) → BOOLEAN`

Checks whether the given value is an Agar object (of the given class).

procedure: `(make-object CLASS [parent: OBJECT] [name: STRING]) → OBJECT`

Creates a new object of the given class, optionally attached to the given parent and identified by the given name.

procedure: `(destroy-object! OBJECT) → UNSPECIFIED`

Destroys the given object.

procedure: `(object-class OBJECT) → CLASS`

Returns the class descriptor of the given Agar object.

procedure: `(object-name OBJECT) → STRING`

procedure: `(object-name-set! OBJECT STRING) → UNSPECIFIED`

Accessors for the name identifying an Agar object within the context of the parent it is attached to.

object-name has object-name-set! attached as a setter.

procedure: `(lookup-object OBJECT PATH) → OBJECT`

Locates an object by its name and the names of its parents, starting at a given root object.

syntax: `(:object-child <VARIABLE> OBJECT)`

SRFI-42 generator for the children of a given Agar object.

procedure: `(object-children OBJECT) → LIST`

Returns the children of a given Agar object as a list.

procedure: `(class? ANY) → BOOLEAN`

Checks whether the given value is an Agar class descriptor.

procedure: `(lookup-class NAME) → CLASS`

Locates an Agar class descriptor by name. Returns #f if no matching class is found.

procedure: `(class-hierarchy CLASS) → STRING`

Returns the full name of the given class descriptor.

procedure: `(class-version CLASS) → (values INTEGER INTEGER)`

Returns the major and minor version of the given class descriptor.

procedure: `(object-ref OBJECT NAME) → ANY`

procedure: `(object-set! OBJECT NAME ANY) → UNSPECIFIED`

Accessors for the value of a bound variable identified by the given name in the given Agar object.

object-ref has object-set! attached as a setter.

procedure: `(event-add! OBJECT NAME PROC) → UNSPECIFIED`

Adds a handler procedure to the event identifier by the given name in the given Agar object.

Widgets

procedure: `(widget-expand! WIDGET [hfill: BOOLEAN] [vfill: BOOLEAN] [expand: BOOLEAN]) → UNSPECIFIED`

Makes the given widget fill available layout space in horizontal, vertical or both directions.

procedure: `(widget-position-set! WIDGET X Y) → UNSPECIFIED`

Sets the layout position of the given widget.

procedure: `(widget-size-set! WIDGET WIDTH HEIGHT) → UNSPECIFIED`

Sets the layout dimensions of the given widget.

procedure: `(make-window [name: STRING] [caption: STRING] [main?: BOOLEAN]) → OBJECT`

Creates a new window, passing various flags and settings as specified.

procedure: `(window-caption WINDOW) → STRING`

procedure: `(window-caption-set! WINDOW STRING) → UNSPECIFIED`

Accessors for the title of a given window.

window-caption has window-caption-set! attached as a setter.

procedure: `(window-visible? WINDOW) → STRING`

procedure: `(window-visible-set! WINDOW STRING) → UNSPECIFIED`

Accessors for the visibility state of a given window.

window-visible? has window-visible-set! attached as a setter.

procedure: `(make-box PARENT [name: STRING] [label: STRING] [orient: SYMBOL] [homogenous?: BOOLEAN] [padding: INTEGER] [spacing: INTEGER] [hfill?: BOOLEAN] [vfill?: BOOLEAN] [expand?: BOOLEAN]) → OBJECT`

Creates a new layout container, passing various flags and settings as specified. The orientation can be one of the symbols horizontal, horiz, vertical, vert.