Module: Pango

Defined in:
pango/lib/pango.rb

Overview

Version:

  • 1.0

Defined Under Namespace

Modules: Alignment, AttrType, BidiType, CoverageLevel, Direction, EllipsizeMode, FontMask, Gravity, GravityHint, RenderPart, Script, ShapeFlags, ShowFlags, Stretch, Style, TabAlign, Underline, Variant, Weight, WrapMode Classes: Attr, Context, Coverage, Engine, EngineLang, EngineShape, Font, FontFace, FontFamily, FontMap, Fontset, FontsetSimple, Layout, Renderer

Constant Summary collapse

ANALYSIS_FLAG_CENTERED_BASELINE =

Whether the segment should be shifted to center around the baseline. Used in vertical writing directions mostly.

1
ANALYSIS_FLAG_IS_ELLIPSIS =

This flag is used to mark runs that hold ellipsized text, in an ellipsized layout.

2
ANALYSIS_FLAG_NEED_HYPHEN =

This flag tells Pango to add a hyphen at the end of the run during shaping.

4
ATTR_INDEX_FROM_TEXT_BEGINNING =

This value can be used to set the start_index member of a Pango::Attribute such that the attribute covers from the beginning of the text.

0
ENGINE_TYPE_LANG =

A string constant defining the engine type for language engines. These engines derive from Pango::EngineLang.

PangoEngineLang
ENGINE_TYPE_SHAPE =

A string constant defining the engine type for shaping engines. These engines derive from Pango::EngineShape.

PangoEngineShape
GLYPH_EMPTY =

The %PANGO_GLYPH_EMPTY macro represents a Pango::Glyph value that has a

special meaning, which is a zero-width empty glyph.  This is useful for

example in shaper modules, to use as the glyph for various zero-width Unicode characters (those passing pango_is_zero_width()).

268435455
GLYPH_INVALID_INPUT =

The %PANGO_GLYPH_INVALID_INPUT macro represents a Pango::Glyph value that has a special meaning of invalid input. Pango::Layout produces one such glyph per invalid input UTF-8 byte and such a glyph is rendered as a crossed box.

Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG on.

4294967295
GLYPH_UNKNOWN_FLAG =

The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to a #gunichar value of a valid Unicode character, to produce a Pango::Glyph value, representing an unknown-character glyph for the respective #gunichar.

268435456
RENDER_TYPE_NONE =

A string constant defining the render type for engines that are not rendering-system specific.

PangoRenderNone
SCALE =

The %PANGO_SCALE macro represents the scale between dimensions used for Pango distances and device units. (The definition of device units is dependent on the output device; it will typically be pixels for a screen, and points for a printer.) %PANGO_SCALE is currently 1024, but this may be changed in the future.

When setting font sizes, device units are always considered to be points (as in “12 point font”), rather than pixels.

1024
UNKNOWN_GLYPH_HEIGHT =
14
UNKNOWN_GLYPH_WIDTH =
10
VERSION_MIN_REQUIRED =

A macro that should be defined by the user prior to including the pango.h header. The definition should be one of the predefined Pango version macros: %PANGO_VERSION_1_2, %PANGO_VERSION_1_4,…

This macro defines the earliest version of Pango that the package is required to be able to compile against.

If the compiler is configured to warn about the use of deprecated functions, then using functions that were deprecated in version %PANGO_VERSION_MIN_REQUIRED or earlier will cause warnings (but using functions deprecated in later releases will not).

2
LOG_DOMAIN =
"Pango"

Instance Method Summary collapse

Instance Method Details

#attr_allow_breaks_new(allow_breaks) ⇒ Pango::Attribute

Create a new allow-breaks attribute.

If breaks are disabled, the range will be kept in a single run, as far as possible.

Parameters:

  • allow_breaks (TrueClass)

    true if we line breaks are allowed

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy()

#attr_background_alpha_new(alpha) ⇒ Pango::Attribute

Create a new background alpha attribute.

Parameters:

  • alpha (Integer)

    the alpha value, between 1 and 65536

Returns:

  • (Pango::Attribute)

    the new allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_background_new(red, green, blue) ⇒ Pango::Attribute

Create a new background color attribute.

Parameters:

  • red (Integer)

    the red value (ranging from 0 to 65535)

  • green (Integer)

    the green value

  • blue (Integer)

    the blue value

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_fallback_new(enable_fallback) ⇒ Pango::Attribute

Create a new font fallback attribute.

If fallback is disabled, characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text.

Parameters:

  • enable_fallback (TrueClass)

    true if we should fall back on other fonts for characters the active font is missing.

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_family_new(family) ⇒ Pango::Attribute

Create a new font family attribute.

Parameters:

  • family (String)

    the family or comma separated list of families

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_font_desc_new(desc) ⇒ Pango::Attribute

Create a new font description attribute. This attribute allows setting family, style, weight, variant, stretch, and size simultaneously.

Parameters:

  • desc (Pango::FontDescription)

    the font description

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_font_features_new(features) ⇒ Pango::Attribute

Create a new font features tag attribute.

Parameters:

  • features (String)

    a string with OpenType font features, in CSS syntax

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_foreground_alpha_new(alpha) ⇒ Pango::Attribute

Create a new foreground alpha attribute.

