Using the LibCSS API
====================

This document explains how to use LibCSS. In addition to this document, please
see the examples and the headers (found in /usr/local/include/libcss or a
similar location). Experience with C is assumed.

Using the library consists of the following general steps:

1. Initialize the library.
2. Load one or more CSS files.
3. Use the Selection API to determine styles.
4. Use the computed styles.
5. Shut down the library.

Please see example1.c for a demonstration of these steps.


Initialize the library
----------------------

The library is initialized using css_initialise():

  css_initialise("Aliases", myrealloc, 0);

The first argument is the pathname of an Aliases file, which maps character
encoding names to their canonical form. For an example, see test/data/Aliases.

The 2nd argument is an allocation function. All allocations required by library
initialization will be made by calling this function. It takes the same
arguments as realloc(); a pointer and a size. If pointer is NULL a new block is
being requested. If size is 0 the block should be freed. Otherwise an existing
block is being resized. In many cases this function can simply call realloc().

The allocation function also takes a private data pointer, which is the third
argument to css_initialise(). This is not used by LibCSS but may be used to
communicate context to the allocation function.

The allocation function pointer and private data pointer are arguments to many
LibCSS functions and work in the same way.

css_initialise() returns a css_error value. It is CSS_OK if everything worked,
and an error code otherwise. The error codes are defined in libcss/errors.h.

Many LibCSS functions return a css_error value. Checking the return value of
every call that does is advised, for example:

  css_error code;
  code = css_initialise("../test/data/Aliases", myrealloc, 0);
  if (code != CSS_OK) {
    fprintf(stderr, "ERROR: css_initialise failed: %s\n",
                    css_error_to_string(code));
    exit(EXIT_FAILURE);
  }

LibCSS depends on LibWapcaplet. This must be initialized before LibCSS. For
example:

  lwc_code = lwc_initialise(myrealloc, NULL, 0);
  if (lwc_code != lwc_error_ok)
    ...


Load one or more CSS files
--------------------------

A stylesheet is represented by the opaque type css_stylesheet. To create one,
use css_stylesheet_create(), for example:

  css_stylesheet *sheet;
  code = css_stylesheet_create(CSS_LEVEL_DEFAULT, "UTF-8", "", NULL,
             false, false, myrealloc, 0, resolve_url, 0, &sheet);
  if (code != CSS_OK)
    ...

The arguments are as follows:

  css_language_level level
    Which version of CSS the stylesheet should be treated as. It currently has
    no effect and is reserved for future use. The recommended value is
    CSS_LEVEL_DEFAULT.

  const char *charset
    The encoding of the stylesheet data, or NULL if LibCSS should attempt to
    detect it. If the encoding is known, for example from the Content-Type
    header or a file attribute, then it should be supplied here.

  const char *url
    The URL that the stylesheet was retrieved from. LibCSS uses this along with
    the resolve function (see below) to convert relative URLs in the stylesheet
    (e.g. imports, background images) to absolute URLs. If the stylesheet has
    no URL, use "".

  const char *title
    This is intended for the stylesheet title (for example from the <link> tag).
    The title is not used by LibCSS but may be retrieved using
    css_stylesheet_get_title(). May be NULL if there is no title.

  bool allow_quirks


  bool inline_style


  css_allocator_fn alloc
  void *alloc_pw


  css_url_resolution_fn resolve
  void *resolve_pw


  css_stylesheet **stylesheet
    Updated with the newly created stylesheet object.

Once the stylesheet has been created, CSS source data can be added to it. LibCSS
parses the data into internal structures. Only data in memory is supported; you
must handle reading from files or the network if required. Data is added using
css_stylesheet_append_data(), for example:

  code = css_stylesheet_append_data(sheet, data, length);
  if (code != CSS_OK && code != CSS_NEEDDATA)
    ...

The second argument is a pointer to a buffer containing some CSS to be parsed,
with length in bytes given in the 3rd argument.

This function may be called repeatedly with more data from the same stylesheet,
for example as data arrives over the network.

The return value may be CSS_NEEDDATA instead of CSS_OK. This indicates that more
data may be expected. The two states can be treated identically.

When all the data has been supplied, css_stylesheet_data_done() completes the
processing:

  code = css_stylesheet_data_done(sheet);
  if (code != CSS_OK)
    ...

