pango.Layout
Prev | The pango Class Reference | Next

## pango.Layout

pango.Layout — an object representing a paragraph of text with attributes.

## Synopsis

    class pango.Layout(gobject.GObject):
        pango.Layout(context)
        def copy()
        def get_context()
        def set_attributes(attrs)
        def get_attributes()
        def set_text(text)
        def get_text()
        def set_markup(markup)
        def set_markup_with_accel(markup, accel_marker)
        def get_font_description()
        def set_font_description(desc)
        def set_width(width)
        def get_width()
        def set_wrap(wrap)
        def get_wrap()
        def set_indent(indent)
        def get_indent()
        def set_spacing(spacing)
        def get_spacing()
        def set_justify(justify)
        def get_justify()
        def set_alignment(alignment)
        def get_alignment()
        def set_tabs(tabs)
        def get_tabs()
        def set_single_paragraph_mode(setting)
        def get_single_paragraph_mode()
        def context_changed()
        def index_to_pos(index)
        def get_cursor_pos(index)
        def move_cursor_visually(strong, old_index, old_trailing, direction)
        def xy_to_index(x, y)
        def get_extents()
        def get_pixel_extents()
        def get_size()
        def get_pixel_size()
        def get_line_count()
        def get_line(line)
        def get_iter()

## Ancestry

    +-- gobject.GObject
      +-- pango.Layout

## Description

A `pango.Layout` object represents a paragraph of text with a `pango.Context`, a UTF-8 text string and a set of attributes for that string. The set of formatted lines can be extracted from the object, the layout can be rendered, and conversion between logical character positions within the layout's text, and the physical position of the resulting glyphs can be made. Also there are a number of attributes that adjust the formatting of the layout.

## Constructor

        pango.Layout(context)

`context` : | a `pango.Context`
Returns : | a new `pango.Layout`.

Creates a new `pango.Layout` object with attributes initialized to the default values of the `pango.Context` specified by `context`.

## Methods

### pango.Layout.copy

        def copy()

Returns : | a new `pango.Layout` that is a copy of the layout

The `copy`() method returns a `pango.Layout` that is a deep copy-by-value of the layout. The attribute list, tab array, and text from the layout are all copied by value.

### pango.Layout.get_context

        def get_context()

Returns : | the `pango.Context` for the layout.

The `get_context`() method returns the `pango.Context` used for this layout.

### pango.Layout.set_attributes

        def set_attributes(attrs)

`attrs` : | a `pango.AttrList`

The `set_attributes`() method sets the `pango.AttrList` for the layout object to the value specified by `attrs`.

### pango.Layout.get_attributes

        def get_attributes()

Returns : | a `pango.AttrList`

The `get_attributes`() method returns the `pango.AttrList` for the layout, if any.

### pango.Layout.set_text

        def set_text(text)

`text` : | a UTF8-string

The `set_text`() method sets the text of the layout to the value specified by `text`.

### pango.Layout.get_text

        def get_text()

Returns : | the text in the layout

The `get_text`() method returns the text in the layout.

### pango.Layout.set_markup

        def set_markup(markup)

`markup` : | marked-up text

The `set_markup`() method is the same as the `set_markup_with_accel`() method but the markup text isn't scanned for accelerators.

### pango.Layout.set_markup_with_accel

        def set_markup_with_accel(markup, accel_marker)

`markup` : | some marked-up text (see the Pango Markup Language reference page)
`accel_marker` : | marker for accelerators in the text
Returns : | the accelerator character if any

The `set_markup_with_accel`() method sets the layout text and attribute list from marked-up text to the value specified by `markup_format` (see the Pango Markup Language reference page). The current text and attribute list of the layout are replaced. If `accel_marker` is nonzero the markup will be parsed for the marker and the character following the first marker becomes the accelerator character. For example, if the accelerator marker is an underscore, the character after the first underscore will be the accelerator character. All characters marked as an accelerator will be displayed with a `pango.UNDERLINE_LOW` attribute, and the accelerator character will be returned in `accel_char`. A literal `accel_marker` character can be put in the markup by using two `accel_marker` characters together.

### pango.Layout.get_font_description

        def get_font_description()

Returns : | the layout's font description, or `None` if the font description from the layout's context is inherited.

The `get_font_description`() method returns the font description for the layout, if any

### pango.Layout.set_font_description

        def set_font_description(desc)

`desc` : | the new `pango.FontDescription`, or `None` to unset the current font description.

The `set_font_description`() method set the default `pango.FontDescription` for the layout to the value specified by `desc`. If no font description is set on the layout, the font description from the layout's context is used.

### pango.Layout.set_width

        def set_width(width)

`width` : | the desired width, or -1 to indicate that no wrapping should be performed.

The `set_width`() method sets the wrap width for the lines of the `pango.Layout` to the value specified by `width`. If the value of `width` is -1 no wrapping should be performed.

### pango.Layout.get_width

        def get_width()

Returns : | the width

The `get_width`() method returns the width at which the lines of the `pango.Layout` should be wrapped.