Parameters:

  • alpha (Integer)

    the alpha value, between 1 and 65536

Returns:

  • (Pango::Attribute)

    the new allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_foreground_new(red, green, blue) ⇒ Pango::Attribute

Create a new foreground color attribute.

Parameters:

  • red (Integer)

    the red value (ranging from 0 to 65535)

  • green (Integer)

    the green value

  • blue (Integer)

    the blue value

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_gravity_hint_new(hint) ⇒ Pango::Attribute

Create a new gravity hint attribute.

Parameters:

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_gravity_new(gravity) ⇒ Pango::Attribute

Create a new gravity attribute.

Parameters:

  • gravity (Pango::Gravity)

    the gravity value; should not be %PANGO_GRAVITY_AUTO.

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_insert_hyphens_new(insert_hyphens) ⇒ Pango::Attribute

Create a new insert-hyphens attribute.

Pango will insert hyphens when breaking lines in the middle of a word. This attribute can be used to suppress the hyphen.

Parameters:

  • insert_hyphens (TrueClass)

    true if hyphens should be inserted

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy()

#attr_language_new(language) ⇒ Pango::Attribute

Create a new language tag attribute.

Parameters:

  • language (Pango::Language)

    language tag

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_letter_spacing_new(letter_spacing) ⇒ Pango::Attribute

Create a new letter-spacing attribute.

Parameters:

  • letter_spacing (Integer)

    amount of extra space to add between graphemes of the text, in Pango units.

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_rise_new(rise) ⇒ Pango::Attribute

Create a new baseline displacement attribute.

Parameters:

  • rise (Integer)

    the amount that the text should be displaced vertically, in Pango units. Positive values displace the text upwards.

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_scale_new(scale_factor) ⇒ Pango::Attribute

Create a new font size scale attribute. The base font for the affected text will have its size multiplied by scale_factor.

Parameters:

  • scale_factor (Float)

    factor to scale the font

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_shape_new(ink_rect, logical_rect) ⇒ Pango::Attribute

Create a new shape attribute. A shape is used to impose a particular ink and logical rectangle on the result of shaping a particular glyph. This might be used, for instance, for embedding a picture or a widget inside a Pango::Layout.

Parameters:

  • ink_rect (Pango::Rectangle)

    ink rectangle to assign to each character

  • logical_rect (Pango::Rectangle)

    logical rectangle to assign to each character

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_shape_new_with_data(ink_rect, logical_rect, data, copy_func, destroy_func) ⇒ Pango::Attribute

Like pango_attr_shape_new(), but a user data pointer is also provided; this pointer can be accessed when later rendering the glyph.

Parameters:

  • ink_rect (Pango::Rectangle)

    ink rectangle to assign to each character

  • logical_rect (Pango::Rectangle)

    logical rectangle to assign to each character

  • data (GObject)

    user data pointer

  • copy_func (Pango::AttrDataCopyFunc)

    function to copy data when the attribute is copied. If nil, data is simply copied as a pointer.

  • destroy_func (GLib::DestroyNotify)

    function to free data when the attribute is freed, or nil

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_show_new(flags) ⇒ Pango::Attribute

Create a new attribute that influences how invisible characters are rendered.

Parameters:

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_size_new(size) ⇒ Pango::Attribute

Create a new font-size attribute in fractional points.

Parameters:

  • size (Integer)

    the font size, in %PANGO_SCALEths of a point.

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_size_new_absolute(size) ⇒ Pango::Attribute

Create a new font-size attribute in device units.

Parameters:

  • size (Integer)

    the font size, in %PANGO_SCALEths of a device unit.

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_stretch_new(stretch) ⇒ Pango::Attribute

Create a new font stretch attribute

Parameters:

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_strikethrough_color_new(red, green, blue) ⇒ Pango::Attribute

Create a new strikethrough color attribute. This attribute modifies the color of strikethrough lines. If not set, strikethrough lines will use the foreground color.

Parameters:

  • red (Integer)

    the red value (ranging from 0 to 65535)

  • green (Integer)

    the green value

  • blue (Integer)

    the blue value

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_strikethrough_new(strikethrough) ⇒ Pango::Attribute

Create a new strike-through attribute.

Parameters:

  • strikethrough (TrueClass)

    true if the text should be struck-through.

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_style_new(style) ⇒ Pango::Attribute

Create a new font slant style attribute.

Parameters:

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_type_get_name(type) ⇒ String

Fetches the attribute type name passed in when registering the type using pango_attr_type_register().

The returned value is an interned string (see g_intern_string() for what that means) that should not be modified or freed. nil if type is a built-in Pango attribute type or invalid.

Parameters:

Returns:

  • (String)

    the type ID name (which may be nil), or

#attr_type_register(name) ⇒ Pango::AttrType

Allocate a new attribute type ID. The attribute type name can be accessed later by using pango_attr_type_get_name().

Parameters:

  • name (String)

    an identifier for the type

Returns:

#attr_underline_color_new(red, green, blue) ⇒ Pango::Attribute

Create a new underline color attribute. This attribute modifies the color of underlines. If not set, underlines will use the foreground color.

Parameters:

  • red (Integer)

    the red value (ranging from 0 to 65535)

  • green (Integer)

    the green value

  • blue (Integer)

    the blue value

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_underline_new(underline) ⇒ Pango::Attribute

