Miscellaneous Utilities: Pango Reference Manual

## Miscellaneous Utilities Miscellaneous Utilities — Various convenience and utility functions |

## Functions

char ** | pango_split_file_list ()
char * | pango_trim_string ()
gint | pango_read_line ()
gboolean | pango_skip_space ()
gboolean | pango_scan_word ()
gboolean | pango_scan_string ()
gboolean | pango_scan_int ()
char * | pango_config_key_get ()
char * | pango_config_key_get_system ()
void | pango_lookup_aliases ()
gboolean | pango_parse_enum ()
gboolean | pango_parse_style ()
gboolean | pango_parse_variant ()
gboolean | pango_parse_weight ()
gboolean | pango_parse_stretch ()
const char * | pango_get_sysconf_subdirectory ()
const char * | pango_get_lib_subdirectory ()
guint8 * | pango_log2vis_get_embedding_levels ()
gboolean | pango_is_zero_width ()
void | pango_quantize_line_geometry ()

## Description

The functions and utilities in this section are mostly used from Pango backends and modules, but may be useful for other purposes too.

## Functions

### pango_split_file_list ()

    char **
    pango_split_file_list (const char *str);

`pango_split_file_list` has been deprecated since version 1.38 and should not be used in newly-written code.

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

#### Parameters

str | a `G_SEARCHPATH_SEPARATOR` separated list of filenames |

#### Returns

a list of strings to be freed with `g_strfreev()`.

[transfer full][array zero-terminated=1]

### pango_trim_string ()

    char *
    pango_trim_string (const char *str);

`pango_trim_string` has been deprecated since version 1.38 and should not be used in newly-written code.

Trims leading and trailing whitespace from a string.

#### Parameters

str | a string |

#### Returns

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

### pango_read_line ()

    gint
    pango_read_line (FILE *stream,
                     GString *str);

`pango_read_line` has been deprecated since version 1.38 and should not be used in newly-written code.

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 | a stdio stream |
str | GString buffer into which to write the result. | [out]

#### 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 '\')

### pango_skip_space ()

    gboolean
    pango_skip_space (const char **pos);

`pango_skip_space` has been deprecated since version 1.38 and should not be used in newly-written code.

Skips 0 or more characters of white space.

#### Parameters

pos | in/out string position. | [inout]

#### Returns

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

### pango_scan_word ()

    gboolean
    pango_scan_word (const char **pos,
                     GString *out);

`pango_scan_word` has been deprecated since version 1.38 and should not be used in newly-written code.

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 | in/out string position. | [inout]
out | a GString into which to write the result. | [out]

#### Returns

`FALSE` if a parse error occurred.

### pango_scan_string ()

    gboolean
    pango_scan_string (const char **pos,
                       GString *out);

`pango_scan_string` has been deprecated since version 1.38 and should not be used in newly-written code.

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 | in/out string position. | [inout]
out | a GString into which to write the result. | [out]

#### Returns

`FALSE` if a parse error occurred.

### pango_scan_int ()

    gboolean
    pango_scan_int (const char **pos,
                    int *out);

`pango_scan_int` has been deprecated since version 1.38 and should not be used in newly-written code.

Scans an integer. Leading white space is skipped.

#### Parameters

pos | in/out string position. | [inout]
out | an int into which to write the result. | [out]

#### Returns

`FALSE` if a parse error occurred.

### pango_config_key_get ()

    char *
    pango_config_key_get (const char *key);

`pango_config_key_get` has been deprecated since version 1.38 and should not be used in newly-written code.

Do not use. Does not do anything.

#### Parameters

key | Key to look up, in the form "SECTION/KEY". |

#### Returns

`NULL`

### pango_config_key_get_system ()

    char *
    pango_config_key_get_system (const char *key);

`pango_config_key_get_system` has been deprecated since version 1.38 and should not be used in newly-written code.

Do not use. Does not do anything.

#### Parameters

key | Key to look up, in the form "SECTION/KEY". |

#### Returns

`NULL`

### pango_lookup_aliases ()

    void
    pango_lookup_aliases (const char *fontname,
                          char ***families,
                          int *n_families);

`pango_lookup_aliases` has been deprecated since version 1.32 and should not be used in newly-written code.

