[cairo] API Proposal: cairo_font_metrics_t

[Behdad Esfahbod]

There is a historical mistake in cairo's API, that
cairo_font_extents_t is not opaque.  This makes it impossible to
add new members to it.  A transparent struct makes sense for
cairo_glyph_extents_t which should be fast to work with, but for
font extents, an approach like cairo_font_options_t is more
suitable.

Anyway, to fix this without breaking and deprecating API, I
suggest a new type: cairo_font_metrics_t.  I want to propose the
following new API (for 1.6):

typedef struct _cairo_font_metrics cairo_font_metrics_t;

cairo_font_metrics_create/copy/destroy()

cairo_font_metrics()
cairo_scaled_font_metrics()

cairo_font_metrics_get_slope()
cairo_font_metrics_get_underline_position()
cairo_font_metrics_get_underline_thickness()
cairo_font_metrics_get_strikethrough_position()
cairo_font_metrics_get_strikethrough_thickness()

The cairo_font_metrics() and cairo_scaled_font_metrics() names
are chosen to match cairo_font_extents() and
cairo_scaled_font_extents().  This is in contrast to names like
cairo_scaled_font_get_font_options().  This distinction makes
sense when you note that font_extents and font_metrics are
readonly objects that can only be get and never set.

The individual members and their accessors are directly borrowed
from Pango, except for get_slope() which I've wanted to add to
Pango for long.  Pango has code to extract the
underline/strikethrough properties from FreeType/Win32/....

The major difference to the Pango API is that the Pango API for
font metrics is per-language.  This is the reason I left
approximate_char_width and approximate_digit_width out.  So I'm
assuming that a font has constant underline/strikethrough
position/thickness, and any per-language adjustments are done in
other layers, like the OpenType BASE table.  I'm fairly confident
that this is the case for all font formats that provide these
data.  Owen?

-- 
behdad
http://behdad.org/

"Those who would give up Essential Liberty to purchase a little
 Temporary Safety, deserve neither Liberty nor Safety."
        -- Benjamin Franklin, 1759