Functions -
Pango 1.0 ([original](https://lazka.github.io/pgi-docs/Pango-1.0/functions.html)) ([raw](?raw))Details¶
Pango.attr_allow_breaks_new(allow_breaks)[source]¶
Parameters:
allow_breaks (bool) – True if we line breaks are allowed
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new allow-breaks attribute.
If breaks are disabled, the range will be kept in a single run, as far as possible.
New in version 1.44.
Pango.attr_background_alpha_new(alpha)[source]¶
Parameters:
alpha (int) – the alpha value, between 1 and 65536
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new background alpha attribute.
New in version 1.38.
Pango.attr_background_new(red, green, blue)[source]¶
Parameters:
- red (int) – the red value (ranging from 0 to 65535)
- green (int) – the green value
- blue (int) – the blue value
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new background color attribute.
Pango.attr_baseline_shift_new(shift)[source]¶
Parameters:
shift (int) – 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:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
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.
<source srcset=”baseline-shift-dark.png” media=”(prefers-color-scheme: dark)”> <img alt=”Baseline Shift” src=”baseline-shift-light.png”>
New in version 1.50.
Pango.attr_break(text, length, attr_list, offset)[source]¶
Parameters:
- text (str) – text to break. Must be valid UTF-8
- length (int) – length of text in bytes (may be -1 if text is nul-terminated)
- attr_list (Pango.AttrList) –
PangoAttrListto apply - offset (int) – Byte offset of text from the beginning of the paragraph
Returns:
array with onePangoLogAttr per character in text, plus one extra, to be filled in
Return type:
attrs: [Pango.LogAttr]
Apply customization from attributes to the breaks in attrs.
The line breaks are assumed to have been produced by [func`Pango`.default_break] and [func`Pango`.tailor_break].
New in version 1.50.
Pango.attr_fallback_new(enable_fallback)[source]¶
Parameters:
enable_fallback (bool) – True if we should fall back on other fonts for characters the active font is missing
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
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.
New in version 1.4.
Pango.attr_family_new(family)[source]¶
Parameters:
family (str) – the family or comma-separated list of families
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new font family attribute.
Pango.attr_font_desc_new(desc)[source]¶
Parameters:
desc (Pango.FontDescription) – the font description
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new font description attribute.
This attribute allows setting family, style, weight, variant, stretch, and size simultaneously.
Pango.attr_font_features_new(features)[source]¶
Parameters:
features (str) – a string with OpenType font features, with the syntax of the CSS font-feature-settings property
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
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.
New in version 1.38.
Pango.attr_font_scale_new(scale)[source]¶
Parameters:
scale (Pango.FontScale) – a PangoFontScale value, which indicates font size change relative to the size of the previous run.
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
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.
New in version 1.50.
Pango.attr_foreground_alpha_new(alpha)[source]¶
Parameters:
alpha (int) – the alpha value, between 1 and 65536
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new foreground alpha attribute.
New in version 1.38.
Pango.attr_foreground_new(red, green, blue)[source]¶
Parameters:
- red (int) – the red value (ranging from 0 to 65535)
- green (int) – the green value
- blue (int) – the blue value
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new foreground color attribute.
Pango.attr_gravity_hint_new(hint)[source]¶
Parameters:
hint (Pango.GravityHint) – the gravity hint value
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new gravity hint attribute.
New in version 1.16.
Pango.attr_gravity_new(gravity)[source]¶
Parameters:
gravity (Pango.Gravity) – the gravity value; should not be Pango.Gravity.AUTO
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new gravity attribute.
New in version 1.16.
Pango.attr_insert_hyphens_new(insert_hyphens)[source]¶
Parameters:
insert_hyphens (bool) – True if hyphens should be inserted
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
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.
New in version 1.44.
Pango.attr_language_new(language)[source]¶
Parameters:
language (Pango.Language) – language tag
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new language tag attribute.
Pango.attr_letter_spacing_new(letter_spacing)[source]¶
Parameters:
letter_spacing (int) – amount of extra space to add between graphemes of the text, in Pango units
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new letter-spacing attribute.
New in version 1.6.
Pango.attr_line_height_new(factor)[source]¶
Parameters:
factor (float) – the scaling factor to apply to the logical height
Return type:
Modify the height of logical line extents by a factor.
This affects the values returned by [method`Pango`.LayoutLine.get_extents], [method`Pango`.LayoutLine.get_pixel_extents] and [method`Pango`.LayoutIter.get_line_extents].
New in version 1.50.
Pango.attr_line_height_new_absolute(height)[source]¶
Parameters:
height (int) – the line height, in Pango.SCALE-ths of a point
Return type:
Override the height of logical line extents to be height.
This affects the values returned by [method`Pango`.LayoutLine.get_extents], [method`Pango`.LayoutLine.get_pixel_extents] and [method`Pango`.LayoutIter.get_line_extents].
New in version 1.50.
Pango.attr_list_from_string(text)[source]¶
Parameters:
text (str) – a string
Returns:
a new PangoAttrList
Return type:
Deserializes a PangoAttrList from a string.
This is the counterpart to [method`Pango`.AttrList.to_string]. See that functions for details about the format.
New in version 1.50.
Pango.attr_overline_color_new(red, green, blue)[source]¶
Parameters:
- red (int) – the red value (ranging from 0 to 65535)
- green (int) – the green value
- blue (int) – the blue value
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new overline color attribute.
This attribute modifies the color of overlines. If not set, overlines will use the foreground color.
New in version 1.46.
Pango.attr_overline_new(overline)[source]¶
Parameters:
overline (Pango.Overline) – the overline style
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new overline-style attribute.
New in version 1.46.
Pango.attr_rise_new(rise)[source]¶
Parameters:
rise (int) – the amount that the text should be displaced vertically, in Pango units. Positive values displace the text upwards.
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new baseline displacement attribute.
Pango.attr_scale_new(scale_factor)[source]¶
Parameters:
scale_factor (float) – factor to scale the font
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new font size scale attribute.
The base font for the affected text will have its size multiplied by scale_factor.
Pango.attr_sentence_new()[source]¶
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Marks the range of the attribute as a single sentence.
Note that this may require adjustments to word and sentence classification around the range.
New in version 1.50.
Pango.attr_shape_new(ink_rect, logical_rect)[source]¶
Parameters:
- ink_rect (Pango.Rectangle) – ink rectangle to assign to each character
- logical_rect (Pango.Rectangle) – logical rectangle to assign to each character
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
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.
Pango.attr_shape_new_with_data(ink_rect, logical_rect, data, copy_func)[source]¶
Parameters:
- ink_rect (Pango.Rectangle) – ink rectangle to assign to each character
- logical_rect (Pango.Rectangle) – logical rectangle to assign to each character
- data (object or None) – user data pointer
- copy_func (Pango.AttrDataCopyFunc or None) – function to copy data when the attribute is copied. If None, data is simply copied as a pointer
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Creates a new shape attribute.
Like [func`Pango`.AttrShape.new], but a user data pointer is also provided; this pointer can be accessed when later rendering the glyph.
New in version 1.8.
Pango.attr_show_new(flags)[source]¶
Parameters:
flags (Pango.ShowFlags) – PangoShowFlags to apply
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new attribute that influences how invisible characters are rendered.
New in version 1.44.
Pango.attr_size_new(size)[source]¶
Parameters:
size (int) – the font size, in Pango.SCALE-ths of a point
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new font-size attribute in fractional points.
Pango.attr_size_new_absolute(size)[source]¶
Parameters:
size (int) – the font size, in Pango.SCALE-ths of a device unit
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new font-size attribute in device units.
New in version 1.8.
Pango.attr_stretch_new(stretch)[source]¶
Parameters:
stretch (Pango.Stretch) – the stretch
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new font stretch attribute.
Pango.attr_strikethrough_color_new(red, green, blue)[source]¶
Parameters:
- red (int) – the red value (ranging from 0 to 65535)
- green (int) – the green value
- blue (int) – the blue value
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new strikethrough color attribute.
This attribute modifies the color of strikethrough lines. If not set, strikethrough lines will use the foreground color.
New in version 1.8.
Pango.attr_strikethrough_new(strikethrough)[source]¶
Parameters:
strikethrough (bool) – True if the text should be struck-through
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new strike-through attribute.
Pango.attr_style_new(style)[source]¶
Parameters:
style (Pango.Style) – the slant style
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new font slant style attribute.
Pango.attr_text_transform_new(transform)[source]¶
Parameters:
transform (Pango.TextTransform) – PangoTextTransform to apply
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new attribute that influences how characters are transformed during shaping.
New in version 1.50.
Pango.attr_type_get_name(type)[source]¶
Parameters:
type (Pango.AttrType) – an attribute type ID to fetch the name for
Returns:
the type ID name (which may be None), or None if type is a built-in Pango attribute type or invalid.
Return type:
Fetches the attribute type name.
The attribute type name is the string passed in when registering the type using [func`Pango`.AttrType.register].
The returned value is an interned string (seeGLib.intern_string() for what that means) that should not be modified or freed.
New in version 1.22.
Pango.attr_type_register(name)[source]¶
Parameters:
name (str) – an identifier for the type
Returns:
the new type ID.
Return type:
Allocate a new attribute type ID.
The attribute type name can be accessed later by using [func`Pango`.AttrType.get_name].
Pango.attr_underline_color_new(red, green, blue)[source]¶
Parameters:
- red (int) – the red value (ranging from 0 to 65535)
- green (int) – the green value
- blue (int) – the blue value
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new underline color attribute.
This attribute modifies the color of underlines. If not set, underlines will use the foreground color.
New in version 1.8.
Pango.attr_underline_new(underline)[source]¶
Parameters:
underline (Pango.Underline) – the underline style
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new underline-style attribute.
Pango.attr_variant_new(variant)[source]¶
Parameters:
variant (Pango.Variant) – the variant
Returns:
the newly allocated PangoAttribute, which should be freed with [method`Pango`.Attribute.destroy].
Return type:
Create a new font variant attribute (normal or small caps).
Pango.attr_weight_new(weight)[source]¶
Parameters:
weight (Pango.Weight) – the weight
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Create a new font weight attribute.
Pango.attr_word_new()[source]¶
Returns:
the newly allocatedPangoAttribute, which should be freed with [method`Pango`.Attribute.destroy]
Return type:
Marks the range of the attribute as a single word.
Note that this may require adjustments to word and sentence classification around the range.
New in version 1.50.
Pango.bidi_type_for_unichar(ch)[source]¶
Parameters:
ch (str) – a Unicode character
Returns:
the bidirectional character type, as used in the Unicode bidirectional algorithm.
Return type:
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 [func`unichar_direction`].
New in version 1.22.
Pango.break_(text, length, analysis)[source]¶
Parameters:
- text (str) – the text to process. Must be valid UTF-8
- length (int) – length of text in bytes (may be -1 if text is nul-terminated)
- analysis (Pango.Analysis) –
PangoAnalysisstructure for text
Returns:
an array to store character information in
Return type:
attrs: [Pango.LogAttr]
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 [func`Pango`.get_log_attrs].
Deprecated since version 1.44: Use [func`Pango`.default_break], [func`Pango`.tailor_break] and [func`Pango`.attr_break].
Pango.default_break(text, length, analysis)[source]¶
Parameters:
- text (str) – text to break. Must be valid UTF-8
- length (int) – length of text in bytes (may be -1 if text is nul-terminated)
- analysis (Pango.Analysis or None) – a
PangoAnalysisstructure for the text
Returns:
logical attributes to fill in
Return type:
attrs: [Pango.LogAttr]
This is the default break algorithm.
It applies rules from the Unicode Line Breaking Algorithmwithout language-specific tailoring, therefore the analyis argument is unused and can be None.
See [func`Pango`.tailor_break] for language-specific breaks.
See [func`Pango`.attr_break] for attribute-based customization.
Pango.extents_to_pixels(inclusive, nearest)[source]¶
Parameters:
- inclusive (Pango.Rectangle or None) – rectangle to round to pixels inclusively
- nearest (Pango.Rectangle or None) – rectangle to round to nearest pixels
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 asinclusive. If you want two touching-but-not-overlapping rectangles stay touching-but-not-overlapping after rounding to device units, pass them in as nearest.
New in version 1.16.
Pango.find_base_dir(text, length)[source]¶
Parameters:
- text (str) – the text to process. Must be valid UTF-8
- length (int) – length of text in bytes (may be -1 if text is nul-terminated)
Returns:
The direction corresponding to the first strong character. If no such character is found, then Pango.Direction.NEUTRAL is returned.
Return type:
Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm.
New in version 1.4.
Pango.find_paragraph_boundary(text, length)[source]¶
Parameters:
Returns:
paragraph_delimiter_index:
return location for index of delimiter
next_paragraph_start:
return location for start of next paragraph
Return type:
(paragraph_delimiter_index: int, next_paragraph_start: int)
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 inparagraph_delimiter_index. The index of the start of the next paragraph (index after all delimiters) is stored nnext_paragraph_start.
If no delimiters are found, both paragraph_delimiter_indexand next_paragraph_start are filled with the length of text(an index one off the end).
Pango.font_description_from_string(str)[source]¶
Parameters:
str (str) – string representation of a font description.
Returns:
a new PangoFontDescription.
Return type:
Creates a new font description from a string representation.
The string must have the form
‘FAMILY-LIST [STYLE-OPTIONS]’ ‘SIZE [VARIATIONS]’ [FEATURES]
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.
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”.
VARIATIONS is a comma-separated list of font variations of the form @axis1=value,axis2=value,…
FEATURES is a comma-separated list of font features of the form \#feature1=value,feature2=value,… The =value part can be ommitted if the value is 1.
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 None. 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 @wght=200 #tnum=1
Pango.get_log_attrs(text, length, level, language)[source]¶
Parameters:
- text (str) – text to process. Must be valid UTF-8
- length (int) – length in bytes of text
- level (int) – embedding level, or -1 if unknown
- language (Pango.Language) – language tag
Returns:
array with onePangoLogAttr per character in text, plus one extra, to be filled in
Return type:
attrs: [Pango.LogAttr]
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).
Pango.get_mirror_char(ch)[source]¶
Parameters:
ch (str) – a Unicode character
Returns:
True if ch has a mirrored character and mirrored_ch is filled in, False otherwise
mirrored_ch:
location to store the mirrored character
Return type:
Returns the mirrored character of a Unicode character.
Mirror characters are determined by the Unicode mirrored property.
Deprecated since version 1.30: Use [func`GLib`.unichar_get_mirror_char] instead; the docs for that function provide full details.
Pango.gravity_get_for_matrix(matrix)[source]¶
Parameters:
matrix (Pango.Matrix or None) – a PangoMatrix
Returns:
the gravity of matrix, which will never bePango.Gravity.AUTO, or Pango.Gravity.SOUTH if matrix is None
Return type:
Finds the gravity that best matches the rotation component in a PangoMatrix.
New in version 1.16.
Pango.gravity_get_for_script(script, base_gravity, hint)[source]¶
Parameters:
- script (Pango.Script) –
PangoScriptto query - base_gravity (Pango.Gravity) – base gravity of the paragraph
- hint (Pango.GravityHint) – orientation hint
Returns:
resolved gravity suitable to use for a run of text with script
Return type:
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.GravityHint.STRONG in.
New in version 1.16.
Pango.gravity_get_for_script_and_width(script, wide, base_gravity, hint)[source]¶
Parameters:
- script (Pango.Script) –
PangoScriptto query - wide (bool) – True for wide characters as returned by GLib.unichar_iswide()
- base_gravity (Pango.Gravity) – base gravity of the paragraph
- hint (Pango.GravityHint) – orientation hint
Returns:
resolved gravity suitable to use for a run of text with script and wide.
Return type:
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 [func`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 *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.
New in version 1.26.
Pango.gravity_to_rotation(gravity)[source]¶
Parameters:
gravity (Pango.Gravity) – gravity to query, should not be Pango.Gravity.AUTO
Returns:
the rotation value corresponding to gravity.
Return type:
Converts a PangoGravity value to its natural rotation in radians.
Note that [method`Pango`.Matrix.rotate] takes angle in degrees, not radians. So, to call [method`Pango`.Matrix,rotate] with the output of this function you should multiply it by (180. / GLib.PI).
New in version 1.16.
Pango.is_zero_width(ch)[source]¶
Parameters:
ch (str) – a Unicode character
Returns:
True if ch is a zero-width character, False otherwise
Return type:
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 [func`GLib`.unichar_iszerowidth] and is at best misnamed.
New in version 1.10.
Pango.itemize(context, text, start_index, length, attrs, cached_iter)[source]¶
Parameters:
- context (Pango.Context) – a structure holding information that affects the itemization process.
- text (str) – the text to itemize. Must be valid UTF-8
- start_index (int) – first byte in text to process
- length (int) – 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 or None) – Cached attribute iterator
Returns:
a GList of [struct`Pango`.Item] structures. The items should be freed using [method`Pango`.Item.free] in combination with [func`GLib`.List.free_full].
Return type:
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 afterstart_index + length. (i.e. if itemizing in a loop, just keep passing in the same cached_iter).
Pango.itemize_with_base_dir(context, base_dir, text, start_index, length, attrs, cached_iter)[source]¶
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 (str) – the text to itemize.
- start_index (int) – first byte in text to process
- length (int) – 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 or None) – Cached attribute iterator
Returns:
a GList of [struct`Pango`.Item] structures. The items should be freed using [method`Pango`.Item.free] probably in combination with [func`GLib`.List.free_full].
Return type:
Like pango_itemize(), but with an explicitly specified base direction.
The base direction is used when computing bidirectional levels. [func`itemize`] gets the base direction from the PangoContext(see [method`Pango`.Context.set_base_dir]).
New in version 1.4.
Pango.language_from_string(language)[source]¶
Parameters:
language (str or None) – a string representing a language tag
Returns:
a PangoLanguage
Return type:
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 [func`Pango`.Language.get_default] if you want to get thePangoLanguage for the current locale of the process.
Pango.language_get_default()[source]¶
Returns:
the default language as a PangoLanguage
Return type:
Returns the PangoLanguage for the current locale of the process.
On Unix systems, this is the return value is derived fromsetlocale (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.
New in version 1.16.
Pango.language_get_preferred()[source]¶
Returns:
a None-terminated array of PangoLanguage *
Return type:
[Pango.Language] or None
Returns the list of languages that the user prefers.
The list is specified by the PANGO_LANGUAGE or LANGUAGEenvironment variables, in order of preference. Note that this list does not necessarily include the language returned by [func`Pango`.Language.get_default].
When choosing language-specific resources, such as the sample text returned by [method`Pango`.Language.get_sample_string], you should first try the default language, followed by the languages returned by this function.
New in version 1.48.
Pango.layout_deserialize_error_quark()[source]¶
Return type:
Pango.log2vis_get_embedding_levels(text, length, pbase_dir)[source]¶
Parameters:
- text (str) – the text to itemize.
- length (int) – 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:
a newly allocated array of embedding levels, one item per character (not byte), that should be freed using [func`GLib`.free].
pbase_dir:
input base direction, and output resolved direction.
Return type:
(bytes, pbase_dir: Pango.Direction)
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.
New in version 1.4.
Pango.markup_parser_finish(context)[source]¶
Parameters:
context (GLib.MarkupParseContext) – A valid parse context that was returned from [func`markup_parser_new`]
Raises:
Returns:
False if error is set, otherwise True
attr_list:
address of return location for a PangoAttrList
text:
address of return location for text with tags stripped
accel_char:
address of return location for accelerator str
Return type:
(bool, attr_list: Pango.AttrList, text: str, accel_char: str)
Finishes parsing markup.
After feeding a Pango markup parser some data with [method`GLib`.MarkupParseContext.parse], use this function to get the list of attributes and text out of the markup. This function will not free context, use [method`GLib`.MarkupParseContext.free] to do so.
New in version 1.31.0.
Pango.markup_parser_new(accel_marker)[source]¶
Parameters:
accel_marker (str) – character that precedes an accelerator, or 0 for none
Returns:
a GMarkupParseContext that should be destroyed with [method`GLib`.MarkupParseContext.free].
Return type:
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_markermight 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 [func`markup_parser_finish`]. Two accel_marker characters following each other produce a single literal accel_marker character.
To feed markup to the parser, use [method`GLib`.MarkupParseContext.parse] on the returned [struct`GLib`.MarkupParseContext]. When done with feeding markup to the parser, use [func`markup_parser_finish`] to get the data out of it, and then use [method`GLib`.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 [func`Pango`.parse_markup] API is recommended instead.
New in version 1.31.0.
Pango.parse_enum(type, str, warn)[source]¶
Parameters:
- type (GObject.GType) – enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE
- str (str or None) – string to parse
- warn (bool) – if True, issue a g_warning() on bad input
Returns:
True if str was successfully parsed
value:
integer to store the result in
possible_values:
place to store list of possible values on failure
Return type:
(bool, value: int, possible_values: str)
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 None, returned string should be freed using GLib.free().
New in version 1.16.
Deprecated since version 1.38.
Pango.parse_markup(markup_text, length, accel_marker)[source]¶
Parameters:
- markup_text (str) – markup to parse (see the Pango Markup docs)
- length (int) – length of markup_text, or -1 if nul-terminated
- accel_marker (str) – character that precedes an accelerator, or 0 for none
Raises:
Returns:
False if error is set, otherwise True
attr_list:
address of return location for a PangoAttrList
text:
address of return location for text with tags stripped
accel_char:
address of return location for accelerator str
Return type:
(bool, attr_list: Pango.AttrList, text: str, accel_char: str)
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_markermight 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 [func`markup_parser_new`].
If any error happens, none of the output arguments are touched except for error.
Pango.parse_stretch(str, warn)[source]¶
Parameters:
Returns:
True if str was successfully parsed.
stretch:
a PangoStretch to store the result in.
Return type:
(bool, stretch: Pango.Stretch)
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.
Pango.parse_style(str, warn)[source]¶
Parameters:
Returns:
True if str was successfully parsed.
style:
a PangoStyle to store the result in.
Return type:
(bool, style: Pango.Style)
Parses a font style.
The allowed values are “normal”, “italic” and “oblique”, case variations being ignored.
Pango.parse_variant(str, warn)[source]¶
Parameters:
Returns:
True if str was successfully parsed.
variant:
a PangoVariant to store the result in.
Return type:
(bool, variant: Pango.Variant)
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.
Pango.parse_weight(str, warn)[source]¶
Parameters:
Returns:
True if str was successfully parsed.
weight:
a PangoWeight to store the result in.
Return type:
(bool, weight: Pango.Weight)
Parses a font weight.
The allowed values are “heavy”, “ultrabold”, “bold”, “normal”, “light”, “ultraleight” and integers. Case variations are ignored.
Pango.quantize_line_geometry(thickness, position)[source]¶
Parameters:
- thickness (int) – pointer to the thickness of a line, in Pango units
- position (int) – corresponding position
Returns:
thickness:
pointer to the thickness of a line, in Pango units
position:
corresponding position
Return type:
(thickness: int, position: int)
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.
New in version 1.12.
Pango.read_line(stream, str)[source]¶
Parameters:
- stream (object or None) – a stdio stream
- str (GLib.String) –
GStringbuffer into which to write the result
Returns:
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 ‘\’)
Return type:
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.
Deprecated since version 1.38.
Pango.reorder_items(items)[source]¶
Parameters:
items ([Pango.Item]) – a GList of PangoItemin logical order.
Returns:
a GListof PangoItem structures in visual order.
Return type:
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:
pos (str) – in/out string position
Returns:
False if a parse error occurred
pos:
in/out string position
out:
an int into which to write the result
Return type:
Scans an integer.
Leading white space is skipped.
Deprecated since version 1.38.
Pango.scan_string(pos, out)[source]¶
Parameters:
- pos (str) – in/out string position
- out (GLib.String) – a
GStringinto which to write the result
Returns:
False if a parse error occurred
pos:
in/out string position
Return type:
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.
Deprecated since version 1.38.
Pango.scan_word(pos, out)[source]¶
Parameters:
- pos (str) – in/out string position
- out (GLib.String) – a
GStringinto which to write the result
Returns:
False if a parse error occurred
pos:
in/out string position
Return type:
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.
Deprecated since version 1.38.
Pango.script_for_unichar(ch)[source]¶
Parameters:
ch (str) – a Unicode character
Returns:
the PangoScript for the character.
Return type:
Looks up the script for a particular character.
The script of a character is defined byUnicode 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 [func`GLib`.unichar_get_script]. Callers must be prepared to handle unknown values.
New in version 1.4.
Pango.script_get_sample_language(script)[source]¶
Parameters:
script (Pango.Script) – a PangoScript
Returns:
a PangoLanguage that is representative of the script
Return type:
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 forPango.Script.CYRILLIC is ru (Russian), the sample language forPango.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 variablesPANGO_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 [method`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.
New in version 1.4.
Pango.shape(text, length, analysis)[source]¶
Parameters:
- text (str) – the text to process
- length (int) – the length (in bytes) of text
- analysis (Pango.Analysis) –
PangoAnalysisstructure from [func`Pango`.itemize]
Returns:
glyph string in which to store results
Return type:
glyphs: Pango.GlyphString
Convert the characters in text into glyphs.
Given a segment of text and the corresponding PangoAnalysis structure returned from [func`Pango`.itemize], convert the characters into glyphs. You may also pass in only a substring of the item from [func`Pango`.itemize].
It is recommended that you use [func`Pango`.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 [func`Pango`.shape_item].
Note that the extra attributes in the analyis that is returned from [func`Pango`.itemize] have indices that are relative to the entire paragraph, so you need to subtract the item offset from their indices before calling [func`Pango`.shape].
Pango.shape_full(item_text, item_length, paragraph_text, paragraph_length, analysis)[source]¶
Parameters:
- item_text (str) – valid UTF-8 text to shape.
- item_length (int) – the length (in bytes) of item_text. -1 means nul-terminated text.
- paragraph_text (str or None) – text of the paragraph (see details).
- paragraph_length (int) – the length (in bytes) of paragraph_text. -1 means nul-terminated text.
- analysis (Pango.Analysis) –
PangoAnalysisstructure from [func`Pango`.itemize].
Returns:
glyph string in which to store results.
Return type:
glyphs: Pango.GlyphString
Convert the characters in text into glyphs.
Given a segment of text and the corresponding PangoAnalysis structure returned from [func`Pango`.itemize], convert the characters into glyphs. You may also pass in only a substring of the item from [func`Pango`.itemize].
This is similar to [func`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 asparagraph_text. If paragraph_text is None, 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 [func`Pango`.shape_item].
Note that the extra attributes in the analyis that is returned from [func`Pango`.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 [func`Pango`.shape_full].
New in version 1.32.
Pango.shape_item(item, paragraph_text, paragraph_length, log_attrs, flags)[source]¶
Parameters:
- item (Pango.Item) –
PangoItemto shape - paragraph_text (str or None) – text of the paragraph (see details).
- paragraph_length (int) – the length (in bytes) of paragraph_text. -1 means nul-terminated text.
- log_attrs (Pango.LogAttr or None) – array of
PangoLogAttrfor item - flags (Pango.ShapeFlags) – flags influencing the shaping process
Returns:
glyph string in which to store results
Return type:
glyphs: Pango.GlyphString
Convert the characters in item into glyphs.
This is similar to [func`Pango`.shape_with_flags], except it takes aPangoItem 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 [func`Pango`.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 [func`Pango`.shape_with_flags].
New in version 1.50.
Pango.shape_with_flags(item_text, item_length, paragraph_text, paragraph_length, analysis, flags)[source]¶
Parameters:
- item_text (str) – valid UTF-8 text to shape
- item_length (int) – the length (in bytes) of item_text. -1 means nul-terminated text.
- paragraph_text (str or None) – text of the paragraph (see details).
- paragraph_length (int) – the length (in bytes) of paragraph_text. -1 means nul-terminated text.
- analysis (Pango.Analysis) –
PangoAnalysisstructure from [func`Pango`.itemize] - flags (Pango.ShapeFlags) – flags influencing the shaping process
Returns:
glyph string in which to store results
Return type:
glyphs: Pango.GlyphString
Convert the characters in text into glyphs.
Given a segment of text and the corresponding PangoAnalysis structure returned from [func`Pango`.itemize], convert the characters into glyphs. You may also pass in only a substring of the item from [func`Pango`.itemize].
This is similar to [func`Pango`.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 [func`Pango`.shape_item].
Note that the extra attributes in the analyis that is returned from [func`Pango`.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 [func`Pango`.shape_with_flags].
New in version 1.44.
Pango.skip_space(pos)[source]¶
Parameters:
pos (str) – in/out string position
Returns:
False if skipping the white space leaves the position at a ‘\0’ character.
pos:
in/out string position
Return type:
Skips 0 or more characters of white space.
Deprecated since version 1.38.
Pango.split_file_list(str)[source]¶
Parameters:
str (str) – a GLib.SEARCHPATH_SEPARATOR separated list of filenames
Returns:
a list of strings to be freed with GLib.strfreev()
Return type:
[str]
Splits a GLib.SEARCHPATH_SEPARATOR-separated list of files, stripping white space and substituting ~/ with $HOME/.
Deprecated since version 1.38.
Pango.tab_array_from_string(text)[source]¶
Parameters:
text (str) – a string
Returns:
a new PangoTabArray
Return type:
Deserializes a PangoTabArray from a string.
This is the counterpart to [method`Pango`.TabArray.to_string]. See that functions for details about the format.
New in version 1.50.
Pango.tailor_break(text, length, analysis, offset)[source]¶
Parameters:
- text (str) – text to process. Must be valid UTF-8
- length (int) – length in bytes of text
- analysis (Pango.Analysis) –
PangoAnalysisfor text - offset (int) – Byte offset of text from the beginning of the paragraph, or -1 to ignore attributes from analysis
Returns:
array with onePangoLogAttr per character in text, plus one extra, to be filled in
Return type:
attrs: [Pango.LogAttr]
Apply language-specific tailoring to the breaks in attrs.
The line breaks are assumed to have been produced by [func`Pango`.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 [func`Pango`.attr_break] to apply attributes to the whole paragraph.
New in version 1.44.
Pango.trim_string(str)[source]¶
Parameters:
str (str) – a string
Returns:
A newly-allocated string that must be freed with GLib.free()
Return type:
Trims leading and trailing whitespace from a string.
Deprecated since version 1.38.
Pango.unichar_direction(ch)[source]¶
Parameters:
ch (str) – a Unicode character
Returns:
the direction of the character.
Return type:
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, [func`Pango`.BidiType.for_unichar] can be used instead.
Pango.units_from_double(d)[source]¶
Parameters:
d (float) – double floating-point value
Returns:
the value in Pango units.
Return type:
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.
New in version 1.16.
Pango.units_to_double(i)[source]¶
Parameters:
i (int) – value in Pango units
Returns:
the double value.
Return type:
Converts a number in Pango units to floating-point.
The conversion is done by dividing i by Pango.SCALE.
New in version 1.16.
Returns:
The encoded version of Pango library available at run time.
Return type:
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().
New in version 1.16.
Pango.version_check(required_major, required_minor, required_micro)[source]¶
Parameters:
- required_major (int) – the required major version
- required_minor (int) – the required minor version
- required_micro (int) – the required major version
Returns:
None 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.
Return type:
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 versionrequired_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().
New in version 1.16.
Pango.version_string()[source]¶
Returns:
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.
Return type:
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.
New in version 1.16.