— Class: <pango-layout>

Derives from <gobject>.

This class defines no direct slots.

— Class: <pango-layout-iter>

Derives from <gboxed>.

This class defines no direct slots.

— Class: <pango-layout-line>

Derives from <gboxed>.

This class defines no direct slots.

— Function: pango-layout-new (context <pango-context>) ⇒  (ret <pango-layout>)

Create a new <pango-layout> object with attributes initialized to default values for a particular <pango-context>.

context

a <pango-context>

ret

the newly allocated <pango-layout>, with a reference count of one, which should be freed with g-object-unref.

— Function: pango-layout-copy (self <pango-layout>) ⇒  (ret <pango-layout>)
— Method: copy

Does a deep copy-by-value of the src layout. The attribute list, tab array, and text from the original layout are all copied by value.

src

a <pango-layout>

ret

the newly allocated <pango-layout>, with a reference count of one, which should be freed with g-object-unref.

— Function: pango-layout-get-context (self <pango-layout>) ⇒  (ret <pango-context>)
— Method: get-context

Retrieves the <pango-context> used for this layout.

layout

a <pango-layout>

ret

the <pango-context> for the layout. This does not have an additional refcount added, so if you want to keep a copy of this around, you must reference it yourself.

— Function: pango-layout-context-changed (self <pango-layout>)
— Method: context-changed

Forces recomputation of any state in the <pango-layout> that might depend on the layout's context. This function should be called if you make changes to the context subsequent to creating the layout.

layout

a <pango-layout>

— Function: pango-layout-set-text (self <pango-layout>) (text mchars) (length int)
— Method: set-text

Sets the text of the layout.

layout

a <pango-layout>

text

a valid UTF-8 string

length

maximum length of text, in bytes. -1 indicates that the string is nul-terminated and the length should be calculated. The text will also be truncated on encountering a nul-termination even when length is positive.

— Function: pango-layout-get-text (self <pango-layout>) ⇒  (ret mchars)
— Method: get-text

Gets the text in the layout. The returned text should not be freed or modified.

layout

a <pango-layout>

ret

the text in the layout.

— Function: pango-layout-set-markup (self <pango-layout>) (markup mchars) (length int)
— Method: set-markup

Same as pango-layout-set-markup-with-accel, but the markup text isn't scanned for accelerators.

layout

a <pango-layout>

markup

marked-up text

length

length of marked-up text in bytes, or -1 if markup is nul-terminated

— Function: pango-layout-set-markup-with-accel (self <pango-layout>) (markup mchars) (length int) (accel_marker unsigned-int32) ⇒  (accel_char unsigned-int32)
— Method: set-markup-with-accel

Sets the layout text and attribute list from marked-up text (see markup format). Replaces the current text and attribute list.

If accel-marker is nonzero, the given character will mark the character following it as an accelerator. For example, accel-marker might be an ampersand or underscore. All characters marked as an accelerator will receive a ‘PANGO_UNDERLINE_LOW’ attribute, and the first character so marked will be returned in accel-char. Two accel-marker characters following each other produce a single literal accel-marker character.

layout

a <pango-layout>

markup

marked-up text (see markup format)

length

length of marked-up text in bytes, or -1 if markup is nul-terminated

accel-marker

marker for accelerators in the text

accel-char

return location for first located accelerator, or ‘#f’

— Function: pango-layout-set-attributes (self <pango-layout>) (attrs <pango-attr-list>)
— Method: set-attributes

Sets the text attributes for a layout object.

layout

a <pango-layout>

attrs

a <pango-attr-list>

— Function: pango-layout-get-attributes (self <pango-layout>) ⇒  (ret <pango-attr-list>)
— Method: get-attributes

Gets the attribute list for the layout, if any.

layout

a <pango-layout>

ret

a <pango-attr-list>.

— Function: pango-layout-set-font-description (self <pango-layout>) (desc <pango-font-description>)
— Method: set-font-description

Sets the default font description for the layout. If no font description is set on the layout, the font description from the layout's context is used.

layout

a <pango-layout>

