fitz/outline.h

Index

Outline

enum fz_outline_flag

enum fz_outline_flag
{
        FZ_OUTLINE_FLAG_BOLD = 1,
        FZ_OUTLINE_FLAG_ITALIC = 2,
}

enum fz_outline_iterator_state

enum fz_outline_iterator_state
{
        FZ_OUTLINE_ITERATOR_DID_NOT_MOVE = -1,
        FZ_OUTLINE_ITERATOR_AT_ITEM = 0,
        FZ_OUTLINE_ITERATOR_AT_EMPTY = 1,
}

function fz_outline_iterator_item

fz_outline_item *
fz_outline_iterator_item (
        fz_context *ctx,
        fz_outline_iterator *iter
)

Call to get the current outline item.

Can return NULL. The item is only valid until the next call.

function fz_outline_iterator_next

int
fz_outline_iterator_next (
        fz_context *ctx,
        fz_outline_iterator *iter
)

Calls to move the iterator position.

A negative return value means we could not move as requested. Otherwise: 0 = the final position has a valid item. 1 = not a valid item, but we can insert an item here.

function fz_outline_iterator_prev

int
fz_outline_iterator_prev (
        fz_context *ctx,
        fz_outline_iterator *iter
)

function fz_outline_iterator_up

int
fz_outline_iterator_up (
        fz_context *ctx,
        fz_outline_iterator *iter
)

function fz_outline_iterator_down

int
fz_outline_iterator_down (
        fz_context *ctx,
        fz_outline_iterator *iter
)

function fz_outline_iterator_insert

int
fz_outline_iterator_insert (
        fz_context *ctx,
        fz_outline_iterator *iter,
        fz_outline_item *item
)

Call to insert a new item BEFORE the current point.

Ownership of pointers are retained by the caller. The item data will be copied.

After an insert, we do not change where we are pointing. The return code is the same as for next, it indicates the current iterator position.

Note that for PDF documents at least, the is_open field is ignored. All childless nodes are considered closed by PDF, hence (given every newly inserted node is childless by definition) all new nodes are inserted with is_open == false.

function fz_outline_iterator_delete

int
fz_outline_iterator_delete (
        fz_context *ctx,
        fz_outline_iterator *iter
)

Delete the current item.

This implicitly moves us to the ‘next’ item, and the return code is as for fz_outline_iterator_next.

function fz_outline_iterator_update

void
fz_outline_iterator_update (
        fz_context *ctx,
        fz_outline_iterator *iter,
        fz_outline_item *item
)

Update the current item properties according to the given item.

function fz_drop_outline_iterator

void
fz_drop_outline_iterator (
        fz_context *ctx,
        fz_outline_iterator *iter
)

Drop the current iterator.

Structure based API

struct fz_outline

struct fz_outline
{
        int refs;
        char *title;
        char *uri;
        fz_location page;
        float x, y;
        struct fz_outline *next;
        struct fz_outline *down;
        unsigned int is_open : 1;
        unsigned int flags : 7;
        unsigned int r : 8;
        unsigned int g : 8;
        unsigned int b : 8;
}

fz_outline is a tree of the outline of a document (also known as table of contents).

title:: Title of outline item using UTF-8 encoding. May be NULL if the outline item has no text string.
uri:: Destination in the document to be displayed when this outline item is activated. May be an internal or external link, or NULL if the outline item does not have a destination.
page:: The page number of an internal link, or -1 for external links or links with no destination.
next:: The next outline item at the same level as this outline item. May be NULL if no more outline items exist at this level.
down:: The outline items immediate children in the hierarchy. May be NULL if no children exist.
is_open:: If zero, the outline element is closed in the UI. If 1, it should be open, showing any child elements.
flags:: Bit 0 set -> Bold, Bit 1 set -> Italic. All other bits reserved.
r, g, b:: The RGB components of the color of this entry.

function fz_new_outline

fz_outline *
fz_new_outline (
        fz_context *ctx
)

Create a new outline entry with zeroed fields for the caller to fill in.

function fz_keep_outline

fz_outline *
fz_keep_outline (
        fz_context *ctx,
        fz_outline *outline
)

Increment the reference count. Returns the same pointer.

Never throws exceptions.

function fz_drop_outline

void
fz_drop_outline (
        fz_context *ctx,
        fz_outline *outline
)

Decrements the reference count. When the reference point reaches zero, the outline is freed.

When freed, it will drop linked outline entries (next and down) too, thus a whole outline structure can be dropped by dropping the top entry.

Never throws exceptions.

function fz_load_outline_from_iterator

fz_outline *
fz_load_outline_from_iterator (
        fz_context *ctx,
        fz_outline_iterator *iter
)

Routine to implement the old Structure based API from an iterator.

Implementation details. Of use to people coding new document handlers.

typedef fz_outline_iterator_item_fn

typedef fz_outline_item *(fz_outline_iterator_item_fn)(fz_context *ctx, fz_outline_iterator *iter)

Function type for getting the current item.

Can return NULL. The item is only valid until the next call.

typedef fz_outline_iterator_next_fn

typedef int (fz_outline_iterator_next_fn)(fz_context *ctx, fz_outline_iterator *iter)

Function types for moving the iterator position.

A negative return value means we could not move as requested. Otherwise: 0 = the final position has a valid item. 1 = not a valid item, but we can insert an item here.

typedef fz_outline_iterator_prev_fn

typedef int (fz_outline_iterator_prev_fn)(fz_context *ctx, fz_outline_iterator *iter)

typedef fz_outline_iterator_up_fn

typedef int (fz_outline_iterator_up_fn)(fz_context *ctx, fz_outline_iterator *iter)

typedef fz_outline_iterator_down_fn

typedef int (fz_outline_iterator_down_fn)(fz_context *ctx, fz_outline_iterator *iter)

typedef fz_outline_iterator_insert_fn

typedef int (fz_outline_iterator_insert_fn)(fz_context *ctx, fz_outline_iterator *iter, fz_outline_item *item)

Function type for inserting a new item BEFORE the current point.

Ownership of pointers are retained by the caller. The item data will be copied.

After an insert, we implicitly do a next, so that a successive insert operation would insert after the item inserted here. The return code is therefore as for next.

typedef fz_outline_iterator_delete_fn

typedef int (fz_outline_iterator_delete_fn)(fz_context *ctx, fz_outline_iterator *iter)

Function type for deleting the current item.