GI.Pango.Functions

Methods

attrAllowBreaksNew

attrAllowBreaksNew

Arguments

:: (HasCallStack, MonadIO m)

=> Bool

allowBreaks: True if we line breaks are allowed

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new allow-breaks attribute.

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

Since: 1.44

attrBackgroundAlphaNew

attrBackgroundAlphaNew

Arguments

:: (HasCallStack, MonadIO m)

=> Word16

alpha: the alpha value, between 1 and 65536

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new background alpha attribute.

Since: 1.38

attrBackgroundNew

attrBackgroundNew

Arguments

:: (HasCallStack, MonadIO m)

=> Word16

red: the red value (ranging from 0 to 65535)

-> Word16

green: the green value

-> Word16

blue: the blue value

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new background color attribute.

attrBaselineShiftNew

attrBaselineShiftNew

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

shift: 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.

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

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.

<picture> <source srcset="baseline-shift-dark.png" media="(prefers-color-scheme: dark)"> <img alt="Baseline Shift" src="baseline-shift-light.png"> </picture>

Since: 1.50

attrBreak

attrBreak

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: text to break. Must be valid UTF-8

-> Int32

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

-> AttrList

attrList: PangoAttrList to apply

-> Int32

offset: Byte offset of text from the beginning of the paragraph

-> [LogAttr]

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

-> m ()

Apply customization from attributes to the breaks in attrs.

The line breaks are assumed to have been produced by defaultBreak and tailorBreak.

Since: 1.50

attrFallbackNew

attrFallbackNew

Arguments

:: (HasCallStack, MonadIO m)

=> Bool

enableFallback: True if we should fall back on other fonts for characters the active font is missing

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

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.

Since: 1.4

attrFamilyNew

attrFamilyNew

Arguments

:: (HasCallStack, MonadIO m)

=> Text

family: the family or comma-separated list of families

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new font family attribute.

attrFontScaleNew

attrFontScaleNew

Arguments

:: (HasCallStack, MonadIO m)

=> FontScale

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

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

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.

Since: 1.50

attrForegroundAlphaNew

attrForegroundAlphaNew

Arguments

:: (HasCallStack, MonadIO m)

=> Word16

alpha: the alpha value, between 1 and 65536

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new foreground alpha attribute.

Since: 1.38

attrForegroundNew

attrForegroundNew

Arguments

:: (HasCallStack, MonadIO m)

=> Word16

red: the red value (ranging from 0 to 65535)

-> Word16

green: the green value

-> Word16

blue: the blue value

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new foreground color attribute.

attrGravityHintNew

attrGravityHintNew

Arguments

:: (HasCallStack, MonadIO m)

=> GravityHint

hint: the gravity hint value

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new gravity hint attribute.

Since: 1.16

attrGravityNew

attrGravityNew

Arguments

:: (HasCallStack, MonadIO m)

=> Gravity

gravity: the gravity value; should not be GravityAuto

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new gravity attribute.

Since: 1.16

attrInsertHyphensNew

attrInsertHyphensNew

Arguments

:: (HasCallStack, MonadIO m)

=> Bool

insertHyphens: True if hyphens should be inserted

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

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.

Since: 1.44

attrLetterSpacingNew

attrLetterSpacingNew

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

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

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new letter-spacing attribute.

Since: 1.6

attrLineHeightNew

attrLineHeightNew

Arguments

:: (HasCallStack, MonadIO m)

=> Double

factor: the scaling factor to apply to the logical height

-> m Attribute

Modify the height of logical line extents by a factor.

This affects the values returned by layoutLineGetExtents, layoutLineGetPixelExtents and layoutIterGetLineExtents.

Since: 1.50

attrLineHeightNewAbsolute

attrLineHeightNewAbsolute

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

height: the line height, in SCALE-ths of a point

-> m Attribute

Override the height of logical line extents to be height.

This affects the values returned by layoutLineGetExtents, layoutLineGetPixelExtents and layoutIterGetLineExtents.

Since: 1.50

attrOverlineColorNew

attrOverlineColorNew

Arguments

:: (HasCallStack, MonadIO m)

=> Word16

red: the red value (ranging from 0 to 65535)

-> Word16

green: the green value

-> Word16

blue: the blue value

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new overline color attribute.

This attribute modifies the color of overlines. If not set, overlines will use the foreground color.

Since: 1.46

attrOverlineNew

attrOverlineNew

Arguments

:: (HasCallStack, MonadIO m)

=> Overline

overline: the overline style

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new overline-style attribute.

Since: 1.46

