fitz/link.h

Index

Link

typedef fz_link_set_rect_fn

typedef void (fz_link_set_rect_fn)(fz_context *ctx, fz_link *link, fz_rect rect)

typedef fz_link_set_uri_fn

typedef void (fz_link_set_uri_fn)(fz_context *ctx, fz_link *link, const char *uri)

typedef fz_link_drop_link_fn

typedef void (fz_link_drop_link_fn)(fz_context *ctx, fz_link *link)

struct fz_location

struct fz_location
{
        int chapter;
        int page;
}

Locations within the document are referred to in terms of chapter and page, rather than just a page number. For some documents (such as epub documents with large numbers of pages broken into many chapters) this can make navigation much faster as only the required chapter needs to be decoded at a time.

function fz_make_location

fz_location
fz_make_location (
        int chapter,
        int page
)

Simple constructor for fz_locations.

struct fz_link

struct fz_link
{
        int refs;
        struct fz_link *next;
        fz_rect rect;
        char *uri;
        fz_link_set_rect_fn *set_rect_fn;
        fz_link_set_uri_fn *set_uri_fn;
        fz_link_drop_link_fn *drop;
}

fz_link is a list of interactive links on a page.

There is no relation between the order of the links in the list and the order they appear on the page. The list of links for a given page can be obtained from fz_load_links.

A link is reference counted. Dropping a reference to a link is done by calling fz_drop_link.

rect:: The hot zone. The area that can be clicked in untransformed coordinates.
uri:: Link destinations come in two forms: internal and external. Internal links refer to other pages in the same document. External links are URLs to other documents.
next:: A pointer to the next link on the same page.

enum fz_link_dest_type

enum fz_link_dest_type
{
        FZ_LINK_DEST_FIT,
        FZ_LINK_DEST_FIT_B,
        FZ_LINK_DEST_FIT_H,
        FZ_LINK_DEST_FIT_BH,
        FZ_LINK_DEST_FIT_V,
        FZ_LINK_DEST_FIT_BV,
        FZ_LINK_DEST_FIT_R,
        FZ_LINK_DEST_XYZ
}

struct fz_link_dest

struct fz_link_dest
{
        fz_location loc;
        fz_link_dest_type type;
        float x, y, w, h, zoom;
}

function fz_make_link_dest_none

fz_link_dest
fz_make_link_dest_none (
        void
)

function fz_make_link_dest_xyz

fz_link_dest
fz_make_link_dest_xyz (
        int chapter,
        int page,
        float x,
        float y,
        float z
)

function fz_new_link_of_size

fz_link *
fz_new_link_of_size (
        fz_context *ctx,
        int size,
        fz_rect rect,
        const char *uri
)

Create a new link record.

next is set to NULL with the expectation that the caller will handle the linked list setup. Internal function.

Different document types will be implemented by deriving from fz_link. This macro allocates such derived structures, and initialises the base sections.

macro fz_new_derived_link

#define fz_new_derived_link(CTX,TYPE,RECT,URI)

function fz_keep_link

fz_link *
fz_keep_link (
        fz_context *ctx,
        fz_link *link
)

Increment the reference count for a link. The same pointer is returned.

Never throws exceptions.

function fz_drop_link

void
fz_drop_link (
        fz_context *ctx,
        fz_link *link
)

Decrement the reference count for a link. When the reference count reaches zero, the link is destroyed.

When a link is freed, the reference for any linked link (next) is dropped too, thus an entire linked list of fz_link’s can be freed by just dropping the head.

function fz_is_external_link

int
fz_is_external_link (
        fz_context *ctx,
        const char *uri
)

Query whether a link is external to a document (determined by uri containing a ‘:’, intended to match with ‘://’ which separates the scheme from the scheme specific parts in URIs).

function fz_set_link_rect

void
fz_set_link_rect (
        fz_context *ctx,
        fz_link *link,
        fz_rect rect
)

function fz_set_link_uri

void
fz_set_link_uri (
        fz_context *ctx,
        fz_link *link,
        const char *uri
)