diff options
Diffstat (limited to 'docs/tmpl/pangocairo.sgml')
| -rw-r--r-- | docs/tmpl/pangocairo.sgml | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/docs/tmpl/pangocairo.sgml b/docs/tmpl/pangocairo.sgml new file mode 100644 index 00000000..723a4a09 --- /dev/null +++ b/docs/tmpl/pangocairo.sgml @@ -0,0 +1,248 @@ +<!-- ##### SECTION Title ##### --> +Cairo Rendering + +<!-- ##### SECTION Short_Description ##### --> +Rendering with the Cairo backend + +<!-- ##### SECTION Long_Description ##### --> +<para> +The <ulink url="http://cairographics.org">Cairo library</ulink> is a +vector graphics library with a powerful rendering model. It has such +features as anti-aliased primitives, alpha-compositing, and +gradients. Multiple backends for Cairo are available, to allow +rendering to images, to PDF files, and to the screen on X and on other +windowing systems. The functions in this section allow using Pango +to render to Cairo surfaces. +</para> +<para> +Using Pango with Cairo is straightforward. A #PangoContext created +with pango_cairo_font_map_create_context() can be used on any +Cairo context (cairo_t), but needs to be updated to match the +current transformation matrix and target surface of the Cairo context +using pango_cairo_update_context(). The convenience functions +pango_cairo_create_layout() and pango_cairo_update_layout() handle +the common case where the program doesn't need to manipulate the +properties of the #PangoContext. +</para> +<para> +When you get the metrics of a layout or of a piece of a layout using +functions such as pango_layout_get_extents(), the reported metrics +are in user-space coordinates. If a piece of text is 10 units long, +and you call cairo_scale (cr, 2.0), it still is more-or-less 10 +units long. However, the results will be affected by hinting +(that is, the process of adjusting the text to look good on the +pixel grid), so you shouldn't assume they are completely independent +of the current transformation matrix. Note that the basic metrics +functions in Pango report results in integer Pango units. To get +to the floating point units used in Cairo divide by %PANGO_SCALE. +</para> +<example id="rotated-example"> +<title>Using Pango with Cairo</title> +<programlisting> +#include <math.h> +#include <pango/pangocairo.h> + +static void +draw_text (cairo_t *cr) +{ +#define RADIUS 150 +#define N_WORDS 10 +#define FONT "Sans Bold 27" + + PangoLayout *layout; + PangoFontDescription *desc; + int i; + + /* Center coordinates on the middle of the region we are drawing + */ + cairo_translate (cr, RADIUS, RADIUS); + + /* Create a PangoLayout, set the font and text */ + layout = pango_cairo_create_layout (cr); + + pango_layout_set_text (layout, "Text", -1); + desc = pango_font_description_from_string (FONT); + pango_layout_set_font_description (layout, desc); + pango_font_description_free (desc); + + /* Draw the layout N_WORDS times in a circle */ + for (i = 0; i < N_WORDS; i++) + { + int width, height; + double angle = (360. * i) / N_WORDS; + double red; + + cairo_save (cr); + + /* Gradient from red at angle == 60 to blue at angle == 300 */ + red = (1 + cos ((angle - 60) * G_PI / 180.)) / 2; + cairo_set_rgb_color (cr, red, 0, 1.0 - red); + + cairo_rotate (cr, angle * G_PI / 180.); + + /* Inform Pango to re-layout the text with the new transformation */ + pango_cairo_update_layout (cr, layout); + + pango_layout_get_size (layout, &width, &height); + cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS); + pango_cairo_show_layout (cr, layout); + + cairo_restore (cr); + } + + /* free the layout object */ + g_object_unref (layout); +} + +int main (int argc, char **argv) +{ + cairo_t *cr; + FILE *f; + + if (argc != 2) + { + g_printerr ("Usage: cairo-example OUTPUT_FILENAME\n"); + return 1; + } + + f = fopen (argv[1], "w"); + if (!f) + { + g_printerr ("Usage: cannot open '%s'\n", argv[1]); + return 1; + } + + cr = cairo_create(); + cairo_set_target_png (cr, f, + CAIRO_FORMAT_ARGB32, + 2 * RADIUS, 2 * RADIUS); + + cairo_set_rgb_color (cr, 1.0, 1.0, 1.0); + cairo_rectangle (cr, 0, 0, 2 * RADIUS, 2 * RADIUS); + cairo_fill (cr); + draw_text (cr); + + cairo_destroy (cr); + fclose (f); + + return 0; +} +</programlisting> +</example> +<figure> + <title>Output of <xref linkend="rotated-example"/></title> + <graphic fileref="rotated-text.png" format="PNG"/> +</figure> + +<!-- ##### SECTION See_Also ##### --> +<para> + +</para> + +<!-- ##### STRUCT PangoCairoFontMap ##### --> +<para> + +</para> + + +<!-- ##### FUNCTION pango_cairo_font_map_new ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION pango_cairo_font_map_get_default ##### --> +<para> + +</para> + +@Returns: + + +<!-- ##### FUNCTION pango_cairo_font_map_set_resolution ##### --> +<para> + +</para> + +@fontmap: +@dpi: +<!-- # Unused Parameters # --> +@dpi_x: +@dpi_y: + + +<!-- ##### FUNCTION pango_cairo_font_map_get_resolution ##### --> +<para> + +</para> + +@fontmap: +@Returns: + + +<!-- ##### FUNCTION pango_cairo_font_map_create_context ##### --> +<para> + +</para> + +@fontmap: +@Returns: + + +<!-- ##### FUNCTION pango_cairo_update_context ##### --> +<para> + +</para> + +@cr: +@context: + + +<!-- ##### FUNCTION pango_cairo_create_layout ##### --> +<para> + +</para> + +@cr: +@Returns: + + +<!-- ##### FUNCTION pango_cairo_update_layout ##### --> +<para> + +</para> + +@cr: +@layout: + + +<!-- ##### FUNCTION pango_cairo_show_glyphs ##### --> +<para> + +</para> + +@cr: +@font: +@glyphs: + + +<!-- ##### FUNCTION pango_cairo_show_layout_line ##### --> +<para> + +</para> + +@cr: +@line: + + +<!-- ##### FUNCTION pango_cairo_show_layout ##### --> +<para> + +</para> + +@cr: +@layout: + + |