MuPDF X.Y.Z

fitz/story-writer.h

Index

typedef

struct

function

Story Writer

struct fz_write_story_position

struct fz_write_story_position
{
        fz_story_element_position element;
        int page_num;
}

A fz_story_element_position plus page number information; used with fz_write_story() and fz_write_stabilized_story().

struct fz_write_story_positions

struct fz_write_story_positions
{
        fz_write_story_position *positions;
        int num;
}

A set of fz_write_story_position items; used with fz_write_stabilized_story().

typedef fz_write_story_rectfn

typedef int (fz_write_story_rectfn)(fz_context *ctx, void *ref, int num, fz_rect filled, fz_rect *rect, fz_matrix *ctm, fz_rect *mediabox)

Callback type used by fz_write_story() and fz_write_stabilized_story().

Should set rect to rect number . If this is on a new page should also set mediabox and return 1, otherwise return 0.

ref:
As passed to fz_write_story() or fz_write_stabilized_story().
num:
The rect number. Will typically increment by one each time, being reset to zero when fz_write_stabilized_story() starts a new iteration.
filled:
From earlier internal call to fz_place_story().
rect:
Out param.
ctm:
Out param, defaults to fz_identity.
mediabox:
Out param, only used if we return 1.

typedef fz_write_story_positionfn

typedef void (fz_write_story_positionfn)(fz_context *ctx, void *ref, const fz_write_story_position *position)

Callback used by fz_write_story() to report information about element positions. Slightly different from fz_story_position_callback() because also includes the page number.

ref:
As passed to fz_write_story() or fz_write_stabilized_story().
position:
Called via internal call to fz_story_position_callback().

typedef fz_write_story_pagefn

typedef void (fz_write_story_pagefn)(fz_context *ctx, void *ref, int page_num, fz_rect mediabox, fz_device *dev, int after)

Callback for fz_write_story(), called twice for each page, before (after=0) and after (after=1) the story is written.

ref:
As passed to fz_write_story() or fz_write_stabilized_story().
page_num:
Page number, starting from 1.
mediabox:
As returned from fz_write_story_rectfn().
dev:
Created from the fz_writer passed to fz_write_story() or fz_write_stabilized_story().
after:
0 - before writing the story. 1 - after writing the story.

typedef fz_write_story_contentfn

typedef void (fz_write_story_contentfn)(fz_context *ctx, void *ref, const fz_write_story_positions *positions, fz_buffer *buffer)

Callback type for fz_write_stabilized_story().

Should populate the supplied buffer with html content for use with internal calls to fz_new_story(). This may include extra content derived from information in , for example a table of contents.

ref:
As passed to fz_write_stabilized_story().
positions:
Information from previous iteration.
buffer:
Where to write the new content. Will be initially empty.

function fz_write_story

void
fz_write_story (
        fz_context *ctx,
        fz_document_writer *writer,
        fz_story *story,
        fz_write_story_rectfn rectfn,
        void *rectfn_ref,
        fz_write_story_positionfn positionfn,
        void *positionfn_ref,
        fz_write_story_pagefn pagefn,
        void *pagefn_ref
)

Places and writes a story to a fz_document_writer. Avoids the need for calling code to implement a loop that calls fz_place_story() and fz_draw_story() etc, at the expense of having to provide a fz_write_story_rectfn() callback.

story:
The story to place and write.
writer:
Where to write the story; can be NULL.
rectfn:
Should return information about the rect to be used in the next internal call to fz_place_story().
rectfn_ref:
Passed to rectfn().
positionfn:
If not NULL, is called via internal calls to fz_story_positions().
positionfn_ref:
Passed to positionfn().
pagefn:
If not NULL, called at start and end of each page (before and after all story content has been written to the device).
pagefn_ref:
Passed to pagefn().

function fz_write_stabilized_story

void
fz_write_stabilized_story (
        fz_context *ctx,
        fz_document_writer *writer,
        const char *user_css,
        float em,
        fz_write_story_contentfn contentfn,
        void *contentfn_ref,
        fz_write_story_rectfn rectfn,
        void *rectfn_ref,
        fz_write_story_pagefn pagefn,
        void *pagefn_ref,
        fz_archive *dir
)

Does iterative layout of html content to a fz_document_writer. For example this allows one to add a table of contents section while ensuring that page numbers are patched up until stable.

Repeatedly creates new story from (contentfn(), contentfn_ref, user_css, em) and lays it out with internal call to fz_write_story(); uses a NULL writer and populates a fz_write_story_positions which is passed to the next call of contentfn().

When the html from contentfn() becomes unchanged, we do a final iteration using writer.

writer:
Where to write in the final iteration.
user_css:
Used in internal calls to fz_new_story().
em:
Used in internal calls to fz_new_story().
contentfn:
Should return html content for use with fz_new_story(), possibly including extra content such as a table-of-contents.
contentfn_ref:
Passed to contentfn().
rectfn:
Should return information about the rect to be used in the next internal call to fz_place_story().
rectfn_ref:
Passed to rectfn().
fz_write_story_pagefn:
If not NULL, called at start and end of each page (before and after all story content has been written to the device).
pagefn_ref:
Passed to pagefn().
dir:
NULL, or a directory context to load images etc from.