## 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