## FoArea FoArea |

## Synopsis

                        FoArea;
                        FoAreaClass;
    FoArea*             fo_area_new                         (void);
    FoArea*             fo_area_get_page                    (FoArea *fo_area);
    FoArea*             fo_area_get_reference               (FoArea *fo_area);
    FoArea*             fo_area_get_page_sequence           (FoArea *fo_area);
    gboolean            fo_area_get_is_first                (FoArea *fo_area);
    gboolean            fo_area_get_is_last                 (FoArea *fo_area);
    gfloat              fo_area_get_next_x                  (FoArea *fo_area);
    void                fo_area_set_next_x                  (FoArea *fo_area,
                                                             gfloat new_next_x);
    gfloat              fo_area_get_next_y                  (FoArea *fo_area);
    void                fo_area_set_next_y                  (FoArea *fo_area,
                                                             gfloat new_next_y);
    gfloat              fo_area_get_available_width         (FoArea *fo_area);
    void                fo_area_set_available_width         (FoArea *fo_area,
                                                             gfloat new_available_width);
    gfloat              fo_area_get_available_height        (FoArea *fo_area);
    void                fo_area_set_available_height        (FoArea *fo_area,
                                                             gfloat new_available_height);
    gfloat              fo_area_get_child_available_ipdim   (FoArea *fo_area);
    void                fo_area_set_child_available_ipdim   (FoArea *fo_area,
                                                             gfloat new_child_available_ipdim);
    gfloat              fo_area_get_child_available_bpdim   (FoArea *fo_area);
    void                fo_area_set_child_available_bpdim   (FoArea *fo_area,
                                                             gfloat new_child_available_bpdim);
    FoFo*               fo_area_get_generated_by            (FoArea *fo_area);
    void                fo_area_set_generated_by            (FoArea *fo_area,
                                                             FoFo *new_fo);
    FoArea*             fo_area_add_child                   (FoArea *parent,
                                                             FoArea *child);
    FoArea*             fo_area_size_request                (FoArea *child);
    void                fo_area_debug_dump_properties       (FoArea *area,
                                                             gint depth);
    void                fo_area_border_padding_space_resolve
                                                            (FoArea *parent_area,
                                                             FoArea *child_area);
    FoArea*             fo_area_break_resolve               (FoArea *parent_area,
                                                             FoArea *new_area);
    void                fo_area_set_height_from_children    (FoArea *parent_area);
    FoArea*             fo_area_clone                       (FoArea *original);
    void                fo_area_update_after_clone          (FoArea *clone,
                                                             FoArea *original);
    FoArea*             fo_area_split_before_height         (FoArea *area,
                                                             gfloat height);
    gboolean            fo_area_split_before_height_check   (FoArea *area,
                                                             gfloat height);
    void                fo_area_resolve_text_align          (FoArea *area);
    gboolean            (*FoAreaTraverseFunc)               (FoArea *area,
                                                             gpointer data);
    void                (*FoAreaForeachFunc)                (FoArea *area,
                                                             gpointer data);
    #define             FO_AREA_IS_ROOT                     (area)
    #define             FO_AREA_IS_LEAF                     (area)
    FoArea*             fo_area_insert                      (FoArea *parent,
                                                             gint position,
                                                             FoArea *area);
    FoArea*             fo_area_insert_before               (FoArea *parent,
                                                             FoArea *sibling,
                                                             FoArea *area);
    FoArea*             fo_area_insert_after                (FoArea *parent,
                                                             FoArea *sibling,
                                                             FoArea *area);
    FoArea*             fo_area_prepend                     (FoArea *parent,
                                                             FoArea *area);
    guint               fo_area_n_areas                     (FoArea *root,
                                                             GTraverseFlags flags);
    FoArea*             fo_area_get_root                    (FoArea *area);
    gboolean            fo_area_is_ancestor                 (FoArea *area,
                                                             FoArea *descendant);
    guint               fo_area_depth                       (FoArea *area);
    FoArea*             fo_area_append                      (FoArea *parent,
                                                             FoArea *area);
    void                fo_area_traverse                    (FoArea *root,
                                                             GTraverseType order,
                                                             GTraverseFlags flags,
                                                             gint max_depth,
                                                             FoAreaTraverseFunc func,
                                                             gpointer data);
    guint               fo_area_max_height                  (FoArea *root);
    void                fo_area_children_foreach            (FoArea *area,
                                                             GTraverseFlags flags,
                                                             FoAreaForeachFunc func,
                                                             gpointer data);
    void                fo_area_reverse_children            (FoArea *area);
    guint               fo_area_n_children                  (FoArea *area);
    FoArea*             fo_area_nth_child                   (FoArea *area,
                                                             guint n);
    FoArea*             fo_area_last_child                  (FoArea *area);
    guint               fo_area_child_position              (FoArea *area,
                                                             FoArea *child);
    FoArea*             fo_area_first_sibling               (FoArea *area);
    FoArea*             fo_area_last_sibling                (FoArea *area);
    FoArea*             fo_area_prev_sibling                (FoArea *area);
    FoArea*             fo_area_next_sibling                (FoArea *area);
    FoArea*             fo_area_first_child                 (FoArea *area);
    FoArea*             fo_area_parent                      (FoArea *area);
    void                fo_area_unlink                      (FoArea *area);
    void                fo_area_unlink_with_next_siblings   (FoArea *area);
    FoArea*             fo_area_insert_with_next_siblings   (FoArea *parent,
                                                             gint position,
                                                             FoArea *area);

