pango-Vertical-Text: Vertical Text
Description
Laying text out in vertical directionsDetailed 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 PangoAttribute
s 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.