Create a new underline-style attribute.

Parameters:

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_variant_new(variant) ⇒ Pango::Attribute

Create a new font variant attribute (normal or small caps)

Parameters:

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#attr_weight_new(weight) ⇒ Pango::Attribute

Create a new font weight attribute.

Parameters:

Returns:

  • (Pango::Attribute)

    the newly allocated Pango::Attribute, which should be freed with pango_attribute_destroy().

#bidi_type_for_unichar(ch) ⇒ Pango::BidiType

Determines the normative bidirectional character type of a character, as specified in the Unicode Character Database.

A simplified version of this function is available as pango_unichar_direction(). Unicode bidirectional algorithm.

Parameters:

  • ch (String)

    a Unicode character

Returns:

#break(text, length, analysis, attrs, attrs_len) ⇒ nil

Determines possible line, word, and character breaks for a string of Unicode text with a single analysis. For most purposes you may want to use pango_get_log_attrs().

Parameters:

  • text (String)

    the text to process. Must be valid UTF-8

  • length (Integer)

    length of text in bytes (may be -1 if text is nul-terminated)

  • analysis (Pango::Analysis)

    Pango::Analysis structure from pango_itemize()

  • attrs (Array<Pango::LogAttr>)

    an array to store character information in

  • attrs_len (Integer)

    size of the array passed as attrs

Returns:

  • (nil)

#default_break(text, length, analysis, attrs, attrs_len) ⇒ nil

This is the default break algorithm. It applies Unicode rules without language-specific tailoring, therefore the analyis argument is unused and can be nil.

See pango_tailor_break() for language-specific breaks.

Parameters:

  • text (String)

    text to break. Must be valid UTF-8

  • length (Integer)

    length of text in bytes (may be -1 if text is nul-terminated)

  • analysis (Pango::Analysis)

    a Pango::Analysis for the text

  • attrs (Pango::LogAttr)

    logical attributes to fill in

  • attrs_len (Integer)

    size of the array passed as attrs

Returns:

  • (nil)

#extents_to_pixels(inclusive, nearest) ⇒ nil

Converts extents from Pango units to device units, dividing by the %PANGO_SCALE factor and performing rounding.

The inclusive rectangle is converted by flooring the x/y coordinates and extending width/height, such that the final rectangle completely includes the original rectangle.

The nearest rectangle is converted by rounding the coordinates of the rectangle to the nearest device unit (pixel).

The rule to which argument to use is: if you want the resulting device-space rectangle to completely contain the original rectangle, pass it in as inclusive. If you want two touching-but-not-overlapping rectangles stay touching-but-not-overlapping after rounding to device units, pass them in as nearest.

Parameters:

  • inclusive (Pango::Rectangle)

    rectangle to round to pixels inclusively, or nil.

  • nearest (Pango::Rectangle)

    rectangle to round to nearest pixels, or nil.

Returns:

  • (nil)

#find_base_dir(text, length) ⇒ Pango::Direction

Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm. If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned.

Parameters:

  • text (String)

    the text to process. Must be valid UTF-8

  • length (Integer)

    length of text in bytes (may be -1 if text is nul-terminated)

Returns:

  • (Pango::Direction)

    The direction corresponding to the first strong character.

#find_map(language, engine_type_id, render_type_id) ⇒ Pango::Map

Do not use. Does not do anything.

Parameters:

  • language (Pango::Language)

    the language tag for which to find the map

  • engine_type_id (Integer)

    the engine type for the map to find

  • render_type_id (Integer)

    the render type for the map to find

Returns:

  • (Pango::Map)

    nil.

#find_paragraph_boundary(text, length, paragraph_delimiter_index, next_paragraph_start) ⇒ nil

Locates a paragraph boundary in text. A boundary is caused by delimiter characters, such as a newline, carriage return, carriage return-newline pair, or Unicode paragraph separator character. The index of the run of delimiters is returned in paragraph_delimiter_index. The index of the start of the paragraph (index after all delimiters) is stored in next_paragraph_start.

If no delimiters are found, both paragraph_delimiter_index and next_paragraph_start are filled with the length of text (an index one off the end).

Parameters:

  • text (String)

    UTF-8 text

  • length (Integer)

    length of text in bytes, or -1 if nul-terminated

  • paragraph_delimiter_index (Integer)

    return location for index of delimiter

  • next_paragraph_start (Integer)

    return location for start of next paragraph

Returns:

  • (nil)

#font_description_from_string(str) ⇒ Pango::FontDescription

Creates a new font description from a string representation in the form

“[FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS]”,

where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier “px” for absolute size. VARIATIONS is a comma-separated list of font variation specifications of the form “<b>axis</b>=value” (the = sign is optional).

The following words are understood as styles: “Normal”, “Roman”, “Oblique”, “Italic”.

The following words are understood as variants: “Small-Caps”.

The following words are understood as weights: “Thin”, “Ultra-Light”, “Extra-Light”, “Light”, “Semi-Light”, “Demi-Light”, “Book”, “Regular”, “Medium”, “Semi-Bold”, “Demi-Bold”, “Bold”, “Ultra-Bold”, “Extra-Bold”, “Heavy”, “Black”, “Ultra-Black”, “Extra-Black”.

