[cairo] API proposal for document links

[Benjamin Otte]

Now that you blogged about it, I got aware of this.

Alp Toker <alp <at> atoker.com> writes:

> /* cairo_link(): A document operator that links the fill of the current 
> path (according to the current fill rule) to the currently set 
> destination. If a document surface supports only rectangular link areas, 
> this operation will use the fill extents of the current path. The 
> current path will be cleared from the cairo context. */
> /* Commentary: PDF: "A link annotation represents either a hypertext 
> link to a destination elsewhere in the document." */
> /* Commentary: XPS: "Hyperlinks are specified inline on any <Canvas>, 
> <Path>, or <Glyphs> element by means of the FixedPage.NavigateUri 
> attribute. The value of the attribute is the destination URI." External 
> and internal links are both represented using URIs. */
> 
> void
> cairo_link (cairo_t *cr);
> 
> /* cairo_link_preserve(): Like cairo_link(), but preserves the path 
> within the cairo context. */
> void
> cairo_link_preserve (cairo_t *cr);
> 
It seems to me, you're introducing linking as a render operation here. This
doesn't make a lot of sense to me. Just imagine the documentation: "Cairo
supports 5 rendering operations: Paint, Fill, Stroke, Clip and Link".

I would imagine a link as an attribute of the cairo_t, just like the
transformation matrix or the fill rule. So you're code would look like that:
cairo_set_hyperlink_uri (cr, "http://www.cairographics.org");
/* do some _fill(), _stroke(), or show_glyphs() */
cairo_unset_hyperlink (cr);
And everything that was rendered between the setting and unsetting would link to
the Cairo web page.
This makes more sense to me from a pure API user's point of view. I have no idea
about implementation details in the backends that should support it (PDF, PS,
SVG) though.

Cheers,
Benjamin