attrRiseNew

attrRiseNew

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

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

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new baseline displacement attribute.

attrScaleNew

attrScaleNew

Arguments

:: (HasCallStack, MonadIO m)

=> Double

scaleFactor: factor to scale the font

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new font size scale attribute.

The base font for the affected text will have its size multiplied by scaleFactor.

attrSentenceNew

attrSentenceNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Marks the range of the attribute as a single sentence.

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

Since: 1.50

attrShowNew

attrShowNew

Arguments

:: (HasCallStack, MonadIO m)

=> [ShowFlags]

flags: PangoShowFlags to apply

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

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

Since: 1.44

attrStretchNew

attrStretchNew

Arguments

:: (HasCallStack, MonadIO m)

=> Stretch

stretch: the stretch

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new font stretch attribute.

attrStrikethroughColorNew

attrStrikethroughColorNew

Arguments

:: (HasCallStack, MonadIO m)

=> Word16

red: the red value (ranging from 0 to 65535)

-> Word16

green: the green value

-> Word16

blue: the blue value

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new strikethrough color attribute.

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

Since: 1.8

attrStrikethroughNew

attrStrikethroughNew

Arguments

:: (HasCallStack, MonadIO m)

=> Bool

strikethrough: True if the text should be struck-through

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new strike-through attribute.

attrStyleNew

attrStyleNew

Arguments

:: (HasCallStack, MonadIO m)

=> Style

style: the slant style

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new font slant style attribute.

attrTextTransformNew

attrTextTransformNew

Arguments

:: (HasCallStack, MonadIO m)

=> TextTransform

transform: PangoTextTransform to apply

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

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

Since: 1.50

attrUnderlineColorNew

attrUnderlineColorNew

Arguments

:: (HasCallStack, MonadIO m)

=> Word16

red: the red value (ranging from 0 to 65535)

-> Word16

green: the green value

-> Word16

blue: the blue value

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new underline color attribute.

This attribute modifies the color of underlines. If not set, underlines will use the foreground color.

Since: 1.8

attrUnderlineNew

attrUnderlineNew

Arguments

:: (HasCallStack, MonadIO m)

=> Underline

underline: the underline style

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new underline-style attribute.

attrVariantNew

attrVariantNew

Arguments

:: (HasCallStack, MonadIO m)

=> Variant

variant: the variant

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy.

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

attrWeightNew

attrWeightNew

Arguments

:: (HasCallStack, MonadIO m)

=> Weight

weight: the weight

-> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Create a new font weight attribute.

attrWordNew

attrWordNew

Arguments

:: (HasCallStack, MonadIO m)

=> m Attribute

Returns: the newly allocated PangoAttribute, which should be freed with attributeDestroy

Marks the range of the attribute as a single word.

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

Since: 1.50

break

break

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: the text to process. Must be valid UTF-8

-> Int32

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

-> Analysis

analysis: PangoAnalysis structure for text

-> [LogAttr]

attrs: an array to store character information in

-> m ()

Deprecated: (Since version 1.44)Use defaultBreak, tailorBreak and attrBreak.

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

defaultBreak

defaultBreak

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: text to break. Must be valid UTF-8

-> Int32

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

-> Maybe Analysis

analysis: a PangoAnalysis structure for the text

-> LogAttr

attrs: logical attributes to fill in

-> Int32

attrsLen: size of the array passed as attrs

-> m ()

This is the default break algorithm.

It applies rules from the Unicode Line Breaking Algorithm without language-specific tailoring, therefore the analyis argument is unused and can be Nothing.

See tailorBreak for language-specific breaks.

See attrBreak for attribute-based customization.

extentsToPixels

extentsToPixels

Arguments

:: (HasCallStack, MonadIO m)

=> Maybe Rectangle

inclusive: rectangle to round to pixels inclusively

-> Maybe Rectangle

nearest: rectangle to round to nearest pixels

-> m ()

Converts extents from Pango units to device units.

The conversion is done by dividing by the 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.

Since: 1.16

findBaseDir

findBaseDir

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: the text to process. Must be valid UTF-8

-> Int32

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

-> m Direction

Returns: The direction corresponding to the first strong character. If no such character is found, then DirectionNeutral is returned.

Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm.

Since: 1.4

findParagraphBoundary

findParagraphBoundary

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: UTF-8 text

-> Int32

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

-> m (Int32, Int32)

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 paragraphDelimiterIndex. The index of the start of the next paragraph (index after all delimiters) is stored n nextParagraphStart.

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

getLogAttrs

getLogAttrs

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: text to process. Must be valid UTF-8

