## ccss_node_t

ccss_node_t

## Synopsis

    typedef             ccss_grammar_t;
    ccss_grammar_t *    ccss_grammar_create_css             (void);
    ccss_grammar_t *    ccss_grammar_create_generic         (void);
    void                ccss_grammar_destroy                (ccss_grammar_t *self);
    ccss_grammar_t *    ccss_grammar_reference              (ccss_grammar_t *self);
    unsigned int        ccss_grammar_get_reference_count    (ccss_grammar_t const *self);
    void                ccss_grammar_add_properties         (ccss_grammar_t *self,
                                                             ccss_property_class_t const *properties);
    ccss_property_class_t const * ccss_grammar_lookup_property
                                                            (ccss_grammar_t const *self,
                                                             char const *name);
    void                ccss_grammar_add_functions          (ccss_grammar_t *self,
                                                             ccss_function_t const *functions);
    ccss_function_t const * ccss_grammar_lookup_function    (ccss_grammar_t const *self,
                                                             char const *name);
    ccss_stylesheet_t * ccss_grammar_create_stylesheet      (ccss_grammar_t *self);
    ccss_stylesheet_t * ccss_grammar_create_stylesheet_from_buffer
                                                            (ccss_grammar_t *self,
                                                             char const *buffer,
                                                             size_t size,
                                                             void *user_data);
    ccss_stylesheet_t * ccss_grammar_create_stylesheet_from_file
                                                            (ccss_grammar_t *self,
                                                             char const *css_file,
                                                             void *user_data);
    char *              ccss_grammar_invoke_function        (ccss_grammar_t const *self,
                                                             char const *function_name,
                                                             CRTerm const *values,
                                                             void *user_data);
    typedef             ccss_node_t;
                        ccss_node_class_t;
    bool                (*ccss_node_is_a_f)                 (ccss_node_t *self,
                                                             char const *type_name);
    ccss_node_t *       (*ccss_node_get_container_f)        (ccss_node_t const *self);
    ccss_node_t *       (*ccss_node_get_base_style_f)       (ccss_node_t const *self);
    ptrdiff_t           (*ccss_node_get_instance_f)         (ccss_node_t const *self);
    const char *        (*ccss_node_get_id_f)               (ccss_node_t const *self);
    const char *        (*ccss_node_get_type_f)             (ccss_node_t const *self);
    const char *        (*ccss_node_get_class_f)            (ccss_node_t const *self);
    char *              (*ccss_node_get_attribute_f)        (ccss_node_t const *self,
                                                             char const *name);
    const char *        (*ccss_node_get_style_f)            (ccss_node_t const *self,
                                                             unsigned int descriptor);
    bool                (*ccss_node_get_viewport_f)         (ccss_node_t const *self,
                                                             double *x,
                                                             double *y,
                                                             double *width,
                                                             double *height);
    void                (*ccss_node_release_f)              (ccss_node_t *self);
    void                ccss_node_init                      (ccss_node_t *self,
                                                             ccss_node_class_t *node_class);

## Description

## Details

### ccss_grammar_t

    typedef struct ccss_grammar_ ccss_grammar_t;

Represents a context for the creation of stylesheets of similar kind.

### ccss_grammar_create_css ()

    ccss_grammar_t *    ccss_grammar_create_css             (void);

Create a new grammar instance that interprets suppported CSS rules.

Grammar objects provide a factory to create stylesheets of the same class.

Returns : | a new ccss_grammar_t instance.

### ccss_grammar_create_generic ()

    ccss_grammar_t *    ccss_grammar_create_generic         (void);

Create a new grammar instance.

Grammar objects provide a factory to create stylesheets of the same class.

Returns : | a new ccss_grammar_t instance.

### ccss_grammar_destroy ()

    void                ccss_grammar_destroy                (ccss_grammar_t *self);

Decreases the reference count on `self` by one. If the result is zero, then `self` and all associated resources are freed. See `ccss_grammar_reference()`.

`self` : | a ccss_grammar_t.

### ccss_grammar_reference ()

    ccss_grammar_t *    ccss_grammar_reference              (ccss_grammar_t *self);

Increases the reference count on `self` by one. This prevents `self` from being destroyed until a matching call to `ccss_grammar_destroy()` is made.

The number of references to a ccss_grammar_t can be acquired using `ccss_grammar_get_reference_count()`.

`self` : | a ccss_grammar_t.
Returns : | the referenced ccss_grammar_t.

### ccss_grammar_get_reference_count ()

    unsigned int        ccss_grammar_get_reference_count    (ccss_grammar_t const *self);

`self` : | a ccss_grammar_t.
Returns : | the current reference count of `self`. If `self` is a nil object, 0 will be returned.

