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, highlights/underlines/strikeouts 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:

/*
   fz_first_annot: Return a pointer to the first annotation on a page.

   Does not throw exceptions.
*/
fz_annot *fz_first_annot(fz_context *ctx, fz_page *page);

/*
   fz_next_annot: Return a pointer to the next annotation on a page.

   Does not throw exceptions.
*/
fz_annot *fz_next_annot(fz_context *ctx, fz_annot *annot);

/*
   fz_keep_annot: Take a new reference to an annotation.
*/
fz_annot *fz_keep_annot(fz_context *ctx, fz_annot *annot);

/*
   fz_drop_annot: Drop a reference to an annotation. If the
   reference count reaches zero, annot will be destroyed.
*/
void fz_drop_annot(fz_context *ctx, fz_annot *annot);

/*
fz_bound_annot: Return the bounding rectangle of the annotation.

Does not throw exceptions.
*/
fz_rect *fz_bound_annot(fz_context *ctx, fz_annot *annot, fz_rect *rect);

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.

/*
   fz_load_links: Load the list of links for a page.

   Returns a linked list of all the links on the page, each with
   its clickable region and link destination. Each link is
   reference counted so drop and free the list of links by
   calling fz_drop_link on the pointer return from fz_load_links.

   page: Page obtained from fz_load_page.
*/
fz_link *fz_load_links(fz_context *ctx, fz_page *page);

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

8.6 Anatomy of a Page