-> Int32

length: length in bytes of text

-> Int32

level: embedding level, or -1 if unknown

-> Language

language: language tag

-> [LogAttr]

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

-> m ()

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

getMirrorChar

getMirrorChar

Arguments

:: (HasCallStack, MonadIO m)

=> Char

ch: a Unicode character

-> Char

mirroredCh: location to store the mirrored character

-> m Bool

Returns: True if ch has a mirrored character and mirroredCh is filled in, False otherwise

Deprecated: (Since version 1.30)Use unicharGetMirrorChar instead; the docs for that function provide full details.

Returns the mirrored character of a Unicode character.

Mirror characters are determined by the Unicode mirrored property.

isZeroWidth

isZeroWidth

Arguments

:: (HasCallStack, MonadIO m)

=> Char

ch: a Unicode character

-> m Bool

Returns: True if ch is a zero-width character, False otherwise

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 unicharIszerowidth and is at best misnamed.

Since: 1.10

itemize

itemize

Arguments

:: (HasCallStack, MonadIO m, IsContext a)

=> a

context: a structure holding information that affects the itemization process.

-> Text

text: the text to itemize. Must be valid UTF-8

-> Int32

startIndex: first byte in text to process

-> Int32

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

-> AttrList

attrs: the set of attributes that apply to text.

-> Maybe AttrIterator

cachedIter: Cached attribute iterator

-> m [Item]

Returns: a GList of [structpango.Item] structures. The items should be freed using itemFree in combination with [funcgLib.List.free_full].

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

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

itemizeWithBaseDir

itemizeWithBaseDir

Arguments

:: (HasCallStack, MonadIO m, IsContext a)

=> a

context: a structure holding information that affects the itemization process.

-> Direction

baseDir: base direction to use for bidirectional processing

-> Text

text: the text to itemize.

-> Int32

startIndex: first byte in text to process

-> Int32

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

-> AttrList

attrs: the set of attributes that apply to text.

-> Maybe AttrIterator

cachedIter: Cached attribute iterator

-> m [Item]

Returns: a GList of [structpango.Item] structures. The items should be freed using itemFree probably in combination with [funcgLib.List.free_full].

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

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

Since: 1.4

log2visGetEmbeddingLevels

log2visGetEmbeddingLevels

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: the text to itemize.

-> Int32

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

-> Direction

pbaseDir: input base direction, and output resolved direction.

-> m Word8

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

Return the bidirectional embedding levels of the input paragraph.

The bidirectional embedding levels are defined by the <http://www.unicode.org/reports/tr9/ 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.

Since: 1.4

markupParserFinish

markupParserFinish

Arguments

:: (HasCallStack, MonadIO m)

=> MarkupParseContext

context: A valid parse context that was returned from [funcmarkupParserNew]

-> m (AttrList, Text, Char)

(Can throw GError)

Finishes parsing markup.

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

Since: 1.31.0

markupParserNew

markupParserNew

Arguments

:: (HasCallStack, MonadIO m)

=> Char

accelMarker: character that precedes an accelerator, or 0 for none

-> m MarkupParseContext

Returns: a GMarkupParseContext that should be destroyed with markupParseContextFree.

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 accelMarker is nonzero, the given character will mark the character following it as an accelerator. For example, accelMarker might be an ampersand or underscore. All characters marked as an accelerator will receive a UnderlineLow attribute, and the first character so marked will be returned in accelChar, when calling [funcmarkupParserFinish]. Two accelMarker characters following each other produce a single literal accelMarker character.

To feed markup to the parser, use markupParseContextParse on the returned [structgLib.MarkupParseContext]. When done with feeding markup to the parser, use [funcmarkupParserFinish] to get the data out of it, and then use markupParseContextFree to free it.

This function is designed for applications that read Pango markup from streams. To simply parse a string containing Pango markup, the parseMarkup API is recommended instead.

Since: 1.31.0

parseEnum

parseEnum

Arguments

:: (HasCallStack, MonadIO m)

=> GType

type: enum type to parse, eg. PANGO_TYPE_ELLIPSIZE_MODE

-> Maybe Text

str: string to parse

-> Bool

warn: if True, issue a g_warning() on bad input

-> m (Bool, Int32, Text)

Returns: True if str was successfully parsed

Deprecated: (Since version 1.38)

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 possibleValues. The list is slash-separated, eg. "none/start/middle/end".

If failed and possibleValues is not Nothing, returned string should be freed using free.

Since: 1.16

parseMarkup

parseMarkup

Arguments