The following words are understood as stretch values: “Ultra-Condensed”, “Extra-Condensed”, “Condensed”, “Semi-Condensed”, “Semi-Expanded”, “Expanded”, “Extra-Expanded”, “Ultra-Expanded”.

The following words are understood as gravity values: “Not-Rotated”, “South”, “Upside-Down”, “North”, “Rotated-Left”, “East”, “Rotated-Right”, “West”.

Any one of the options may be absent. If FAMILY-LIST is absent, then the family_name field of the resulting font description will be initialized to nil. If STYLE-OPTIONS is missing, then all style options will be set to the default values. If SIZE is missing, the size in the resulting font description will be set to 0.

A typical example:

“Cantarell Italic Light 15 <b>wght</b>=200”

Parameters:

  • str (String)

    string representation of a font description.

Returns:

  • (Pango::FontDescription)

    a new Pango::FontDescription.

#get_log_attrs(text, length, level, language, log_attrs, attrs_len) ⇒ nil

Computes a Pango::LogAttr for each character in text. The log_attrs array must have one Pango::LogAttr for each position in text; if text contains N characters, it has N+1 positions, including the last position at the end of the text. text should be an entire paragraph; logical attributes can’t be computed without context (for example you need to see spaces on either side of a word to know the word is a word).

Parameters:

  • text (String)

    text to process. Must be valid UTF-8

  • length (Integer)

    length in bytes of text

  • level (Integer)

    embedding level, or -1 if unknown

  • language (Pango::Language)

    language tag

  • log_attrs (Array<Pango::LogAttr>)

    array with one Pango::LogAttr per character in text, plus one extra, to be filled in

  • attrs_len (Integer)

    length of log_attrs array

Returns:

  • (nil)

#get_mirror_char(ch, mirrored_ch) ⇒ TrueClass

If ch has the Unicode mirrored property and there is another Unicode character that typically has a glyph that is the mirror image of ch’s glyph, puts that character in the address pointed to by mirrored_ch.

Use g_unichar_get_mirror_char() instead; the docs for that function provide full details. filled in, false otherwise

Parameters:

  • ch (String)

    a Unicode character

  • mirrored_ch (String)

    location to store the mirrored character

Returns:

  • (TrueClass)

    true if ch has a mirrored character and mirrored_ch is

#gravity_get_for_matrix(matrix) ⇒ Pango::Gravity

Finds the gravity that best matches the rotation component in a Pango::Matrix. %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if matrix is nil

Parameters:

  • matrix (Pango::Matrix)

    a Pango::Matrix

Returns:

#gravity_get_for_script(script, base_gravity, hint) ⇒ Pango::Gravity

Based on the script, base gravity, and hint, returns actual gravity to use in laying out a single Pango::Item.

If base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the preferred gravity of script. To get the preferred gravity of a script, pass %PANGO_GRAVITY_AUTO and %PANGO_GRAVITY_HINT_STRONG in. with script.

Parameters:

Returns:

  • (Pango::Gravity)

    resolved gravity suitable to use for a run of text

#gravity_get_for_script_and_width(script, wide, base_gravity, hint) ⇒ Pango::Gravity

Based on the script, East Asian width, base gravity, and hint, returns actual gravity to use in laying out a single character or Pango::Item.

This function is similar to pango_gravity_get_for_script() except that this function makes a distinction between narrow/half-width and wide/full-width characters also. Wide/full-width characters always stand <emphasis>upright</emphasis>, that is, they always take the base gravity, whereas narrow/full-width characters are always rotated in vertical context.

If base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the preferred gravity of script. with script and wide.

Parameters:

  • script (Pango::Script)

    Pango::Script to query

  • wide (TrueClass)

    true for wide characters as returned by g_unichar_iswide()

  • base_gravity (Pango::Gravity)

    base gravity of the paragraph

  • hint (Pango::GravityHint)

    orientation hint

Returns:

  • (Pango::Gravity)

    resolved gravity suitable to use for a run of text

#gravity_to_rotation(gravity) ⇒ Float

Converts a Pango::Gravity value to its natural rotation in radians. gravity should not be %PANGO_GRAVITY_AUTO.

Note that pango_matrix_rotate() takes angle in degrees, not radians. So, to call pango_matrix_rotate() with the output of this function you should multiply it by (180. / G_PI).

Parameters:

Returns:

  • (Float)

    the rotation value corresponding to gravity.

#is_zero_width(ch) ⇒ TrueClass

Checks ch to see if it is a character that should not be normally rendered on the screen. This includes all Unicode characters with “ZERO WIDTH” in their name, as well as <firstterm>bidi</firstterm> formatting characters, and a few other ones. This is totally different from g_unichar_iszerowidth() and is at best misnamed.

Parameters:

  • ch (String)

    a Unicode character

Returns:

  • (TrueClass)

    true if ch is a zero-width character, false otherwise

#itemize(context, text, start_index, length, attrs, cached_iter) ⇒ GLib::List

Breaks a piece of text into segments with consistent directional level and shaping engine. Each byte of text will be contained in exactly one of the items in the returned list; the generated list of items will be in logical order (the start offsets of the items are ascending).

cached_iter should be an iterator over attrs currently positioned at a range before or containing start_index; cached_iter will be advanced to the range covering the position just after start_index + length. (i.e. if itemizing in a loop, just keep passing in the same cached_iter).

