pango-Vertical-Text: Vertical Text

Description Methods and Functions Detailed Description Enums and Flags Author(s) References

Description

Laying text out in vertical directions

Methods and Functions

pangoGravityGetForMatrix(matrix)
pangoGravityGetForScript(script, base.gravity, hint)
pangoGravityGetForScriptAndWidth(script, wide, base.gravity, hint)
pangoGravityToRotation(base.gravity)

Detailed Description

Since 1.16, Pango is able to correctly lay vertical text out. In fact, it can set layouts of mixed vertical and non-vertical text. This section describes the types used for setting vertical text parameters.

The way this is implemented is through the concept of gravity. Gravity of normal Latin text is south. A gravity value of east means that glyphs will be rotated ninety degrees counterclockwise. So, to render vertical text one needs to set the gravity and rotate the layout using the matrix machinery already in place. This has the huge advantage that most algorithms working on a PangoLayout do not need any change as the assumption that lines run in the X direction and stack in the Y direction holds even for vertical text layouts.

Applications should only need to set base gravity on PangoContext in use, and let Pango decide the gravity assigned to each run of text. This automatically handles text with mixed scripts. A very common use is to set the context base gravity to auto using pangoContextSetBaseGravity and rotate the layout normally. Pango will make sure that Asian languages take the right form, while other scripts are rotated normally.

The correct way to set gravity on a layout is to set it on the context associated with it using pangoContextSetBaseGravity. The context of a layout can be accessed using pangoLayoutGetContext. The currently set base gravity of the context can be accessed using pangoContextGetBaseGravity and the resolved gravity of it using pangoContextGetGravity. The resolved gravity is the same as the base gravity for the most part, except that if the base gravity is set to PANGO_GRAVITY_AUTO, the resolved gravity will depend on the current matrix set on context, and is derived using pangoGravityGetForMatrix.

The next thing an application may want to set on the context is the gravity hint. A PangoGravityHint instructs how different scripts should react to the set base gravity.

Font descriptions have a gravity property too, that can be set using pangoFontDescriptionSetGravity and accessed using pangoFontDescriptionGetGravity. However, those are rarely useful from application code and are mainly used by PangoLayout internally.

Last but not least, one can create PangoAttributes for gravity and gravity hint using pangoAttrGravityNew and pangoAttrGravityHintNew.

Enums and Flags

PangoGravity

The PangoGravity type represents the orientation of glyphs in a segment of text. This is useful when rendering vertical text layouts. In those situations, the layout is rotated using a non-identity PangoMatrix, and then glyph orientation is controlled using PangoGravity. Not every value in this enumeration makes sense for every usage of PangoGravity; for example, PANGO_GRAVITY_AUTO only can be passed to pangoContextSetBaseGravity and can only be returned by pangoContextGetBaseGravity.

See also: PangoGravityHint Since 1.16

south

Glyphs stand upright (default)

east

Glyphs are rotated 90 degrees clockwise

north

Glyphs are upside-down

west

Glyphs are rotated 90 degrees counter-clockwise

auto

Gravity is resolved from the context matrix

PangoGravityHint

The PangoGravityHint defines how horizontal scripts should behave in a vertical context. That is, English excerpt in a vertical paragraph for example.

See PangoGravity. Since 1.16

natural

scripts will take their natural gravity based on the base gravity and the script. This is the default.

strong

always use the base gravity set, regardless of the script.

line

for scripts not in their natural direction (eg. Latin in East gravity), choose per-script gravity such that every script respects the line progression. This means, Latin and Arabic will take opposite gravities and both flow top-to-bottom for example.

Author(s)

Derived by RGtkGen from GTK+ documentation

References

https://developer.gnome.org/pango/stable/pango-Vertical-Text.html


RGtk2 documentation built on Oct. 14, 2021, 5:08 p.m.