:: (HasCallStack, MonadIO m)

=> Text

markupText: markup to parse (see the Pango Markup docs)

-> Int32

length: length of markupText, or -1 if nul-terminated

-> Char

accelMarker: character that precedes an accelerator, or 0 for none

-> m (AttrList, Text, Char)

(Can throw GError)

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 accelMarker is nonzero, the given character will mark the character following it as an accelerator. For example, accelMarker might be an ampersand or underscore. All characters marked as an accelerator will receive a UnderlineLow attribute, and the first character so marked will be returned in accelChar. Two accelMarker characters following each other produce a single literal accelMarker character.

To parse a stream of pango markup incrementally, use [funcmarkupParserNew].

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

parseStretch

parseStretch

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: a string to parse.

-> Bool

warn: if True, issue a g_warning() on bad input.

-> m (Bool, Stretch)

Returns: True if str was successfully parsed.

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.

parseStyle

parseStyle

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: a string to parse.

-> Bool

warn: if True, issue a g_warning() on bad input.

-> m (Bool, Style)

Returns: True if str was successfully parsed.

Parses a font style.

The allowed values are "normal", "italic" and "oblique", case variations being ignored.

parseVariant

parseVariant

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: a string to parse.

-> Bool

warn: if True, issue a g_warning() on bad input.

-> m (Bool, Variant)

Returns: True if str was successfully parsed.

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.

parseWeight

parseWeight

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: a string to parse.

-> Bool

warn: if True, issue a g_warning() on bad input.

-> m (Bool, Weight)

Returns: True if str was successfully parsed.

Parses a font weight.

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

quantizeLineGeometry

quantizeLineGeometry

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

thickness: pointer to the thickness of a line, in Pango units

-> Int32

position: corresponding position

-> m (Int32, Int32)

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.

Since: 1.12

readLine

readLine

Arguments

:: (HasCallStack, MonadIO m)

=> Ptr ()

stream: a stdio stream

-> String

str: GString buffer into which to write the result

-> m Int32

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

Deprecated: (Since version 1.38)

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.

reorderItems

reorderItems

Arguments

:: (HasCallStack, MonadIO m)

=> [Item]

items: a GList of PangoItem in logical order.

-> m [Item]

Returns: a GList of PangoItem structures in visual order.

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

scanInt

scanInt

Arguments

:: (HasCallStack, MonadIO m)

=> Text

pos: in/out string position

-> m (Bool, Text, Int32)

Returns: False if a parse error occurred

Deprecated: (Since version 1.38)

Scans an integer.

Leading white space is skipped.

scanString

scanString

Arguments

:: (HasCallStack, MonadIO m)

=> Text

pos: in/out string position

-> String

out: a GString into which to write the result

-> m (Bool, Text)

Returns: False if a parse error occurred

Deprecated: (Since version 1.38)

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.

scanWord

scanWord

Arguments

:: (HasCallStack, MonadIO m)

=> Text

pos: in/out string position

-> String

out: a GString into which to write the result

-> m (Bool, Text)

Returns: False if a parse error occurred

Deprecated: (Since version 1.38)

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.

shape

shape

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: the text to process

-> Int32

length: the length (in bytes) of text

-> Analysis

analysis: PangoAnalysis structure from itemize

-> GlyphString

glyphs: glyph string in which to store results

-> m ()

Convert the characters in text into glyphs.

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

It is recommended that you use shapeFull 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 shapeItem.

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

shapeFull

shapeFull

Arguments

:: (HasCallStack, MonadIO m)

=> Text

itemText: valid UTF-8 text to shape.

-> Int32

itemLength: the length (in bytes) of itemText. -1 means nul-terminated text.

-> Maybe Text

paragraphText: text of the paragraph (see details).

-> Int32

paragraphLength: the length (in bytes) of paragraphText. -1 means nul-terminated text.

-> Analysis

analysis: PangoAnalysis structure from itemize.

-> GlyphString

glyphs: glyph string in which to store results.

-> m ()

Convert the characters in text into glyphs.

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

This is similar to 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 itemText is part of, provide the broader text as paragraphText. If paragraphText is Nothing, 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 shapeItem.

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

Since: 1.32

shapeItem

shapeItem

Arguments

:: (HasCallStack, MonadIO m)

=> Item

item: PangoItem to shape

-> Maybe Text

paragraphText: text of the paragraph (see details).

-> Int32

paragraphLength: the length (in bytes) of paragraphText. -1 means nul-terminated text.

-> Maybe LogAttr

logAttrs: array of PangoLogAttr for item

