Next: , Previous: Input Devices, Up: Top


26 Pango Interaction

Using Pango in GDK

26.1 Overview

Pango is the text layout system used by GDK and GTK+. The functions and types in this section are used to render Pango objects to GDK. drawables, and also extend the set of Pango attributes to include stippling and embossing.

Creating a <pango-layout> object is the first step in rendering text, and requires getting a handle to a <pango-context>. For GTK+ programs, you'll usually want to use gtk-widget-get-pango-context, or gtk-widget-create-pango-layout, rather than using the lowlevel gdk-pango-context-get-for-screen. Once you have a <pango-layout>, you can set the text and attributes of it with Pango functions like pango-layout-set-text and get its size with pango-layout-get-size. (Note that Pango uses a fixed point system internally, so converting between Pango units and pixels using PANGO_SCALE or the pango-pixels macro.)

Rendering a Pango layout is done most simply with gdk-draw-layout; you can also draw pieces of the layout with gdk-draw-layout or gdk-draw-glyphs. <gdk-pango-renderer> is a subclass of <pango-renderer> that is used internally to implement these functions. Using it directly or subclassing it can be useful in some cases. See the <gdk-pango-renderer> documentation for details.

     
     #define RADIUS 100
     #define N_WORDS 10
     #define FONT "Sans Bold 18"
     
     GdkScreen *screen = gdk_drawable_get_screen (drawable);
     PangoRenderer *renderer;
     GdkGC *gc;
     
     PangoMatrix matrix = PANGO_MATRIX_INIT;
     PangoContext *context;
     PangoLayout *layout;
     PangoFontDescription *desc;
     
     double device_radius;
     int width, height;
     int i;
     
     /* Get the default renderer for the screen, and set it up for drawing  */
     renderer = gdk_pango_renderer_get_default (screen);
     gdk_pango_renderer_set_drawable (GDK_PANGO_RENDERER (renderer), drawable);
     
     gc = gdk_gc_new (drawable);
     gdk_pango_renderer_set_gc (GDK_PANGO_RENDERER (renderer), gc);
     
     /* Set up a transformation matrix so that the user space coordinates for
      * where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS]
      * We first center, then change the scale */
     gdk_drawable_get_size (drawable, &width, &height);
     device_radius = MIN (width, height) / 2.;
     
     pango_matrix_translate (&matrix,
                             device_radius + (width - 2 * device_radius) / 2,
                             device_radius + (height - 2 * device_radius) / 2);
     pango_matrix_scale (&matrix, device_radius / RADIUS, device_radius / RADIUS);
     
     /* Create a PangoLayout, set the font and text */
     context = gdk_pango_context_get_for_screen (screen);
     layout = pango_layout_new (context);
     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++)
       {
         GdkColor color;
         PangoMatrix rotated_matrix = matrix;
         int width, height;
         double angle = (360. * i) / N_WORDS;
     
         /* Gradient from red at angle == 60 to blue at angle == 300 */
         color.red   = 65535 * (1 + cos ((angle - 60) * M_PI / 180.)) / 2;
         color.green = 0;
         color.blue  = 65535  - color.red;
     
         gdk_pango_renderer_set_override_color (GDK_PANGO_RENDERER (renderer),
                                                PANGO_RENDER_PART_FOREGROUND, &color);
     
         pango_matrix_rotate (&rotated_matrix, angle);
     
         pango_context_set_matrix (context, &rotated_matrix);
     
         /* Inform Pango to re-layout the text with the new transformation matrix */
         pango_layout_context_changed (layout);
     
         pango_layout_get_size (layout, &width, &height);
         pango_renderer_draw_layout (renderer, layout,
                                     - width / 2, - RADIUS * PANGO_SCALE);
       }
     
     /* Clean up default renderer, since it is shared */
     gdk_pango_renderer_set_override_color (GDK_PANGO_RENDERER (renderer),
                                            PANGO_RENDER_PART_FOREGROUND, NULL);
     gdk_pango_renderer_set_drawable (GDK_PANGO_RENDERER (renderer), NULL);
     gdk_pango_renderer_set_gc (GDK_PANGO_RENDERER (renderer), NULL);
     
     /* free the objects we created */
     g_object_unref (layout);
     g_object_unref (context);
     g_object_unref (gc);

26.2 Usage

— Class: <gdk-pango-renderer>

Derives from <pango-renderer>.

This class defines the following slots:

screen
the GdkScreen for the renderer
— Function: gdk-pango-renderer-new (screen <gdk-screen>) ⇒  (ret <pango-renderer>)

