Functions

  attr_type_get_name (type)
  attr_type_register (name)
  bidi_type_for_unichar (ch)
  break_ (text, length, analysis, attrs)
  config_key_get (key)
  config_key_get_system (key)
  default_break (text, length, analysis, attrs, attrs_len)
  extents_to_pixels (inclusive, nearest)
  find_base_dir (text, length)
  find_paragraph_boundary (text, length)
  font_description_from_string (str)
  get_lib_subdirectory ()
  get_log_attrs (text, length, level, language, log_attrs)
  get_mirror_char (ch, mirrored_ch)
  get_sysconf_subdirectory ()
  gravity_get_for_matrix (matrix)
  gravity_get_for_script (script, base_gravity, hint)
  gravity_get_for_script_and_width (script, wide, base_gravity, hint)
  gravity_to_rotation (gravity)
  is_zero_width (ch)
  itemize (context, text, start_index, length, attrs, cached_iter)
  itemize_with_base_dir (context, base_dir, text, start_index, length, attrs, cached_iter)
  language_from_string (language)
  language_get_default ()
  log2vis_get_embedding_levels (text, length, pbase_dir)
  lookup_aliases (fontname)
  markup_parser_finish (context)
  markup_parser_new (accel_marker)
  module_register (module)
  parse_enum (type, str, warn)
  parse_markup (markup_text, length, accel_marker)
  parse_stretch (str, warn)
  parse_style (str, warn)
  parse_variant (str, warn)
  parse_weight (str, warn)
  quantize_line_geometry (thickness, position)
  read_line (stream)
  reorder_items (logical_items)
  scan_int (pos)
  scan_string (pos)
  scan_word (pos)
  script_for_unichar (ch)
  script_get_sample_language (script)
  shape (text, length, analysis, glyphs)
  shape_full (item_text, item_length, paragraph_text, paragraph_length, analysis, glyphs)
  skip_space (pos)
  split_file_list (str)
  trim_string (str)
  unichar_direction (ch)
  units_from_double (d)
  units_to_double (i)
  version ()
  version_check (required_major, required_minor, required_micro)
  version_string ()

Details

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:str or None

Fetches the attribute type name passed in when registering the type using Pango.AttrType.register().

