[cairo] About cairo_show_text and UTF-8...

[Carl Worth]

On Fri, 06 Jan 2006 11:38:45 -0800, Carl Worth wrote:
> On Thu, 5 Jan 2006 11:53:18 -0500 (EST), Behdad Esfahbod wrote:
> 
> > In particular, can we have this feature in the immediately next
> > cairo release?
> > 
> >   Need cairo_scaled_font_text_extents
> >   https://bugs.freedesktop.org/show_bug.cgi?id=5495
> 
> Yes, I've added this bug to the cairo ROADMAP. I put a giant rambling
> comment in the bug report, but after all is said and done, I think you
> should ignore most of what I wrote there and implement
> cairo_scaled_font_text_extents. I think it will be the cleanest
> solution and it should actually be quite easy to implement on top of
> _cairo_scaled_font_text_to_glyphs and cairo_scaled_font_glyph_extents.

Behdad,

Thanks for putting the patch together for this. It does look like it
was about as easy as I had hoped. For anyone not following Bugzilla
closely, the patch is available at:

	https://bugs.freedesktop.org/attachment.cgi?id=4403

The indentation for the patch needs to be changed from two spaces to
cairo's standard of four spaces (see cairo/CODING_STYLE for more
details).

Beyond that, I would like to see a little bit more detail in the
documentation to describe what the returned extents actually are,
(that is how they correspond to something that might be drawn). I
recognize that you modelled the new documentation from the existing
documentation for cairo_scaled_font_glyph_extents---it should be fixed
as well.

For example, the documentation for cairo_text_extents has the
following paragraph:

    * Gets the extents for a string of text. The extents describe a
    * user-space rectangle that encloses the "inked" portion of the text,
    * (as it would be drawn by cairo_show_text()). Additionally, the
    * x_advance and y_advance values indicate the amount by which the
    * current point would be advanced by cairo_show_text().

This makes very clear the strong association between the values
returned by cairo_text_extents and the effects of cairo_show_text.
(There's also a second paragraph about whitespace character which you
may just want to copy verbatim.)

For cairo_scaled_font_text_extents, the first paragraph is a bit
trickier to write since the drawing operation to reference is
cairo_show_text, but only if the cairo_t is using the same scaled
font. Maybe the right way to describe the operation would be to have
the literal code necessary to achieve the same effect. Maybe something
like:

	cairo_font_face_t *font_face;
	cairo_matrix_t font_matrix, ctm;
	cairo_font_options_t font_options;

	font_face = cairo_scaled_font_get_font_face (scaled_font);
	cairo_scaled_font_get_font_matrix (scaled_font, &font_matrix);
	cairo_scaled_font_get_ctm (scaled_font, &ctm);
	cairo_scaled_font_get_font_options (scaled_font, &font_options);

	cairo_set_font_face (cr, font_face);
	cairo_set_font_matrix (cr, &font_matrix);
	cairo_set_matrix (cr, &ctm);
	cairo_set_font_options (cr, &font_options);

	cairo_show_text (cr, text);

Though, now that I type that all out, maybe it would be easier to just
describe it with text, saying something like "as it would be drawn by
cairo_show_text if the cairo graphics state were set to the same
font_face, font_matrix, ctm, and font_options as @scaled_font).

Anyway, I'll let you take a whack at the complete paragraph.

Does anybody see any problem with adding this new
cairo_scaled_font_text_extents function? I've been convinced that this
makes sense *instead of* ever adding any sort of text_to_glyphs
functionality within cairo.

-Carl
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/cairo/attachments/20060120/844d6539/attachment.pgp