This function is not thread-safe.

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

#### Parameters

fontname | an ascii string |
families | will be set to an array of font family names. this array is owned by pango and should not be freed. | [out][array length=n_families]
n_families | will be set to the length of the `families` array. | [out]

### pango_parse_enum ()

    gboolean
    pango_parse_enum (GType type,
                      const char *str,
                      int *value,
                      gboolean warn,
                      char **possible_values);

`pango_parse_enum` has been deprecated since version 1.38 and should not be used in newly-written code.

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 `NULL`, returned string should be freed using `g_free()`.

#### Parameters

type | enum type to parse, eg. `PANGO_TYPE_ELLIPSIZE_MODE`. |
str | string to parse. May be `NULL`. | [allow-none]
value | integer to store the result in, or `NULL`. | [out][allow-none]
warn | if `TRUE`, issue a `g_warning()` on bad input. |
possible_values | place to store list of possible values on failure, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` if `str` was successfully parsed.

Since: 1.16

### pango_parse_style ()

    gboolean
    pango_parse_style (const char *str,
                       PangoStyle *style,
                       gboolean warn);

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

#### Parameters

str | a string to parse. |
style | a PangoStyle to store the result in. | [out caller-allocates]
warn | if `TRUE`, issue a `g_warning()` on bad input. |

#### Returns

`TRUE` if `str` was successfully parsed.

### pango_parse_variant ()

    gboolean
    pango_parse_variant (const char *str,
                         PangoVariant *variant,
                         gboolean warn);

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

#### Parameters

str | a string to parse. |
variant | a PangoVariant to store the result in. | [out caller-allocates]
warn | if `TRUE`, issue a `g_warning()` on bad input. |

#### Returns

`TRUE` if `str` was successfully parsed.

### pango_parse_weight ()

    gboolean
    pango_parse_weight (const char *str,
                        PangoWeight *weight,
                        gboolean warn);

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

#### Parameters

str | a string to parse. |
weight | a PangoWeight to store the result in. | [out caller-allocates]
warn | if `TRUE`, issue a `g_warning()` on bad input. |

#### Returns

`TRUE` if `str` was successfully parsed.

### pango_parse_stretch ()

    gboolean
    pango_parse_stretch (const char *str,
                         PangoStretch *stretch,
                         gboolean warn);

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 | a string to parse. |
stretch | a PangoStretch to store the result in. | [out caller-allocates]
warn | if `TRUE`, issue a `g_warning()` on bad input. |

#### Returns

`TRUE` if `str` was successfully parsed.

### pango_get_sysconf_subdirectory ()

    const char *
    pango_get_sysconf_subdirectory (void);

`pango_get_sysconf_subdirectory` has been deprecated since version 1.38 and should not be used in newly-written code.

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

#### Returns

the Pango sysconf directory. The returned string should not be freed.

### pango_get_lib_subdirectory ()

    const char *
    pango_get_lib_subdirectory (void);

`pango_get_lib_subdirectory` has been deprecated since version 1.38 and should not be used in newly-written code.

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

#### Returns

the Pango lib directory. The returned string should not be freed.

### pango_log2vis_get_embedding_levels ()

    guint8 *
    pango_log2vis_get_embedding_levels (const gchar *text,
                                        int length,
                                        PangoDirection *pbase_dir);

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

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

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

#### Parameters

text | the text to itemize. |
length | the number of bytes (not characters) to process, or -1 if `text` is nul-terminated and the length should be calculated. |
pbase_dir | 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 g_free.

Since: 1.4

### pango_is_zero_width ()

    gboolean
    pango_is_zero_width (gunichar ch);

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 `g_unichar_iszerowidth()` and is at best misnamed.

#### Parameters

ch | a Unicode character |

#### Returns

`TRUE` if `ch` is a zero-width character, `FALSE` otherwise

Since: 1.10

### pango_quantize_line_geometry ()

    void
    pango_quantize_line_geometry (int *thickness,
                                  int *position);

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

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

#### Parameters

thickness | pointer to the thickness of a line, in Pango units. | [inout]
position | corresponding position. | [inout]

Since: 1.12

## Types and Values