## Object Hierarchy

      GObject
       +----FoObject
             +----FoNode
                   +----FoArea
                         +----FoAreaArea
                         +----FoAreaTree

## Properties

      "available-height"         gfloat                : Read / Write
      "available-width"          gfloat                : Read / Write
      "child-available-bpdim"    gfloat                : Read / Write
      "child-available-ipdim"    gfloat                : Read / Write
      "generated-by"             FoFo*                 : Read / Write
      "is-first"                 gboolean              : Read
      "is-last"                  gboolean              : Read
      "next-x"                   gfloat                : Read / Write
      "next-y"                   gfloat                : Read / Write
      "page"                     FoArea*               : Read
      "page-sequence"            FoFo*                 : Read / Write

## Description

## Details

### FoArea

    typedef struct _FoArea FoArea;

Instance of the base class for area objects.

### FoAreaClass

    typedef struct _FoAreaClass FoAreaClass;

Class structure for the base class for area objects.

### fo_area_new ()

    FoArea*             fo_area_new                         (void);

Creates a new FoArea initialized to default value.

Returns : | the new FoArea

### fo_area_get_page ()

    FoArea*             fo_area_get_page                    (FoArea *fo_area);

Gets the page property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "page" property value

### fo_area_get_reference ()

    FoArea*             fo_area_get_reference               (FoArea *fo_area);

Gets the reference property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "reference" property value

### fo_area_get_page_sequence ()

    FoArea*             fo_area_get_page_sequence           (FoArea *fo_area);

Gets the page_sequence property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "page-sequence" property value

### fo_area_get_is_first ()

    gboolean            fo_area_get_is_first                (FoArea *fo_area);

Gets the is_first property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "is-first" property value

### fo_area_get_is_last ()

    gboolean            fo_area_get_is_last                 (FoArea *fo_area);

Gets the is_last property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "is-last" property value

### fo_area_get_next_x ()

    gfloat              fo_area_get_next_x                  (FoArea *fo_area);

Gets the next_x property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "next_x" property value

### fo_area_set_next_x ()

    void                fo_area_set_next_x                  (FoArea *fo_area,
                                                             gfloat new_next_x);

Sets the next-x property of `area` to `new_next_x`

`fo_area` : | The `FoArea` object
`new_next_x` : | The new "next_x" property value

### fo_area_get_next_y ()

    gfloat              fo_area_get_next_y                  (FoArea *fo_area);

Gets the "next_y" property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "next-y" property value

### fo_area_set_next_y ()

    void                fo_area_set_next_y                  (FoArea *fo_area,
                                                             gfloat new_next_y);

Sets the next-y property of `area` to `new_next_y`

