Class Pango

java.lang.Object
org.gnome.pango.Pango
@Generated("org.javagi.JavaGI") public final class Pango extends Object
Constants and functions that are declared in the global Pango namespace.

  • Field Details

    • ANALYSIS_FLAG_CENTERED_BASELINE

      public static final int ANALYSIS_FLAG_CENTERED_BASELINE

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

      This is mainly used in vertical writing directions.

      Since:
      1.16
      See Also:

    • ANALYSIS_FLAG_IS_ELLIPSIS

      public static final int ANALYSIS_FLAG_IS_ELLIPSIS
      Whether this run holds ellipsized text.
      Since:
      1.36.7
      See Also:

    • ANALYSIS_FLAG_NEED_HYPHEN

      public static final int ANALYSIS_FLAG_NEED_HYPHEN
      Whether to add a hyphen at the end of the run during shaping.
      Since:
      1.44
      See Also:

    • ATTR_INDEX_FROM_TEXT_BEGINNING

      public static final int ATTR_INDEX_FROM_TEXT_BEGINNING
      Value for startIndex in PangoAttribute that indicates the beginning of the text.
      Since:
      1.24
      See Also:

    • ATTR_INDEX_TO_TEXT_END

      public static final int ATTR_INDEX_TO_TEXT_END
      Value for endIndex in PangoAttribute that indicates the end of the text.
      Since:
      1.24
      See Also:

    • GLYPH_EMPTY

      public static final Glyph GLYPH_EMPTY

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

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

    • GLYPH_INVALID_INPUT

      public static final Glyph GLYPH_INVALID_INPUT

      A PangoGlyph value for invalid input.

      PangoLayout produces one such glyph per invalid input UTF-8 byte and such a glyph is rendered as a crossed box.

      Note that this value is defined such that it has the PANGO_GLYPH_UNKNOWN_FLAG set.

      Since:
      1.20

    • GLYPH_UNKNOWN_FLAG

      public static final Glyph GLYPH_UNKNOWN_FLAG

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

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

    • SCALE

      public static final int SCALE

      The scale between dimensions used for Pango distances and device units.

      The definition of device units is dependent on the output device; it will typically be pixels for a screen, and points for a printer. PANGO_SCALE is currently 1024, but this may be changed in the future.

      When setting font sizes, device units are always considered to be points (as in "12 point font"), rather than pixels.

      See Also:

    • VERSION_MAJOR

      public static final int VERSION_MAJOR
      The major component of the version of Pango available at compile-time.
      See Also:

    • VERSION_MICRO

      public static final int VERSION_MICRO
      The micro component of the version of Pango available at compile-time.
      See Also:

    • VERSION_MINOR

      public static final int VERSION_MINOR
      The minor component of the version of Pango available at compile-time.
      See Also:

    • VERSION_STRING

      public static final String VERSION_STRING
      A string literal containing the version of Pango available at compile-time.
      See Also:

  • Constructor Details

    • Pango

      public Pango()

  • Method Details

    • javagi$ensureInitialized

      public static void javagi$ensureInitialized()

    • attrAllowBreaksNew

      public static Attribute attrAllowBreaksNew(boolean allowBreaks)

      Create a new allow-breaks attribute.

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

      Parameters:
      allowBreaks - true if we line breaks are allowed
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.44

    • attrBackgroundAlphaNew

      public static Attribute attrBackgroundAlphaNew(short alpha)
      Create a new background alpha attribute.
      Parameters:
      alpha - the alpha value, between 1 and 65536
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.38

    • attrBackgroundNew

      public static Attribute attrBackgroundNew(short red, short green, short blue)
      Create a new background color attribute.
      Parameters:
      red - the red value (ranging from 0 to 65535)
      green - the green value
      blue - the blue value
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrBaselineShiftNew

      public static Attribute attrBaselineShiftNew(int shift)

      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.

      Baseline Shift
      Parameters:
      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.
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.50

    • attrBreak

      public static void attrBreak(String text, int length, AttrList attrList, int offset, @Nullable Out<LogAttr[]> attrs)

      Apply customization from attributes to the breaks in attrs.

      The line breaks are assumed to have been produced by defaultBreak(String, int, Analysis, Out) and tailorBreak(String, int, Analysis, int, Out).

      Parameters:
      text - text to break. Must be valid UTF-8
      length - length of text in bytes (may be -1 if text is nul-terminated)
      attrList - PangoAttrList to apply
      offset - Byte offset of text from the beginning of the paragraph
      attrs - array with one PangoLogAttr per character in text, plus one extra, to be filled in
      Since:
      1.50

    • attrFallbackNew

      public static Attribute attrFallbackNew(boolean enableFallback)

      Create a new font fallback attribute.

      If fallback is disabled, characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text.

      Parameters:
      enableFallback - true if we should fall back on other fonts for characters the active font is missing
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.4

    • attrFamilyNew

      public static Attribute attrFamilyNew(String family)
      Create a new font family attribute.
      Parameters:
      family - the family or comma-separated list of families
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrFontScaleNew

      public static Attribute attrFontScaleNew(FontScale scale)

      Create a new font scale attribute.

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

      Parameters:
      scale - a PangoFontScale value, which indicates font size change relative to the size of the previous run.
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.50

    • attrForegroundAlphaNew

      public static Attribute attrForegroundAlphaNew(short alpha)
      Create a new foreground alpha attribute.
      Parameters:
      alpha - the alpha value, between 1 and 65536
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.38

    • attrForegroundNew

      public static Attribute attrForegroundNew(short red, short green, short blue)
      Create a new foreground color attribute.
      Parameters:
      red - the red value (ranging from 0 to 65535)
      green - the green value
      blue - the blue value
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrGravityHintNew

      public static Attribute attrGravityHintNew(GravityHint hint)
      Create a new gravity hint attribute.
      Parameters:
      hint - the gravity hint value
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.16

    • attrGravityNew

      public static Attribute attrGravityNew(Gravity gravity)
      Create a new gravity attribute.
      Parameters:
      gravity - the gravity value; should not be Gravity.AUTO
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.16

    • attrInsertHyphensNew

      public static Attribute attrInsertHyphensNew(boolean insertHyphens)

      Create a new insert-hyphens attribute.

      Pango will insert hyphens when breaking lines in the middle of a word. This attribute can be used to suppress the hyphen.

      Parameters:
      insertHyphens - true if hyphens should be inserted
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.44

    • attrLetterSpacingNew

      public static Attribute attrLetterSpacingNew(int letterSpacing)
      Create a new letter-spacing attribute.
      Parameters:
      letterSpacing - amount of extra space to add between graphemes of the text, in Pango units
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.6

    • attrLineHeightNew

      public static Attribute attrLineHeightNew(double factor)

      Modify the height of logical line extents by a factor.

      This affects the values returned by LayoutLine.getExtents(Rectangle, Rectangle), LayoutLine.getPixelExtents(Rectangle, Rectangle) and LayoutIter.getLineExtents(Rectangle, Rectangle).

      Parameters:
      factor - the scaling factor to apply to the logical height
      Since:
      1.50

    • attrLineHeightNewAbsolute

      public static Attribute attrLineHeightNewAbsolute(int height)

      Override the height of logical line extents to be height.

      This affects the values returned by LayoutLine.getExtents(Rectangle, Rectangle), LayoutLine.getPixelExtents(Rectangle, Rectangle) and LayoutIter.getLineExtents(Rectangle, Rectangle).

      Parameters:
      height - the line height, in PANGO_SCALE-ths of a point
      Since:
      1.50

    • attrOverlineColorNew

      public static Attribute attrOverlineColorNew(short red, short green, short blue)

      Create a new overline color attribute.

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

      Parameters:
      red - the red value (ranging from 0 to 65535)
      green - the green value
      blue - the blue value
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.46

    • attrOverlineNew

      public static Attribute attrOverlineNew(Overline overline)
      Create a new overline-style attribute.
      Parameters:
      overline - the overline style
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.46

    • attrRiseNew

      public static Attribute attrRiseNew(int rise)
      Create a new baseline displacement attribute.
      Parameters:
      rise - the amount that the text should be displaced vertically, in Pango units. Positive values displace the text upwards.
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrScaleNew

      public static Attribute attrScaleNew(double scaleFactor)

      Create a new font size scale attribute.

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

      Parameters:
      scaleFactor - factor to scale the font
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrSentenceNew

      public static Attribute attrSentenceNew()

      Marks the range of the attribute as a single sentence.

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

      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.50

    • attrShowNew

      public static Attribute attrShowNew(Set<ShowFlags> flags)
      Create a new attribute that influences how invisible characters are rendered.
      Parameters:
      flags - PangoShowFlags to apply
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.44

    • attrShowNew

      public static Attribute attrShowNew(ShowFlags... flags)
      Create a new attribute that influences how invisible characters are rendered.
      Parameters:
      flags - PangoShowFlags to apply
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.44

    • attrStretchNew

      public static Attribute attrStretchNew(Stretch stretch)
      Create a new font stretch attribute.
      Parameters:
      stretch - the stretch
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrStrikethroughColorNew

      public static Attribute attrStrikethroughColorNew(short red, short green, short blue)

      Create a new strikethrough color attribute.

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

      Parameters:
      red - the red value (ranging from 0 to 65535)
      green - the green value
      blue - the blue value
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.8

    • attrStrikethroughNew

      public static Attribute attrStrikethroughNew(boolean strikethrough)
      Create a new strike-through attribute.
      Parameters:
      strikethrough - true if the text should be struck-through
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrStyleNew

      public static Attribute attrStyleNew(Style style)
      Create a new font slant style attribute.
      Parameters:
      style - the slant style
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrTextTransformNew

      public static Attribute attrTextTransformNew(TextTransform transform)
      Create a new attribute that influences how characters are transformed during shaping.
      Parameters:
      transform - PangoTextTransform to apply
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.50

    • attrUnderlineColorNew

      public static Attribute attrUnderlineColorNew(short red, short green, short blue)

      Create a new underline color attribute.

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

      Parameters:
      red - the red value (ranging from 0 to 65535)
      green - the green value
      blue - the blue value
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.8

    • attrUnderlineNew

      public static Attribute attrUnderlineNew(Underline underline)
      Create a new underline-style attribute.
      Parameters:
      underline - the underline style
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrVariantNew

      public static Attribute attrVariantNew(Variant variant)
      Create a new font variant attribute (normal or small caps).
      Parameters:
      variant - the variant
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy().

    • attrWeightNew

      public static Attribute attrWeightNew(Weight weight)
      Create a new font weight attribute.
      Parameters:
      weight - the weight
      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()

    • attrWordNew

      public static Attribute attrWordNew()

      Marks the range of the attribute as a single word.

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

      Returns:
      the newly allocated PangoAttribute, which should be freed with Attribute.destroy()
      Since:
      1.50

    • break_

      @Deprecated public static void break_(String text, int length, Analysis analysis, @Nullable Out<LogAttr[]> attrs)
      Deprecated.
      Use defaultBreak(String, int, Analysis, Out), tailorBreak(String, int, Analysis, int, Out) and attrBreak(String, int, AttrList, int, Out).

      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(String, int, int, Language, Out).

      Parameters:
      text - the text to process. Must be valid UTF-8
      length - length of text in bytes (may be -1 if text is nul-terminated)
      analysis - PangoAnalysis structure for text
      attrs - an array to store character information in

    • defaultBreak

      public static void defaultBreak(String text, int length, @Nullable Analysis analysis, @Nullable Out<LogAttr[]> attrs)

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

      See tailorBreak(String, int, Analysis, int, Out) for language-specific breaks.

      See attrBreak(String, int, AttrList, int, Out) for attribute-based customization.

      Parameters:
      text - text to break. Must be valid UTF-8
      length - length of text in bytes (may be -1 if text is nul-terminated)
      analysis - a PangoAnalysis structure for the text
      attrs - logical attributes to fill in

    • extentsToPixels

      public static void extentsToPixels(@Nullable Rectangle inclusive, @Nullable Rectangle nearest)

      Converts extents from Pango units to device units.

      The conversion is done by dividing by the PANGO_SCALE factor and performing rounding.

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

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

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

      Parameters:
      inclusive - rectangle to round to pixels inclusively
      nearest - rectangle to round to nearest pixels
      Since:
      1.16

    • findBaseDir

      public static Direction findBaseDir(String text, int length)
      Searches a string the first character that has a strong direction, according to the Unicode bidirectional algorithm.
      Parameters:
      text - the text to process. Must be valid UTF-8
      length - 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 Direction.NEUTRAL is returned.
      Since:
      1.4

    • findParagraphBoundary

      public static void findParagraphBoundary(String text, int length, @Nullable Out<Integer> paragraphDelimiterIndex, @Nullable Out<Integer> nextParagraphStart)

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

      Parameters:
      text - UTF-8 text
      length - length of text in bytes, or -1 if nul-terminated
      paragraphDelimiterIndex - return location for index of delimiter
      nextParagraphStart - return location for start of next paragraph

    • getLogAttrs

      public static void getLogAttrs(String text, int length, int level, Language language, @Nullable Out<LogAttr[]> attrs)

      Computes a PangoLogAttr for each character in text.

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

      Parameters:
      text - text to process. Must be valid UTF-8
      length - length in bytes of text
      level - embedding level, or -1 if unknown
      language - language tag
      attrs - array with one PangoLogAttr per character in text, plus one extra, to be filled in

    • getMirrorChar

      @Deprecated public static boolean getMirrorChar(int ch, @Nullable Out<Integer> mirroredCh)
      Deprecated.
      Use GLib#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.

      Parameters:
      ch - a Unicode character
      mirroredCh - location to store the mirrored character
      Returns:
      true if ch has a mirrored character and mirroredCh is filled in, false otherwise

    • isZeroWidth

      public static boolean isZeroWidth(int ch)

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

      Parameters:
      ch - a Unicode character
      Returns:
      true if ch is a zero-width character, false otherwise
      Since:
      1.10

    • itemize

      public static List<Item> itemize(Context context, String text, int startIndex, int length, AttrList attrs, @Nullable AttrIterator cachedIter)

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

      Parameters:
      context - a structure holding information that affects the itemization process.
      text - the text to itemize. Must be valid UTF-8
      startIndex - first byte in text to process
      length - the number of bytes (not characters) to process after startIndex. This must be >= 0.
      attrs - the set of attributes that apply to text.
      cachedIter - Cached attribute iterator
      Returns:
      a GList of Pango.Item structures. The items should be freed using Item.free() in combination with org.gnome.glib.List.freeFull.

    • itemizeWithBaseDir

      public static List<Item> itemizeWithBaseDir(Context context, Direction baseDir, String text, int startIndex, int length, AttrList attrs, @Nullable AttrIterator cachedIter)

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

      The base direction is used when computing bidirectional levels. itemize(Context, String, int, int, AttrList, AttrIterator) gets the base direction from the PangoContext (see Context.setBaseDir(Direction)).

      Parameters:
      context - a structure holding information that affects the itemization process.
      baseDir - base direction to use for bidirectional processing
      text - the text to itemize.
      startIndex - first byte in text to process
      length - the number of bytes (not characters) to process after startIndex. This must be >= 0.
      attrs - the set of attributes that apply to text.
      cachedIter - Cached attribute iterator
      Returns:
      a GList of Pango.Item structures. The items should be freed using Item.free() probably in combination with org.gnome.glib.List.freeFull.
      Since:
      1.4

    • markupParserFinish

      public static boolean markupParserFinish(MarkupParseContext context, @Nullable Out<AttrList> attrList, @Nullable Out<String> text, @Nullable Out<Integer> accelChar) throws GErrorException

      Finishes parsing markup.

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

      Parameters:
      context - A valid parse context that was returned from markupParserNew(int)
      attrList - address of return location for a PangoAttrList
      text - address of return location for text with tags stripped
      accelChar - address of return location for accelerator char
      Returns:
      false if error is set, otherwise true
      Throws:
      GErrorException - see GError
      Since:
      1.31.0

    • markupParserNew

      public static MarkupParseContext markupParserNew(int accelMarker)

      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 Underline.LOW attribute, and the first character so marked will be returned in accelChar, when calling markupParserFinish(MarkupParseContext, Out, Out, Out). Two accelMarker characters following each other produce a single literal accelMarker character.

      To feed markup to the parser, use MarkupParseContext#parse on the returned GLib.MarkupParseContext. When done with feeding markup to the parser, use markupParserFinish(MarkupParseContext, Out, Out, Out) to get the data out of it, and then use 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 parseMarkup(String, int, int, Out, Out, Out) API is recommended instead.

      Parameters:
      accelMarker - character that precedes an accelerator, or 0 for none
      Returns:
      a GMarkupParseContext that should be destroyed with MarkupParseContext#free.
      Since:
      1.31.0

    • parseEnum

      @Deprecated public static boolean parseEnum(Type type, @Nullable String str, @Nullable Out<Integer> value, boolean warn, @Nullable Out<String> possibleValues)
      Deprecated.

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

      Parameters:
      type - enum type to parse, eg. PANGO_TYPE_ELLIPSIZE_MODE
      str - string to parse
      value - integer to store the result in
      warn - if true, issue a g_warning() on bad input
      possibleValues - place to store list of possible values on failure
      Returns:
      true if str was successfully parsed
      Since:
      1.16

    • parseMarkup

      public static boolean parseMarkup(String markupText, int length, int accelMarker, @Nullable Out<AttrList> attrList, @Nullable Out<String> text, @Nullable Out<Integer> accelChar) throws GErrorException

      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 Underline.LOW 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 markupParserNew(int).

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

      Parameters:
      markupText - markup to parse (see the Pango Markup docs)
      length - length of markupText, or -1 if nul-terminated
      accelMarker - character that precedes an accelerator, or 0 for none
      attrList - address of return location for a PangoAttrList
      text - address of return location for text with tags stripped
      accelChar - address of return location for accelerator char
      Returns:
      false if error is set, otherwise true
      Throws:
      GErrorException - see GError

    • parseStretch

      public static boolean parseStretch(String str, Out<Stretch> stretch, boolean 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.
      warn - if true, issue a g_warning() on bad input.
      Returns:
      true if str was successfully parsed.

    • parseStyle

      public static boolean parseStyle(String str, Out<Style> style, boolean 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.
      warn - if true, issue a g_warning() on bad input.
      Returns:
      true if str was successfully parsed.

    • parseVariant

      public static boolean parseVariant(String str, Out<Variant> variant, boolean warn)

      Parses a font variant.

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

      Parameters:
      str - a string to parse.
      variant - a PangoVariant to store the result in.
      warn - if true, issue a g_warning() on bad input.
      Returns:
      true if str was successfully parsed.

    • parseWeight

      public static boolean parseWeight(String str, Out<Weight> weight, boolean 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.
      warn - if true, issue a g_warning() on bad input.
      Returns:
      true if str was successfully parsed.

    • quantizeLineGeometry

      public static void quantizeLineGeometry(Out<Integer> thickness, Out<Integer> position)

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

      This is typically used for underline or strikethrough. The purpose of this function is to avoid such lines looking blurry.

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

      Parameters:
      thickness - pointer to the thickness of a line, in Pango units
      position - corresponding position
      Since:
      1.12

    • readLine

      @Deprecated public static int readLine(@Nullable MemorySegment stream, String str)
      Deprecated.

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

    • reorderItems

      public static List<Item> reorderItems(List<Item> items)

      Reorder items from logical order to visual order.

      The visual order is determined from the associated directional levels of the items. The original list is unmodified.

      (Please open a bug if you use this function. It is not a particularly convenient interface, and the code is duplicated elsewhere in Pango for that reason.)

      Parameters:
      items - a GList of PangoItem in logical order.
      Returns:
      a GList of PangoItem structures in visual order.

    • scanInt

      @Deprecated public static boolean scanInt(Out<String> pos, Out<Integer> out)
      Deprecated.

      Scans an integer.

      Leading white space is skipped.

      Parameters:
      pos - in/out string position
      out - an int into which to write the result
      Returns:
      false if a parse error occurred

    • scanString

      @Deprecated public static boolean scanString(Out<String> pos, String out)
      Deprecated.

      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
      out - a GString into which to write the result
      Returns:
      false if a parse error occurred

    • scanWord

      @Deprecated public static boolean scanWord(Out<String> pos, String out)
      Deprecated.

      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
      out - a GString into which to write the result
      Returns:
      false if a parse error occurred

    • shape

      public static void shape(String text, int length, Analysis analysis, GlyphString glyphs)

      Convert the characters in text into glyphs.

      Given a segment of text and the corresponding PangoAnalysis structure returned from itemize(Context, String, int, int, AttrList, AttrIterator), convert the characters into glyphs. You may also pass in only a substring of the item from itemize(Context, String, int, int, AttrList, AttrIterator).

      It is recommended that you use shapeFull(String, int, String, int, Analysis, GlyphString) 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(Item, String, int, LogAttr, GlyphString, Set).

      Note that the extra attributes in the analyis that is returned from itemize(Context, String, int, int, AttrList, AttrIterator) have indices that are relative to the entire paragraph, so you need to subtract the item offset from their indices before calling shape(String, int, Analysis, GlyphString).

      Parameters:
      text - the text to process
      length - the length (in bytes) of text
      analysis - PangoAnalysis structure from itemize(Context, String, int, int, AttrList, AttrIterator)
      glyphs - glyph string in which to store results

    • shapeFull

      public static void shapeFull(String itemText, int itemLength, @Nullable String paragraphText, int paragraphLength, Analysis analysis, GlyphString glyphs)

      Convert the characters in text into glyphs.

      Given a segment of text and the corresponding PangoAnalysis structure returned from itemize(Context, String, int, int, AttrList, AttrIterator), convert the characters into glyphs. You may also pass in only a substring of the item from itemize(Context, String, int, int, AttrList, AttrIterator).

      This is similar to shape(String, int, Analysis, GlyphString), 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 null, 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(Item, String, int, LogAttr, GlyphString, Set).

      Note that the extra attributes in the analyis that is returned from itemize(Context, String, int, int, AttrList, AttrIterator) 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(String, int, String, int, Analysis, GlyphString).

      Parameters:
      itemText - valid UTF-8 text to shape.
      itemLength - the length (in bytes) of itemText. -1 means nul-terminated text.
      paragraphText - text of the paragraph (see details).
      paragraphLength - the length (in bytes) of paragraphText. -1 means nul-terminated text.
      analysis - PangoAnalysis structure from itemize(Context, String, int, int, AttrList, AttrIterator).
      glyphs - glyph string in which to store results.
      Since:
      1.32

    • shapeItem

      public static void shapeItem(Item item, @Nullable String paragraphText, int paragraphLength, @Nullable LogAttr logAttrs, GlyphString glyphs, Set<ShapeFlags> flags)

      Convert the characters in item into glyphs.

      This is similar to shapeWithFlags(String, int, String, int, Analysis, GlyphString, Set), 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(Context, String, int, int, AttrList, AttrIterator) 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(String, int, String, int, Analysis, GlyphString, Set).

      Parameters:
      item - PangoItem to shape
      paragraphText - text of the paragraph (see details).
      paragraphLength - the length (in bytes) of paragraphText. -1 means nul-terminated text.
      logAttrs - array of PangoLogAttr for item
      glyphs - glyph string in which to store results
      flags - flags influencing the shaping process
      Since:
      1.50

    • shapeItem

      public static void shapeItem(Item item, @Nullable String paragraphText, int paragraphLength, @Nullable LogAttr logAttrs, GlyphString glyphs, ShapeFlags... flags)

      Convert the characters in item into glyphs.

      This is similar to shapeWithFlags(String, int, String, int, Analysis, GlyphString, Set), 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(Context, String, int, int, AttrList, AttrIterator) 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(String, int, String, int, Analysis, GlyphString, Set).

      Parameters:
      item - PangoItem to shape
      paragraphText - text of the paragraph (see details).
      paragraphLength - the length (in bytes) of paragraphText. -1 means nul-terminated text.
      logAttrs - array of PangoLogAttr for item
      glyphs - glyph string in which to store results
      flags - flags influencing the shaping process
      Since:
      1.50

    • shapeWithFlags

      public static void shapeWithFlags(String itemText, int itemLength, @Nullable String paragraphText, int paragraphLength, Analysis analysis, GlyphString glyphs, Set<ShapeFlags> flags)

      Convert the characters in text into glyphs.

      Given a segment of text and the corresponding PangoAnalysis structure returned from itemize(Context, String, int, int, AttrList, AttrIterator), convert the characters into glyphs. You may also pass in only a substring of the item from itemize(Context, String, int, int, AttrList, AttrIterator).

      This is similar to shapeFull(String, int, String, int, Analysis, GlyphString), 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(Item, String, int, LogAttr, GlyphString, Set).

      Note that the extra attributes in the analyis that is returned from itemize(Context, String, int, int, AttrList, AttrIterator) 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(String, int, String, int, Analysis, GlyphString, Set).

      Parameters:
      itemText - valid UTF-8 text to shape
      itemLength - the length (in bytes) of itemText. -1 means nul-terminated text.
      paragraphText - text of the paragraph (see details).
      paragraphLength - the length (in bytes) of paragraphText. -1 means nul-terminated text.
      analysis - PangoAnalysis structure from itemize(Context, String, int, int, AttrList, AttrIterator)
      glyphs - glyph string in which to store results
      flags - flags influencing the shaping process
      Since:
      1.44

    • shapeWithFlags

      public static void shapeWithFlags(String itemText, int itemLength, @Nullable String paragraphText, int paragraphLength, Analysis analysis, GlyphString glyphs, ShapeFlags... flags)

      Convert the characters in text into glyphs.

      Given a segment of text and the corresponding PangoAnalysis structure returned from itemize(Context, String, int, int, AttrList, AttrIterator), convert the characters into glyphs. You may also pass in only a substring of the item from itemize(Context, String, int, int, AttrList, AttrIterator).

      This is similar to shapeFull(String, int, String, int, Analysis, GlyphString), 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(Item, String, int, LogAttr, GlyphString, Set).

      Note that the extra attributes in the analyis that is returned from itemize(Context, String, int, int, AttrList, AttrIterator) 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(String, int, String, int, Analysis, GlyphString, Set).

      Parameters:
      itemText - valid UTF-8 text to shape
      itemLength - the length (in bytes) of itemText. -1 means nul-terminated text.
      paragraphText - text of the paragraph (see details).
      paragraphLength - the length (in bytes) of paragraphText. -1 means nul-terminated text.
      analysis - PangoAnalysis structure from itemize(Context, String, int, int, AttrList, AttrIterator)
      glyphs - glyph string in which to store results
      flags - flags influencing the shaping process
      Since:
      1.44

    • skipSpace

      @Deprecated public static boolean skipSpace(Out<String> pos)
      Deprecated.
      Skips 0 or more characters of white space.
      Parameters:
      pos - in/out string position
      Returns:
      false if skipping the white space leaves the position at a '\0' character.

    • splitFileList

      @Deprecated public static String[] splitFileList(String str)
      Deprecated.
      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()

    • tailorBreak

      public static void tailorBreak(String text, int length, Analysis analysis, int offset, @Nullable Out<LogAttr[]> attrs)

      Apply language-specific tailoring to the breaks in attrs.

      The line breaks are assumed to have been produced by defaultBreak(String, int, Analysis, Out).

      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(String, int, AttrList, int, Out) to apply attributes to the whole paragraph.

      Parameters:
      text - text to process. Must be valid UTF-8
      length - length in bytes of text
      analysis - PangoAnalysis for text
      offset - Byte offset of text from the beginning of the paragraph, or -1 to ignore attributes from analysis
      attrs - array with one PangoLogAttr per character in text, plus one extra, to be filled in
      Since:
      1.44

    • trimString

      @Deprecated public static String trimString(String str)
      Deprecated.
      Trims leading and trailing whitespace from a string.
      Parameters:
      str - a string
      Returns:
      A newly-allocated string that must be freed with g_free()

    • unicharDirection

      public static Direction unicharDirection(int ch)

      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, BidiType.forUnichar(int) can be used instead.

      Parameters:
      ch - a Unicode character
      Returns:
      the direction of the character.

    • unitsFromDouble

      public static int unitsFromDouble(double d)

      Converts a floating-point number to Pango units.

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

      Parameters:
      d - double floating-point value
      Returns:
      the value in Pango units.
      Since:
      1.16

    • unitsToDouble

      public static double unitsToDouble(int i)

      Converts a number in Pango units to floating-point.

      The conversion is done by dividing i by PANGO_SCALE.

      Parameters:
      i - value in Pango units
      Returns:
      the double value.
      Since:
      1.16

    • version

      public static int version()

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

      This is similar to the macro PANGO_VERSION except that the macro returns the encoded version available at compile-time. A version number can be encoded into an integer using PANGO_VERSION_ENCODE().

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

    • versionCheck

      public static @Nullable String versionCheck(int requiredMajor, int requiredMinor, int requiredMicro)

      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 requiredMicro. Second the running library must be binary compatible with the version requiredMicro (same major version.)

      For compile-time version checking use PANGO_VERSION_CHECK().

      Parameters:
      requiredMajor - the required major version
      requiredMinor - the required minor version
      requiredMicro - the required major version
      Returns:
      null 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.
      Since:
      1.16

    • versionString

      public static String versionString()

      Returns the version of Pango available at run-time.

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

      Returns:
      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.
      Since:
      1.16