[cairo] API proposal for document links

[Alp Toker]

Alp Toker wrote:
> Hi,
> 
> I've started adding printing support to WebKit/GTK+. One feature that 
> we're missing from Cairo is support for hyperlinks and destinations in 
> document surfaces.
> 
> I've studied the PDF and XPS specifications and come up with a first 
> draft for a proposed general API to mark link sources and destinations. 
> The API is slightly more expressive than the CoreGraphics equivalent in 
> that it allows for an arbitrary path to provide the area of the link, 
> rather than just a rectangle, and is generalised to apply to any 
> portable document formats that Cairo might support rather than just PDF.
> 
> The API is easy to follow if you're familiar with the cairo_set_source() 
> variants and cairo_fill(). Here's it is along with commentary from the 
> PDF and XPS specifications where appropriate:
> 
> /* Document functions */
> 
> /* cairo_destination(): Mark the current point on the current page as a 
> link destination with the given name. This can later be used as the 
> destination for a link using cairo_set_link_destination(). */
> /* Commentary: PDF: "Instead of being defined directly ... a destination 
> may be referred to indirectly by means of a name object." */
> /* Commentary: XPS: "Producers can mark any <FixedPage>, <Canvas>, 
> <Path>, or <Glyphs> element as an addressable location within the XPS 
> Document by specifying a value for the Name attribute." */
> 
> void
> cairo_destination (cairo_t *cr, const char *name);
> 
> 
> /* cairo_set_link_destination(): Set the link destination within cr to 
> the destination of the given name. This destination will be used for 
> subsequent link operations. */
> /* Commentary: XPS: There are some fairly strict restrictions on 
> internal link names since they end up being represented as part of the 
> fragment component of the URI schema. We might need to do some 
> normalisation. */
> 
> void
> cairo_set_link_destination (cairo_t *cr, const char *name);
> 
> 
> /* cairo_set_link_page(): Set the link destination within cr to the 
> given absolute page number. This destination will be used for subsequent 
> link operations. */
> /* Commentary: PDF: There is built-in support for linking to a page 
> number. */
> /* Commentary: XPS: My understanding is that the page number to link to 
> is equivalent to a destination name with the number as a string, and is 
> contained in the fragment component of the URI schema. */
> 
> void
> cairo_set_link_destination (cairo_t *cr, const char *name);
> 

Copy-and-paste error. That should be:

void
cairo_set_link_page (cairo_t *cr, int page_number);

I'm also less comfortable with this function than the rest of the 
proposal, since there's no API in Cairo to query the current page 
number, and I'm not sure if that would be a good thing.