`fo_area` : | The `FoArea` object
`new_next_y` : | The new "next-y" property value

### fo_area_get_available_width ()

    gfloat              fo_area_get_available_width         (FoArea *fo_area);

Gets the "available-width" property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "available-width" property value

### fo_area_set_available_width ()

    void                fo_area_set_available_width         (FoArea *fo_area,
                                                             gfloat new_available_width);

Sets the "available-width" property of `area` to `new_available_width`

`fo_area` : | The `FoArea` object
`new_available_width` : | The new "available-width" property value

### fo_area_get_available_height ()

    gfloat              fo_area_get_available_height        (FoArea *fo_area);

Gets the available-height property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "available_height" property value

### fo_area_set_available_height ()

    void                fo_area_set_available_height        (FoArea *fo_area,
                                                             gfloat new_available_height);

Sets the available-height property of `area` to `new_available_height`

`fo_area` : | The `FoArea` object
`new_available_height` : | The new "available-height" property value

### fo_area_get_child_available_ipdim ()

    gfloat              fo_area_get_child_available_ipdim   (FoArea *fo_area);

Gets the "child-available-ipdim" property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "child-available-ipdim" property value

### fo_area_set_child_available_ipdim ()

    void                fo_area_set_child_available_ipdim   (FoArea *fo_area,
                                                             gfloat new_child_available_ipdim);

Sets the "child-available-ipdim" property of `area` to `new_child_available_ipdim`

`fo_area` : | The `FoArea` object
`new_child_available_ipdim` : | The new "child-available-ipdim" property value

### fo_area_get_child_available_bpdim ()

    gfloat              fo_area_get_child_available_bpdim   (FoArea *fo_area);

Gets the "child-available-bpdim" property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "child-available-bpdim" property value

### fo_area_set_child_available_bpdim ()

    void                fo_area_set_child_available_bpdim   (FoArea *fo_area,
                                                             gfloat new_child_available_bpdim);

Sets the "child-available-bpdim" property of `area` to `new_child_available_bpdim`

`fo_area` : | The `FoArea` object
`new_child_available_bpdim` : | The new "child-available-bpdim" property value

### fo_area_get_generated_by ()

    FoFo*               fo_area_get_generated_by            (FoArea *fo_area);

Gets the generated-by property of `area`

`fo_area` : | The `FoArea` object
Returns : | The "generated-by" property value

### fo_area_set_generated_by ()

    void                fo_area_set_generated_by            (FoArea *fo_area,
                                                             FoFo *new_fo);

Sets the generated-by property of `area` to `new_fo`

`fo_area` : | The `FoArea` object
`new_fo` : | The new "generated-by" property value

### fo_area_add_child ()

    FoArea*             fo_area_add_child                   (FoArea *parent,
                                                             FoArea *child);

Add `child` to `parent` by calling the `_add_child()` function for `parent`.

`parent` : | Parent area node
`child` : | Child area node
Returns : | `child`

### fo_area_size_request ()

    FoArea*             fo_area_size_request                (FoArea *child);

Checks that the parent area of `child` has sufficient space for `child`. If not enough space, requests that the parent has sufficient space allocated for it, then adjusts `child` and its siblings as necessary to fit into the resized parent area.

You should call #`fo_area_size_request()` immediately after adding an area to the area tree or making a change to the area's height.

The child area's requested height is taken from the area's height property value. Its requested width is taken from its width property value.

The height allocated to the area is set in the area's available_height property value. Its width allocation is set in its available_width property value.

Immediately after calling this function, the child area should set its height and width according to the available_height and available_width property values. How the child area resolves any difference between the available height and width and the height and width that it needs is up to the child area to work out.

The child area's x and y property values may also have been adjusted, but a child area doesn't set its own x and y property values anyway.

The area that is returned may be a different area object than the child area that is passed as the argument to this function. For example, the parent area may not have been large enough to contain the child area at its requested height, and the child area, the parent area, and all ancestor areas up to an FoAreaPage may have been split (possibly more than once) and the overflow placed on one or more new pages.

`child` : | Child area
Returns : | Pointer to the last area generated from `child` after any reallocation and resizing

