GXPSDocumentStructure

## GXPSDocumentStructure GXPSDocumentStructure — Structure of XPS Document |

## Synopsis

    #include <libgxps/gxps.h>

    struct              GXPSDocumentStructure;
    struct              GXPSOutlineIter;
    gboolean            gxps_document_structure_has_outline (GXPSDocumentStructure *structure);

    gboolean            gxps_document_structure_outline_iter_init
                                                            (GXPSOutlineIter *iter,
                                                             GXPSDocumentStructure *structure);
    gboolean            gxps_outline_iter_next              (GXPSOutlineIter *iter);
    gboolean            gxps_outline_iter_children          (GXPSOutlineIter *iter,
                                                             GXPSOutlineIter *parent);
    const gchar *       gxps_outline_iter_get_description   (GXPSOutlineIter *iter);
    GXPSLinkTarget *    gxps_outline_iter_get_target        (GXPSOutlineIter *iter);

## Object Hierarchy

      GObject
       +----GXPSDocumentStructure

## Properties

      "archive"                  GXPSArchive*          : Write / Construct Only
      "source"                   gchar*                : Write / Construct Only

## Description

GXPSDocumentStructure represents the structural organization of a XPS document. A GXPSDocumentStructure can contain the document outline, similar to a table of contents, containing hyperlinks. To iterate over the outline items you can use GXPSOutlineIter.

GXPSDocumentStructure objects can not be created directly, they are retrieved from a GXPSDocument with `gxps_document_get_structure()`.

## Details

### struct GXPSDocumentStructure

    struct GXPSDocumentStructure;

The GXPSDocumentStructure struct contains only private fields and should not be directly accessed.

### struct GXPSOutlineIter

    struct GXPSOutlineIter {
    };

GXPSOutlineIter represents an iterator that can be used to iterate over the items of an outline contained in a GXPSDocumentStructure

### gxps_document_structure_has_outline ()

    gboolean            gxps_document_structure_has_outline (GXPSDocumentStructure *structure);

Whether `structure` has an outline or not.

`structure` : | a GXPSDocumentStructure
Returns : | `TRUE` if `structure` has an outline, `FALSE` otherwise.

### gxps_document_structure_outline_iter_init ()

    gboolean            gxps_document_structure_outline_iter_init
                                                            (GXPSOutlineIter *iter,
                                                             GXPSDocumentStructure *structure);

Initializes `iter` to the root item of the outline contained by `structure` and a associates it with `structure`.

Here is a simple example of some code that walks the full outline:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    static void
    walk_outline (GXPSOutlineIter *iter)
    {
        do {
            GXPSOutlineIter child_iter;
            const gchar    *description = gxps_outline_iter_get_description (iter);
            GXPSLinkTarget *target = gxps_outline_iter_get_target (iter);

            /* Do something with description and taregt */
            if (gxps_outline_iter_children (&child_iter, iter))
                walk_outline (&child_iter);
        } while (gxps_outline_iter_next (iter));
    }
    ...
    {
        GXPSOutlineIter iter;
        if (gxps_document_structure_outline_iter_init (&iter, structure))
            walk_outline (&iter);
    }

`iter` : | an uninitialized GXPSOutlineIter
`structure` : | a GXPSDocumentStructure
Returns : | `TRUE` if `iter` was successfully initialized to the root item, `FALSE` if it failed or `structure` does not have an outline.

### gxps_outline_iter_next ()

    gboolean            gxps_outline_iter_next              (GXPSOutlineIter *iter);

Advances `iter` to the next item at the current level. See `gxps_document_structure_outline_iter_init()` for more details.

`iter` : | an initialized GXPSOutlineIter
Returns : | `TRUE` if `iter` was set to the next item, `FALSE` if the end of the current level has been reached

### gxps_outline_iter_children ()

    gboolean            gxps_outline_iter_children          (GXPSOutlineIter *iter,
                                                             GXPSOutlineIter *parent);

Initializes `iter` to the first child item of `parent`. See `gxps_document_structure_outline_iter_init()` for more details.

`iter` : | an uninitialized GXPSOutlineIter
`parent` : | an initialized GXPSOutlineIter
Returns : | `TRUE` if `iter` was set to the first child of `parent`, `FALSE` if `parent` does not have children.

### gxps_outline_iter_get_description ()

    const gchar *       gxps_outline_iter_get_description   (GXPSOutlineIter *iter);

Gets the description of the outline item associated with `iter`. See `gxps_document_structure_outline_iter_init()` for more details.

`iter` : | an initialized GXPSOutlineIter
Returns : | the description of the outline item

### gxps_outline_iter_get_target ()

    GXPSLinkTarget *    gxps_outline_iter_get_target        (GXPSOutlineIter *iter);

Gets the GXPSLinkTarget of the outline item associated with `iter`. See `gxps_document_structure_outline_iter_init()` for more details.

`iter` : | an initialized GXPSOutlineIter
Returns : | a new allocated GXPSLinkTarget. Free the returned object with `gxps_link_target_free()`.

## Property Details

### The `"archive"` property

      "archive"                  GXPSArchive*          : Write / Construct Only

The document archive.

### The `"source"` property

      "source"                   gchar*                : Write / Construct Only

The DocStructure Source File.

Default value: NULL

## See Also

GXPSDocument, GXPSLinkTarget