diff options
author | Matthias Clasen <mclasen@redhat.com> | 2021-02-17 01:10:49 -0500 |
---|---|---|
committer | Matthias Clasen <mclasen@redhat.com> | 2021-03-11 13:17:36 -0500 |
commit | 6ac8ad77700090dd1caf21192f3e3e4eb0c948b3 (patch) | |
tree | ff12881c509cf50a57d3d3a1a729ca36d5c14628 /docs | |
parent | 9f5733a7e34b88d85248cd6e6b214f261b1e66fc (diff) | |
download | pango-6ac8ad77700090dd1caf21192f3e3e4eb0c948b3.tar.gz |
docs: Convert bidi and vertical sections to pango_bidi.md
Diffstat (limited to 'docs')
-rw-r--r-- | docs/meson.build | 1 | ||||
-rw-r--r-- | docs/pango.toml.in | 1 | ||||
-rw-r--r-- | docs/pango_bidi.md | 58 |
3 files changed, 60 insertions, 0 deletions
diff --git a/docs/meson.build b/docs/meson.build index fdf49162..e5c4e350 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -4,6 +4,7 @@ pango_content_files = [ 'pango_rendering.md', 'pango_markup.md', 'pango_fonts.md', + 'pango_bidi.md', 'pango-name.png', 'layout.png', 'pipeline.png', diff --git a/docs/pango.toml.in b/docs/pango.toml.in index eca52ea2..1d3a1b43 100644 --- a/docs/pango.toml.in +++ b/docs/pango.toml.in @@ -58,6 +58,7 @@ content_files = [ "pango_rendering.md", "pango_markup.md", "pango_fonts.md", + "pango_bidi.md", ] content_images = [ diff --git a/docs/pango_bidi.md b/docs/pango_bidi.md new file mode 100644 index 00000000..12e75e38 --- /dev/null +++ b/docs/pango_bidi.md @@ -0,0 +1,58 @@ +--- +Title: Bidirectional and Vertical Text +--- + +# Bidirectional Text + +Pango supports bidirectional text (like Arabic and Hebrew) automatically. +Some applications however, need some help to correctly handle bidirectional text. + +The [enum@Pango.Direction] type can be used with [method@Pango.Context.set_base_dir] +to instruct Pango about direction of text, though in most cases Pango detects +that correctly and automatically. For application that need more direct +control over bidirectional setting of text, Pango provides APIs such as +[func@unichar_direction], [func@find_base_dir], [func@get_mirror_char] +or [func@bidi_type_for_unichar]. + +# Vertical Text + +Pango is not only capable of vertical text layout, it can handle mixed vertical +and non-vertical text correctly. 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 +[class@Pango.Layout] 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 [class@Pango.Context] 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 [method@Pango.Context.set_base_gravity] 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 [method@Pango.Context.set_base_gravity]. The context of a layout can +be accessed using [method@Pango.Layout.get_context]. The currently set base gravity +of the context can be accessed using [method@Pango.Context.get_base_gravity] and the +*resolved* gravity of it using [method@Pango.Context.get_gravity]. 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 [func@gravity_get_for_matrix]. + +The next thing an application may want to set on the context is the *gravity hint*. +A [enum@Pango.GravityHint] instructs how different scripts should react to the set +base gravity. + +Font descriptions have a gravity property too, that can be set using +[method@Pango.FontDescription.set_gravity] and accessed using +[method@Pango.FontDescription.get_gravity]. 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 [func@attr_gravity_new] and [func@attr_gravity_hint_new]. |