### fo_area_debug_dump_properties ()

    void                fo_area_debug_dump_properties       (FoArea *area,
                                                             gint depth);

Dump the properties of `area`.

`area` : | The FoArea object
`depth` : | Indent level to add to the output

### fo_area_border_padding_space_resolve ()

    void                fo_area_border_padding_space_resolve
                                                            (FoArea *parent_area,
                                                             FoArea *child_area);

Resolves the border, padding, and space properties of `child_area`.

`parent_area` : | Parent area of `child_area`.
`child_area` : | FoArea for which to resolve properties.

### fo_area_break_resolve ()

    FoArea*             fo_area_break_resolve               (FoArea *parent_area,
                                                             FoArea *new_area);

Resolves the break properties of `new_area`, which may result in `new_area` being split into multiple areas.

`parent_area` : | Parent area of `new_area`.
`new_area` : | FoArea for which to resolve breaks.
Returns : | Last area resulting from resolving breaks.

### fo_area_set_height_from_children ()

    void                fo_area_set_height_from_children    (FoArea *parent_area);

`parent_area` : |

### fo_area_clone ()

    FoArea*             fo_area_clone                       (FoArea *original);

Make a clone of `original` and insert the clone after `original` in the area tree. Set instance properties of the clone to match `original`.

`original` : | Area object to be cloned.
Returns : | Clone of `original`.

### fo_area_update_after_clone ()

    void                fo_area_update_after_clone          (FoArea *clone,
                                                             FoArea *original);

Update the instance variables of `clone` to match those of `original`.

`clone` : | New object cloned from `original`.
`original` : | Original area object.

### fo_area_split_before_height ()

    FoArea*             fo_area_split_before_height         (FoArea *area,
                                                             gfloat height);

Split `area` at or before `height`.

`area` : | FoArea to be split
`height` : | Maximum block-progression-dimension of `area`
Returns : | The part of `area` spit from `area`, or NULL if unsplit.

### fo_area_split_before_height_check ()

    gboolean            fo_area_split_before_height_check   (FoArea *area,
                                                             gfloat height);

Check whether `area` can split at or before `height`.

`area` : | FoArea to be split
`height` : | Maximum block-progression-dimension of `area`
Returns : | TRUE if can split, otherwise FALSE.

### fo_area_resolve_text_align ()

    void                fo_area_resolve_text_align          (FoArea *area);

Resolves the text alignment value for `area` and its descendants.

`area` : | FoArea for which to resolve text alignment.

### FoAreaTraverseFunc ()

    gboolean            (*FoAreaTraverseFunc)               (FoArea *area,
                                                             gpointer data);

`area` : |
`data` : |
Returns : |

### FoAreaForeachFunc ()

    void                (*FoAreaForeachFunc)                (FoArea *area,
                                                             gpointer data);

`area` : |
`data` : |

### FO_AREA_IS_ROOT()

    #define FO_AREA_IS_ROOT(area)    (FO_NODE_IS_ROOT(((FoNode*) (area))))

`area` : |

### FO_AREA_IS_LEAF()

    #define FO_AREA_IS_LEAF(area)    (FO_NODE_IS_LEAF(((FoNode*) (area))))

`area` : |

### fo_area_insert ()

    FoArea*             fo_area_insert                      (FoArea *parent,
                                                             gint position,
                                                             FoArea *area);

`parent` : |
`position` : |
`area` : |
Returns : |

### fo_area_insert_before ()

    FoArea*             fo_area_insert_before               (FoArea *parent,
                                                             FoArea *sibling,
                                                             FoArea *area);

`parent` : |
`sibling` : |
`area` : |
Returns : |

### fo_area_insert_after ()

    FoArea*             fo_area_insert_after                (FoArea *parent,
                                                             FoArea *sibling,
                                                             FoArea *area);

`parent` : |
`sibling` : |
`area` : |
Returns : |

### fo_area_prepend ()

    FoArea*             fo_area_prepend                     (FoArea *parent,
                                                             FoArea *area);

Inserts a FoArea as the first child of the given parent and updates the inserted FoArea.