The returned value is an interned string (see GLib.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:Pango.AttrType

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

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:Pango.BidiType

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

A simplified version of this function is available as Pango.unichar_direction().

New in version 1.22.

Pango.break_(text, length, analysis, attrs)[source]
Parameters:

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

Pango.config_key_get(key)[source]
Parameters:key (str) – Key to look up, in the form “SECTION/KEY”.
Returns:None
Return type:str

Do not use. Does not do anything.

Deprecated since version 1.38.

Pango.config_key_get_system(key)[source]
Parameters:key (str) – Key to look up, in the form “SECTION/KEY”.
Returns:None
Return type:str

Do not use. Does not do anything.

Deprecated since version 1.38.

Pango.default_break(text, length, analysis, attrs, attrs_len)[source]
Parameters:
  • text (str) – text to break
  • length (int) – length of text in bytes (may be -1 if text is nul-terminated)
  • analysis (Pango.Analysis or None) – a Pango.Analysis for the text
  • attrs (Pango.LogAttr) – logical attributes to fill in
  • attrs_len (int) – size of the array passed as attrs

This is the default break algorithm, used if no language engine overrides it. Normally you should use Pango.break_() instead. Unlike Pango.break_(), analysis can be None, but only do that if you know what you’re doing. If you need an analysis to pass to Pango.break_(), you need to Pango.itemize(). In most cases however you should simply use Pango.get_log_attrs().

Pango.extents_to_pixels(inclusive, nearest)[source]
Parameters:

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

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

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

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

New in version 1.16.

Pango.find_base_dir(text, length)[source]
Parameters:
  • text (str) – the text to process
  • 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:

Pango.Direction

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:
  • text (str) – UTF-8 text
  • length (int) – length of text in bytes, or -1 if nul-terminated
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 in paragraph_delimiter_index. The index of the start of the paragraph (index after all delimiters) is stored in next_paragraph_start.

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

Pango.font_description_from_string(str)[source]
Parameters:str (str) – string representation of a font description.
Returns:a new Pango.FontDescription.
Return type:Pango.FontDescription

Creates a new font description from a string representation in the form “‘FAMILY-LIST [STYLE-OPTIONS]’ [SIZE]”, 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. 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.

Pango.get_lib_subdirectory()[source]
Returns:the Pango lib directory. The returned string should not be freed.
Return type:str

Returns the name of the “pango” subdirectory of LIBDIR (which is set at compile time).

Deprecated since version 1.38.

Pango.get_log_attrs(text, length, level, language, log_attrs)[source]
Parameters:
  • text (str) – text to process
  • length (int) – length in bytes of text
  • level (int) – embedding level, or -1 if unknown
  • language (Pango.Language) – language tag
  • log_attrs ([Pango.LogAttr]) – array with one Pango.LogAttr per character in text, plus one extra, to be filled in

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

Pango.get_mirror_char(ch, mirrored_ch)[source]
Parameters:
  • ch (str) – a Unicode character
  • mirrored_ch (str) – location to store the mirrored character
Returns:

True if ch has a mirrored character and mirrored_ch is filled in, False otherwise

Return type:

bool

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

Use GLib.unichar_get_mirror_char() instead; the docs for that function provide full details.

Pango.get_sysconf_subdirectory()[source]
Returns:the Pango sysconf directory. The returned string should not be freed.
Return type:str

Returns the name of the “pango” subdirectory of SYSCONFDIR (which is set at compile time).

Deprecated since version 1.38.

Pango.gravity_get_for_matrix(matrix)[source]
Parameters:matrix (Pango.Matrix or None) – a Pango.Matrix
Returns:the gravity of matrix, which will never be Pango.Gravity.AUTO, or Pango.Gravity.SOUTH if matrix is None
Return type:Pango.Gravity

Finds the gravity that best matches the rotation component in a Pango.Matrix.

New in version 1.16.

Pango.gravity_get_for_script(script, base_gravity, hint)[source]
Parameters:
Returns:

resolved gravity suitable to use for a run of text with script.

Return type:

Pango.Gravity

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

If base_gravity is Pango.Gravity.AUTO, it is first replaced with the preferred gravity of script. To get the preferred gravity of a script, pass Pango.Gravity.AUTO and Pango.GravityHint.STRONG in.

New in version 1.16.

Pango.gravity_get_for_script_and_width(script, wide, base_gravity, hint)[source]
Parameters:
Returns:

resolved gravity suitable to use for a run of text with script and wide.

Return type:

Pango.Gravity

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

This function is similar to Pango.Gravity.get_for_script() except that this function makes a distinction between narrow/half-width and wide/full-width characters also. Wide/full-width characters always stand 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
Returns:the rotation value corresponding to gravity.
Return type:float

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

Note that Pango.Matrix.rotate() takes angle in degrees, not radians. So, to call Pango.Matrix.rotate() with the output of this function you should multiply it by (180. / 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:bool

Checks ch to see if it is a character that should not be normally rendered on the screen. This includes all Unicode characters with “ZERO WIDTH” in their name, as well as bidi formatting characters, and a few other ones. This is totally different from 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.
  • 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, or None
Returns:

a GLib.List of Pango.Item structures. The items should be freed using Pango.Item.free() probably in combination with g_list_foreach(), and the list itself using g_list_free().

Return type:

[Pango.Item]

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

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

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, or None
Returns:

a GLib.List of Pango.Item structures. The items should be freed using Pango.Item.free() probably in combination with g_list_foreach(), and the list itself using g_list_free().

Return type:

[Pango.Item]

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

New in version 1.4.

Pango.language_from_string(language)[source]
Parameters:language (str or None) – a string representing a language tag, or None
Returns:an opaque pointer to a Pango.Language structure, or None if language was None. The returned pointer will be valid forever after, and should not be freed.
Return type:Pango.Language or None

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

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

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

Pango.language_get_default()[source]
Returns:the default language as a Pango.Language, must not be freed.
Return type:Pango.Language

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

On Unix systems, this is the return value is derived from 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 man setlocale for more details.

New in version 1.16.

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 GLib.free.

Return type:

int

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

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

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

New in version 1.4.

Pango.lookup_aliases(fontname)[source]
Parameters:fontname (str) – an ascii string
Returns:will be set to an array of font family names. this array is owned by pango and should not be freed.
Return type:families: [str]

Look up all user defined aliases for the alias fontname. The resulting font family names will be stored in families, and the number of families in n_families.

Deprecated since version 1.32: This function is not thread-safe.

Pango.markup_parser_finish(context)[source]
Parameters:context (GLib.MarkupParseContext) – A valid parse context that was returned from Pango.markup_parser_new()
Raises:GLib.Error
Returns:False if error is set, otherwise True
attr_list:address of return location for a Pango.AttrList, or None
text:address of return location for text with tags stripped, or None
accel_char:address of return location for accelerator str, or None
Return type:(bool, attr_list: Pango.AttrList, text: str, accel_char: str)

After feeding a pango markup parser some data with GLib.MarkupParseContext.parse(), use this function to get the list of pango attributes and text out of the markup. This function will not free context, use 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 GLib.MarkupParseContext that should be destroyed with GLib.MarkupParseContext.free().
Return type:GLib.MarkupParseContext

Parses marked-up text (see

markup format) to create a plain-text string and an attribute list.

If accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, accel_marker might be an ampersand or underscore. All characters marked as an accelerator will receive a Pango.Underline.LOW attribute, and the first character so marked will be returned in accel_char, when calling finish(). Two accel_marker characters following each other produce a single literal accel_marker character.

To feed markup to the parser, use GLib.MarkupParseContext.parse() on the returned GLib.MarkupParseContext. When done with feeding markup to the parser, use Pango.markup_parser_finish() to get the data out of it, and then use 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 simpler Pango.parse_markup() API is recommended instead.

New in version 1.31.0.

Pango.module_register(module)[source]
Parameters:module (Pango.IncludedModule) – a Pango.IncludedModule

Do not use. Does not do anything.

Deprecated since version 1.38.

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. May be None.
  • 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, or None.
possible_values:
 place to store list of possible values on failure, or None.

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 markup format)
  • length (int) – length of markup_text, or -1 if nul-terminated
  • accel_marker (str) – character that precedes an accelerator, or 0 for none
Raises:

GLib.Error

Returns:

False if error is set, otherwise True

attr_list:address of return location for a Pango.AttrList, or None
text:address of return location for text with tags stripped, or None
accel_char:address of return location for accelerator str, or None

Return type:

(bool, attr_list: Pango.AttrList, text: str, accel_char: str)

Parses marked-up text (see

markup format) to create a plain-text string and an attribute list.

If accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, accel_marker might be an ampersand or underscore. All characters marked as an accelerator will receive a Pango.Underline.LOW attribute, and the first character so marked will be returned in accel_char. Two accel_marker characters following each other produce a single literal accel_marker character.

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

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

Pango.parse_stretch(str, warn)[source]
Parameters:
  • str (str) – a string to parse.
  • warn (bool) – if True, issue a g_warning() on bad input.
Returns:

True if str was successfully parsed.

stretch:a Pango.Stretch 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:
  • str (str) – a string to parse.
  • warn (bool) – if True, issue a g_warning() on bad input.
Returns:

True if str was successfully parsed.

style:a Pango.Style 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:
  • str (str) – a string to parse.
  • warn (bool) – if True, issue a g_warning() on bad input.
Returns:

True if str was successfully parsed.

variant:a Pango.Variant to store the result in.

Return type:

(bool, variant: Pango.Variant)

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

Pango.parse_weight(str, warn)[source]
Parameters:
  • str (str) – a string to parse.
  • warn (bool) – if True, issue a g_warning() on bad input.
Returns:

True if str was successfully parsed.

weight:a Pango.Weight 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, typically an underline or strikethrough, to whole device pixels, that is integer multiples of Pango.SCALE. The purpose of this function is to avoid such lines looking blurry.

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

New in version 1.12.

Pango.read_line(stream)[source]
Parameters:stream (object or None) – a stdio stream
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 ‘')
str:GLib.String buffer into which to write the result
Return type:(int, str: GLib.String)

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(logical_items)[source]
Parameters:logical_items ([Pango.Item]) – a GLib.List of Pango.Item in logical order.
Returns:a GLib.List of Pango.Item structures in visual order.

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

Return type:[Pango.Item]

From a list of items in logical order and the associated directional levels, produce a list in visual order. The original list is unmodified.

Pango.scan_int(pos)[source]
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:(bool, pos: str, out: int)

Scans an integer. Leading white space is skipped.

Deprecated since version 1.38.

Pango.scan_string(pos)[source]
Parameters:pos (str) – in/out string position
Returns:False if a parse error occurred.
pos:in/out string position
out:a GLib.String into which to write the result
Return type:(bool, pos: str, out: GLib.String)

Scans a string into a GLib.String 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)[source]
Parameters:pos (str) – in/out string position
Returns:False if a parse error occurred.
pos:in/out string position
out:a GLib.String into which to write the result
Return type:(bool, pos: str, out: GLib.String)

