Module: Pango

Extended by:
GLib::Deprecatable
Defined in:
lib/pango/color.rb,
lib/pango.rb,
lib/pango/layout.rb,
lib/pango/loader.rb,
lib/pango/markup.rb,
lib/pango/matrix.rb,
lib/pango/version.rb,
lib/pango/language.rb,
lib/pango/attr-list.rb,
lib/pango/attr-type.rb,
lib/pango/rectangle.rb,
lib/pango/deprecated.rb,
lib/pango/font-description.rb

Overview

Copyright (C) 2017 Ruby-GNOME2 Project Team

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Defined Under Namespace

Modules: Alignment, BaselineShift, BidiType, CoverageLevel, Direction, EllipsizeMode, FontMask, FontScale, GravityHint, LayoutDeserializeError, LayoutDeserializeFlags, LayoutSerializeFlags, Overline, RenderPart, Script, ShapeFlags, ShowFlags, Stretch, Style, TabAlign, TextTransform, Underline, Variant, Version, Weight, WrapMode Classes: Attr, AttrList, AttrScale, AttrType, AttrUnderline, Color, Context, Coverage, Font, FontDescription, FontFace, FontFamily, FontMap, Fontset, FontsetSimple, Gravity, Language, Layout, Loader, Matrix, Rectangle, Renderer

Constant Summary collapse

ANALYSIS_FLAG_CENTERED_BASELINE =

Whether the segment should be shifted to center around the baseline.

This is mainly used in vertical writing directions.

1
ANALYSIS_FLAG_IS_ELLIPSIS =

Whether this run holds ellipsized text.

2
ANALYSIS_FLAG_NEED_HYPHEN =

Whether to add a hyphen at the end of the run during shaping.

4
ATTR_INDEX_FROM_TEXT_BEGINNING =

Value for start_index in PangoAttribute that indicates
the beginning of the text.

0
ATTR_INDEX_TO_TEXT_END =

Value for end_index in PangoAttribute that indicates
the end of the text.

4294967295
GLYPH_EMPTY =

A PangoGlyph value that indicates a zero-width empty glpyh.

This is useful for example in shaper modules, to use as the glyph for
various zero-width Unicode characters (those passing [funcis_zero_width]).

268435455
GLYPH_INVALID_INPUT =

A PangoGlyph value for invalid input.

PangoLayout 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
set.

4294967295
GLYPH_UNKNOWN_FLAG =

Flag used in PangoGlyph to turn a gunichar value of a valid Unicode
character into an unknown-character glyph for that gunichar.

Such unknown-character glyphs may be rendered as a 'hex box'.

268435456
SCALE =

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
VERSION_MAJOR =

The major component of the version of Pango available at compile-time.

1
VERSION_MICRO =

The micro component of the version of Pango available at compile-time.

1
VERSION_MINOR =

The minor component of the version of Pango available at compile-time.

52
VERSION_STRING =

A string literal containing the version of Pango available at compile-time.

1.52.1
LOG_DOMAIN = 
"Pango"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.parse_markup(markup_text, accel_marker = nil) ⇒ Object 



20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/pango/markup.rb', line 20

def parse_markup(markup_text, accel_marker=nil)
  accel_marker ||= 0
  success, attr_list, text, accel_char =
    parse_markup_raw(markup_text,
                     markup_text.bytesize,
                     accel_marker)
  return nil unless success

  accel_char = nil if accel_char.empty?
  [attr_list, text, accel_char]
end

.parse_markup_raw ⇒ Object 



19
 
# File 'lib/pango/markup.rb', line 19

alias_method :parse_markup_raw, :parse_markup

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 (Boolean) —

    true if we line breaks are allowed

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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 newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_baseline_shift_new(shift) ⇒ Pango::Attribute

Create a new baseline displacement attribute.

The effect of this attribute is to shift the baseline of a run,
relative to the run of preceding run.

Parameters:

  • shift (Integer) —

    either a PangoBaselineShift enumeration value or an absolute value (> 1024)
    in Pango units, relative to the baseline of the previous run.
    Positive values displace the text upwards.

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_break(text, length, attr_list, offset, attrs, attrs_len) ⇒ nil

Apply customization from attributes to the breaks in attrs.

