DragonFly On-Line Manual Pages

LIBRUIN(3)            DragonFly 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
     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

SEE ALSO
     ncurses(3NCURSES)

POSIX                            March 7, 2007                           POSIX