NAME

libRUIN API functions

SYNOPSIS

#include <curses.h>
#include <libguile.h>
#include <libruin.h>

void ruin_init();

void ruin_shutdown();

void ruin_draw(ruin_window_t *rwin, SCM document);

void ruin_draw_string(ruin_window_t *rwin, char *document);

void ruin_draw_file(ruin_window_t *rwin, char *filename);

ruin_window_t *ruin_window_new(WINDOW *nwin);

void ruin_window_free(ruin_window_t *rwin);

void ruin_input_send(ruin_window_t *rwin, int ch);

DESCRIPTION

libRUIN (Renderer for User Interfaces in Ncurses) is a framework for rendering user interfaces specified in XML- and CSS-based markup languages, using the Ncurses terminal control library as the rendering target. The functions listed above constitute the entire C API for rendering the interfaces and transmitting user input to the interface once it has been rendered.

See the libRUIN Texinfo manual for a more detailed information on the use of libRUIN, including how the recommended way to initialize Ncurses and Guile, and instructions for adding event handlers to your interface documents.

ruin_init initializes libRUIN for use and must be called before any of the other functions can be called.

ruin_shutdown frees the internal data structures allocated by ruin_init, after which the API cannot be used until it is initialized again.

The three "draw" functions render the document passed as the second argument, using the ruin_window_t pointer passed as the first. ruin_draw_file() loads the XML document from the location given by filename; ruin_draw_string() parses the XML document from the NULL-terminated string document; ruin_draw() uses the Guile Scheme object document as the XML document to be rendered -- it should contain a valid SDOM document. Each of the draw functions returns once the document has been rendered in the specified window, at which point the application may begin interacting with it via ruin_input_send().

ruin_window_new() allocates a new ruin_window_t structure that uses the Ncurses window nwin as its canvas for document rendering. ruin_window_free() should be used to free this structure when it is no longer in use.

ruin_input_send() sends the input character ch to the document currently rendered in the ruin_window_t structure rwin. The appropriate keyboard event handlers registered for this document will be called, as well as libRUIN's default event handlers.

RETURN VALUE

ruin_init() returns one on success, zero on failure. libRUIN can fail to initialize if ruin_init() has already been called or if any of the required Guile Scheme modules could not be loaded. ruin_window_new() returns a newly-allocated ruin_window_t structure (that should be freed later with ruin_window_free()).

ENVIRONMENT

libRUIN checks the following environment variables during initialization, and uses them to locate required Guile Scheme modules:

RUIN_SCHEME_SXML_PATH: The full path to the installation directory of the SXML module
RUIN_SCHEME_SDOM_PATH: The full path to the installation directory of the SDOM module
RUIN_SCHEME_SCSS_PATH: The full path to the installation directory of the SCSS module

Additionally, libRUIN uses the following environment variables as hints for discovering aspects of screen geometry which it cannot otherwise obtain reliably:

RUIN_FONT_HEIGHT: The height of the terminal font in pixels. This figure is used to compute values for lengths specified in px. The default is 16.
RUIN_FONT_WIDTH: The width of the terminal font in pixels. This figure is used to compute values for lengths specified in px. The default is 8.
RUIN_DPI: The number of "dots" per inch on the terminal display. This figure is used to compute values specified in absolute units such as cm or in. The default is 96.

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ENVIRONMENT

SEE ALSO