diff options
Diffstat (limited to 'pango/pango-gravity.c')
| -rw-r--r-- | pango/pango-gravity.c | 88 |
1 files changed, 16 insertions, 72 deletions
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c index 8565db16..a21749b6 100644 --- a/pango/pango-gravity.c +++ b/pango/pango-gravity.c @@ -19,64 +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 - * <firstterm>gravity</firstterm>. 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 <firstterm>resolved</firstterm> - * 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 - * <firstterm>gravity hint</firstterm>. 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 #PangoAttribute<!---->s for gravity - * and gravity hint using pango_attr_gravity_new() and - * pango_attr_gravity_hint_new(). - */ #include "config.h" #include "pango-gravity.h" @@ -85,13 +27,12 @@ /** * pango_gravity_to_rotation: - * @gravity: gravity to query + * @gravity: gravity to query, should not be %PANGO_GRAVITY_AUTO * * Converts a #PangoGravity value to its natural rotation in radians. - * @gravity should not be %PANGO_GRAVITY_AUTO. * - * Note that pango_matrix_rotate() takes angle in degrees, not radians. - * So, to call pango_matrix_rotate() with the output of this function + * Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians. + * So, to call [method@Pango.Matrix,rotate] with the output of this function * you should multiply it by (180. / G_PI). * * Return value: the rotation value corresponding to @gravity. @@ -120,10 +61,10 @@ pango_gravity_to_rotation (PangoGravity gravity) /** * pango_gravity_get_for_matrix: - * @matrix: (nullable): a #PangoMatrix + * @matrix: (nullable): a `PangoMatrix` * * Finds the gravity that best matches the rotation component - * in a #PangoMatrix. + * in a `PangoMatrix`. * * Return value: the gravity of @matrix, which will never be * %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if @matrix is %NULL @@ -295,8 +236,9 @@ get_script_properties (PangoScript script) * @base_gravity: base gravity of the paragraph * @hint: orientation hint * - * Based on the script, base gravity, and hint, returns actual gravity - * to use in laying out a single #PangoItem. + * Returns the gravity to use in laying out a `PangoItem`. + * + * The gravity is determined based on the script, base gravity, and hint. * * If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the * preferred gravity of @script. To get the preferred gravity of a script, @@ -328,14 +270,16 @@ pango_gravity_get_for_script (PangoScript script, * @base_gravity: base gravity of the paragraph * @hint: orientation hint * - * Based on the script, East Asian width, base gravity, and hint, - * returns actual gravity to use in laying out a single character - * or #PangoItem. + * Returns the gravity to use in laying out a single character + * or `PangoItem`. + * + * The gravity is determined based on the script, East Asian width, + * base gravity, and hint, * - * This function is similar to pango_gravity_get_for_script() except + * This function is similar to [type_func@Pango.Gravity.get_for_script] except * that this function makes a distinction between narrow/half-width and - * wide/full-width characters also. Wide/full-width characters always - * stand <emphasis>upright</emphasis>, that is, they always take the base gravity, + * wide/full-width characters also. Wide/full-width characters always + * stand *upright*, that is, they always take the base gravity, * whereas narrow/full-width characters are always rotated in vertical * context. * |