Debian Codegraph @

docs/pango_bidi.md

raw
1 ---
2 Title: Bidirectional and Vertical Text
3 ---
4
5 # Bidirectional Text
6
7 Pango supports bidirectional text (like Arabic and Hebrew) automatically.
8 Some applications however, need some help to correctly handle bidirectional text.
9
10 The [[email protected]] type can be used with [[email protected]_base_dir]
11 to instruct Pango about direction of text, though in most cases Pango detects
12 that correctly and automatically. For application that need more direct
13 control over bidirectional setting of text, Pango provides APIs such as
14 [func@unichar_direction], [func@find_base_dir], [func@get_mirror_char]
15 or [[email protected]_unichar].
16
17 Here is an example for mixed-direction text (shown in logical order):
18
19 <picture>
20 <source srcset="bidi-input-dark.png" media="(prefers-color-scheme: dark)">
21 <img alt="mixed-direction text, logical order" src="bidi-input-light.png">
22 </picture>
23
24 (the text to copy is: abאב12αβ )
25
26 Pango reorders the text according to the direction of the runs:
27
28 <picture>
29 <source srcset="bidi-annotate-dark.png" media="(prefers-color-scheme: dark)">
30 <img alt="mixed-direction text, visual order" src="bidi-annotate-light.png">
31 </picture>
32
33 # Vertical Text
34
35 Pango is not only capable of vertical text layout, it can handle mixed vertical
36 and non-vertical text correctly. This section describes the types used for setting
37 vertical text parameters.
38
39 <picture>
40 <source srcset="vertical-dark.png" media="(prefers-color-scheme: dark)">
41 <img alt="gravity west, rotated 90 degrees" align="right" valign="top" src="vertical-light.png">
42 </picture>
43 The way this is implemented is through the concept of *gravity*. Gravity tells glyphs which way is down, so the gravity of normal Latin text is south. A gravity value of east means that glyphs will be rotated ninety degrees
44 counterclockwise. So, to render vertical text one needs
45 to set the gravity and rotate the layout using the matrix machinery already
46 in place. This has the huge advantage that most algorithms working on a
47 [[email protected]] do not need any change as the assumption that lines run
48 in the X direction and stack in the Y direction holds even for vertical text
49 layouts.
50
51 Here is an example for some English text rendered with gravity west, rotated 90 degrees:
52
53 Applications should only need to set base gravity on [[email protected]] in use,
54 and let Pango decide the gravity assigned to each run of text. This automatically
55 handles text with mixed scripts. A very common use is to set the context base
56 gravity to auto using [[email protected]_base_gravity] and rotate the layout
57 normally. Pango will make sure that Asian languages take the right form, while
58 other scripts are rotated normally.
59
60 The correct way to set gravity on a layout is to set it on the context associated
61 with it using [[email protected]_base_gravity]. The context of a layout can
62 be accessed using [[email protected]_context]. The currently set base gravity
63 of the context can be accessed using [[email protected]_base_gravity] and the
64 *resolved* gravity of it using [[email protected]_gravity]. The resolved
65 gravity is the same as the base gravity for the most part, except that if the base
66 gravity is set to `PANGO_GRAVITY_AUTO`, the resolved gravity will depend on the
67 current matrix set on context, and is derived using [[email protected]_for_matrix].
68
69 The next thing an application may want to set on the context is the *gravity hint*.
70 A [[email protected]] instructs how different scripts should react to the set
71 base gravity.
72
73 Font descriptions have a gravity property too, that can be set using
74 [[email protected]_gravity] and accessed using
75 [[email protected]_gravity]. However, those are rarely useful
76 from application code and are mainly used by `PangoLayout` internally.
77
78 Last but not least, one can create `PangoAttributes` for gravity and gravity
79 hint using [func@attr_gravity_new] and [func@attr_gravity_hint_new].