### ccss_grammar_add_properties ()

    void                ccss_grammar_add_properties         (ccss_grammar_t *self,
                                                             ccss_property_class_t const *properties);

Register a set of custom CSS properties with the grammar.

`self` : | a ccss_grammar_t.
`properties` : | Null-terminated array of ccss_property_class_t to register.

### ccss_grammar_lookup_property ()

    ccss_property_class_t const * ccss_grammar_lookup_property
                                                            (ccss_grammar_t const *self,
                                                             char const *name);

Look up a property handler by name.

`self` : | a ccss_grammar_t.
`name` : | name of the property class to look up.
Returns : | the property handler or `NULL` if not found.

### ccss_grammar_add_functions ()

    void                ccss_grammar_add_functions          (ccss_grammar_t *self,
                                                             ccss_function_t const *functions);

Register a set of custom css function handlers with the grammar.

`self` : | a ccss_grammar_t.
`functions` : | Null-terminated array of ccss_function_t to register.

### ccss_grammar_lookup_function ()

    ccss_function_t const * ccss_grammar_lookup_function    (ccss_grammar_t const *self,
                                                             char const *name);

Look up a function handler by name.

`self` : | a ccss_grammar_t.
`name` : | name of the function handler to look up.
Returns : | the property handler or `NULL` if not found.

### ccss_grammar_create_stylesheet ()

    ccss_stylesheet_t * ccss_grammar_create_stylesheet      (ccss_grammar_t *self);

Create an empty stylesheet associated with grammar `self`.

`self` : | a ccss_grammar_t.
Returns : | an empty ccss_stylesheet_t.

### ccss_grammar_create_stylesheet_from_buffer ()

    ccss_stylesheet_t * ccss_grammar_create_stylesheet_from_buffer
                                                            (ccss_grammar_t *self,
                                                             char const *buffer,
                                                             size_t size,
                                                             void *user_data);

Create a new stylesheet instance based on a CSS string.

`self` : | a ccss_grammar_t.
`buffer` : | buffer to parse.
`size` : | size of the buffer.
`user_data` : | user-data passed to property- and function-handlers.
Returns : | a ccss_stylesheet_t representation of the CSS string.

### ccss_grammar_create_stylesheet_from_file ()

    ccss_stylesheet_t * ccss_grammar_create_stylesheet_from_file
                                                            (ccss_grammar_t *self,
                                                             char const *css_file,
                                                             void *user_data);

Create a new stylesheet instance based on a CSS file.

`self` : | a ccss_grammar_t.
`css_file` : | file to parse.
`user_data` : | user-data passed to property- and function-handlers.
Returns : | a ccss_stylesheet_t representation of the CSS file.

### ccss_grammar_invoke_function ()

    char *              ccss_grammar_invoke_function        (ccss_grammar_t const *self,
                                                             char const *function_name,
                                                             CRTerm const *values,
                                                             void *user_data);