Parameters:

  • context (Pango::Context)

    a structure holding information that affects the itemization process.

  • text (String)

    the text to itemize. Must be valid UTF-8

  • start_index (Integer)

    first byte in text to process

  • length (Integer)

    the number of bytes (not characters) to process after start_index. This must be >= 0.

  • attrs (Pango::AttrList)

    the set of attributes that apply to text.

  • cached_iter (Pango::AttrIterator)

    Cached attribute iterator, or nil

Returns:

  • (GLib::List)

    a #GList of Pango::Item structures. The items should be freed using pango_item_free() probably in combination with g_list_foreach(), and the list itself using g_list_free().

#itemize_with_base_dir(context, base_dir, text, start_index, length, attrs, cached_iter) ⇒ GLib::List

Like pango_itemize(), but the base direction to use when computing bidirectional levels (see pango_context_set_base_dir ()), is specified explicitly rather than gotten from the Pango::Context.

Parameters:

  • context (Pango::Context)

    a structure holding information that affects the itemization process.

  • base_dir (Pango::Direction)

    base direction to use for bidirectional processing

  • text (String)

    the text to itemize.

  • start_index (Integer)

    first byte in text to process

  • length (Integer)

    the number of bytes (not characters) to process after start_index. This must be >= 0.

  • attrs (Pango::AttrList)

    the set of attributes that apply to text.

  • cached_iter (Pango::AttrIterator)

    Cached attribute iterator, or nil

Returns:

  • (GLib::List)

    a #GList of Pango::Item structures. The items should be freed using pango_item_free() probably in combination with g_list_foreach(), and the list itself using g_list_free().

#language_from_string(language) ⇒ Pango::Language

Take a RFC-3066 format language tag as a string and convert it to a Pango::Language pointer that can be efficiently copied (copy the pointer) and compared with other language tags (compare the pointer.)

This function first canonicalizes the string by converting it to lowercase, mapping ‘_’ to ‘-’, and stripping all characters other than letters and ‘-’.

Use pango_language_get_default() if you want to get the Pango::Language for the current locale of the process.

Parameters:

  • language (String)

    a string representing a language tag, or nil

Returns:

  • (Pango::Language)

    an opaque pointer to a Pango::Language structure, or nil if language was nil. The returned pointer will be valid forever after, and should not be freed.

#language_get_defaultPango::Language

Returns the Pango::Language for the current locale of the process. Note that this can change over the life of an application.

On Unix systems, this is the return value is derived from <literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can affect this through the environment variables LC_ALL, LC_CTYPE or LANG (checked in that order). The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and COUNTRY is an ISO-3166 country code. For instance, sv_FI for Swedish as written in Finland or pt_BR for Portuguese as written in Brazil.

On Windows, the C library does not use any such environment variables, and setting them won’t affect the behavior of functions like ctime(). The user sets the locale through the Regional Options in the Control Panel. The C library (in the setlocale() function) does not use country and language codes, but country and language names spelled out in English. However, this function does check the above environment variables, and does return a Unix-style locale string based on either said environment variables or the thread’s current locale.

Your application should call <literal>setlocale(LC_ALL, “”);</literal> for the user settings to take effect. Gtk+ does this in its initialization functions automatically (by calling gtk_set_locale()). See <literal>man setlocale</literal> for more details.

Returns:

  • (Pango::Language)

    the default language as a Pango::Language, must not be freed.

#log2vis_get_embedding_levels(text, length, pbase_dir) ⇒ Integer

This will return the bidirectional embedding levels of the input paragraph as defined by the Unicode Bidirectional Algorithm available at:

http://www.unicode.org/reports/tr9/

If the input base direction is a weak direction, the direction of the characters in the text will determine the final resolved direction.

Parameters:

  • text (String)

    the text to itemize.

  • length (Integer)

    the number of bytes (not characters) to process, or -1 if text is nul-terminated and the length should be calculated.

  • pbase_dir (Pango::Direction)

    input base direction, and output resolved direction.

Returns:

  • (Integer)

    a newly allocated array of embedding levels, one item per character (not byte), that should be freed using g_free.

#markup_parser_finish(context, attr_list, text, accel_char) ⇒ TrueClass

After feeding a pango markup parser some data with g_markup_parse_context_parse(), use this function to get the list of pango attributes and text out of the markup. This function will not free context, use g_markup_parse_context_free() to do so.

Parameters:

  • context (GLib::MarkupParseContext)

    A valid parse context that was returned from pango_markup_parser_new()

  • attr_list (Pango::AttrList)

    address of return location for a Pango::AttrList, or nil

  • text (String)

    address of return location for text with tags stripped, or nil

  • accel_char (String)

    address of return location for accelerator char, or nil

Returns:

  • (TrueClass)

    false if error is set, otherwise true

#markup_parser_new(accel_marker) ⇒ GLib::MarkupParseContext

Parses marked-up text (see <link linkend=“PangoMarkupFormat”>markup format</link>) to create a plain-text string and an 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, when calling finish(). Two accel_marker characters following each other produce a single literal accel_marker character.

To feed markup to the parser, use g_markup_parse_context_parse() on the returned GMarkup::ParseContext. When done with feeding markup to the parser, use pango_markup_parser_finish() to get the data out of it, and then use g_markup_parse_context_free() to free it.