`parent` : | the FoArea to place the new FoArea under.
`area` : | the FoArea to insert.
Returns : | the inserted FoArea.

### fo_area_n_areas ()

    guint               fo_area_n_areas                     (FoArea *root,
                                                             GTraverseFlags flags);

Gets the number of nodes in a tree.

`root` : | a FoArea.
`flags` : | which types of children are to be counted, one of `G_TRAVERSE_ALL`, `G_TRAVERSE_LEAFS` and `G_TRAVERSE_NON_LEAFS`.
Returns : | the number of nodes in the tree.

### fo_area_get_root ()

    FoArea*             fo_area_get_root                    (FoArea *area);

`area` : |
Returns : |

### fo_area_is_ancestor ()

    gboolean            fo_area_is_ancestor                 (FoArea *area,
                                                             FoArea *descendant);

`area` : |
`descendant` : |
Returns : |

### fo_area_depth ()

    guint               fo_area_depth                       (FoArea *area);

Gets the depth of a FoArea.

If `area` is `NULL` the depth is 0. The root node has a depth of 1. For the children of the root node the depth is 2. And so on.

`area` : | a FoArea.
Returns : | the depth of the FoArea.

### fo_area_append ()

    FoArea*             fo_area_append                      (FoArea *parent,
                                                             FoArea *area);

Inserts a FoArea as the last child of the given parent and updates the inserted FoArea.

`parent` : | the FoArea to place the new FoArea under.
`area` : | the FoArea to insert.
Returns : | the inserted FoArea.

### fo_area_traverse ()

    void                fo_area_traverse                    (FoArea *root,
                                                             GTraverseType order,
                                                             GTraverseFlags flags,
                                                             gint max_depth,
                                                             FoAreaTraverseFunc func,
                                                             gpointer data);

`root` : |
`order` : |
`flags` : |
`max_depth` : |
`func` : |
`data` : |

### fo_area_max_height ()

    guint               fo_area_max_height                  (FoArea *root);

Gets the maximum height of all branches beneath a FoArea. This is the maximum distance from the FoArea to all leaf nodes.

If `root` is `NULL`, 0 is returned. If `root` has no children, 1 is returned. If `root` has children, 2 is returned. And so on.

`root` : | Root node of a FoArea tree.
Returns : | the maximum height of the tree beneath `root`.

### fo_area_children_foreach ()

    void                fo_area_children_foreach            (FoArea *area,
                                                             GTraverseFlags flags,
                                                             FoAreaForeachFunc func,
                                                             gpointer data);

Calls a function for each of the children of a FoArea. Note that it doesn't descend beneath the child nodes.

`area` : | a FoArea.
`flags` : | which types of children are to be visited, one of `G_TRAVERSE_ALL`, `G_TRAVERSE_LEAFS` and `G_TRAVERSE_NON_LEAFS`.
`func` : | the function to call for each visited node.
`data` : | user data to pass to the function.

### fo_area_reverse_children ()

    void                fo_area_reverse_children            (FoArea *area);

