LIBRUIN(3) BSD Library Functions Manual LIBRUIN(3)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 ren‐
dering 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 docu‐
ments.
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 argu‐
ment, using the ruin_window_t pointer passed as the first.
ruin_draw_file() loads the XML document from the location given by file‐
name; 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 interact‐
ing 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_win‐
dow_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 VALUEruin_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
SEE ALSOncurses(3NCURSES)POSIX March 7, 2007 POSIX