desc

the new <pango-font-description>, or ‘#f’ to unset the current font description

— Function: pango-layout-set-width (self <pango-layout>) (width int)
— Method: set-width

Sets the width to which the lines of the <pango-layout> should wrap.

layout

a <pango-layout>.

width

the desired width in Pango units, or -1 to indicate that no wrapping should be performed.

— Function: pango-layout-get-width (self <pango-layout>) ⇒  (ret int)
— Method: get-width

Gets the width to which the lines of the <pango-layout> should wrap.

layout

a <pango-layout>

ret

the width, or -1 if no width set.

— Function: pango-layout-set-wrap (self <pango-layout>) (wrap <pango-wrap-mode>)
— Method: set-wrap

Sets the wrap mode; the wrap mode only has effect if a width is set on the layout with pango-layout-set-width. To turn off wrapping, set the width to -1.

layout

a <pango-layout>

wrap

the wrap mode

— Function: pango-layout-get-wrap (self <pango-layout>) ⇒  (ret <pango-wrap-mode>)
— Method: get-wrap

Gets the wrap mode for the layout.

layout

a <pango-layout>

ret

active wrap mode.

— Function: pango-layout-set-ellipsize (self <pango-layout>) (ellipsize <pango-ellipsize-mode>)
— Method: set-ellipsize

Sets the type of ellipsization being performed for layout. Depending on the ellipsization mode ellipsize text is removed from the start, middle, or end of lines so they fit within the width of layout set with pango-layout-set-width.

If the layout contains characters such as newlines that force it to be layed out in multiple lines, then each line is ellipsized separately.

layout

a <pango-layout>

ellipsize

the new ellipsization mode for layout

Since 1.6

— Function: pango-layout-get-ellipsize (self <pango-layout>) ⇒  (ret <pango-ellipsize-mode>)
— Method: get-ellipsize

Gets the type of ellipsization being performed for layout. See pango-layout-set-ellipsize

layout

a <pango-layout>

ret

the current ellipsization mode for layout.

Since 1.6

— Function: pango-layout-set-indent (self <pango-layout>) (indent int)
— Method: set-indent

Sets the width in Pango units to indent each paragraph. A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent.

layout

a <pango-layout>.

indent

the amount by which to indent.

— Function: pango-layout-get-indent (self <pango-layout>) ⇒  (ret int)
— Method: get-indent

Gets the paragraph indent width in Pango units. A negative value indicates a hanging indentation.

layout

a <pango-layout>

ret

the indent.

— Function: pango-layout-get-spacing (self <pango-layout>) ⇒  (ret int)
— Method: get-spacing

Gets the amount of spacing in <pango-glyph-unit> between the lines of the layout.

layout

a <pango-layout>

ret

the spacing.

— Function: pango-layout-set-spacing (self <pango-layout>) (spacing int)
— Method: set-spacing

Sets the amount of spacing in <pango-glyph-unit> between the lines of the layout.

layout

a <pango-layout>.

spacing

the amount of spacing

— Function: pango-layout-set-justify (self <pango-layout>) (justify bool)
— Method: set-justify

Sets whether 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 may be done in more complex ways, like extending the characters.

Note that as of Pango-1.16, this functionality is not yet implemented.

layout

a <pango-layout>

justify

whether the lines in the layout should be justified.

— Function: pango-layout-get-justify (self <pango-layout>) ⇒  (ret bool)
— Method: get-justify

Gets whether each complete line should be stretched to fill the entire width of the layout.

layout

a <pango-layout>

ret

the justify.

— Function: pango-layout-set-auto-dir (self <pango-layout>) (auto_dir bool)
— Method: set-auto-dir

Sets whether to calculate the bidirectional base direction for the layout according to the contents of the layout; when this flag is on (the default), then paragraphs in layout that begin with strong right-to-left characters (Arabic and Hebrew principally), will have right-to-left layout, paragraphs with letters from other scripts will have left-to-right layout. Paragraphs with only neutral characters get their direction from the surrounding paragraphs.

