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.
procedure: (make-button PARENT [name: STRING] [label: STRING] [sticky?: BOOLEAN] [hfill?: BOOLEAN] [vfill?: BOOLEAN] [expand?: BOOLEAN]) → OBJECT
Creates a new button, passing various flags and settings as specified.
procedure: (make-checkbox PARENT [name: STRING] [label: STRING] [state: BOOLEAN] [hfill?: BOOLEAN] [vfill?: BOOLEAN] [expand?: BOOLEAN]) → OBJECT
Creates a new checkbox, passing various flags and settings as specified.
procedure: (make-radio PARENT [name: STRING] [label: STRING] [items: LIST] [hfill?: BOOLEAN] [vfill?: BOOLEAN] [expand?: BOOLEAN]) → OBJECT
Creates a new radio button group, passing various flags and settings as specified.
procedure: (radio-items-clear! RADIO) → UNSPECIFIED
Removes all radio buttons from a given group.
procedure: (radio-item-add! RADIO STRING) → UNSPECIFIED
Adds a radio button to a given group.
procedure: (make-textbox PARENT [name: STRING] [label: STRING] [multiline?: BOOLEAN] [multilingual?: BOOLEAN] [password?: BOOLEAN] [int-only?: BOOLEAN] [flt-only?: BOOLEAN] [catch-tab?: BOOLEAN] [noemacs?: BOOLEAN] [nolatin1?: BOOLEAN] [nopopup?: BOOLEAN] [readonly?: BOOLEAN] [hfill?: BOOLEAN] [vfill?: BOOLEAN] [expand?: BOOLEAN]) → OBJECT
Creates a new textbox, passing various flags and settings as specified.
procedure: (textbox-string TEXTBOX) → STRING
procedure: (textbox-string-set! TEXTBOX STRING) → STRING
Accessors for the string content in a textbox.
textbox-string has textbox-string-set! attached as a setter.
Event Loop
procedure: (event-loop) → INTEGER
Runs the event loop until terminate! is called (explicitly or implicitly). Returns an arbitrary exit status code.
procedure: (terminate! [INTEGER]) → UNSPECIFIED
Terminates a running event loop, optionally passing the given status code.