[cairo-commit] [cairo-www] src/FAQ.mdwn

[Carl Worth]

 src/FAQ.mdwn |   80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

New commits:
commit b7782bf662be09ea82fc4340e276fa15b2de0a66
Author: Carl Worth <cworth at cworth.org>
Date:   Wed Oct 1 22:00:40 2008 -0700

    FAQ: Add example showing how to use pango.
    
    Many thanks to Behdad for the pango example, originally on
    the cairo list here:
    
    	http://lists.freedesktop.org/archives/cairo/2008-July/014560.html

diff --git a/src/FAQ.mdwn b/src/FAQ.mdwn
index 39e052f..1423712 100644
--- a/src/FAQ.mdwn
+++ b/src/FAQ.mdwn
@@ -15,6 +15,7 @@ new users to cairo.
       <li><a href="#clear_a_surface">How do I clear a surface?</a></li>
       <li><a href="#paint_from_a_surface">How do I paint from one surface to another?</a></li>
       <li><a href="#sharp_lines">How do I draw a sharp, single-pixel-wide line?</a></li>
+      <li><a href="#using_pango">How do I use pango instead of cairo's "toy" text API?</a></li>
     </ol>
   </li>
   <li><a href="#performance_concerns">Performance Concerns</a>
@@ -234,6 +235,85 @@ fill or a stroke with an even-integer line width, this function might
 round to the nearest integer. For a stroke with an odd-integer line
 width, it might round to the nearest half integer.
 
+<h2 id="using_pango">How do I use pango instead of cairo's "toy" text
+API?</h2>
+
+In the <a href="#getting_started">getting started</a> example, we
+showed how simple it can be to display a few text characters with
+cairo:
+
+	cairo_select_font_face (cr, "serif", CAIRO_FONT_SLANT_NORMAL, CAIRO_FONT_WEIGHT_BOLD);
+	cairo_set_font_size (cr, 32.0);
+	cairo_set_source_rgb (cr, 0.0, 0.0, 1.0);
+	cairo_move_to (cr, 10.0, 50.0);
+	cairo_show_text (cr, "Hello, world");
+
+But as you read the cairo documentation and talk to expert cairo
+users, you learn that `cairo_show_text` is part of cairo's "toy" text
+API. It's fine for quick demos, and for learning how to use cairo, but
+it's not intended for use in actual applications.
+
+It's not hard to run into some of the limitations of
+`cairo_show_text`. For example, it will only display glyphs from a
+single font so if you happen to choose a font that doesn't provide
+glyphs covering every character in your string, then some characters
+just won't appear. It has a host of other limitations with respect to
+layout, ligatures, and shaping. We won't go into all of those details
+here, but suffice it to say that if you have any aspirations of having
+reasonable internationalized text display in your application, then
+you don't want to be using `cairo_show_text`.
+
+Meanwhile, the non-toy APIs in cairo, (`cairo_show_glyphs` and
+`cairo_show_text_glyphs`), are really hard to use. Compared to
+`cairo_show_text`, these still don't do any of the heavy lifting of
+text, but instead expect that the caller has done all of that
+already. So you could use these as the basis of a sophisticated
+text-layout engine, but chances are that you'd rather spend the next
+several years on your application instead.
+
+Fortunately, the pango library exists and does do sophisticated text
+layout, shaping, etc. and integrates very nicely with cairo. We
+heartily recommend that "real" applications wanting to display
+text with cairo use pango to do it.
+
+And, it's also really easy to get started using pango. The pango-using
+equivalent of our code above is:
+
+	#include <pango/pangocairo.h>
+	PangoLayout *layout;
+	PangoFontDescription *font_description;
+
+	font_description = pango_font_description_new ();
+	pango_font_description_set_family (font_description, "serif");
+	pango_font_description_set_weight (font_description, PANGO_WEIGHT_BOLD);
+	pango_font_description_set_absolute_size (font_description, 32 * PANGO_SCALE);
+
+	layout = pango_cairo_create_layout (cr);
+	pango_layout_set_font_description (layout, font_description);
+	pango_layout_set_text (layout, "Hello, world", -1);
+
+	cairo_set_source_rgb (cr, 0.0, 0.0, 1.0);
+	cairo_move_to (cr, 10.0, 50.0);
+	pango_cairo_show_layout (cr, layout);
+
+	g_object_unref (layout);
+	pango_font_description_free (font_description);
+
+Note that this does have slightly different text placement from the
+previous example. To get the same text origin as `cairo_show_text`,
+(baseline left, instead of Pango's top left), replace the
+`pango_cairo_show_layout` line with this:
+
+	pango_cairo_show_layout_line (cr, pango_layout_get_line (layout, 0));
+
+Also, to compile a pango-using program, you'll want to change the
+compilation flags we suggested before from $(pkg-config --cflags
+--libs cairo) to $(pkg-config --cflags --libs pangocairo).
+
+Hopefully that's enough to get started using pango. See the [Pango
+Reference Manual](http://library.gnome.org/devel/pango/stable/) for
+more details as needed.
+
 <h1 id="performance_concerns">Performance concerns</h1>
 
 <h2 id="clipping_performance">Clipping should only make things faster, right?</h2>