Reverses the order of the children of a FoArea. (It doesn't change the order of the grandchildren.)

`area` : | a FoArea.

### fo_area_n_children ()

    guint               fo_area_n_children                  (FoArea *area);

Gets the number of children of a FoArea.

`area` : | a FoArea.
Returns : | the number of children of `area`.

### fo_area_nth_child ()

    FoArea*             fo_area_nth_child                   (FoArea *area,
                                                             guint n);

Gets a child of a FoArea, using the given index. The first child is at index 0. If the index is too big, `NULL` is returned.

`area` : | a FoArea.
`n` : | the index of the desired child.
Returns : | the child of `area` at index `n`.

### fo_area_last_child ()

    FoArea*             fo_area_last_child                  (FoArea *area);

Gets the last child of a FoArea.

`area` : | a FoArea (nust not be `NULL`).
Returns : | the last child of `area`, or `NULL` if `area` has no children.

### fo_area_child_position ()

    guint               fo_area_child_position              (FoArea *area,
                                                             FoArea *child);

Gets the position of a FoArea with respect to its siblings. `child` must be a child of `area`. The first child is numbered 0, the second 1, and so on.

`area` : | a FoArea.
`child` : | a child of `area`.
Returns : | the position of `child` with respect to its siblings.

### fo_area_first_sibling ()

    FoArea*             fo_area_first_sibling               (FoArea *area);

Gets the first sibling of a FoArea. This could possibly be the node itself.

`area` : | a FoArea.
Returns : | the first sibling of `area`.

### fo_area_last_sibling ()

    FoArea*             fo_area_last_sibling                (FoArea *area);

Gets the last sibling of a FoArea. This could possibly be the node itself.

`area` : | a FoArea.
Returns : | the last sibling of `area`.

### fo_area_prev_sibling ()

    FoArea*             fo_area_prev_sibling                (FoArea *area);

Gets the previous sibling of a FoArea.

`area` : | a FoArea.
Returns : | the previous sibling of `area`, or `NULL` if `area` is `NULL`.

### fo_area_next_sibling ()

    FoArea*             fo_area_next_sibling                (FoArea *area);

Gets the next sibling of a FoArea.

`area` : | a FoArea.
Returns : | the next sibling of `area`, or `NULL` if `area` is `NULL`.

### fo_area_first_child ()

    FoArea*             fo_area_first_child                 (FoArea *area);

Gets the first child of a FoArea.

`area` : | A FoArea.
Returns : | the first child of `area`, or `NULL` if `area` is `NULL` or has no children.

### fo_area_parent ()

    FoArea*             fo_area_parent                      (FoArea *area);

Gets the parent of a FoArea.

`area` : | a FoArea.
Returns : | the parent of `area`, or `NULL` if `area` is the root of the tree.

### fo_area_unlink ()

    void                fo_area_unlink                      (FoArea *area);

Unlinks an FoArea from an FoArea tree, resulting in two separate trees.

`area` : | the FoArea to unlink, which becomes the root of a new tree.

### fo_area_unlink_with_next_siblings ()

    void                fo_area_unlink_with_next_siblings   (FoArea *area);

Unlinks `area` and its following siblings.

`area` : | First FoArea to unlink.

### fo_area_insert_with_next_siblings ()

    FoArea*             fo_area_insert_with_next_siblings   (FoArea *parent,
                                                             gint position,
                                                             FoArea *area);

Implements fo_node_insert_with_next_siblings for FoArea.

`parent` : | FoArea to be parent of `area` and its siblings.
`position` : | Offset at which to insert `area` and its siblings.
`area` : | FoArea, possibly with following siblings.
Returns : | `parent` with `area` and siblings inserted.

## Property Details

### The `"available-height"` property

      "available-height"         gfloat                : Read / Write

Height available to child areas.

Default value: 0

### The `"available-width"` property

      "available-width"          gfloat                : Read / Write

Width available to child areas.

Allowed values: >= 0

Default value: 0

### The `"child-available-bpdim"` property

      "child-available-bpdim"    gfloat                : Read / Write

Block-progression-dimension available to child areas.

Allowed values: >= 0

Default value: 0

### The `"child-available-ipdim"` property

      "child-available-ipdim"    gfloat                : Read / Write

Inline-progression-dimension available to child areas.

Allowed values: >= 0

Default value: 0

### The `"generated-by"` property

      "generated-by"             FoFo*                 : Read / Write

Formatting object that generated this area.

### The `"is-first"` property

      "is-first"                 gboolean              : Read

Is this the first area produced by the formatting object?.

Default value: TRUE

### The `"is-last"` property

      "is-last"                  gboolean              : Read

Is this the last area produced by the formatting object?.

Default value: TRUE

### The `"next-x"` property

      "next-x"                   gfloat                : Read / Write

x-coordinate of next child area.

Allowed values: >= 0

Default value: 0

### The `"next-y"` property

      "next-y"                   gfloat                : Read / Write

y-coordinate of next child area.

Allowed values: >= 0

Default value: 0

### The `"page"` property

      "page"                     FoArea*               : Read

Ancestor FoAreaPage node in the area tree.

### The `"page-sequence"` property

      "page-sequence"            FoFo*                 : Read / Write

Ancestor fo:page_sequence node in the formatting object tree.