This function is designed for applications that read pango markup from streams. To simply parse a string containing pango markup, the simpler pango_parse_markup() API is recommended instead. destroyed with g_markup_parse_context_free().

Parameters:

  • accel_marker (String)

    character that precedes an accelerator, or 0 for none

Returns:

  • (GLib::MarkupParseContext)

    a GMarkup::ParseContext that should be

#module_register(module) ⇒ nil

Do not use. Does not do anything.

Parameters:

  • module (Pango::IncludedModule)

    a Pango::IncludedModule

Returns:

  • (nil)

#parse_enum(type, str, value, warn, possible_values) ⇒ TrueClass

Parses an enum type and stores the result in value.

If str does not match the nick name of any of the possible values for the enum and is not an integer, false is returned, a warning is issued if warn is true, and a string representing the list of possible values is stored in possible_values. The list is slash-separated, eg. “none/start/middle/end”. If failed and possible_values is not nil, returned string should be freed using g_free().

Parameters:

  • type (GLib::Type)

    enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE.

  • str (String)

    string to parse. May be nil.

  • value (Integer)

    integer to store the result in, or nil.

  • warn (TrueClass)

    if true, issue a g_warning() on bad input.

  • possible_values (String)

    place to store list of possible values on failure, or nil.

Returns:

  • (TrueClass)

    true if str was successfully parsed.

#parse_markup(markup_text, length, accel_marker, attr_list, text, accel_char) ⇒ TrueClass

Parses marked-up text (see <link linkend=“PangoMarkupFormat”>markup format</link>) to create a plain-text string and an 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.

To parse a stream of pango markup incrementally, use pango_markup_parser_new().

If any error happens, none of the output arguments are touched except for error.

Parameters:

  • markup_text (String)

    markup to parse (see <link linkend=“PangoMarkupFormat”>markup format</link>)

  • length (Integer)

    length of markup_text, or -1 if nul-terminated

  • accel_marker (String)

    character that precedes an accelerator, or 0 for none

  • attr_list (Pango::AttrList)

    address of return location for a Pango::AttrList, or nil

  • text (String)

    address of return location for text with tags stripped, or nil

  • accel_char (String)

    address of return location for accelerator char, or nil

Returns:

  • (TrueClass)

    false if error is set, otherwise true

#parse_stretch(str, stretch, warn) ⇒ TrueClass

Parses a font stretch. The allowed values are “ultra_condensed”, “extra_condensed”, “condensed”, “semi_condensed”, “normal”, “semi_expanded”, “expanded”, “extra_expanded” and “ultra_expanded”. Case variations are ignored and the ‘_’ characters may be omitted.

Parameters:

  • str (String)

    a string to parse.

  • stretch (Pango::Stretch)

    a Pango::Stretch to store the result in.

  • warn (TrueClass)

    if true, issue a g_warning() on bad input.

Returns:

  • (TrueClass)

    true if str was successfully parsed.

#parse_style(str, style, warn) ⇒ TrueClass

Parses a font style. The allowed values are “normal”, “italic” and “oblique”, case variations being ignored.

Parameters:

  • str (String)

    a string to parse.

  • style (Pango::Style)

    a Pango::Style to store the result in.

  • warn (TrueClass)

    if true, issue a g_warning() on bad input.

Returns:

  • (TrueClass)

    true if str was successfully parsed.

#parse_variant(str, variant, warn) ⇒ TrueClass

Parses a font variant. The allowed values are “normal” and “smallcaps” or “small_caps”, case variations being ignored.

Parameters:

  • str (String)

    a string to parse.

  • variant (Pango::Variant)

    a Pango::Variant to store the result in.

  • warn (TrueClass)

    if true, issue a g_warning() on bad input.

Returns:

  • (TrueClass)

    true if str was successfully parsed.

#parse_weight(str, weight, warn) ⇒ TrueClass

Parses a font weight. The allowed values are “heavy”, “ultrabold”, “bold”, “normal”, “light”, “ultraleight” and integers. Case variations are ignored.

Parameters:

  • str (String)

    a string to parse.

  • weight (Pango::Weight)

    a Pango::Weight to store the result in.

  • warn (TrueClass)

    if true, issue a g_warning() on bad input.

Returns:

  • (TrueClass)

    true if str was successfully parsed.

#quantize_line_geometry(thickness, position) ⇒ nil

Quantizes the thickness and position of a line, typically an underline or strikethrough, to whole device pixels, that is integer multiples of %PANGO_SCALE. The purpose of this function is to avoid such lines looking blurry.

Care is taken to make sure thickness is at least one pixel when this function returns, but returned position may become zero as a result of rounding.

Parameters:

  • thickness (Integer)

    pointer to the thickness of a line, in Pango units

  • position (Integer)

    corresponding position

Returns:

  • (nil)

#read_line(stream, str) ⇒ Integer

Reads an entire line from a file into a buffer. Lines may be delimited with ‘n’, ‘r’, ‘nr’, or ‘rn’. The delimiter is not written into the buffer. Text after a ‘#’ character is treated as a comment and skipped. ‘' can be used to escape a # character. ’' proceeding a line delimiter combines adjacent lines. A ‘' proceeding any other character is ignored and written into the output buffer unmodified.