The stylesheet is now in memory and ready for further use.


Use the Selection API to determine styles
-----------------------------------------

The Selection API is currently the only way to get information about styles from
stylesheets that have been loaded. It takes a document node as input and returns
the computed style that applies to that node. For example, it can be used to
answer the question "What style should this <h1> element have?"

CSS selectors can be complex and apply to certain arrangments of elements within
a document tree. Therefore LibCSS has to be able to navigate your document tree
and read attributes of it to determine if a style applies. It does this through
a series of functions that you supply. In this way LibCSS is independent of the
representation of the document. For example, with the style rule:

  table h2 { color: red; }

when requesting the style for an h2 element node, LibCSS will search its
ancestors for a table element to determine if this style applies.

The first step in using the Selection API is creating a selection context. This
is a list of the stylesheets to be used. A context is created using
css_select_ctx_create():

  css_select_ctx *select_ctx;
  code = css_select_ctx_create(myrealloc, 0, &select_ctx);
  if (code != CSS_OK)
    ...

Stylesheets are added to the context using css_select_ctx_append_sheet():

  code = css_select_ctx_append_sheet(select_ctx, sheet, CSS_ORIGIN_AUTHOR,
                                     CSS_MEDIA_ALL);
  if (code != CSS_OK)
    ...

When adding a stylesheet, the origin and media can be specified. These are used
in the computation of styles as defined in the CSS specification.

Alternatively stylesheets may be added using css_select_ctx_insert_sheet().

After the context has been prepared, an empty computed style is created:

  css_computed_style *style;
  code = css_computed_style_create(myrealloc, 0, &style);
  if (code != CSS_OK)
    ...

The style is then determined for a document node using css_select_style():

  code = css_select_style(select_ctx, element_node, 0,
                          CSS_MEDIA_SCREEN, NULL, style,
                          &select_handler, 0);
  if (code != CSS_OK)
    ...

The arguments are as follows:

  css_select_ctx *ctx
    The selection context, as described above.

  void *node
    A pointer to the document node for which the style is required. This is a
    void pointer and may therefore be of any desired type. LibCSS can not use it
    directly; instead it gets information about it through the functions given
    in the handler argument, described below. Usually this will be a node in a
    document tree.

  uint32_t pseudo_element
  
  uint64_t media
    The media that the style should apply to. The computed style will only
    consider stylesheets or @media blocks that include this media. See the CSS
    specification for more details.
  
  const css_stylesheet *inline_style

  css_computed_style *result
    Updated to the computed style for the node.

  css_select_handler *handler
    This is a table of functions that are used to get information from and to
    navigate the document tree, in order to determine if a CSS selector matches
    the document node. Further details are below.

  void *pw
    A private data pointer that is passed to each of the handler functions.

The types of the handler functions that need to be supplied and the definition
of css_select_handler are given in libcss/select.h. The functions all have the
following in common:

 * the first argument is the private data pointer that was the last argument to
   css_select_style()

 * the second argument is the document node that is being queried is some way

 * the last one or two arguments are pointers that must be updated with the
   required information
 
 * the return value is a css_error and should be CSS_OK if everything worked and
   an error code otherwise

For example, the node_name function, which determines the element name of a
node, could be this:

  css_error node_name(void *pw, void *n, lwc_string **name)
  {
    my_document_node *node = n;
    *name = lwc_string_ref(node->name);
    return CSS_OK;
  }

where my_document_node is your document tree node type (e.g. a struct of some
sort).


Use the computed styles
-----------------------

After the style has been computed by css_select_style() the CSS properties can
finally be retrieved. This is done using the property accessor functions
declared in libcss/computed.h.

Note that although struct css_computed_style is declared in computed.h, its
members must not be used directly. The accessors carry out various additional
work to read the properties correctly.

For example, the css_computed_color() accessor retrieves the color property:

  uint8_t color_type;
  css_color color_shade;
  color_type = css_computed_color(style, &color_shade);

In this case color_type can be CSS_COLOR_INHERIT or CSS_COLOR_COLOR. In the
latter case, color_shade contains the actual color in RRGGBBAA format. Together
these two variables encode the possible values for the property given by the
CSS specification.