docs/xml/vertical.xml

   1 <refentry id="pango-Vertical-Text">
   2 <refmeta>
   3 <refentrytitle role="top_of_page" id="pango-Vertical-Text.top_of_page">Vertical Text</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>PANGO Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Vertical Text</refname>
  10 <refpurpose>Laying text out in vertical directions</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv id="pango-Vertical-Text.synopsis" role="synopsis">
  14 <title role="synopsis.title">Synopsis</title>
  15
  16 <synopsis>
  17 enum                <link linkend="PangoGravity">PangoGravity</link>;
  18 enum                <link linkend="PangoGravityHint">PangoGravityHint</link>;
  19 #define             <link linkend="PANGO-GRAVITY-IS-VERTICAL--CAPS">PANGO_GRAVITY_IS_VERTICAL</link>           (gravity)
  20 <link linkend="PangoGravity">PangoGravity</link>        <link linkend="pango-gravity-get-for-matrix">pango_gravity_get_for_matrix</link>        (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix);
  21 <link linkend="PangoGravity">PangoGravity</link>        <link linkend="pango-gravity-get-for-script">pango_gravity_get_for_script</link>        (<link linkend="PangoScript">PangoScript</link> script,
  22                                                          <link linkend="PangoGravity">PangoGravity</link> base_gravity,
  23                                                          <link linkend="PangoGravityHint">PangoGravityHint</link> hint);
  24 <link linkend="PangoGravity">PangoGravity</link>        <link linkend="pango-gravity-get-for-script-and-width">pango_gravity_get_for_script_and_width</link>
  25                                                         (<link linkend="PangoScript">PangoScript</link> script,
  26                                                          <link linkend="gboolean">gboolean</link> wide,
  27                                                          <link linkend="PangoGravity">PangoGravity</link> base_gravity,
  28                                                          <link linkend="PangoGravityHint">PangoGravityHint</link> hint);
  29 <link linkend="double">double</link>              <link linkend="pango-gravity-to-rotation">pango_gravity_to_rotation</link>           (<link linkend="PangoGravity">PangoGravity</link> gravity);
  30 </synopsis>
  31 </refsynopsisdiv>
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41 <refsect1 id="pango-Vertical-Text.description" role="desc">
  42 <title role="desc.title">Description</title>
  43 <para>
  44 Since 1.16, Pango is able to correctly lay vertical text out.  In fact, it can
  45 set layouts of mixed vertical and non-vertical text.  This section describes
  46 the types used for setting vertical text parameters.
  47 </para>
  48 <para>
  49 The way this is implemented is through the concept of
  50 <firstterm>gravity</firstterm>.  Gravity of normal Latin text is south.  A
  51 gravity value of east means that glyphs will be rotated ninety degrees
  52 counterclockwise.  So, to render vertical text one needs to set the gravity
  53 and rotate the layout using the matrix machinery already in place.  This has
  54 the huge advantage that most algorithms working on a <link linkend="PangoLayout"><type>PangoLayout</type></link> do not need
  55 any change as the assumption that lines run in the X direction and stack in
  56 the Y direction holds even for vertical text layouts.
  57 </para>
  58 <para>
  59 Applications should only need to set base gravity on <link linkend="PangoContext"><type>PangoContext</type></link> in use, and
  60 let Pango decide the gravity assigned to each run of text.  This automatically
  61 handles text with mixed scripts.  A very common use is to set the context base
  62 gravity to auto using <link linkend="pango-context-set-base-gravity"><function>pango_context_set_base_gravity()</function></link>
  63 and rotate the layout normally.  Pango will make sure that
  64 Asian languages take the right form, while other scripts are rotated normally.
  65 </para>
  66 <para>
  67 The correct way to set gravity on a layout is to set it on the context
  68 associated with it using <link linkend="pango-context-set-base-gravity"><function>pango_context_set_base_gravity()</function></link>.  The context
  69 of a layout can be accessed using <link linkend="pango-layout-get-context"><function>pango_layout_get_context()</function></link>.  The currently
  70 set base gravity of the context can be accessed using
  71 <link linkend="pango-context-get-base-gravity"><function>pango_context_get_base_gravity()</function></link> and the <firstterm>resolved</firstterm>
  72 gravity of it using <link linkend="pango-context-get-gravity"><function>pango_context_get_gravity()</function></link>.  The resolved gravity is
  73 the same as the base gravity for the most part, except that if the base
  74 gravity is set to <link linkend="PANGO-GRAVITY-AUTO--CAPS"><literal>PANGO_GRAVITY_AUTO</literal></link>, the resolved gravity will depend
  75 on the current matrix set on context, and is derived using
  76 <link linkend="pango-gravity-get-for-matrix"><function>pango_gravity_get_for_matrix()</function></link>.
  77 </para>
  78 <para>
  79 The next thing an application may want to set on the context is the
  80 <firstterm>gravity hint</firstterm>.  A <link linkend="PangoGravityHint"><type>PangoGravityHint</type></link> instructs how
  81 different scripts should react to the set base gravity.
  82 </para>
  83 <para>
  84 Font descriptions have a gravity property too, that can be set using
  85 <link linkend="pango-font-description-set-gravity"><function>pango_font_description_set_gravity()</function></link> and accessed using
  86 <link linkend="pango-font-description-get-gravity"><function>pango_font_description_get_gravity()</function></link>.  However, those are rarely useful
  87 from application code and are mainly used by <link linkend="PangoLayout"><type>PangoLayout</type></link> internally.
  88 </para>
  89 <para>
  90 Last but not least, one can create <link linkend="PangoAttribute"><type>PangoAttribute</type></link><!---->s for gravity
  91 and gravity hint using <link linkend="pango-attr-gravity-new"><function>pango_attr_gravity_new()</function></link> and
  92 <link linkend="pango-attr-gravity-hint-new"><function>pango_attr_gravity_hint_new()</function></link>.
  93 </para>
  94 </refsect1>
  95
  96 <refsect1 id="pango-Vertical-Text.details" role="details">
  97 <title role="details.title">Details</title>
  98 <refsect2 id="PangoGravity" role="enum" condition="since:1.16">
  99 <title>enum PangoGravity</title>
 100 <indexterm zone="PangoGravity" role="1.16"><primary sortas="PangoGravity">PangoGravity</primary></indexterm><programlisting>typedef enum {
 101   PANGO_GRAVITY_SOUTH,
 102   PANGO_GRAVITY_EAST,
 103   PANGO_GRAVITY_NORTH,
 104   PANGO_GRAVITY_WEST,
 105   PANGO_GRAVITY_AUTO
 106 } PangoGravity;
 107 </programlisting>
 108 <para>
 109 The <link linkend="PangoGravity"><type>PangoGravity</type></link> type represents the orientation of glyphs in a segment
 110 of text.  This is useful when rendering vertical text layouts.  In
 111 those situations, the layout is rotated using a non-identity PangoMatrix,
 112 and then glyph orientation is controlled using <link linkend="PangoGravity"><type>PangoGravity</type></link>.
 113 Not every value in this enumeration makes sense for every usage of
 114 <link linkend="PangoGravity"><type>PangoGravity</type></link>; for example, <link linkend="PANGO-GRAVITY-AUTO--CAPS"><literal>PANGO_GRAVITY_AUTO</literal></link> only can be passed to
 115 <link linkend="pango-context-set-base-gravity"><function>pango_context_set_base_gravity()</function></link> and can only be returned by
 116 <link linkend="pango-context-get-base-gravity"><function>pango_context_get_base_gravity()</function></link>.
 117 </para>
 118 <para>
 119 See also: <link linkend="PangoGravityHint"><type>PangoGravityHint</type></link></para>
 120 <para>
 121 </para><variablelist role="enum">
 122 <varlistentry id="PANGO-GRAVITY-SOUTH--CAPS" role="constant">
 123 <term><literal>PANGO_GRAVITY_SOUTH</literal></term>
 124 <listitem><simpara> Glyphs stand upright (default)
 125 </simpara></listitem>
 126 </varlistentry>
 127 <varlistentry id="PANGO-GRAVITY-EAST--CAPS" role="constant">
 128 <term><literal>PANGO_GRAVITY_EAST</literal></term>
 129 <listitem><simpara> Glyphs are rotated 90 degrees clockwise
 130 </simpara></listitem>
 131 </varlistentry>
 132 <varlistentry id="PANGO-GRAVITY-NORTH--CAPS" role="constant">
 133 <term><literal>PANGO_GRAVITY_NORTH</literal></term>
 134 <listitem><simpara> Glyphs are upside-down
 135 </simpara></listitem>
 136 </varlistentry>
 137 <varlistentry id="PANGO-GRAVITY-WEST--CAPS" role="constant">
 138 <term><literal>PANGO_GRAVITY_WEST</literal></term>
 139 <listitem><simpara> Glyphs are rotated 90 degrees counter-clockwise
 140 </simpara></listitem>
 141 </varlistentry>
 142 <varlistentry id="PANGO-GRAVITY-AUTO--CAPS" role="constant">
 143 <term><literal>PANGO_GRAVITY_AUTO</literal></term>
 144 <listitem><simpara> Gravity is resolved from the context matrix
 145 </simpara></listitem>
 146 </varlistentry>
 147 </variablelist><para role="since">Since 1.16</para></refsect2>
 148 <refsect2 id="PangoGravityHint" role="enum" condition="since:1.16">
 149 <title>enum PangoGravityHint</title>
 150 <indexterm zone="PangoGravityHint" role="1.16"><primary sortas="PangoGravityHint">PangoGravityHint</primary></indexterm><programlisting>typedef enum {
 151   PANGO_GRAVITY_HINT_NATURAL,
 152   PANGO_GRAVITY_HINT_STRONG,
 153   PANGO_GRAVITY_HINT_LINE
 154 } PangoGravityHint;
 155 </programlisting>
 156 <para>
 157 The <link linkend="PangoGravityHint"><type>PangoGravityHint</type></link> defines how horizontal scripts should behave in a
 158 vertical context.  That is, English excerpt in a vertical paragraph for
 159 example.
 160 </para>
 161 <para>
 162 See <link linkend="PangoGravity"><type>PangoGravity</type></link>.</para>
 163 <para>
 164 </para><variablelist role="enum">
 165 <varlistentry id="PANGO-GRAVITY-HINT-NATURAL--CAPS" role="constant">
 166 <term><literal>PANGO_GRAVITY_HINT_NATURAL</literal></term>
 167 <listitem><simpara> scripts will take their natural gravity based
 168 on the base gravity and the script.  This is the default.
 169 </simpara></listitem>
 170 </varlistentry>
 171 <varlistentry id="PANGO-GRAVITY-HINT-STRONG--CAPS" role="constant">
 172 <term><literal>PANGO_GRAVITY_HINT_STRONG</literal></term>
 173 <listitem><simpara> always use the base gravity set, regardless of
 174 the script.
 175 </simpara></listitem>
 176 </varlistentry>
 177 <varlistentry id="PANGO-GRAVITY-HINT-LINE--CAPS" role="constant">
 178 <term><literal>PANGO_GRAVITY_HINT_LINE</literal></term>
 179 <listitem><simpara> for scripts not in their natural direction (eg.
 180 Latin in East gravity), choose per-script gravity such that every script
 181 respects the line progression.  This means, Latin and Arabic will take
 182 opposite gravities and both flow top-to-bottom for example.
 183 </simpara></listitem>
 184 </varlistentry>
 185 </variablelist><para role="since">Since 1.16</para></refsect2>
 186 <refsect2 id="PANGO-GRAVITY-IS-VERTICAL--CAPS" role="macro" condition="since:1.16">
 187 <title>PANGO_GRAVITY_IS_VERTICAL()</title>
 188 <indexterm zone="PANGO-GRAVITY-IS-VERTICAL--CAPS" role="1.16"><primary sortas="PANGO_GRAVITY_IS_VERTICAL">PANGO_GRAVITY_IS_VERTICAL</primary></indexterm><programlisting>#define             PANGO_GRAVITY_IS_VERTICAL(gravity)</programlisting>
 189 <para>
 190 Whether a <link linkend="PangoGravity"><type>PangoGravity</type></link> represents vertical writing directions.</para>
 191 <para>
 192 </para><variablelist role="params">
 193 <varlistentry><term><parameter>gravity</parameter>&#160;:</term>
 194 <listitem><simpara> the <link linkend="PangoGravity"><type>PangoGravity</type></link> to check
 195 </simpara></listitem></varlistentry>
 196 </variablelist><para role="since">Since 1.16</para></refsect2>
 197 <refsect2 id="pango-gravity-get-for-matrix" role="function" condition="since:1.16">
 198 <title>pango_gravity_get_for_matrix ()</title>
 199 <indexterm zone="pango-gravity-get-for-matrix" role="1.16"><primary sortas="pango_gravity_get_for_matrix">pango_gravity_get_for_matrix</primary></indexterm><programlisting><link linkend="PangoGravity">PangoGravity</link>        pango_gravity_get_for_matrix        (const <link linkend="PangoMatrix">PangoMatrix</link> *matrix);</programlisting>
 200 <para>
 201 Finds the gravity that best matches the rotation component
 202 in a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>.</para>
 203 <para>
 204 </para><variablelist role="params">
 205 <varlistentry><term><parameter>matrix</parameter>&#160;:</term>
 206 <listitem><simpara> a <link linkend="PangoMatrix"><type>PangoMatrix</type></link>
 207 </simpara></listitem></varlistentry>
 208 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the gravity of <parameter>matrix</parameter>, which will never be
 209 <link linkend="PANGO-GRAVITY-AUTO--CAPS"><literal>PANGO_GRAVITY_AUTO</literal></link>, or <link linkend="PANGO-GRAVITY-SOUTH--CAPS"><literal>PANGO_GRAVITY_SOUTH</literal></link> if <parameter>matrix</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 210
 211 </simpara></listitem></varlistentry>
 212 </variablelist><para role="since">Since 1.16</para></refsect2>
 213 <refsect2 id="pango-gravity-get-for-script" role="function" condition="since:1.16">
 214 <title>pango_gravity_get_for_script ()</title>
 215 <indexterm zone="pango-gravity-get-for-script" role="1.16"><primary sortas="pango_gravity_get_for_script">pango_gravity_get_for_script</primary></indexterm><programlisting><link linkend="PangoGravity">PangoGravity</link>        pango_gravity_get_for_script        (<link linkend="PangoScript">PangoScript</link> script,
 216                                                          <link linkend="PangoGravity">PangoGravity</link> base_gravity,
 217                                                          <link linkend="PangoGravityHint">PangoGravityHint</link> hint);</programlisting>
 218 <para>
 219 Based on the script, base gravity, and hint, returns actual gravity
 220 to use in laying out a single <link linkend="PangoItem"><type>PangoItem</type></link>.
 221 </para>
 222 <para>
 223 If <parameter>base_gravity</parameter> is <link linkend="PANGO-GRAVITY-AUTO--CAPS"><literal>PANGO_GRAVITY_AUTO</literal></link>, it is first replaced with the
 224 preferred gravity of <parameter>script</parameter>.  To get the preferred gravity of a script,
 225 pass <link linkend="PANGO-GRAVITY-AUTO--CAPS"><literal>PANGO_GRAVITY_AUTO</literal></link> and <link linkend="PANGO-GRAVITY-HINT-STRONG--CAPS"><literal>PANGO_GRAVITY_HINT_STRONG</literal></link> in.</para>
 226 <para>
 227 </para><variablelist role="params">
 228 <varlistentry><term><parameter>script</parameter>&#160;:</term>
 229 <listitem><simpara> <link linkend="PangoScript"><type>PangoScript</type></link> to query
 230 </simpara></listitem></varlistentry>
 231 <varlistentry><term><parameter>base_gravity</parameter>&#160;:</term>
 232 <listitem><simpara> base gravity of the paragraph
 233 </simpara></listitem></varlistentry>
 234 <varlistentry><term><parameter>hint</parameter>&#160;:</term>
 235 <listitem><simpara> orientation hint
 236 </simpara></listitem></varlistentry>
 237 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> resolved gravity suitable to use for a run of text
 238 with <parameter>script</parameter>.
 239
 240 </simpara></listitem></varlistentry>
 241 </variablelist><para role="since">Since 1.16</para></refsect2>
 242 <refsect2 id="pango-gravity-get-for-script-and-width" role="function" condition="since:1.26">
 243 <title>pango_gravity_get_for_script_and_width ()</title>
 244 <indexterm zone="pango-gravity-get-for-script-and-width" role="1.26"><primary sortas="pango_gravity_get_for_script_and_width">pango_gravity_get_for_script_and_width</primary></indexterm><programlisting><link linkend="PangoGravity">PangoGravity</link>        pango_gravity_get_for_script_and_width
 245                                                         (<link linkend="PangoScript">PangoScript</link> script,
 246                                                          <link linkend="gboolean">gboolean</link> wide,
 247                                                          <link linkend="PangoGravity">PangoGravity</link> base_gravity,
 248                                                          <link linkend="PangoGravityHint">PangoGravityHint</link> hint);</programlisting>
 249 <para>
 250 Based on the script, East Asian width, base gravity, and hint,
 251 returns actual gravity to use in laying out a single character
 252 or <link linkend="PangoItem"><type>PangoItem</type></link>.
 253 </para>
 254 <para>
 255 This function is similar to <link linkend="pango-gravity-get-for-script"><function>pango_gravity_get_for_script()</function></link> except
 256 that this function makes a distinction between narrow/half-width and
 257 wide/full-width characters also.  Wide/full-width characters always
 258 stand <emph>upright</emph>, that is, they always take the base gravity,
 259 whereas narrow/full-width characters are always rotated in vertical
 260 context.
 261 </para>
 262 <para>
 263 If <parameter>base_gravity</parameter> is <link linkend="PANGO-GRAVITY-AUTO--CAPS"><literal>PANGO_GRAVITY_AUTO</literal></link>, it is first replaced with the
 264 preferred gravity of <parameter>script</parameter>.</para>
 265 <para>
 266 </para><variablelist role="params">
 267 <varlistentry><term><parameter>script</parameter>&#160;:</term>
 268 <listitem><simpara> <link linkend="PangoScript"><type>PangoScript</type></link> to query
 269 </simpara></listitem></varlistentry>
 270 <varlistentry><term><parameter>wide</parameter>&#160;:</term>
 271 <listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> for wide characters as returned by <link linkend="g-unichar-iswide"><function>g_unichar_iswide()</function></link>
 272 </simpara></listitem></varlistentry>
 273 <varlistentry><term><parameter>base_gravity</parameter>&#160;:</term>
 274 <listitem><simpara> base gravity of the paragraph
 275 </simpara></listitem></varlistentry>
 276 <varlistentry><term><parameter>hint</parameter>&#160;:</term>
 277 <listitem><simpara> orientation hint
 278 </simpara></listitem></varlistentry>
 279 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> resolved gravity suitable to use for a run of text
 280 with <parameter>script</parameter> and <parameter>wide</parameter>.
 281
 282 </simpara></listitem></varlistentry>
 283 </variablelist><para role="since">Since 1.26</para></refsect2>
 284 <refsect2 id="pango-gravity-to-rotation" role="function" condition="since:1.16">
 285 <title>pango_gravity_to_rotation ()</title>
 286 <indexterm zone="pango-gravity-to-rotation" role="1.16"><primary sortas="pango_gravity_to_rotation">pango_gravity_to_rotation</primary></indexterm><programlisting><link linkend="double">double</link>              pango_gravity_to_rotation           (<link linkend="PangoGravity">PangoGravity</link> gravity);</programlisting>
 287 <para>
 288 Converts a <link linkend="PangoGravity"><type>PangoGravity</type></link> value to its natural rotation in radians.
 289 <parameter>gravity</parameter> should not be <link linkend="PANGO-GRAVITY-AUTO--CAPS"><literal>PANGO_GRAVITY_AUTO</literal></link>.
 290 </para>
 291 <para>
 292 Note that <link linkend="pango-matrix-rotate"><function>pango_matrix_rotate()</function></link> takes angle in degrees, not radians.
 293 So, to call <link linkend="pango-matrix-rotate"><function>pango_matrix_rotate()</function></link> with the output of this function
 294 you should multiply it by (180. / G_PI).</para>
 295 <para>
 296 </para><variablelist role="params">
 297 <varlistentry><term><parameter>gravity</parameter>&#160;:</term>
 298 <listitem><simpara> gravity to query
 299 </simpara></listitem></varlistentry>
 300 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the rotation value corresponding to <parameter>gravity</parameter>.
 301
 302 </simpara></listitem></varlistentry>
 303 </variablelist><para role="since">Since 1.16</para></refsect2>
 304
 305 </refsect1>
 306
 307
 308
 309 <refsect1 id="pango-Vertical-Text.see-also">
 310 <title>See Also</title>
 311 <para>
 312 <link linkend="pango-context-get-base-gravity"><function>pango_context_get_base_gravity()</function></link>,
 313 <link linkend="pango-context-set-base-gravity"><function>pango_context_set_base_gravity()</function></link>,
 314 <link linkend="pango-context-get-gravity"><function>pango_context_get_gravity()</function></link>,
 315 <link linkend="pango-context-get-gravity-hint"><function>pango_context_get_gravity_hint()</function></link>,
 316 <link linkend="pango-context-set-gravity-hint"><function>pango_context_set_gravity_hint()</function></link>,
 317 <link linkend="pango-font-description-set-gravity"><function>pango_font_description_set_gravity()</function></link>,
 318 <link linkend="pango-font-description-get-gravity"><function>pango_font_description_get_gravity()</function></link>,
 319 <link linkend="pango-attr-gravity-new"><function>pango_attr_gravity_new()</function></link>,
 320 <link linkend="pango-attr-gravity-hint-new"><function>pango_attr_gravity_hint_new()</function></link>
 321 </para>
 322 </refsect1>
 323
 324 </refentry>