The line breaks are assumed to have been produced
by [funcPango.default_break] and [funcPango.tailor_break].

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)

  • attr_list (Pango::AttrList) —

    PangoAttrList to apply

  • offset (Integer) —

    Byte offset of text from the beginning of the paragraph

  • attrs (Array<Pango::LogAttr>) —

    array with one PangoLogAttr
    per character in text, plus one extra, to be filled in

  • attrs_len (Integer) —

    length of attrs array

Returns:

  • (nil)

#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 (Boolean) —

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

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.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:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_font_features_new(features) ⇒ Pango::Attribute

Create a new font features tag attribute.

You can use this attribute to select OpenType font features like small-caps,
alternative glyphs, ligatures, etc. for fonts that support them.
font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc)

Parameters:

  • features (String) —

    a string with OpenType font features, with the syntax of the [CSS

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_font_scale_new(scale) ⇒ Pango::Attribute

Create a new font scale attribute.

The effect of this attribute is to change the font size of a run,
relative to the size of preceding run.

Parameters:

  • scale (Pango::FontScale) —

    a PangoFontScale value, which indicates font size change relative
    to the size of the previous run.

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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 newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_gravity_hint_new(hint) ⇒ Pango::Attribute

Create a new gravity hint attribute.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.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 (Boolean) —

    true if hyphens should be inserted

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_language_new(language) ⇒ Pango::Attribute

Create a new language tag attribute.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_line_height_new(factor) ⇒ Pango::Attribute

Modify the height of logical line extents by a factor.

This affects the values returned by
[methodPango.LayoutLine.get_extents],
[methodPango.LayoutLine.get_pixel_extents] and
[methodPango.LayoutIter.get_line_extents].

Parameters:

  • factor (Float) —

    the scaling factor to apply to the logical height

Returns:

  • (Pango::Attribute)

#attr_line_height_new_absolute(height) ⇒ Pango::Attribute

Override the height of logical line extents to be height.

This affects the values returned by
[methodPango.LayoutLine.get_extents],
[methodPango.LayoutLine.get_pixel_extents] and
[methodPango.LayoutIter.get_line_extents].

Parameters:

  • height (Integer) —

    the line height, in %PANGO_SCALE-ths of a point

Returns:

  • (Pango::Attribute)

#attr_list_from_string(text) ⇒ Pango::AttrList

Deserializes a PangoAttrList from a string.

This is the counterpart to [methodPango.AttrList.to_string].
See that functions for details about the format.

Parameters:

  • text (String) —

    a string

Returns:

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

Create a new overline color attribute.

This attribute modifies the color of overlines.
If not set, overlines 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
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_overline_new(overline) ⇒ Pango::Attribute

Create a new overline-style attribute.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_sentence_new ⇒ Pango::Attribute

Marks the range of the attribute as a single sentence.

Note that this may require adjustments to word and
sentence classification around the range.

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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 PangoLayout.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

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

Creates a new shape attribute.

Like [funcPango.AttrShape.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

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.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_SCALE-ths of a point

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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_SCALE-ths of a device unit

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_stretch_new(stretch) ⇒ Pango::Attribute

Create a new font stretch attribute.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_strikethrough_new(strikethrough) ⇒ Pango::Attribute

Create a new strike-through attribute.

Parameters:

  • strikethrough (Boolean) —

    true if the text should be struck-through

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_style_new(style) ⇒ Pango::Attribute

Create a new font slant style attribute.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_text_transform_new(transform) ⇒ Pango::Attribute

Create a new attribute that influences how characters
are transformed during shaping.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_type_get_name(type) ⇒ String

Fetches the attribute type name.

The attribute type name is the string passed in
when registering the type using
[funcPango.AttrType.register].

The returned value is an interned string (see
g_intern_string() for what that means) that should
not be modified or freed.

Parameters:

Returns:

  • (String) —

    the type ID name (which
    may be nil), or nil if type is a built-in Pango
    attribute type or invalid.

#attr_type_register(name) ⇒ Pango::AttrType

Allocate a new attribute type ID.

The attribute type name can be accessed later
by using [funcPango.AttrType.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
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_underline_new(underline) ⇒ Pango::Attribute

Create a new underline-style attribute.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.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 PangoAttribute,
    which should be freed with [methodPango.Attribute.destroy].

#attr_weight_new(weight) ⇒ Pango::Attribute

Create a new font weight attribute.

Parameters:

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#attr_word_new ⇒ Pango::Attribute

Marks the range of the attribute as a single word.

Note that this may require adjustments to word and
sentence classification around the range.

Returns:

  • (Pango::Attribute) —

    the newly allocated
    PangoAttribute, which should be freed with
    [methodPango.Attribute.destroy]

#bidi_type_for_unichar(ch) ⇒ Pango::BidiType

Determines the bidirectional type of a character.

The bidirectional type is specified in the Unicode Character Database.

A simplified version of this function is available as [funcunichar_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 [funcPango.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) —

    PangoAnalysis structure for text

  • 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 rules from the Unicode Line Breaking Algorithm
without language-specific tailoring, therefore the analyis argument is unused
and can be nil.

See [funcPango.tailor_break] for language-specific breaks.

See [funcPango.attr_break] for attribute-based customization.

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 PangoAnalysis structure 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.

The conversion is done by 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:

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.

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.
    If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned.

#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
next paragraph (index after all delimiters) is stored n
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.

The string must have 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=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", "All-Small-Caps", "Petite-Caps", "All-Petite-Caps",
"Unicase", "Title-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:

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

Computes a PangoLogAttr for each character in text.

The attrs array must have one PangoLogAttr 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

  • attrs (Array<Pango::LogAttr>) —

    array with one PangoLogAttr
    per character in text, plus one extra, to be filled in

  • attrs_len (Integer) —

    length of attrs array

Returns:

  • (nil)

#get_mirror_char(ch, mirrored_ch) ⇒ Boolean

Returns the mirrored character of a Unicode character.

Mirror characters are determined by the Unicode mirrored property.
filled in, false otherwise

Parameters:

  • ch (String) —

    a Unicode character

  • mirrored_ch (String) —

    location to store the mirrored character

Returns:

  • (Boolean) —

    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 PangoMatrix.
%PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if matrix is nil

Parameters:

Returns:

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

Returns the gravity to use in laying out a PangoItem.

The gravity is determined based on the script, base gravity, and hint.

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

Returns the gravity to use in laying out a single character
or PangoItem.

The gravity is determined based on the script, East Asian width,
base gravity, and hint,

This function is similar to [funcPango.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 upright, 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) —

    PangoScript to query

  • wide (Boolean) —

    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 PangoGravity value to its natural rotation in radians.

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

Parameters:

  • gravity (Pango::Gravity) —

    gravity to query, should not be %PANGO_GRAVITY_AUTO

Returns:

  • (Float) —

    the rotation value corresponding to gravity.

#is_zero_width(ch) ⇒ Boolean

Checks if a character that should not be normally rendered.

This includes all Unicode characters with "ZERO WIDTH" in their name,
as well as bidi formatting characters, and a few other ones.

This is totally different from [funcGLib.unichar_iszerowidth] and is at best misnamed.

Parameters:

  • ch (String) —

    a Unicode character

Returns:

  • (Boolean) —

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

#itemize(context, text, start_index, length, attrs, cached_iter) ⇒ GLib::List<Pango::Item>

Breaks a piece of text into segments with consistent directional
level and font.

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

Returns:

  • (GLib::List<Pango::Item>) —

    a GList of
    [structPango.Item] structures. The items should be freed using
    [methodPango.Item.free] in combination with [funcGLib.List.free_full].

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

Like pango_itemize(), but with an explicitly specified base direction.

The base direction is used when computing bidirectional levels.
[funcitemize] gets the base direction from the PangoContext
(see [methodPango.Context.set_base_dir]).

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

Returns:

  • (GLib::List<Pango::Item>) —

    a GList of
    [structPango.Item] structures. The items should be freed using
    [methodPango.Item.free] probably in combination with [funcGLib.List.free_full].

#language_from_string(language) ⇒ Pango::Language

Convert a language tag to a PangoLanguage.

The language tag must be in a RFC-3066 format. PangoLanguage pointers
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 [funcPango.Language.get_default] if you want to get the
PangoLanguage for the current locale of the process.

Parameters:

  • language (String) —

    a string representing a language tag

Returns:

#language_get_default ⇒ Pango::Language

Returns the PangoLanguage for the current locale of the process.

On Unix systems, this is the return value is derived from
setlocale (LC_CTYPE, NULL), 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 setlocale(LC_ALL, "") for the user
settings to take effect. GTK does this in its initialization
functions automatically (by calling gtk_set_locale()).
See the setlocale() manpage for more details.

Note that the default language can change over the life of an application.

Also note that this function will not do the right thing if you
use per-thread locales with uselocale(). In that case, you should
just call pango_language_from_string() yourself.

Returns:

#language_get_preferred ⇒ Array<Pango::Language>

Returns the list of languages that the user prefers.

The list is specified by the PANGO_LANGUAGE or LANGUAGE
environment variables, in order of preference. Note that this
list does not necessarily include the language returned by
[funcPango.Language.get_default].

When choosing language-specific resources, such as the sample
text returned by [methodPango.Language.get_sample_string],
you should first try the default language, followed by the
languages returned by this function.

Returns:

#layout_deserialize_error_quark ⇒ GLib::Quark

Returns:

  • (GLib::Quark)

#log2vis_get_embedding_levels(text, length, pbase_dir) ⇒ Integer

Return the bidirectional embedding levels of the input paragraph.

The bidirectional embedding levels are defined by the Unicode Bidirectional
Algorithm.

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 [funcGLib.free].

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

Finishes parsing markup.

After feeding a Pango markup parser some data with [methodGLib.MarkupParseContext.parse],
use this function to get the list of attributes and text out of the
markup. This function will not free context, use [methodGLib.MarkupParseContext.free]
to do so.

Parameters:

  • context (GLib::MarkupParseContext) —

    A valid parse context that was returned from [funcmarkup_parser_new]

  • attr_list (Pango::AttrList) —

    address of return location for a PangoAttrList

  • text (String) —

    address of return location for text with tags stripped

  • accel_char (String) —

    address of return location for accelerator char

Returns:

  • (Boolean) —

    false if error is set, otherwise true

#markup_parser_new(accel_marker) ⇒ GLib::MarkupParseContext

Incrementally parses marked-up text to create a plain-text string
and an attribute list.

See the Pango Markup docs for details about the
supported markup.

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 [funcmarkup_parser_finish]. Two accel_marker characters
following each other produce a single literal accel_marker character.

To feed markup to the parser, use [methodGLib.MarkupParseContext.parse]
on the returned [structGLib.MarkupParseContext]. When done with feeding markup
to the parser, use [funcmarkup_parser_finish] to get the data out
of it, and then use [methodGLib.MarkupParseContext.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 [funcPango.parse_markup] API is recommended instead.
destroyed with [methodGLib.MarkupParseContext.free].

Parameters:

  • accel_marker (String) —

    character that precedes an accelerator, or 0 for none

Returns:

  • (GLib::MarkupParseContext) —

    a GMarkupParseContext that should be

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

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

  • value (Integer) —

    integer to store the result in

  • warn (Boolean) —

    if true, issue a g_warning() on bad input

  • possible_values (String) —

    place to store list of possible
    values on failure

Returns:

  • (Boolean) —

    true if str was successfully parsed

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

Parses marked-up text to create a plain-text string and an attribute list.

See the Pango Markup docs for details about the
supported markup.

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 [funcmarkup_parser_new].

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

Parameters:

  • markup_text (String) —

    markup to parse (see the Pango Markup docs)

  • 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 PangoAttrList

  • text (String) —

    address of return location for text with tags stripped

  • accel_char (String) —

    address of return location for accelerator char

Returns:

  • (Boolean) —

    false if error is set, otherwise true

#parse_stretch(str, stretch, warn) ⇒ Boolean

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 PangoStretch to store the result in.

  • warn (Boolean) —

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

Returns:

  • (Boolean) —

    true if str was successfully parsed.

#parse_style(str, style, warn) ⇒ Boolean

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 PangoStyle to store the result in.

  • warn (Boolean) —

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

Returns:

  • (Boolean) —

    true if str was successfully parsed.

#parse_variant(str, variant, warn) ⇒ Boolean

Parses a font variant.

The allowed values are "normal", "small-caps", "all-small-caps",
"petite-caps", "all-petite-caps", "unicase" and "title-caps",
case variations being ignored.

Parameters:

  • str (String) —

    a string to parse.

  • variant (Pango::Variant) —

    a PangoVariant to store the result in.

  • warn (Boolean) —

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

Returns:

  • (Boolean) —

    true if str was successfully parsed.

#parse_weight(str, weight, warn) ⇒ Boolean

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 PangoWeight to store the result in.

  • warn (Boolean) —

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

Returns:

  • (Boolean) —

    true if str was successfully parsed.

#quantize_line_geometry(thickness, position) ⇒ nil

Quantizes the thickness and position of a line to whole device pixels.

This is typically used for underline or strikethrough. 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', '\n\r', or '\r\n'. 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(items) ⇒ GLib::List<Pango::Item>

Reorder items from logical order to visual order.

The visual order is determined from the associated directional
levels of the items. 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:

  • items (GLib::List<Pango::Item>) —

    a GList of PangoItem
    in logical order.

Returns:

  • (GLib::List<Pango::Item>) —

    a GList
    of PangoItem structures in visual order.

#scan_int(pos, out) ⇒ Boolean

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:

  • (Boolean) —

    false if a parse error occurred

#scan_string(pos, out) ⇒ Boolean

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:

  • (Boolean) —

    false if a parse error occurred

#scan_word(pos, out) ⇒ Boolean

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:

  • (Boolean) —

    false if a parse error occurred

#script_for_unichar(ch) ⇒ Pango::Script

Looks up the script for a particular character.

The script of a character is defined by
Unicode Standard Annex 24: Script names.

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 [funcGLib.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

Finds a language tag that is reasonably representative of script.

The language will usually be the most widely spoken or used language
written in that script: for instance, the sample language for
%PANGO_SCRIPT_CYRILLIC is ru (Russian), the sample language for
%PANGO_SCRIPT_ARABIC is ar.

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 [methodPango.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.

Parameters:

Returns:

  • (Pango::Language) —

    a PangoLanguage that is representative
    of the script

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

Convert the characters in text into glyphs.

Given a segment of text and the corresponding PangoAnalysis structure
returned from [funcPango.itemize], convert the characters into glyphs. You
may also pass in only a substring of the item from [funcPango.itemize].

It is recommended that you use [funcPango.shape_full] instead, since
that API allows for shaping interaction happening across text item
boundaries.

Some aspects of hyphen insertion and text transformation (in particular,
capitalization) require log attrs, and thus can only be handled by
[funcPango.shape_item].

Note that the extra attributes in the analyis that is returned from
[funcPango.itemize] have indices that are relative to the entire paragraph,
so you need to subtract the item offset from their indices before
calling [funcPango.shape].

Parameters:

  • text (String) —

    the text to process

  • length (Integer) —

    the length (in bytes) of text

  • analysis (Pango::Analysis) —

    PangoAnalysis structure from [funcPango.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

Convert the characters in text into glyphs.

Given a segment of text and the corresponding PangoAnalysis structure
returned from [funcPango.itemize], convert the characters into glyphs.
You may also pass in only a substring of the item from [funcPango.itemize].

This is similar to [funcPango.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.

Some aspects of hyphen insertion and text transformation (in particular,
capitalization) require log attrs, and thus can only be handled by
[funcPango.shape_item].

Note that the extra attributes in the analyis that is returned from
[funcPango.itemize] have indices that are relative to the entire paragraph,
so you do not pass the full paragraph text as paragraph_text, you need
to subtract the item offset from their indices before calling
[funcPango.shape_full].

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).

  • paragraph_length (Integer) —

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

  • analysis (Pango::Analysis) —

    PangoAnalysis structure from [funcPango.itemize].

  • glyphs (Pango::GlyphString) —

    glyph string in which to store results.

Returns:

  • (nil)

#shape_item(item, paragraph_text, paragraph_length, log_attrs, glyphs, flags) ⇒ nil

Convert the characters in item into glyphs.

This is similar to [funcPango.shape_with_flags], except it takes a
PangoItem instead of separate item_text and analysis arguments.

It also takes log_attrs, which are needed for implementing some aspects
of hyphen insertion and text transforms (in particular, capitalization).

Note that the extra attributes in the analyis that is returned from
[funcPango.itemize] have indices that are relative to the entire paragraph,
so you do not pass the full paragraph text as paragraph_text, you need
to subtract the item offset from their indices before calling
[funcPango.shape_with_flags].

Parameters:

  • item (Pango::Item) —

    PangoItem to shape

  • paragraph_text (String) —

    text of the paragraph (see details).

  • paragraph_length (Integer) —

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

  • log_attrs (Pango::LogAttr) —

    array of PangoLogAttr for item

  • glyphs (Pango::GlyphString) —

    glyph string in which to store results

  • flags (Pango::ShapeFlags) —

    flags influencing the shaping process

Returns:

  • (nil)

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

Convert the characters in text into glyphs.

Given a segment of text and the corresponding PangoAnalysis structure
returned from [funcPango.itemize], convert the characters into glyphs.
You may also pass in only a substring of the item from [funcPango.itemize].

This is similar to [funcPango.shape_full], except it also takes flags
that can influence the shaping process.

Some aspects of hyphen insertion and text transformation (in particular,
capitalization) require log attrs, and thus can only be handled by
[funcPango.shape_item].

Note that the extra attributes in the analyis that is returned from
[funcPango.itemize] have indices that are relative to the entire paragraph,
so you do not pass the full paragraph text as paragraph_text, you need
to subtract the item offset from their indices before calling
[funcPango.shape_with_flags].

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).

  • paragraph_length (Integer) —

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

  • analysis (Pango::Analysis) —

    PangoAnalysis structure from [funcPango.itemize]

  • glyphs (Pango::GlyphString) —

    glyph string in which to store results

  • flags (Pango::ShapeFlags) —

    flags influencing the shaping process

Returns:

  • (nil)

#skip_space(pos) ⇒ Boolean

Skips 0 or more characters of white space.

Parameters:

  • pos (String) —

    in/out string position

Returns:

  • (Boolean) —

    false if skipping the white space leaves
    the position at a '\0' character.

#split_file_list(str) ⇒ Array<String>

Splits a %G_SEARCHPATH_SEPARATOR-separated list of files, stripping
white space and substituting ~/ with $HOME/.

Parameters:

  • str (String) —

    a %G_SEARCHPATH_SEPARATOR separated list of filenames

Returns:

  • (Array<String>) —

    a list of
    strings to be freed with g_strfreev()

#tab_array_from_string(text) ⇒ Pango::TabArray

Deserializes a PangoTabArray from a string.

This is the counterpart to [methodPango.TabArray.to_string].
See that functions for details about the format.

Parameters:

  • text (String) —

    a string

Returns:

  • (Pango::TabArray) —

    a new PangoTabArray

#tailor_break(text, length, analysis, offset, attrs, attrs_len) ⇒ nil

Apply language-specific tailoring to the breaks in attrs.

The line breaks are assumed to have been produced by [funcPango.default_break].

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

Note that it is better to pass -1 for offset and use [funcPango.attr_break]
to apply attributes to the whole paragraph.

Parameters:

  • text (String) —

    text to process. Must be valid UTF-8

  • length (Integer) —

    length in bytes of text

  • analysis (Pango::Analysis) —

    PangoAnalysis for text

  • offset (Integer) —

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

  • attrs (Array<Pango::LogAttr>) —

    array with one PangoLogAttr
    per character in text, plus one extra, to be filled in

  • attrs_len (Integer) —

    length of 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.

The inherent direction is 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, [funcPango.BidiType.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.

The conversion is done by multiplying d by %PANGO_SCALE and
rounding the result 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.

The conversion is done by dividing i by %PANGO_SCALE.

Parameters:

  • i (Integer) —

    value in Pango units

Returns:

  • (Float) —

    the double value.

#version ⇒ Integer

Returns the encoded version of Pango available at run-time.

This is similar to the macro %PANGO_VERSION except that the macro
returns the encoded 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_string ⇒ String

Returns the version of Pango available at run-time.

This is similar to the macro %PANGO_VERSION_STRING except that the
macro returns 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.