gtk.gdk.PangoRenderer
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.PangoRenderer

gtk.gdk.PangoRenderer — an object providing use of Pango in GDK (new in PyGTK 2.8)

## Synopsis

    class gtk.gdk.PangoRenderer(pango.Renderer):
        pango.Renderer(screen=None)
        def set_drawable(drawable)
        def set_gc(gc)
        def set_stipple(part, stipple)
        def set_override_color(part, color)

    Functions

        def gtk.gdk.gdk_pango_renderer_get_default(screen)

## Ancestry

    +-- gobject.GObject
      +-- pango.Renderer
        +-- gtkgdk.PangoRenderer

## Properties

"screen" | Read-Write-Construct Only | The `gtk.gdk.Screen` for the renderer. Available in GTK+ 2.8 and above.

## Description

Pango is the text layout system used by PyGTK (via GDK and GTK+). The functions and types in this section are used to render Pango objects to `gtk.gdk.Drawable` objects, 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 PyGTK programs, you'll usually want to use the `gtk.Widget.get_pango_context`() method, or the `create_pango_layout`()) method, rather than using the lowlevel `gtk.gdk.gdk_pango_context_get_for_screen`() function. Once you have a `pango.Layout`, you can set the text and attributes of it with Pango methods like `pango.Layout.set_text`() and get its size using the `get_size`() method. (Note that Pango uses a fixed point system internally, so convert between Pango units and pixels using `pango.SCALE` or the `pango.PIXELS`() function.)

Rendering a Pango layout is done most simply with the `draw_layout`() method; you can also draw pieces of the layout with the `draw_layout`() method or the `draw_glyphs`() method.

`gtk.gdk.PangoRenderer` 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. The default renderer for a particular screen is obtained with the `gtk.gdk.gdk_pango_renderer_get_default`() function. Pango methods like `pango.Renderer.draw_layout`() and `pango.Renderer.draw_layout_line`() are then used to draw objects with the renderer.

In most simple cases, applications can just use the `draw_layout`() method, and don't need to directly use `gtk.gdk.PangoRenderer` at all. Using the `gtk.gdk.PangoRenderer` directly is most useful when working with a transformation such as a rotation, because the Pango drawing functions take user space coordinates (coordinates before the transformation) instead of device coordinates.

In certain cases it can be useful to subclass `gtk.gdk.PangoRenderer`. Examples of reasons to do this are to add handling of custom attributes by overriding 'prepare_run' or to do custom drawing of embedded objects by overriding 'draw_shape'.

## Constructor

        gtk.gdk.PangoRenderer(screen)

`screen` : | a `gtk.gdk.Screen`
Returns : | a new `gtk.gdk.PangoRenderer` object

### Note

This constructor is available in PyGTK 2.8 and above.

Creates a new `gtk.gdk.PangoRenderer` object for the `gtk.gdk.Screen` specified by screen. Normally you can use the results of the `gtk.gdk.gdk_pango_renderer_get_default`() function rather than creating a new renderer.

## Methods

### gtk.gdk.PangoRenderer.set_drawable

        def set_drawable(drawable)

`drawable` : | the new target `gtk.gdk.Drawable` or `None`.

### Note

This method is available in PyGTK 2.8 and above.

The `set_drawable`() method sets the `gtk.gdk.Drawable` specified by `drawable` as the drawable for rendering.

In PyGTK 2.10, `drawable` may be `None` to unset the drawable.

### gtk.gdk.PangoRenderer.set_gc

        def set_gc(gc)

`gc` : | a `gtk.gdk.GC` or `None`.

### Note

This method is available in PyGTK 2.8 and above.

The `set_gc`() method sets the graphics context the renderer draws with to the `gtk.gdk.GC` specified by `gc`.

In PyGTK 2.10, `gc` may be `None` to unset the gc to use for drawing.

### gtk.gdk.PangoRenderer.set_stipple

        def set_stipple(part, stipple)

`part` : | the part to render with the stipple
`stipple` : | the new stipple bitmap or `None`.

### Note

This method is available in PyGTK 2.8 and above.

The `set_stipple`() method sets the stipple for one render part (foreground, background, underline, strikethrough) to the bitmap specified by `stipple`. The value of part must be one of the Pango Render Part Constants. Note that this is overwritten when iterating through the individual styled runs of a `pango.Layout` or `pango.LayoutLine`. This method is thus only useful when you call low level methods like `draw_glyphs`() directly, or in the 'prepare_run' virtual function of a subclass of `gtk.gdk.PangoRenderer`.

In PyGTK 2.10 `stipple` may be set to `None`.

### gtk.gdk.PangoRenderer.set_override_color

        def set_override_color(part, color)

`part` : | the part to render with `color`
`color` : | a `gtk.gdk.Color` or `None`.

### Note

This method is available in PyGTK 2.8 and above.

The `set_override_color`() method sets the color for a particular render part (foreground, background, underline, strikethrough.) to the `gtk.gdk.Color` specified by `color`, overriding any attributes on the layouts renderered with this renderer.

In PyGTK 2.10 `color` may be set to `None`.

## Functions

### gtk.gdk.gdk_pango_renderer_get_default

        def gtk.gdk.gdk_pango_renderer_get_default(screen)

`screen` : | a `gtk.gdk.Screen`
Returns : | the default `gtk.gdk.PangoRenderer` object for `screen`.

### Note

This function is available in PyGTK 2.8 and above.

The `gtk.gdk.gdk_pango_renderer_get_default`() function returns the default `gtk.gdk.PangoRenderer` for the `gtk.gdk.Screen` specified by `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 methods such as `gtk.gdk.Drawable.draw_layout`().

Before using the renderer, you need to call the `set_drawable`() and `set_gc`() methods to set the drawable and graphics context to use for drawing.

Prev | Up | Next
gtk.gdk.Keymap | Home | gtk.gdk.Pixbuf