### pango.Layout.set_wrap

        def set_wrap(wrap)

`wrap` : | the wrap mode

The `set_wrap`() method sets the wrap style to the value specified by `wrap`. The value of wrap must be one of:

`pango.WRAP_WORD` | Wrap lines at word boundaries.
`pango.WRAP_WORD_CHAR` | wrap lines at word boundaries, but fall back to character boundaries if there is not enough space for a full word.
`pango.WRAP_CHAR` | Wrap lines at character boundaries.

The wrap style is in effect if a width is set on the layout with the `pango.Layout.set_width()`. To turn off wrapping, set the width to -1.

### pango.Layout.get_wrap

        def get_wrap()

Returns : | Active wrap mode.

The `get_wrap`() method returns the value of the wrap mode for the layout. See the `set_wrap`() method for more information.

### pango.Layout.set_indent

        def set_indent(indent)

`indent` : | the amount by which to indent

The `set_indent`() method sets the indentation of the first line of the layout to the value specified by `indent`. The value of `indent` may be negative to provide a hanging indent.

### pango.Layout.get_indent

        def get_indent()

Returns : | the indent

The `get_indent`() method returns the amount of indentation of the first line of the layout.

### pango.Layout.set_spacing

        def set_spacing(spacing)

`spacing` : | the amount of spacing (in 1/`pango.SCALE` of a device unit)

The `set_spacing`() method sets the amount of spacing between the lines of the layout to the value specified by `spacing`.

### pango.Layout.get_spacing

        def get_spacing()

Returns : | the spacing (in 1/`pango.SCALE` of a device unit)

The `get_spacing`() method returns the amount of spacing between the lines of the layout.

### pango.Layout.set_justify

        def set_justify(justify)

`justify` : | if `True` the lines in the layout should be justified.

The `set_justify`() method sets the justification attribute to the value of `justify`. If `justify` is `True` each complete line should be stretched to fill the entire width of the layout. This stretching is typically done by adding whitespace, but for some scripts (such as Arabic), the justification is done by extending the characters.

### pango.Layout.get_justify

        def get_justify()

Returns : | `True` if justification will be used

The `get_justify`() method returns `True` if each complete line should be stretched to fill the entire width of the layout.

### pango.Layout.set_alignment

        def set_alignment(alignment)

`alignment` : | the new alignment

The `set_alignment`() method sets the alignment (how partial lines are positioned within the horizontal space available) for the layout to the value specified by `alignment`. The value of `alignment` must be one of:

`pango.ALIGN_LEFT` | Put all available space on the right
`pango.ALIGN_CENTER` | Center the line within the available space
`pango.ALIGN_RIGHT` | Put all available space on the left

### pango.Layout.get_alignment

        def get_alignment()

Returns : | the alignment value

The `get_alignment`() method returns the alignment (how partial lines are positioned within the horizontal space available) for the layout. See the `set_alignment`() method for more information.

### pango.Layout.set_tabs

        def set_tabs(tabs)

`tabs` : | a `pango.TabArray`

The `set_tabs`() method sets the tabs to the value specified by `tabs` thereby overriding the default tabs (every 8 spaces). If `tabs` is `None`, the default tabs are reinstated.

### pango.Layout.get_tabs

        def get_tabs()

Returns : | a copy of the tabs for this layout, or `None`

The `get_tabs`() method returns the current `pango.TabArray` used by this layout. If no `pango.TabArray` has been set, then the default tabs (every 8 spaces) are in use and `None` is returned

### pango.Layout.set_single_paragraph_mode

        def set_single_paragraph_mode(setting)

`setting` : | if `True` newlines, etc. are not treated as paragraph separators.

The `set_single_paragraph_mode`() method sets the single paragraph mode attribute to the value specified by `setting`. If `setting` is `True`, do not treat newlines and similar characters as paragraph separators; instead, keep all text in a single paragraph, and display a glyph for paragraph separator characters. Used when you want to allow editing of newlines on a single text line.

### pango.Layout.get_single_paragraph_mode

        def get_single_paragraph_mode()

Returns : | `True` if the layout does not break paragraphs at paragraph separator characters

The `get_single_paragraph_mode`() method returns the value set by the `set_single_paragraph_mode`() method.

### pango.Layout.context_changed

        def context_changed()

The `context_changed`() method forces recomputation of any state in the `pango.Layout` that might depend on the layout's context. This method should be called if you make changes to the `pango.Context` subsequent to creating the layout.

### pango.Layout.index_to_pos

        def index_to_pos(index)

`index` : | byte index within the layout
Returns : | a 4-tuple representing the grapheme's position

The `index_to_pos`() method converts from the specified `index` within a `pango.Layout` to the onscreen position corresponding to the grapheme at that index, which is represented as a 4-tuple (x, y, width, height). Note that `x` is always the leading edge of the grapheme and `x + width` the trailing edge of the grapheme. If the directionality of the grapheme is right-to-left, then `width` will be negative.

### pango.Layout.get_cursor_pos

        def get_cursor_pos(index)