Creates a new <pango-renderer> for screen. Normally you can use the results of gdk-pango-renderer-get-default rather than creating a new renderer.

screen
a <gdk-screen>
ret
a newly created <pango-renderer>. Free with g-object-unref.

Since 2.6

— Function: gdk-pango-renderer-get-default (screen <gdk-screen>) ⇒  (ret <pango-renderer>)

Gets the default <pango-renderer> for a screen. This default renderer is shared by all users of the display, so properties such as the color or transformation matrix set for the renderer may be overwritten by functions such as gdk-draw-layout.

Before using the renderer, you need to call gdk-pango-renderer-set-drawable and gdk-pango-renderer-set-gc to set the drawable and graphics context to use for drawing.

screen
a <gdk-screen>
ret
the default <pango-renderer> for screen. The renderer is owned by GTK+ and will be kept around until the screen is closed.

Since 2.6

— Function: gdk-pango-renderer-set-drawable (self <gdk-pango-renderer>) (drawable <gdk-drawable>)
— Method: set-drawable

Sets the drawable the renderer draws to.

gdk-renderer
a <gdk-pango-renderer>
drawable
the new target drawable, or ‘#f

Since 2.6

— Function: gdk-pango-renderer-set-gc (self <gdk-pango-renderer>) (gc <gdk-gc>)
— Method: set-gc

Sets the GC the renderer draws with. Note that the GC must not be modified until it is unset by calling the function again with ‘#f’ for the gc parameter, since GDK may make internal copies of the GC which won't be updated to follow changes to the original GC.

gdk-renderer
a <gdk-pango-renderer>
gc
the new GC to use for drawing, or ‘#f

Since 2.6

— Function: gdk-pango-renderer-set-stipple (self <gdk-pango-renderer>) (part <pango-render-part>) (stipple <gdk-drawable>)
— Method: set-stipple

Sets the stipple for one render part (foreground, background, underline, etc.) Note that this is overwritten when iterating through the individual styled runs of a <pango-layout> or <pango-layout-line>. This function is thus only useful when you call low level functions like pango-renderer-draw-glyphs directly, or in the 'prepare_run' virtual function of a subclass of <gdk-pango-renderer>.

gdk-renderer
a <gdk-pango-renderer>
part
the part to render with the stipple
stipple
the new stipple value.

Since 2.6

— Function: gdk-pango-context-get ⇒  (ret <pango-context>)

Creates a <pango-context> for the default GDK screen.

The context must be freed when you're finished with it.

When using GTK+, normally you should use gtk-widget-get-pango-context instead of this function, to get the appropriate context for the widget you intend to render text onto.

The newly created context will have the default font options (see <cairo-font-options-t>) for the default screen; if these options change it will not be updated. Using gtk-widget-get-pango-context is more convenient if you want to keep a context around and track changes to the screen's font rendering settings.

ret
a new <pango-context> for the default display
— Function: gdk-pango-context-get-for-screen (screen <gdk-screen>) ⇒  (ret <pango-context>)

Creates a <pango-context> for screen.

The context must be freed when you're finished with it.

When using GTK+, normally you should use gtk-widget-get-pango-context instead of this function, to get the appropriate context for the widget you intend to render text onto.

The newly created context will have the default font options (see <cairo-font-options-t>) for the screen; if these options change it will not be updated. Using gtk-widget-get-pango-context is more convenient if you want to keep a context around and track changes to the screen's font rendering settings.

screen
the <gdk-screen> for which the context is to be created.
ret
a new <pango-context> for screen

Since 2.2

— Function: gdk-pango-context-set-colormap (context <pango-context>) (colormap <gdk-colormap>)

gdk_pango_context_set_colormap’ is deprecated and should not be used in newly-written code.

This function used to set the colormap to be used for drawing with context. The colormap is now always derived from the graphics context used for drawing, so calling this function is no longer necessary.

context
a <pango-context>
colormap
a <gdk-colormap>
— Function: gdk-pango-attr-embossed-new (embossed bool) ⇒  (ret <pango-attribute>)

Creates a new attribute containing a embossed bitmap to be used when rendering the text.

embossed
a bitmap to be set as embossed
ret
new <pango-attribute>
— Function: gdk-pango-attr-stipple-new (stipple <gdk-drawable>) ⇒  (ret <pango-attribute>)

Creates a new attribute containing a stipple bitmap to be used when rendering the text.

stipple
a bitmap to be set as stipple
ret
new <pango-attribute>