When ‘#f’, the choice between left-to-right and right-to-left layout is done according to the base direction of the layout's <pango-context>. (See pango-context-set-base-dir).

When the auto-computed direction of a paragraph differs from the base direction of the context, the interpretation of ‘PANGO_ALIGN_LEFT’ and ‘PANGO_ALIGN_RIGHT’ are swapped.

layout

a <pango-layout>

auto-dir

if ‘#t’, compute the bidirectional base direction from the layout's contents.

Since 1.4

— Function: pango-layout-get-auto-dir (self <pango-layout>) ⇒  (ret bool)
— Method: get-auto-dir

Gets whether to calculate the bidirectional base direction for the layout according to the contents of the layout. See pango-layout-set-auto-dir.

layout

a <pango-layout>

ret

‘#t’ if the bidirectional base direction is computed from the layout's contents, ‘#f’ otherwise.

Since 1.4

— Function: pango-layout-set-alignment (self <pango-layout>) (alignment <pango-alignment>)
— Method: set-alignment

Sets the alignment for the layout: how partial lines are positioned within the horizontal space available.

layout

a <pango-layout>

alignment

the alignment

— Function: pango-layout-get-alignment (self <pango-layout>) ⇒  (ret <pango-alignment>)
— Method: get-alignment

Gets the alignment for the layout: how partial lines are positioned within the horizontal space available.

layout

a <pango-layout>

ret

the alignment.

— Function: pango-layout-set-tabs (self <pango-layout>) (tabs <pango-tab-array>)
— Method: set-tabs

Sets the tabs to use for layout, overriding the default tabs (by default, tabs are every 8 spaces). If tabs is ‘#f’, the default tabs are reinstated. tabs is copied into the layout; you must free your copy of tabs yourself.

layout

a <pango-layout>

tabs

a <pango-tab-array>

— Function: pango-layout-get-tabs (self <pango-layout>) ⇒  (ret <pango-tab-array>)
— Method: get-tabs

Gets the current <pango-tab-array> used by this layout. If no <pango-tab-array> has been set, then the default tabs are in use and ‘#f’ is returned. Default tabs are every 8 spaces. The return value should be freed with pango-tab-array-free.

layout

a <pango-layout>

ret

a copy of the tabs for this layout, or ‘#f’.

— Function: pango-layout-index-to-pos (self <pango-layout>) (index_ int) ⇒  (pos <pango-rectangle>)
— Method: index-to-pos

Converts from an index within a <pango-layout> to the onscreen position corresponding to the grapheme at that index, which is represented as rectangle. Note that ‘pos->x’ is always the leading edge of the grapheme and ‘pos->x + pos->width’ the trailing edge of the grapheme. If the directionality of the grapheme is right-to-left, then ‘pos->width’ will be negative.

layout

a <pango-layout>

index

byte index within layout

pos

rectangle in which to store the position of the grapheme

— Function: pango-layout-index-to-line-x (self <pango-layout>) (index_ int) (trailing bool) ⇒  (line int) (x_pos int)
— Method: index-to-line-x

Converts from byte index within the layout to line and X position. (X position is measured from the left edge of the line)

layout

a <pango-layout>

index

the byte index of a grapheme within the layout.

trailing

an integer indicating the edge of the grapheme to retrieve the position of. If 0, the trailing edge of the grapheme, if > 0, the leading of the grapheme.

line

location to store resulting line index. (which will between 0 and pango_layout_get_line_count(layout) - 1)

x-pos

location to store resulting position within line (‘PANGO_SCALE’ units per device unit)

— Function: pango-layout-xy-to-index (self <pango-layout>) (x int) (y int) ⇒  (ret bool) (index_ int) (trailing int)
— Method: xy-to-index

Converts from X and Y position within a layout to the byte index to the character at that logical position. If the Y position is not inside the layout, the closest position is chosen (the position will be clamped inside the layout). If the X position is not within the layout, then the start or the end of the line is chosen as described for pango-layout-x-to-index. If either the X or Y positions were not inside the layout, then the function returns ‘#f’; on an exact hit, it returns ‘#t’.