`index` : | the byte index of the cursor
Returns : | a 2-tuple containing two 4-tuples representing the strong and weak cursor positions

The `get_cursor_pos`() method returns a 2-tuple containing two 4-tuples representing the strong and weak cursor positions of the specified `index` within a layout. The position of each cursor is stored as a zero-width rectangle represented by a 4-tuple (`x`, `y`, `width`, `height`). The strong cursor location is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted.

### pango.Layout.move_cursor_visually

        def move_cursor_visually(strong, old_index, old_trailing, direction)

`strong` : | if `True` the moving cursor is the strong cursor; otherwise, the weak cursor. The strong cursor is the cursor corresponding to text insertion in the base direction for the layout.
`old_index` : | the byte index of the grapheme for the old index
`old_trailing` : | if 0, the cursor was at the trailing edge of the grapheme indicated by `old_index`, if > 0, the cursor was at the leading edge.
`direction` : | direction to move cursor. A negative value indicates motion to the left.
Returns : | a 2-tuple containing: the new cursor byte index (a value of -1 indicates that the cursor has been moved off the beginning of the layout while a value of G_MAXINT indicates that the cursor has been moved off the end of the layout); and, the number of characters to move forward (from the new cursor position) to get the position where the cursor should be displayed.

The `move_cursor_visually`() returns a 2-tuple containing:

- a new cursor position calculated from an old position (specified by `old_index`) and the specified `direction` to move visually
- the number of characters to move forward (from the new cursor position) to get the position where the cursor should be displayed. This allows distinguishing the position at the beginning of one line from the position at the end of the preceding line. the first value is always on the line where the cursor should be displayed.

If `direction` is positive, then the new strong cursor position will be one position to the right of the old cursor position. If `direction` is negative then the new strong cursor position will be one position to the left of the old cursor position.

In the presence of bidirectional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run.

Motion here is in cursor positions, not in characters, so a single call to the `move_cursor_visually`() method may move the cursor over multiple characters when multiple characters combine to form a single grapheme.

### pango.Layout.xy_to_index

        def xy_to_index(x, y)

`x` : | the X offset (in 1/`pango.SCALE` of a device unit) from the left edge of the layout.
`y` : | the Y offset (in 1/`pango.SCALE` of a device unit) from the top edge of the layout
Returns : | a 2-tuple containing the calculated byte index and an integer indicating where in the grapheme the user clicked (it will either be zero, or the number of characters in the grapheme - 0 represents the trailing edge of the grapheme).

The `xy_to_index`() method returns the byte index of the character at the specified `x` and `y` position within a layout. If the position is not inside the layout, the closest position is chosen (the (`x`, `y`) position will be clamped inside the layout).

### pango.Layout.get_extents

        def get_extents()

Returns : | a 2-tuple containing two 4-tuples representing the as drawn and logical extents rectangles of the layout

The `get_extents`() method returns a 2-tuple containing two 4-tuples representing the ink and logical extents rectangles of the layout in device units (one pixel = `pango.SCALE` device units). Logical extents are usually what you want for positioning things. The extents are given in layout coordinates which begin at the top left corner of the layout.

### pango.Layout.get_pixel_extents

        def get_pixel_extents()

Returns : | a 2-tuple containing two 4-tuples representing the as drawn (ink) and logical extents rectangles of the layout

The `get_pixel_extents`() method returns a 2-tuple containing two 4-tuples representing the logical and ink extents rectangles of the layout in pixel units. See the `get_extents`() method for more information. This method just calls the `get_extents`() and then converts the extents to pixels (one pixel = `pango.SCALE` device units).

### pango.Layout.get_size

        def get_size()

Returns : | a 2-tuple containing the logical width and height of the `pango.Layout`

The `get_size`() method returns a 2-tuple containing the logical width and height of the `pango.Layout` in pango device units (one pixel = `pango.SCALE` device units).

### pango.Layout.get_pixel_size

        def get_pixel_size()

Returns : | a 2-tuple containing the logical width height of the `pango.Layout`

The `get_pixel_size`() method returns a 2-tuple containing the logical width and height of the `pango.Layout` in pixels (one pixel = `pango.SCALE` device units). (The `get_size`() returns the width and height in device units.)

### pango.Layout.get_line_count

        def get_line_count()

Returns : | the line count

The `get_line_count`() method returns the count of lines in the layout.

### pango.Layout.get_line

        def get_line(line)

`line` : | the index of a line, which must be between 0 and layout.get_line_count() - 1, inclusive.
Returns : | the requested `pango.LayoutLine`, or `None` if the index is out of range.

### Note

This method is available in PyGTK 2.8 and above.

The `get_line`() method returns the line with the index number specified by `line` from the layout. The returned layout line will become invalid if changes are made to the `pango.Layout`.

### pango.Layout.get_iter

        def get_iter()

Returns : | a new `pango.LayoutIter` object

### Note

This method is available in PyGTK 2.6 and above.

The `get_iter`() method returns a `pango.LayoutIter` object that can be used to iterate over the visual extents of the layout.

Prev | Up | Next
pango.Language | Home | pango.LayoutIter