diff options
| -rw-r--r-- | docs/meson.build | 1 | ||||
| -rw-r--r-- | docs/pango.toml.in | 1 | ||||
| -rw-r--r-- | docs/pango_bidi.md | 58 | ||||
| -rw-r--r-- | pango/pango-bidi-type.c | 18 | ||||
| -rw-r--r-- | pango/pango-gravity.c | 56 |
5 files changed, 60 insertions, 74 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]. diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c index d4d84e03..0fc1c3e4 100644 --- a/pango/pango-bidi-type.c +++ b/pango/pango-bidi-type.c @@ -19,24 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:bidi - * @short_description:Types and functions for bidirectional text - * @title:Bidirectional Text - * @see_also: - * pango_context_get_base_dir(), - * pango_context_set_base_dir(), - * pango_itemize_with_base_dir() - * - * Pango supports bidirectional text (like Arabic and Hebrew) automatically. - * Some applications however, need some help to correctly handle bidirectional text. - * - * The #PangoDirection type can be used with pango_context_set_base_dir() to - * instruct Pango about direction of text, though in most cases Pango detects - * that correctly and automatically. The rest of the facilities in this section - * are used internally by Pango already, and are provided to help applications - * that need more direct control over bidirectional setting of text. - */ #include "config.h" #include <string.h> diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c index 2d48c45e..ea6ef9e2 100644 --- a/pango/pango-gravity.c +++ b/pango/pango-gravity.c @@ -19,62 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:vertical - * @short_description:Laying text out in vertical directions - * @title:Vertical Text - * @see_also: pango_context_get_base_gravity(), - * pango_context_set_base_gravity(), - * pango_context_get_gravity(), - * pango_context_get_gravity_hint(), - * pango_context_set_gravity_hint(), - * pango_font_description_set_gravity(), - * pango_font_description_get_gravity(), - * pango_attr_gravity_new(), - * pango_attr_gravity_hint_new() - * - * 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 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 pango_context_set_base_gravity(). The context - * of a layout can be accessed using pango_layout_get_context(). The currently - * set base gravity of the context can be accessed using - * pango_context_get_base_gravity() and the *resolved* gravity of it using - * 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 pango_gravity_get_for_matrix(). - * - * 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 - * pango_font_description_set_gravity() and accessed using - * pango_font_description_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 pango_attr_gravity_new() and - * pango_attr_gravity_hint_new(). - */ #include "config.h" #include "pango-gravity.h" |