Invoke a registerd function handler. This API is meant to be used by property implementations, like when parsing properties like `background-image: url(foo.png)'.

`self` : | a ccss_grammar_t.
`function_name` : | name of the function to invoke, e.g. `url`.
`values` : | arguments passed to the function handler.
`user_data` : | user-data passed to the function handler. Overrides the user-data assigned in the function handler's definition.
Returns : | string value passed back by the ccss API consumer.

### ccss_node_t

    typedef struct ccss_node_ ccss_node_t;

Stack-allocatable struct representing a document node. Used for querying the ccss_stylesheet_t.

Memory management: Unless specified otherwise, objects of this kind are under the responsibility of the libccss consumer.

### ccss_node_class_t

    typedef struct {
    	ccss_node_is_a_f		is_a;
    	ccss_node_get_container_f get_container;
    	ccss_node_get_base_style_f get_base_style;
    	ccss_node_get_instance_f get_instance;
    	ccss_node_get_id_f		get_id;
    	ccss_node_get_type_f		get_type;
    	ccss_node_get_class_f		get_class;
    	ccss_node_get_pseudo_classes_f get_pseudo_classes;
    	ccss_node_get_attribute_f get_attribute;
    	ccss_node_get_style_f		get_style;
    	ccss_node_get_viewport_f get_viewport;
    	ccss_node_release_f		release;
    } ccss_node_class_t;

Dispatch table a CCSS consumer has to fill so the selection engine can retrieve information about the document the document.

The implemented dispatch table needs to be passed to ccss_node_init.

ccss_node_is_a_f `is_a`; | a ccss_node_is_a_f.
ccss_node_get_container_f `get_container`; | a ccss_node_get_container_f.
ccss_node_get_base_style_f `get_base_style`; | a ccss_node_get_base_style_f.
ccss_node_get_instance_f `get_instance`; | a ccss_node_get_instance_f.
ccss_node_get_id_f `get_id`; | a ccss_node_get_id_f.
ccss_node_get_type_f `get_type`; | a ccss_node_get_type_f.
ccss_node_get_class_f `get_class`; | a ccss_node_get_class_f.
ccss_node_get_pseudo_classes_f `get_pseudo_classes`; | a ccss_node_get_pseudo_classes_f.
ccss_node_get_attribute_f `get_attribute`; | a ccss_node_get_attribute_f.
ccss_node_get_style_f `get_style`; | a ccss_node_get_style_f.
ccss_node_get_viewport_f `get_viewport`; | a ccss_node_get_viewport_f.
ccss_node_release_f `release`; | a ccss_node_release_f.

### ccss_node_is_a_f ()

    bool                (*ccss_node_is_a_f)                 (ccss_node_t *self,
                                                             char const *type_name);

Hook function to query whether a ccss_node_t is of a certain type.

`self` : | a ccss_node_t.
`type_name` : | name to match against, e.g. `div`.
Returns : | `TRUE` if matches.

### ccss_node_get_container_f ()

    ccss_node_t *       (*ccss_node_get_container_f)        (ccss_node_t const *self);

Hook function to query the container of a ccss_node_t.

`self` : | a ccss_node_t.
Returns : | newly allocated container node or `NULL`.

### ccss_node_get_base_style_f ()

    ccss_node_t *       (*ccss_node_get_base_style_f)       (ccss_node_t const *self);

Hook function to query the name of the style a ccss_node_t derives from.

`self` : | a ccss_node_t.
Returns : | base style or `NULL`. The returned value must be valid until it is released.

### ccss_node_get_instance_f ()

    ptrdiff_t           (*ccss_node_get_instance_f)         (ccss_node_t const *self);

Hook function to query for a unique numerical representation of a ccss_node_t.

`self` : | a ccss_node_t.
Returns : | unique numerical id or 0. If 0 is returned, node-based css style will not be considered.

### ccss_node_get_id_f ()

    const char *        (*ccss_node_get_id_f)               (ccss_node_t const *self);

Hook function to query the ID of a ccss_node_t.

`self` : | a ccss_node_t.
Returns : | node ID or `NULL`. The returned value must be valid until the current stylesheet query returns.

### ccss_node_get_type_f ()

    const char *        (*ccss_node_get_type_f)             (ccss_node_t const *self);

Hook function to query the type name of a ccss_node_t.

`self` : | a ccss_node_t.
Returns : | node type name or `NULL`. The returned value must be valid until the current stylesheet query returns.

### ccss_node_get_class_f ()

    const char *        (*ccss_node_get_class_f)            (ccss_node_t const *self);

Hook function to query the class name of a ccss_node_t.

`self` : | a ccss_node_t.
Returns : | node class name or `NULL`. The returned value must be valid until the current stylesheet query returns.

### ccss_node_get_attribute_f ()

    char *              (*ccss_node_get_attribute_f)        (ccss_node_t const *self,
                                                             char const *name);

Hook function to query a ccss_node_t's attributes.

`self` : | a ccss_node_t.
`name` : | attribute name.
Returns : | attribute value or `NULL`. The returned value must be valid until the current stylesheet query returns.

### ccss_node_get_style_f ()

    const char *        (*ccss_node_get_style_f)            (ccss_node_t const *self,
                                                             unsigned int descriptor);

Hook function to query a ccss_node_t's inline CSS style.

See: `ccss_stylesheet_unload()`.

`self` : | a ccss_node_t.
`descriptor` : | handle to unload this style from the stylesheet later on.
Returns : | the node's CSS properties or `NULL`.

### ccss_node_get_viewport_f ()

    bool                (*ccss_node_get_viewport_f)         (ccss_node_t const *self,
                                                             double *x,
                                                             double *y,
                                                             double *width,
                                                             double *height);

Hook function to determine the position of a node in the viewport.

`self` : | a ccss_node_t.
`x` : | horizontal position.
`y` : | vertical position.
`width` : | width of viewport.
`height` : | height of viewport.
Returns : | `TRUE` if a valid viewport position has been assigned to the out parameters.

### ccss_node_release_f ()

    void                (*ccss_node_release_f)              (ccss_node_t *self);

Hook function to deallocate a ccss_node_t instance.

`self` : | a ccss_node_t.

### ccss_node_init ()

    void                ccss_node_init                      (ccss_node_t *self,
                                                             ccss_node_class_t *node_class);

Initializes `node_class` by filling unset functions with the default implementations and attaches it to `self`.

`self` : | a ccss_node_t embedding structure.
`node_class` : | a ccss_node_class_t vtable.