summaryrefslogtreecommitdiff
path: root/docs/API
diff options
context:
space:
mode:
authorJames Bursa <james@netsurf-browser.org>2010-09-16 02:04:38 +0000
committerJames Bursa <james@netsurf-browser.org>2010-09-16 02:04:38 +0000
commit81842e9a4d512fb573aff7d538a798130968c943 (patch)
tree005177ce37e72319b5f3d61c6d090560bd28852d /docs/API
parentea203a6dd8a241d33e4bd1a6b076006cac715776 (diff)
downloadlibcss-81842e9a4d512fb573aff7d538a798130968c943.tar.gz
libcss-81842e9a4d512fb573aff7d538a798130968c943.tar.bz2
LibCSS API documentation, part 1, along with a simple example.
svn path=/trunk/libcss/; revision=10783
Diffstat (limited to 'docs/API')
-rw-r--r--docs/API281
1 files changed, 281 insertions, 0 deletions
diff --git a/docs/API b/docs/API
new file mode 100644
index 0000000..a213871
--- /dev/null
+++ b/docs/API
@@ -0,0 +1,281 @@
+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.
+