Convenience functionality for text

[Owen Taylor <otaylor redhat com>]

[ warning, this is more of a rambling brainstorm rather than
  a coherent mail for which I expect responses. But responses
  woudl be appreciated anyways. ]  

Right now, drawing and measuring text in Pango-ized GTK+ is a little
bit painful. To find the width of a string, the code would
look like:

 PangoRectangle logical_rect;

 PangoLayout *layout = gtk_widget_create_pango_layout (widget);
 gtk_layout_set_text (layout, "Hello", -1);
 gtk_layout_get_extents (layout, NULL, &logical_rect);
 width = logical_rect.width / PANGO_SCALE;
 pango_layout_unref (layout);

The first step would be to add some functions to Pango to
make metrics a bit easier:

We can get rid of the PANGO_SCALE:

 void pango_layout_get_pixel_extents (PangoLayout    *layout,
                                      PangoRectangle *logical_rect,
                                      PangoRectangle *ink_rect);

And also, for the common case of width, get rid of the
rectangle:

 int pango_layout_get_pixel_width (PangoLayout *layout);

It might be better, though, to have

 void pango_layout_get_pixel_size (PangoLayout *layout,
                                  int          *width,
                                  int          *height);

Since height is almost as common, and it is more efficient
to get both at once.
               
 PangoLayout *layout = gtk_widget_create_pango_layout (widget);
 gtk_layout_set_text (layout, "Hello", -1);
 pango_layout_get_pixel_size (layout, &width, NULL);
 pango_layout_unref (layout);

That already is quite a bit better. But creating the layout and
unref'ing it is still annoying when you only use it for one thing. It
may be convenient to create some functions that create a layout, use
it and then destroy it. There is a potential for inefficiency, but it
would be more convenient in many cases:

 pango_context_get_text_pixel_size (gtk_widget_get_pango_context (widget)),
                                    "Hello", -1,
                                    &width, NULL);

Another possibility (or possibility, in addition) would be to make
these convenience function a function on GtkWidget:

 gtk_widget_get_text_size (widget, "Hello", -1, &width, NULL);

However, this is a little less flexible, because you can't do things
like use a different base direction or a different font. Its also a
bit strange to have this function in the GtkWidget namespace. 

A possibility for dealing with the issue of flexibility is to add an
extra PangoFontDescription argument, which would cover the most common
reason you would want to modify the context.

 PangoFontDescription *font_desc = pango_font_description_from_string ("Serif 20");
 gtk_widget_get_text_size (widget, font_desc, "Hello", -1, &width, NULL);
 gtk_widget_get_text_size (widget, NULL, "Hello", -1, &width, NULL);

A parallel issue is drawing text. Its pretty similar, but in that
case, the namespace issue is between:

 gdk_draw_pango_text (drawable, gtk_widget_get_pango_context (widget)), gc,
                      5, 5, "Hello", -1);

and :

 gtk_widget_draw_text (widget, drawable, gc, 5, 5, "Hello", -1);
 
Throughout all of this, the main tension is between keeping things
compact and simple to look at, and keeping them transparent and easy
to understand what is really going on.

Regards,
                                        Owen