Pango Integration

Pango Integration — Using gnome-print with Pango

Synopsis

PangoFontMap *      gnome_print_pango_font_map_new      (void);
PangoFontMap *      gnome_print_pango_get_default_font_map
                                                        (void);
PangoContext *      gnome_print_pango_create_context    (PangoFontMap *fontmap);
void                gnome_print_pango_update_context    (PangoContext *context,
                                                         GnomePrintContext *gpc);
PangoLayout *       gnome_print_pango_create_layout     (GnomePrintContext *gpc);
void                gnome_print_pango_glyph_string      (GnomePrintContext *gpc,
                                                         PangoFont *font,
                                                         PangoGlyphString *glyphs);
void                gnome_print_pango_layout_line       (GnomePrintContext *gpc,
                                                         PangoLayoutLine *line);
void                gnome_print_pango_layout            (GnomePrintContext *gpc,
                                                         PangoLayout *layout);
void                gnome_print_pango_layout_print      (GnomePrintContext *gpc,
                                                         PangoLayout *pl);

Description

The functions in this section allow you to use gnome-print to draw text using the sophisticated layout and internationalization capabilities of the Pango library. In general, for a GNOME application, these are the text APIs you should be using.

There are a number of different types of objects involved in using Pango with gnome-print.

PangoFontMap

A PangoFontMap contains the information necessary to resolve abstract font names to particular fonts on the system. A font map appropriate for use with gnome-print is created using gnome_print_pango_font_map_new(). Normally instead of creating a new font map, you can just use the global default font map returned by gnome_print_pango_get_default_font_map(). The only exception to this is if you need to use lower level Pango APIs to customize how the font name to font lookup is done, since modifying the global default font map isn't allowed.

PangoContext

Information about doing layout for a particular output device with a particular set of options is encapsulated into a PangoContext. Contexts for gnome-print are created using gnome_print_pango_create_context()

A Pango context created in this way is not specific to a particular GnomePrintContext but before using a Pango context to do layout for a gnome-print context, it's necessary to call gnome_print_pango_update_context(). This function also needs to be called if when the current transformation matrix changes.

PangoLayout

A PangoLayout holds one or more paragraphs of text and encapsulates all the necessary logic needed to line wrap and lay out the text. Once you have a PangoContext, you can create a layout using pango_layout_new().

In the normal case, a PangoFontMap created directly with gnome_print_pango_create_layout() is all that is needed. A simple example that uses Pango to draw a string centered in a page looks like:

static void
draw_hello_world (GnomePrintContext *gpc,
                  double             page_width,
                  double             page_height)
{
  PangoLayout *layout = gnome_print_pango_create_layout (gpc);
  int pango_width, pango_height;
  double width, height;
  pango_layout_set_text (layout, "Hello World");
  pango_layout_get_size (layout, &pango_width, &pango_height);
  width = (double) pango_width / PANGO_SCALE;
  height = (double) pango_height / PANGO_SCALE;
  gnome_print_moveto (gpc,
	             (page_width - width) / 2,
                     (page_width - height)/ 2);
  gnome_print_pango_layout (gpc, layout);
  g_object_unref (layout);
}

Note the need to convert from Pango units to the floating point units that gnome-print uses by dividing by PANGO_SCALE.

Details

gnome_print_pango_font_map_new ()

PangoFontMap *      gnome_print_pango_font_map_new      (void);

Creates a new PangoFontMap object suitable for use with gnome-print. In most cases, you probably want to use gnome_print_pango_get_default_font_map() instead.

Returns :

a newly created PangoFontMap object

gnome_print_pango_get_default_font_map ()

PangoFontMap *      gnome_print_pango_get_default_font_map
                                                        (void);

Gets a singleton PangoFontMap object suitable for use with gnome-print.

Returns :

the default PangoFontMap object for gnome-print. The returned object is owned by gnome-print and should not be modified. (If you need to set custom options, create a new font map with gnome_print_pango_font_map_new().) The reference count is not increased.

gnome_print_pango_create_context ()

PangoContext *      gnome_print_pango_create_context    (PangoFontMap *fontmap);

Creates a new PangoContext object for the specified fontmap.

`fontmap` :	a PangoFontMap from `gnome_print_pango_get_default_font_map()` or `gnome_print_pango_create_font_map()`.
Returns :	a newly created PangoContext object

gnome_print_pango_update_context ()

void                gnome_print_pango_update_context    (PangoContext *context,
                                                         GnomePrintContext *gpc);

Update a context so that layout done with it reflects the current state of gpc. In general, every time you use a PangoContext with a different GnomePrintContext, or you change the transformation matrix of the GnomePrintContext (other than pure translations) you should call this function. You also need to call pango_layout_context_changed() for any PangoLayout objects that exit for the PangoContext.

This function currently does nothing and that isn't expected to change for gnome-print. The main benefit of calling it is that your code will be properly prepared for conversion to use with future rendering systems such as Cairo where the corresponding operation will actually do something.

`context` :	a PangoContext from `gnome_print_pango_create_context()`.
`gpc` :	a GnomePrintContext

gnome_print_pango_create_layout ()

PangoLayout *       gnome_print_pango_create_layout     (GnomePrintContext *gpc);

Convenience function that creates a new PangoContext, updates it for rendering to gpc, and then creates a PangoLayout for that PangoContext. Generally this function suffices for most usage of gnome-print with Pango and you don't need to deal with the PangoContext directly.

`gpc` :	a GnomePrintContext
Returns :	the newly created PangoLayout. Free with `g_object_unref()` when you are done with it.

gnome_print_pango_glyph_string ()

void                gnome_print_pango_glyph_string      (GnomePrintContext *gpc,
                                                         PangoFont *font,
                                                         PangoGlyphString *glyphs);

Draws the glyphs in glyphs into the specified GnomePrintContext. Positioning information in glyphs is transformed by the current transformation matrix, the glyphs are drawn in the current color, and the glyphs are positioned so that the left edge of the baseline is at the current point.

`gpc` :	a GnomePrintContext
`font` :	the PangoFont that the glyphs in `glyphs` are from
`glyphs` :	a PangoGlyphString

gnome_print_pango_layout_line ()

void                gnome_print_pango_layout_line       (GnomePrintContext *gpc,
                                                         PangoLayoutLine *line);

Draws the text in line into the specified GnomePrintContext. The text is drawn in the current color unless that has been overridden by attributes set on the layout and the glyphs are positioned so that the left edge of the baseline is at the current point.

`gpc` :	a GnomePrintContext
`line` :	a PangoLayoutLine

gnome_print_pango_layout ()

void                gnome_print_pango_layout            (GnomePrintContext *gpc,
                                                         PangoLayout *layout);

Draws the text in layout into the specified GnomePrintContext. The text is drawn in the current color unless that has been overridden by attributes set on the layout and the glyphs are positioned so that the left edge of the baseline is at the current point.

`gpc` :	a GnomePrintContext
`layout` :	a PangoLayout

gnome_print_pango_layout_print ()

void                gnome_print_pango_layout_print      (GnomePrintContext *gpc,
                                                         PangoLayout *pl);

Draws the text in pl into the specified GnomePrintContext. The text is drawn in the current color unless that has been overridden by attributes set on the layout and the glyphs are positioned so that the left edge of the baseline is at the point (0, 0). This function is obsolete; use gnome_print_pango_layout() instead.

`gpc` :	a GnomePrintContext
`pl` :	the PangoLayout to print

			GNOME Print Reference Manual
Top \| Description