Scans a word into a GLib.String 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 Pango.Script for the character.
Return type:Pango.Script

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

As of Pango 1.18, this function simply returns the return value of GLib.unichar_get_script().

New in version 1.4.

Pango.script_get_sample_language(script)[source]
Parameters:script (Pango.Script) – a Pango.Script
Returns:a Pango.Language that is representative of the script, or None if no such language exists.
Return type:Pango.Language or None

Given a script, finds a language tag that is reasonably representative of that script. This will usually be the most widely spoken or used language written in that script: for instance, the sample language for Pango.Script.CYRILLIC is 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 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, glyphs)[source]
Parameters:

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

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

Pango.shape_full(item_text, item_length, paragraph_text, paragraph_length, analysis, glyphs)[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). May be None.
  • paragraph_length (int) – the length (in bytes) of paragraph_text. -1 means nul-terminated text.
  • analysis (Pango.Analysis) – Pango.Analysis structure from Pango.itemize().
  • glyphs (Pango.GlyphString) – glyph string in which to store results.

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

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

New in version 1.32.

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:(bool, pos: str)

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.trim_string(str)[source]
Parameters:str (str) – a string
Returns:A newly-allocated string that must be freed with GLib.free()
Return type:str

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:Pango.Direction

Determines the inherent direction of a character; either Pango.Direction.LTR, Pango.Direction.RTL, or Pango.Direction.NEUTRAL.

This function is useful to categorize characters into left-to-right letters, right-to-left letters, and everything else. If full Unicode bidirectional type of a character is needed, Pango.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:int

Converts a floating-point number to Pango units: multiplies it by Pango.SCALE and rounds 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:float

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

New in version 1.16.

Pango.version()[source]
Returns:The encoded version of Pango library available at run time.
Return type:int

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

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

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:

str or None

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

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:str

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

New in version 1.16.