Parameters:

  • stream (GObject)

    a stdio stream

  • str (GLib::String)

    #GString buffer into which to write the result

Returns:

  • (Integer)

    0 if the stream was already at an %EOF character, otherwise the number of lines read (this is useful for maintaining a line number counter which doesn’t combine lines with ‘')

#reorder_items(logical_items) ⇒ GLib::List

From a list of items in logical order and the associated directional levels, produce a list in visual order. The original list is unmodified. (Please open a bug if you use this function.

It is not a particularly convenient interface, and the code
is duplicated elsewhere in Pango for that reason.)

Parameters:

  • logical_items (GLib::List)

    a #GList of Pango::Item in logical order.

Returns:

  • (GLib::List)

    a #GList of Pango::Item structures in visual order.

#scan_int(pos, out) ⇒ TrueClass

Scans an integer. Leading white space is skipped.

Parameters:

  • pos (String)

    in/out string position

  • out (Integer)

    an int into which to write the result

Returns:

  • (TrueClass)

    false if a parse error occurred.

#scan_string(pos, out) ⇒ TrueClass

Scans a string into a #GString buffer. The string may either be a sequence of non-white-space characters, or a quoted string with ‘“’. Instead a quoted string, ‘"’ represents a literal quote. Leading white space outside of quotes is skipped.

Parameters:

  • pos (String)

    in/out string position

  • out (GLib::String)

    a #GString into which to write the result

Returns:

  • (TrueClass)

    false if a parse error occurred.

#scan_word(pos, out) ⇒ TrueClass

Scans a word into a #GString buffer. A word consists of [A-Za-z_] followed by zero or more [A-Za-z_0-9] Leading white space is skipped.

Parameters:

  • pos (String)

    in/out string position

  • out (GLib::String)

    a #GString into which to write the result

Returns:

  • (TrueClass)

    false if a parse error occurred.

#script_for_unichar(ch) ⇒ Pango::Script

Looks up the script for a particular character (as defined by Unicode Standard Annex #24). No check is made for ch being a valid Unicode character; if you pass in invalid character, the result is undefined.

Note that while the return type of this function is declared as PangoScript, as of Pango 1.18, this function simply returns the return value of g_unichar_get_script(). Callers must be prepared to handle unknown values.

Parameters:

  • ch (String)

    a Unicode character

Returns:

#script_get_sample_language(script) ⇒ Pango::Language

Given a script, finds a language tag that is reasonably representative of that script. This will usually be the most widely spoken or used language written in that script: for instance, the sample language for %PANGO_SCRIPT_CYRILLIC is <literal>ru</literal> (Russian), the sample language for %PANGO_SCRIPT_ARABIC is <literal>ar</literal>.

For some scripts, no sample language will be returned because there is no language that is sufficiently representative. The best example of this is %PANGO_SCRIPT_HAN, where various different variants of written Chinese, Japanese, and Korean all use significantly different sets of Han characters and forms of shared characters. No sample language can be provided for many historical scripts as well.

As of 1.18, this function checks the environment variables PANGO_LANGUAGE and LANGUAGE (checked in that order) first. If one of them is set, it is parsed as a list of language tags separated by colons or other separators. This function will return the first language in the parsed list that Pango believes may use script for writing. This last predicate is tested using pango_language_includes_script(). This can be used to control Pango’s font selection for non-primary languages. For example, a PANGO_LANGUAGE enviroment variable set to “en:fa” makes Pango choose fonts suitable for Persian (fa) instead of Arabic (ar) when a segment of Arabic text is found in an otherwise non-Arabic text. The same trick can be used to choose a default language for %PANGO_SCRIPT_HAN when setting context language is not feasible. of the script, or nil if no such language exists.

Parameters:

Returns:

  • (Pango::Language)

    a Pango::Language that is representative

#shape(text, length, analysis, glyphs) ⇒ nil

Given a segment of text and the corresponding Pango::Analysis structure returned from pango_itemize(), convert the characters into glyphs. You may also pass in only a substring of the item from pango_itemize().

It is recommended that you use pango_shape_full() instead, since that API allows for shaping interaction happening across text item boundaries.

Parameters:

  • text (String)

    the text to process

  • length (Integer)

    the length (in bytes) of text

  • analysis (Pango::Analysis)

    Pango::Analysis structure from pango_itemize()

  • glyphs (Pango::GlyphString)

    glyph string in which to store results

Returns:

  • (nil)

#shape_full(item_text, item_length, paragraph_text, paragraph_length, analysis, glyphs) ⇒ nil

Given a segment of text and the corresponding Pango::Analysis structure returned from pango_itemize(), convert the characters into glyphs. You may also pass in only a substring of the item from pango_itemize().

This is similar to pango_shape(), except it also can optionally take the full paragraph text as input, which will then be used to perform certain cross-item shaping interactions. If you have access to the broader text of which item_text is part of, provide the broader text as paragraph_text. If paragraph_text is nil, item text is used instead.

Parameters:

  • item_text (String)

    valid UTF-8 text to shape.

  • item_length (Integer)

    the length (in bytes) of item_text. -1 means nul-terminated text.

  • paragraph_text (String)

    text of the paragraph (see details). May be nil.

  • paragraph_length (Integer)

    the length (in bytes) of paragraph_text. -1 means nul-terminated text.

  • analysis (Pango::Analysis)

    Pango::Analysis structure from pango_itemize().

  • glyphs (Pango::GlyphString)

    glyph string in which to store results.

Returns:

  • (nil)

#shape_with_flags(item_text, item_length, paragraph_text, paragraph_length, analysis, glyphs, flags) ⇒ nil

Given a segment of text and the corresponding Pango::Analysis structure returned from pango_itemize(), convert the characters into glyphs. You may also pass in only a substring of the item from pango_itemize().

This is similar to pango_shape_full(), except it also takes flags that can influence the shaping process.

Parameters:

  • item_text (String)

    valid UTF-8 text to shape

  • item_length (Integer)

    the length (in bytes) of item_text. -1 means nul-terminated text.

  • paragraph_text (String)

    text of the paragraph (see details). May be nil.

  • paragraph_length (Integer)

    the length (in bytes) of paragraph_text. -1 means nul-terminated text.

  • analysis (Pango::Analysis)

    Pango::Analysis structure from pango_itemize()

  • glyphs (Pango::GlyphString)

    glyph string in which to store results

  • flags (Pango::ShapeFlags)

    flags influencing the shaping process

Returns:

  • (nil)

#skip_space(pos) ⇒ TrueClass

Skips 0 or more characters of white space. the position at a ‘0’ character.

Parameters:

  • pos (String)

    in/out string position

Returns:

  • (TrueClass)

    false if skipping the white space leaves

#split_file_list(str) ⇒ Array<String>

Splits a %G_SEARCHPATH_SEPARATOR-separated list of files, stripping white space and substituting ~/ with $HOME/. strings to be freed with g_strfreev()

Parameters:

  • str (String)

    a %G_SEARCHPATH_SEPARATOR separated list of filenames

Returns:

  • (Array<String>)

    a list of

#tailor_break(text, length, analysis, offset, log_attrs, log_attrs_len) ⇒ nil

Apply language-specific tailoring to the breaks in log_attrs, which are assumed to have been produced by pango_default_break().

If offset is not -1, it is used to apply attributes from analysis that are relevant to line breaking.

Parameters:

  • text (String)

    text to process. Must be valid UTF-8

  • length (Integer)

    length in bytes of text

  • analysis (Pango::Analysis)

    Pango::Analysis structure from pango_itemize() for text

  • offset (Integer)

    Byte offset of text from the beginning of the paragraph, or -1 to ignore attributes from analysis

  • log_attrs (Array<Pango::LogAttr>)

    array with one Pango::LogAttr per character in text, plus one extra, to be filled in

  • log_attrs_len (Integer)

    length of log_attrs array

Returns:

  • (nil)

#trim_string(str) ⇒ String

Trims leading and trailing whitespace from a string.

Parameters:

  • str (String)

    a string

Returns:

  • (String)

    A newly-allocated string that must be freed with g_free()

#unichar_direction(ch) ⇒ Pango::Direction

Determines the inherent direction of a character; either %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL, or %PANGO_DIRECTION_NEUTRAL.

This function is useful to categorize characters into left-to-right letters, right-to-left letters, and everything else. If full Unicode bidirectional type of a character is needed, pango_bidi_type_for_unichar() can be used instead.

Parameters:

  • ch (String)

    a Unicode character

Returns:

#units_from_double(d) ⇒ Integer

Converts a floating-point number to Pango units: multiplies it by %PANGO_SCALE and rounds to nearest integer.

Parameters:

  • d (Float)

    double floating-point value

Returns:

  • (Integer)

    the value in Pango units.

#units_to_double(i) ⇒ Float

Converts a number in Pango units to floating-point: divides it by %PANGO_SCALE.

Parameters:

  • i (Integer)

    value in Pango units

Returns:

  • (Float)

    the double value.

#versionInteger

This is similar to the macro %PANGO_VERSION except that it returns the encoded version of Pango available at run-time, as opposed to the version available at compile-time.

A version number can be encoded into an integer using PANGO_VERSION_ENCODE().

Returns:

  • (Integer)

    The encoded version of Pango library available at run time.

#version_check(required_major, required_minor, required_micro) ⇒ String

Checks that the Pango library in use is compatible with the given version. Generally you would pass in the constants %PANGO_VERSION_MAJOR, %PANGO_VERSION_MINOR, %PANGO_VERSION_MICRO as the three arguments to this function; that produces a check that the library in use at run-time is compatible with the version of Pango the application or module was compiled against.

Compatibility is defined by two things: first the version of the running library is newer than the version required_major.required_minor.required_micro. Second the running library must be binary compatible with the version required_major.required_minor.required_micro (same major version.)

For compile-time version checking use PANGO_VERSION_CHECK().

Parameters:

  • required_major (Integer)

    the required major version.

  • required_minor (Integer)

    the required minor version.

  • required_micro (Integer)

    the required major version.

Returns:

  • (String)

    nil if the Pango library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by Pango and should not be modified or freed.

#version_stringString

This is similar to the macro %PANGO_VERSION_STRING except that it returns the version of Pango available at run-time, as opposed to the version available at compile-time.

Returns:

  • (String)

    A string containing the version of Pango library available at run time. The returned string is owned by Pango and should not be modified or freed.