-> GlyphString

glyphs: glyph string in which to store results

-> [ShapeFlags]

flags: flags influencing the shaping process

-> m ()

Convert the characters in item into glyphs.

This is similar to shapeWithFlags, except it takes a PangoItem instead of separate itemText and analysis arguments.

It also takes logAttrs, 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 itemize have indices that are relative to the entire paragraph, so you do not pass the full paragraph text as paragraphText, you need to subtract the item offset from their indices before calling shapeWithFlags.

Since: 1.50

shapeWithFlags

shapeWithFlags

Arguments

:: (HasCallStack, MonadIO m)

=> Text

itemText: valid UTF-8 text to shape

-> Int32

itemLength: the length (in bytes) of itemText. -1 means nul-terminated text.

-> Maybe Text

paragraphText: text of the paragraph (see details).

-> Int32

paragraphLength: the length (in bytes) of paragraphText. -1 means nul-terminated text.

-> Analysis

analysis: PangoAnalysis structure from itemize

-> GlyphString

glyphs: glyph string in which to store results

-> [ShapeFlags]

flags: flags influencing the shaping process

-> m ()

Convert the characters in text into glyphs.

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

This is similar to shapeFull, 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 shapeItem.

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

Since: 1.44

skipSpace

skipSpace

Arguments

:: (HasCallStack, MonadIO m)

=> Text

pos: in/out string position

-> m (Bool, Text)

Returns: False if skipping the white space leaves the position at a '\0' character.

Deprecated: (Since version 1.38)

Skips 0 or more characters of white space.

splitFileList

splitFileList

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: a SEARCHPATH_SEPARATOR separated list of filenames

-> m [Text]

Returns: a list of strings to be freed with strfreev

Deprecated: (Since version 1.38)

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

tailorBreak

tailorBreak

Arguments

:: (HasCallStack, MonadIO m)

=> Text

text: text to process. Must be valid UTF-8

-> Int32

length: length in bytes of text

-> Analysis

analysis: PangoAnalysis for text

-> Int32

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

-> [LogAttr]

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

-> m ()

Apply language-specific tailoring to the breaks in attrs.

The line breaks are assumed to have been produced by defaultBreak.

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 attrBreak to apply attributes to the whole paragraph.

Since: 1.44

trimString

trimString

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: a string

-> m Text

Returns: A newly-allocated string that must be freed with free

Deprecated: (Since version 1.38)

Trims leading and trailing whitespace from a string.

unicharDirection

unicharDirection

Arguments

:: (HasCallStack, MonadIO m)

=> Char

ch: a Unicode character

-> m Direction

Returns: the direction of the character.

Determines the inherent direction of a character.

The inherent direction is either PANGO_DIRECTION_LTR, PANGO_DIRECTION_RTL, or PANGO_DIRECTION_NEUTRAL.

This function is useful to categorize characters into left-to-right letters, right-to-left letters, and everything else. If full Unicode bidirectional type of a character is needed, [funcpango.BidiType.for_unichar] can be used instead.

unitsFromDouble

unitsFromDouble

Arguments

:: (HasCallStack, MonadIO m)

=> Double

d: double floating-point value

-> m Int32

Returns: the value in Pango units.

Converts a floating-point number to Pango units.

The conversion is done by multiplying d by SCALE and rounding the result to nearest integer.

Since: 1.16

unitsToDouble

unitsToDouble

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

i: value in Pango units

-> m Double

Returns: the double value.

Converts a number in Pango units to floating-point.

The conversion is done by dividing i by SCALE.

Since: 1.16

version

version

Arguments

:: (HasCallStack, MonadIO m)

=> m Int32

Returns: The encoded version of Pango library available at run time.

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

Since: 1.16

versionCheck

versionCheck

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

requiredMajor: the required major version

-> Int32

requiredMinor: the required minor version

-> Int32

requiredMicro: the required major version

-> m (Maybe Text)

Returns: Nothing 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.

Checks that the Pango library in use is compatible with the given version.

Generally you would pass in the constants VERSION_MAJOR, VERSION_MINOR, 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 requiredMajor.required_minor.requiredMicro. Second the running library must be binary compatible with the version requiredMajor.required_minor.requiredMicro (same major version.)

For compile-time version checking use PANGO_VERSION_CHECK().

Since: 1.16

versionString

versionString

Arguments

:: (HasCallStack, MonadIO m)

=> m Text

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.

Returns the version of Pango available at run-time.

This is similar to the macro VERSION_STRING except that the macro returns the version available at compile-time.

Since: 1.16