[cairo] pdf hyperlinks

[Adrian Johnson]

Dan McMahill wrote:
> Hello,
> 
> Quite some time back there was a proposal on this list for an API for 
> supporting hyperlinks in the pdf output from cairo.  Has there been any 
> further discussion or movement towards implementing this?

At the last cairo summit it was agreed that the best way to make the 
non-graphical PDF features available would be to provide a minimal API 
for inserting objects into the PDF and offload the work to an external 
library [1].

I've recently started looking into this. I've started work on a patch 
for allowing objects to be inserted into the PDF [2]. This allows some 
of the PDF features such as outlines and annotations to be implemented. 
Additional API would be required to support the full set of PDF features.

Currently the API is:

Allocate an object number for later use by cairo_pdf_surface_insert_object()

   int
   cairo_pdf_surface_allocate_object (cairo_surface_t *surface)

Insert a dictionary and stream into the PDF file. stream may be NULL if 
only a dictionary is required.

   void
   cairo_pdf_surface_insert_object (cairo_surface_t      *surface,
                                    int                   object,
                                    const char           *dictionary,
                                    cairo_pdf_read_func_t stream,
                                    void                 *closure)

Insert a key/value pair into the dictionary specified by type

   typedef enum _cairo_pdf_dictionary_type {
     CAIRO_PDF_DICTIONARY_TYPE_CATALOG,
     CAIRO_PDF_DICTIONARY_TYPE_INFO,
     CAIRO_PDF_DICTIONARY_TYPE_PAGE,
   } cairo_pdf_dictionary_type_t;

   void
   cairo_pdf_surface_insert_dictionary_entry (cairo_surface_t *surface,
                                     cairo_pdf_dictionary_type_t type,
                                     const char               *key,
                                     const char               *value)

Return the object number of the current page. I intend changing this to 
take a page number so the object number of any page can be obtained.

   int
   cairo_pdf_surface_get_page_object (cairo_surface_t *surface)


I've also started coding a library that makes the additional PDF 
features available to cairo using the above API [3]. I've used the 
placeholder name "cpdf" for the library until someone can suggest a 
better name.

At present there is not much there. Just a bit of code for creating 
outlines, a function for setting the PDF metadata, and an attempt at 
getting link annotations to work. At this stage I've only been writing 
this code to help design and test the cairo API for inserting PDF 
objects. A real library for adding advanced PDF features to cairo PDFs 
may look very different to this.

[1] http://www.cairographics.org/summit/2008/notes/
[2] http://cgit.freedesktop.org/~ajohnson/cairo/log/?h=pdf-insert-object
[3] http://cgit.freedesktop.org/~ajohnson/cpdf/