Details
struct PangoLayout
The PangoLayout structure represents and entire paragraph
of text. It is initialized with a PangoContext, UTF-8 string
and set of attributes for that string. Once that is done, 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.
There are also a number of parameters to adjust the formatting
of a PangoLayout, which are illustrated in Figure 1.
It is possible, as well, to ignore the 2-D setup, and simply
treat the results of a PangoLayout as a list of lines.
The PangoLayout structure is opaque, and has no user-visible
fields.
pango_layout_new ()
Create a new PangoLayout object with attributes initialized to
default values for a particular PangoContext.
pango_layout_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.
pango_layout_get_context ()
Retrieves the PangoContext used for this layout.
pango_layout_context_changed ()
void pango_layout_context_changed (PangoLayout *layout); |
Forces recomputation of any state in the PangoLayout 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.
pango_layout_set_text ()
void pango_layout_set_text (PangoLayout *layout,
const char *text,
int length); |
Set the text of the layout.
pango_layout_get_text ()
const char* pango_layout_get_text (PangoLayout *layout); |
Gets the text in the layout. The returned text should not
be freed or modified.
pango_layout_set_markup_with_accel ()
void pango_layout_set_markup_with_accel
(PangoLayout *layout,
const char *markup,
int length,
gunichar accel_marker,
gunichar *accel_char); |
Sets the layout text and attribute list from marked-up text (see
<link linkend="PangoMarkupFormat">markup format</link>). 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, the 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.
pango_layout_set_attributes ()
Sets the text attributes for a layout object
pango_layout_get_attributes ()
Gets the attribute list for the layout, if any
pango_layout_set_font_description ()
Set 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.
pango_layout_set_width ()
void pango_layout_set_width (PangoLayout *layout,
int width); |
Sets the width to which the lines of the PangoLayout should be wrapped.
pango_layout_get_width ()
Gets the width to which the lines of the PangoLayout should be wrapped.
pango_layout_set_wrap ()
Sets the wrap style; the wrap style only has an effect if a width
is set on the layout with pango_layout_set_width(). To turn off wrapping,
set the width to -1.
pango_layout_get_wrap ()
Get the wrap mode for the layout.
enum PangoWrapMode
typedef enum {
PANGO_WRAP_WORD,
PANGO_WRAP_CHAR
} PangoWrapMode; |
PANGO_TYPE_WRAP_MODE
#define PANGO_TYPE_WRAP_MODE (pango_wrap_mode_get_type()) |
pango_layout_set_indent ()
void pango_layout_set_indent (PangoLayout *layout,
int indent); |
Sets the amount by which the first line should be shorter than the
rest of the lines. This may be negative, in which case
the subsequent lines will be shorter than the first line. (However,
in either case, the entire width of the layout will be given by
the value
pango_layout_get_indent ()
Gets the amount by which the first line should be shorter than the
rest of the lines.
pango_layout_get_spacing ()
Gets the amount of spacing between the lines of the layout.
pango_layout_set_spacing ()
void pango_layout_set_spacing (PangoLayout *layout,
int spacing); |
Sets the amount of spacing between the lines of the layout.
pango_layout_set_justify ()
Sets whether or not 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 ()
Gets whether or not each complete line should be stretched to
fill the entire width of the layout.
pango_layout_set_alignment ()
Sets the alignment for the layout (how partial lines are
positioned within the horizontal space available.)
pango_layout_get_alignment ()
Sets the alignment for the layout (how partial lines are
positioned within the horizontal space available.)
pango_layout_set_tabs ()
Sets the tabs to use for layout, overriding the default tabs
(by default, tabs are every 8 spaces). If tabs is NULL, the default
tabs are reinstated. tabs is copied into the layout; you must
free your copy of tabs yourself.
pango_layout_get_tabs ()
Get the current PangoTabArray used by this layout. If no
PangoTabArray has been set, then the default tabs are in use
and NULL is returned. Default tabs are every 8 spaces.
The return value should be freed with pango_tab_array_free().
pango_layout_set_single_paragraph_mode ()
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.
enum PangoAlignment
typedef enum {
PANGO_ALIGN_LEFT,
PANGO_ALIGN_CENTER,
PANGO_ALIGN_RIGHT
} PangoAlignment; |
describes how to align the lines of a PangoLayout within the
available space. If the PangoLayout is set to justify
using pango_layout_set_justify(), then this only has an effect
for partial lines.
PANGO_TYPE_ALIGNMENT
#define PANGO_TYPE_ALIGNMENT (pango_alignment_get_type()) |
pango_layout_get_log_attrs ()
Retrieve an array of logical attributes for each character in
the layout.
pango_layout_xy_to_index ()
gboolean pango_layout_xy_to_index (PangoLayout *layout,
int x,
int y,
int *index,
int *trailing); |
Convert from X and Y position within a layout to the byte
index to the character at that logical position. If the
position is not inside the layout, the closest position is chosen
(the x/y position will be clamped inside the layout).
If a closest position is chosen, then the function returns FALSE;
on an exact hit, it returns TRUE.
pango_layout_index_to_pos ()
Convert from an index within a PangoLayout 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.
pango_layout_get_cursor_pos ()
Given an index within a layout, determine 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.
pango_layout_move_cursor_visually ()
void pango_layout_move_cursor_visually
(PangoLayout *layout,
gboolean strong,
int old_index,
int old_trailing,
int direction,
int *new_index,
int *new_trailing); |
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 position
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.
pango_layout_get_extents ()
Compute the logical and ink extents of a layout. See the documentation
for pango_font_get_glyph_extents() for details about the interpretation
of the rectangles.
pango_layout_get_pixel_extents ()
Compute the logical and ink extents of a layout. See the documentation
for 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_get_extents(), which returns the extents in
units of device unit / PANGO_SCALE.
pango_layout_get_size ()
void pango_layout_get_size (PangoLayout *layout,
int *width,
int *height); |
Determine the logical width and height of a PangoLayout
in Pango units. (device units divided by PANGO_SCALE). This
is simply a convenience function around pango_layout_get_extents.
pango_layout_get_pixel_size ()
void pango_layout_get_pixel_size (PangoLayout *layout,
int *width,
int *height); |
Determine the logical width and height of a PangoLayout
in device units. (pango_layout_get_size() returns the width
and height in thousandths of a device unit.) This
is simply a convenience function around pango_layout_get_extents.
pango_layout_get_line_count ()
Retrieve the count of lines for the PangoLayout
pango_layout_get_line ()
Retrieves a particular line from a PangoLayout
pango_layout_get_lines ()
Return the lines of the layout as a list
pango_layout_get_iter ()
Returns an iterator to iterate over the visual extents of the layout.
pango_layout_iter_free ()
Frees an iterator that's no longer in use.
pango_layout_iter_next_run ()
Moves iter forward to the next run in visual order. If iter was
already at the end of the layout, returns FALSE.
pango_layout_iter_next_char ()
Moves iter forward to the next character in visual order. If iter was already at
the end of the layout, returns FALSE.
pango_layout_iter_next_cluster ()
Moves iter forward to the next cluster in visual order. If iter
was already at the end of the layout, returns FALSE.
pango_layout_iter_next_line ()
Moves iter forward to the start of the next line. If iter is
already on the last line, returns FALSE.
pango_layout_iter_at_last_line ()
Determines whether iter is on the last line of the layout.
pango_layout_iter_get_index ()
Gets the current byte index. Note that iterating forward by char
moves in visual order, not logical order, so indexes may not be
sequential.
pango_layout_iter_get_baseline ()
Gets the y position of the current line's baseline, in layout
coordinates (origin at top left of the entire layout).
pango_layout_iter_get_run ()
Gets the current run. When iterating by run, at the end of each
line, there's a position with a NULL run, so this function can return
NULL. The NULL run at the end of each line ensures that all lines have
at least one run, even lines consisting of only a newline.
pango_layout_iter_get_line ()
Gets the current line.
pango_layout_iter_get_char_extents ()
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.
pango_layout_iter_get_cluster_extents ()
Gets the extents of the current cluster, in layout coordinates
(origin is the top left of the entire layout).
pango_layout_iter_get_run_extents ()
Gets the extents of the current run in layout coordinates
(origin is the top left of the entire layout).
pango_layout_iter_get_line_yrange ()
void pango_layout_iter_get_line_yrange
(PangoLayoutIter *iter,
int *y0,
int *y1); |
Divides the vertical space in the PangoLayout 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).
pango_layout_iter_get_line_extents ()
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
PangoLayout). 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().
pango_layout_iter_get_layout_extents ()
Obtains the extents of the PangoLayout being iterated
over. ink_rect or logical_rect can be NULL if you
aren't interested in them.
struct PangoLayoutLine
struct PangoLayoutLine
{
PangoLayout *layout;
gint start_index; /* start of line as byte index into layout->text */
gint length; /* length of line in bytes */
GSList *runs;
}; |
The PangoLayoutLine structure represents one of the lines resulting
from laying out a paragraph via PangoLayout. PangoLayoutLine
structures are obtained by calling pango_layout_get_line() and
are only valid until the text, attributes, or settings of the
parent PangoLayout are modified.
Routines for rendering PangoLayout objects are provided in
code specific to each rendering system.
struct PangoLayoutRun
struct PangoLayoutRun
{
PangoItem *item;
PangoGlyphString *glyphs;
}; |
The PangoLayoutRun structure represents a single run within
a PangoLayoutLine.
pango_layout_line_ref ()
Increase the reference count of a PangoLayoutLine by one.
pango_layout_line_unref ()
Decrease the reference count of a PangoLayoutLine by one.
if the result is zero, the line and all associated memory
will be freed.
pango_layout_line_get_extents ()
Compute the logical and ink extents of a layout line. See the documentation
for pango_font_get_glyph_extents() for details about the interpretation
of the rectangles.
pango_layout_line_get_pixel_extents ()
Compute the logical and ink extents of a layout line. See the documentation
for 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
units of device unit / PANGO_SCALE.
pango_layout_line_index_to_x ()
Convert index within a line to X pos
pango_layout_line_x_to_index ()
Convert from x offset to the byte index of the corresponding
character within the text of the layout. If x_pos is outside the line,
the start or end of the line will be stored at index.
pango_layout_line_get_x_ranges ()
void pango_layout_line_get_x_ranges (PangoLayoutLine *line,
int start_index,
int end_index,
int **ranges,
int *n_ranges); |
Get a list of visual ranges corresponding to a given logical range.
This list is not necessarily minimal - there may be consecutive
ranges which are adjacent. The ranges will be sorted from left to
right. The ranges are with respect to the left edge of the entire
layout, not with respect to the line.