Anatomy of a Page

In MuPDF terminology (largely borrowed from PDF) Pages consist of Page Contents, Annotations, and Links.

Page Contents (or just Contents) are typically the ordinary printed matter that you would get on a page; the text, illustrations, any headers or footers, and maybe some printers marks.

Annotations are normally extra information that is overlaid on the top of these page contents. Examples include freehand scribbles on the page, highlightsunderlinesstrikeouts overlaid on the text, sticky notes etc. Annotations are typically added to a document by people reading the document after it has been published rather than by the original author.

Annotations can be enumerated from the page one at a time, by first calling fz_first_annot, and then fz_next_annot:

$\begin{lstlisting} /* fz_first_annot: Return a pointer to the first annotation ... .... */ fz_annot *fz_next_annot(fz_context *ctx, fz_annot *annot); \end{lstlisting}$

Annotations are reference counted and can be kept and dropped as usual.

$\begin{lstlisting} /* fz_keep_annot: Take a new reference to an annotation. */ ... ...royed. */ void fz_drop_annot(fz_context *ctx, fz_annot *annot); \end{lstlisting}$

They can also be bounded, by passing a rectangle to fz_bound_annot:

$\begin{lstlisting} /* fz_bound_annot: Return the bounding rectangle of the anno... ...z_bound_annot(fz_context *ctx, fz_annot *annot, fz_rect *rect); \end{lstlisting}$

On return, the rectangle is populated with the bounding box of the annotation.

Links describe `active' regions on the page; if the user `clicks' within such a region typically the viewer should respond. Some links move to other places in the document, others launch external clients such as mail or web sites.

The links on a page can be read by calling fz_load_links:

$\begin{lstlisting} /* fz_load_links: Load the list of links for a page. \par Re... ...age. */ fz_link *fz_load_links(fz_context *ctx, fz_page *page); \end{lstlisting}$

This returns a linked list of fz_link structures. link->next gives the next one in the chain.