layout

a <pango-layout>

x

the X offset (in <pango-glyph-unit>) from the left edge of the layout.

y

the Y offset (in <pango-glyph-unit>) from the top edge of the layout

index

location to store calculated byte index

trailing

location to store a 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.

ret

‘#t’ if the coordinates were inside text, ‘#f’ otherwise.

— Function: pango-layout-get-cursor-pos (self <pango-layout>) (index_ int) ⇒  (strong_pos <pango-rectangle>) (weak_pos <pango-rectangle>)
— Method: get-cursor-pos

Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle. 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.

layout

a <pango-layout>

index

the byte index of the cursor

strong-pos

location to store the strong cursor position (may be ‘#f’)

weak-pos

location to store the weak cursor position (may be ‘#f’)

— Function: pango-layout-move-cursor-visually (self <pango-layout>) (strong bool) (old_index int) (old_trailing int) (direction int) ⇒  (new_index int) (new_trailing int)
— Method: move-cursor-visually

Computes a new cursor position from an old position and a count of positions to move visually. If count is positive, then the new strong cursor position will be one position to the right of the old cursor position. If count is negative, then the new strong cursor position will be one position to the left of the old cursor position.

In the presence of bidirection 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 pango-layout-move-cursor-visually may move the cursor over multiple characters when multiple characters combine to form a single grapheme.

layout

a <pango-layout>.

strong

whether the moving cursor is the strong cursor or 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.

new-index

location to store the new cursor byte index. A value of -1 indicates that the cursor has been moved off the beginning of the layout. A value of ‘G_MAXINT’ indicates that the cursor has been moved off the end of the layout.

new-trailing

number of characters to move forward from the location returned for new-index 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. new-index is always on the line where the cursor should be displayed.

— Function: pango-layout-get-extents (self <pango-layout>) ⇒  (ink_rect <pango-rectangle>) (logical_rect <pango-rectangle>)
— Method: get-extents

Computes the logical and ink extents of layout. Logical extents are usually what you want for positioning things. Note that both extents may have non-zero x and y. You may want to use those to offset where you render the layout. Not doing that is a very typical bug that shows up as right-to-left layouts not being correctly positioned in a layout with a set width.

The extents are given in layout coordinates and in Pango units; layout coordinates begin at the top left corner of the layout.

layout

a <pango-layout>

ink-rect

rectangle used to store the extents of the layout as drawn or ‘#f’ to indicate that the result is not needed.

logical-rect

rectangle used to store the logical extents of the layout or ‘#f’ to indicate that the result is not needed.

— Function: pango-layout-get-pixel-extents (self <pango-layout>) ⇒  (ink_rect <pango-rectangle>) (logical_rect <pango-rectangle>)
— Method: get-pixel-extents

Computes the logical and ink extents of layout in device units. See pango-layout-get-extents; this function just calls pango-layout-get-extents and then converts the extents to device units using the ‘PANGO_SCALE’ factor.

layout

a <pango-layout>

ink-rect

rectangle used to store the extents of the layout as drawn or ‘#f’ to indicate that the result is not needed.

logical-rect

rectangle used to store the logical extents of the layout or ‘#f’ to indicate that the result is not needed.

— Function: pango-layout-get-size (self <pango-layout>) ⇒  (width int) (height int)
— Method: get-size

Determines the logical width and height of a <pango-layout> in Pango units. (device units scaled by ‘PANGO_SCALE’). This is simply a convenience function around pango-layout-get-extents.

layout

a <pango-layout>

width

location to store the logical width, or ‘#f’

height

location to store the logical height, or ‘#f’

— Function: pango-layout-get-pixel-size (self <pango-layout>) ⇒  (width int) (height int)
— Method: get-pixel-size

Determines the logical width and height of a <pango-layout> in device units. (pango-layout-get-size returns the width and height scaled by ‘PANGO_SCALE’.) This is simply a convenience function around pango-layout-get-pixel-extents.

layout

a <pango-layout>

width

location to store the logical width, or ‘#f’

height

location to store the logical height, or ‘#f’

— Function: pango-layout-get-line-count (self <pango-layout>) ⇒  (ret int)
— Method: get-line-count

Retrieves the count of lines for the layout.

layout

<pango-layout>

ret

the line count.

— Function: pango-layout-get-line (self <pango-layout>) (line int) ⇒  (ret <pango-layout-line>)
— Method: get-line

Retrieves a particular line from a <pango-layout>.

layout

a <pango-layout>

line

the index of a line, which must be between 0 and ‘pango_layout_get_line_count(layout) - 1’, inclusive.

ret

the requested <pango-layout-line>, or ‘#f’ if the index is out of range. This layout line can be ref'ed and retained, but will become invalid if changes are made to the <pango-layout>.

— Function: pango-layout-get-lines (self <pango-layout>) ⇒  (ret gslist-of)
— Method: get-lines

Returns the lines of the layout as a list.

layout

a <pango-layout>

ret

a <gs-list> containing the lines in the layout. This points to internal data of the <pango-layout> and must be used with care. It will become invalid on any change to the layout's text or properties.

— Function: pango-layout-get-iter (self <pango-layout>) ⇒  (ret <pango-layout-iter>)
— Method: get-iter

Returns an iterator to iterate over the visual extents of the layout.

layout

a <pango-layout>

ret

the new <pango-layout-iter> that should be freed using pango-layout-iter-free.

— Function: pango-layout-iter-next-run (self <pango-layout-iter>) ⇒  (ret bool)

Moves iter forward to the next run in visual order. If iter was already at the end of the layout, returns ‘#f’.

iter

a <pango-layout-iter>

ret

whether motion was possible.

— Function: pango-layout-iter-next-char (self <pango-layout-iter>) ⇒  (ret bool)

Moves iter forward to the next character in visual order. If iter was already at the end of the layout, returns ‘#f’.

iter

a <pango-layout-iter>

ret

whether motion was possible.

— Function: pango-layout-iter-next-cluster (self <pango-layout-iter>) ⇒  (ret bool)

Moves iter forward to the next cluster in visual order. If iter was already at the end of the layout, returns ‘#f’.

iter

a <pango-layout-iter>

ret

whether motion was possible.

— Function: pango-layout-iter-next-line (self <pango-layout-iter>) ⇒  (ret bool)

Moves iter forward to the start of the next line. If iter is already on the last line, returns ‘#f’.

iter

a <pango-layout-iter>

ret

whether motion was possible.

— Function: pango-layout-iter-at-last-line (self <pango-layout-iter>) ⇒  (ret bool)

Determines whether iter is on the last line of the layout.

iter

a <pango-layout-iter>

ret

‘#t’ if iter is on the last line.

— Function: pango-layout-iter-get-index (self <pango-layout-iter>) ⇒  (ret int)

Gets the current byte index. Note that iterating forward by char moves in visual order, not logical order, so indexes may not be sequential. Also, the index may be equal to the length of the text in the layout, if on the ‘#f’ run (see pango-layout-iter-get-run).

iter

a <pango-layout-iter>

ret

current byte index.

— Function: pango-layout-iter-get-baseline (self <pango-layout-iter>) ⇒  (ret int)

Gets the Y position of the current line's baseline, in layout coordinates (origin at top left of the entire layout).

iter

a <pango-layout-iter>

ret

baseline of current line.

— Function: pango-layout-iter-get-line (self <pango-layout-iter>) ⇒  (ret <pango-layout-line>)

Gets the current line.

iter

a <pango-layout-iter>

ret

the current line.

— Function: pango-layout-iter-get-char-extents (self <pango-layout-iter>) ⇒  (logical_rect <pango-rectangle>)

Gets the extents of the current character, in layout coordinates (origin is the top left of the entire layout). Only logical extents can sensibly be obtained for characters; ink extents make sense only down to the level of clusters.

iter

a <pango-layout-iter>

logical-rect

rectangle to fill with logical extents

— Function: pango-layout-iter-get-run-extents (self <pango-layout-iter>) ⇒  (ink_rect <pango-rectangle>) (logical_rect <pango-rectangle>)

Gets the extents of the current run in layout coordinates (origin is the top left of the entire layout).

iter

a <pango-layout-iter>

ink-rect

rectangle to fill with ink extents, or ‘#f’

logical-rect

rectangle to fill with logical extents, or ‘#f’

— Function: pango-layout-iter-get-line-yrange (self <pango-layout-iter>) ⇒  (y0_ int) (y1_ int)

Divides the vertical space in the <pango-layout> being iterated over between the lines in the layout, and returns the space belonging to the current line. A line's range includes the line's logical extents, plus half of the spacing above and below the line, if pango-layout-set-spacing has been called to set layout spacing. The Y positions are in layout coordinates (origin at top left of the entire layout).

iter

a <pango-layout-iter>

y0

start of line

y1

end of line

— Function: pango-layout-iter-get-line-extents (self <pango-layout-iter>) ⇒  (ink_rect <pango-rectangle>) (logical_rect <pango-rectangle>)

Obtains the extents of the current line. ink-rect or logical-rect can be NULL if you aren't interested in them. Extents are in layout coordinates (origin is the top-left corner of the entire <pango-layout>). Thus the extents returned by this function will be the same width/height but not at the same x/y as the extents returned from pango-layout-line-get-extents.

iter

a <pango-layout-iter>

ink-rect

rectangle to fill with ink extents, or ‘#f’

logical-rect

rectangle to fill with logical extents, or ‘#f’

— Function: pango-layout-line-get-extents (self <pango-layout-line>) ⇒  (ink_rect <pango-rectangle>) (logical_rect <pango-rectangle>)

Computes the logical and ink extents of a layout line. See pango-font-get-glyph-extents for details about the interpretation of the rectangles.

line

a <pango-layout-line>

ink-rect

rectangle used to store the extents of the glyph string as drawn, or ‘#f’

logical-rect

rectangle used to store the logical extents of the glyph string, or ‘#f’

— Function: pango-layout-line-get-pixel-extents (self <pango-layout-line>) ⇒  (ink_rect <pango-rectangle>) (logical_rect <pango-rectangle>)

Computes the logical and ink extents of a layout line. See pango-font-get-glyph-extents for details about the interpretation of the rectangles. The returned rectangles are in device units, as opposed to pango-layout-line-get-extents, which returns the extents in <pango-glyph-unit>.

layout-line

a <pango-layout-line>

ink-rect

rectangle used to store the extents of the glyph string as drawn, or ‘#f’

logical-rect

rectangle used to store the logical extents of the glyph string, or ‘#f’

— Function: pango-layout-line-index-to-x (self <pango-layout-line>) (index_ int) (trailing bool) ⇒  (x_pos int)

Converts an index within a line to a X position.

line

a <pango-layout-line>

index

byte offset of a grapheme within the layout

trailing

an integer indicating the edge of the grapheme to retrieve the position of. If 0, the trailing edge of the grapheme, if > 0, the leading of the grapheme.

x-pos

location to store the x_offset (in <pango-glyph-unit>)

— Function: pango-layout-line-x-to-index (self <pango-layout-line>) (x_pos int) ⇒  (ret bool) (index_ int) (trailing int)

Converts from x offset to the byte index of the corresponding character within the text of the layout. If x-pos is outside the line, index and trailing will point to the very first or very last position in the line. This determination is based on the resolved direction of the paragraph; for example, if the resolved direction is right-to-left, then an X position to the right of the line (after it) results in 0 being stored in index and trailing. An X position to the left of the line results in index pointing to the (logical) last grapheme in the line and trailing being set to the number of characters in that grapheme. The reverse is true for a left-to-right line.

line

a <pango-layout-line>

x-pos

the X offset (in <pango-glyph-unit>) from the left edge of the line.

index

location to store calculated byte index for the grapheme in which the user clicked.

trailing

location to store a 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.

ret

‘#f’ if x-pos was outside the line, ‘#t’ if inside