docs/xml/tab-stops.xml

   1 <refentry id="pango-Tab-Stops">
   2 <refmeta>
   3 <refentrytitle role="top_of_page" id="pango-Tab-Stops.top_of_page">Tab Stops</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>PANGO Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Tab Stops</refname>
  10 <refpurpose>Structures for storing tab stops</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv id="pango-Tab-Stops.synopsis" role="synopsis">
  14 <title role="synopsis.title">Synopsis</title>
  15
  16 <synopsis>
  17                     <link linkend="PangoTabArray">PangoTabArray</link>;
  18 #define             <link linkend="PANGO-TYPE-TAB-ARRAY--CAPS">PANGO_TYPE_TAB_ARRAY</link>
  19 enum                <link linkend="PangoTabAlign">PangoTabAlign</link>;
  20 #define             <link linkend="PANGO-TYPE-TAB-ALIGN--CAPS">PANGO_TYPE_TAB_ALIGN</link>
  21 <link linkend="PangoTabArray">PangoTabArray</link> *     <link linkend="pango-tab-array-new">pango_tab_array_new</link>                 (<link linkend="gint">gint</link> initial_size,
  22                                                          <link linkend="gboolean">gboolean</link> positions_in_pixels);
  23 <link linkend="PangoTabArray">PangoTabArray</link> *     <link linkend="pango-tab-array-new-with-positions">pango_tab_array_new_with_positions</link>  (<link linkend="gint">gint</link> size,
  24                                                          <link linkend="gboolean">gboolean</link> positions_in_pixels,
  25                                                          <link linkend="PangoTabAlign">PangoTabAlign</link> first_alignment,
  26                                                          <link linkend="gint">gint</link> first_position,
  27                                                          ...);
  28 <link linkend="PangoTabArray">PangoTabArray</link> *     <link linkend="pango-tab-array-copy">pango_tab_array_copy</link>                (<link linkend="PangoTabArray">PangoTabArray</link> *src);
  29 <link linkend="void">void</link>                <link linkend="pango-tab-array-free">pango_tab_array_free</link>                (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array);
  30 <link linkend="gint">gint</link>                <link linkend="pango-tab-array-get-size">pango_tab_array_get_size</link>            (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array);
  31 <link linkend="void">void</link>                <link linkend="pango-tab-array-resize">pango_tab_array_resize</link>              (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array,
  32                                                          <link linkend="gint">gint</link> new_size);
  33 <link linkend="void">void</link>                <link linkend="pango-tab-array-set-tab">pango_tab_array_set_tab</link>             (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array,
  34                                                          <link linkend="gint">gint</link> tab_index,
  35                                                          <link linkend="PangoTabAlign">PangoTabAlign</link> alignment,
  36                                                          <link linkend="gint">gint</link> location);
  37 <link linkend="void">void</link>                <link linkend="pango-tab-array-get-tab">pango_tab_array_get_tab</link>             (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array,
  38                                                          <link linkend="gint">gint</link> tab_index,
  39                                                          <link linkend="PangoTabAlign">PangoTabAlign</link> *alignment,
  40                                                          <link linkend="gint">gint</link> *location);
  41 <link linkend="void">void</link>                <link linkend="pango-tab-array-get-tabs">pango_tab_array_get_tabs</link>            (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array,
  42                                                          <link linkend="PangoTabAlign">PangoTabAlign</link> **alignments,
  43                                                          <link linkend="gint">gint</link> **locations);
  44 <link linkend="gboolean">gboolean</link>            <link linkend="pango-tab-array-get-positions-in-pixels">pango_tab_array_get_positions_in_pixels</link>
  45                                                         (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array);
  46 </synopsis>
  47 </refsynopsisdiv>
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57 <refsect1 id="pango-Tab-Stops.description" role="desc">
  58 <title role="desc.title">Description</title>
  59 <para>
  60 Functions in this section are used to deal with <link linkend="PangoTabArray"><type>PangoTabArray</type></link> objects
  61 that can be used to set tab stop positions in a <link linkend="PangoLayout"><type>PangoLayout</type></link>.
  62 </para>
  63 </refsect1>
  64
  65 <refsect1 id="pango-Tab-Stops.details" role="details">
  66 <title role="details.title">Details</title>
  67 <refsect2 id="PangoTabArray" role="struct">
  68 <title>PangoTabArray</title>
  69 <indexterm zone="PangoTabArray"><primary sortas="PangoTabArray">PangoTabArray</primary></indexterm><programlisting>typedef struct _PangoTabArray PangoTabArray;</programlisting>
  70 <para>
  71 A <link linkend="PangoTabArray"><type>PangoTabArray</type></link> struct contains an array
  72 of tab stops. Each tab stop has an alignment and a position.
  73 </para></refsect2>
  74 <refsect2 id="PANGO-TYPE-TAB-ARRAY--CAPS" role="macro">
  75 <title>PANGO_TYPE_TAB_ARRAY</title>
  76 <indexterm zone="PANGO-TYPE-TAB-ARRAY--CAPS"><primary sortas="PANGO_TYPE_TAB_ARRAY">PANGO_TYPE_TAB_ARRAY</primary></indexterm><programlisting>#define PANGO_TYPE_TAB_ARRAY (pango_tab_array_get_type ())
  77 </programlisting>
  78 <para>
  79 The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoTabArray"><type>PangoTabArray</type></link>.
  80 </para></refsect2>
  81 <refsect2 id="PangoTabAlign" role="enum">
  82 <title>enum PangoTabAlign</title>
  83 <indexterm zone="PangoTabAlign"><primary sortas="PangoTabAlign">PangoTabAlign</primary></indexterm><programlisting>typedef enum
  84 {
  85   PANGO_TAB_LEFT
  86
  87   /* These are not supported now, but may be in the
  88    * future.
  89    *
  90    *  PANGO_TAB_RIGHT,
  91    *  PANGO_TAB_CENTER,
  92    *  PANGO_TAB_NUMERIC
  93    */
  94 } PangoTabAlign;
  95 </programlisting>
  96 <para>
  97 A <link linkend="PangoTabAlign"><type>PangoTabAlign</type></link> specifies where a tab stop appears relative to the text.
  98 </para><variablelist role="enum">
  99 <varlistentry id="PANGO-TAB-LEFT--CAPS" role="constant">
 100 <term><literal>PANGO_TAB_LEFT</literal></term>
 101 <listitem><simpara>the tab stop appears to the left of the text.
 102 </simpara></listitem>
 103 </varlistentry>
 104 </variablelist></refsect2>
 105 <refsect2 id="PANGO-TYPE-TAB-ALIGN--CAPS" role="macro">
 106 <title>PANGO_TYPE_TAB_ALIGN</title>
 107 <indexterm zone="PANGO-TYPE-TAB-ALIGN--CAPS"><primary sortas="PANGO_TYPE_TAB_ALIGN">PANGO_TYPE_TAB_ALIGN</primary></indexterm><programlisting>#define PANGO_TYPE_TAB_ALIGN (pango_tab_align_get_type())
 108 </programlisting>
 109 <para>
 110 The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoTabAlign"><type>PangoTabAlign</type></link>.
 111 </para></refsect2>
 112 <refsect2 id="pango-tab-array-new" role="function">
 113 <title>pango_tab_array_new ()</title>
 114 <indexterm zone="pango-tab-array-new"><primary sortas="pango_tab_array_new">pango_tab_array_new</primary></indexterm><programlisting><link linkend="PangoTabArray">PangoTabArray</link> *     pango_tab_array_new                 (<link linkend="gint">gint</link> initial_size,
 115                                                          <link linkend="gboolean">gboolean</link> positions_in_pixels);</programlisting>
 116 <para>
 117 Creates an array of <parameter>initial_size</parameter> tab stops. Tab stops are specified in
 118 pixel units if <parameter>positions_in_pixels</parameter> is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, otherwise in Pango
 119 units. All stops are initially at position 0.</para>
 120 <para>
 121 </para><variablelist role="params">
 122 <varlistentry><term><parameter>initial_size</parameter>&#160;:</term>
 123 <listitem><simpara> Initial number of tab stops to allocate, can be 0
 124 </simpara></listitem></varlistentry>
 125 <varlistentry><term><parameter>positions_in_pixels</parameter>&#160;:</term>
 126 <listitem><simpara> whether positions are in pixel units
 127 </simpara></listitem></varlistentry>
 128 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoTabArray"><type>PangoTabArray</type></link>, which should
 129               be freed with <link linkend="pango-tab-array-free"><function>pango_tab_array_free()</function></link>.
 130 </simpara></listitem></varlistentry>
 131 </variablelist></refsect2>
 132 <refsect2 id="pango-tab-array-new-with-positions" role="function">
 133 <title>pango_tab_array_new_with_positions ()</title>
 134 <indexterm zone="pango-tab-array-new-with-positions"><primary sortas="pango_tab_array_new_with_positions">pango_tab_array_new_with_positions</primary></indexterm><programlisting><link linkend="PangoTabArray">PangoTabArray</link> *     pango_tab_array_new_with_positions  (<link linkend="gint">gint</link> size,
 135                                                          <link linkend="gboolean">gboolean</link> positions_in_pixels,
 136                                                          <link linkend="PangoTabAlign">PangoTabAlign</link> first_alignment,
 137                                                          <link linkend="gint">gint</link> first_position,
 138                                                          ...);</programlisting>
 139 <para>
 140 This is a convenience function that creates a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
 141 and allows you to specify the alignment and position of each
 142 tab stop. You <emphasis>must</emphasis> provide an alignment
 143 and position for <parameter>size</parameter> tab stops.</para>
 144 <para>
 145 </para><variablelist role="params">
 146 <varlistentry><term><parameter>size</parameter>&#160;:</term>
 147 <listitem><simpara> number of tab stops in the array
 148 </simpara></listitem></varlistentry>
 149 <varlistentry><term><parameter>positions_in_pixels</parameter>&#160;:</term>
 150 <listitem><simpara> whether positions are in pixel units
 151 </simpara></listitem></varlistentry>
 152 <varlistentry><term><parameter>first_alignment</parameter>&#160;:</term>
 153 <listitem><simpara> alignment of first tab stop
 154 </simpara></listitem></varlistentry>
 155 <varlistentry><term><parameter>first_position</parameter>&#160;:</term>
 156 <listitem><simpara> position of first tab stop
 157 </simpara></listitem></varlistentry>
 158 <varlistentry><term><parameter>...</parameter>&#160;:</term>
 159 <listitem><simpara> additional alignment/position pairs
 160 </simpara></listitem></varlistentry>
 161 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoTabArray"><type>PangoTabArray</type></link>, which should
 162               be freed with <link linkend="pango-tab-array-free"><function>pango_tab_array_free()</function></link>.
 163 </simpara></listitem></varlistentry>
 164 </variablelist></refsect2>
 165 <refsect2 id="pango-tab-array-copy" role="function">
 166 <title>pango_tab_array_copy ()</title>
 167 <indexterm zone="pango-tab-array-copy"><primary sortas="pango_tab_array_copy">pango_tab_array_copy</primary></indexterm><programlisting><link linkend="PangoTabArray">PangoTabArray</link> *     pango_tab_array_copy                (<link linkend="PangoTabArray">PangoTabArray</link> *src);</programlisting>
 168 <para>
 169 Copies a <link linkend="PangoTabArray"><type>PangoTabArray</type></link></para>
 170 <para>
 171 </para><variablelist role="params">
 172 <varlistentry><term><parameter>src</parameter>&#160;:</term>
 173 <listitem><simpara> <link linkend="PangoTabArray"><type>PangoTabArray</type></link> to copy
 174 </simpara></listitem></varlistentry>
 175 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the newly allocated <link linkend="PangoTabArray"><type>PangoTabArray</type></link>, which should
 176               be freed with <link linkend="pango-tab-array-free"><function>pango_tab_array_free()</function></link>.
 177 </simpara></listitem></varlistentry>
 178 </variablelist></refsect2>
 179 <refsect2 id="pango-tab-array-free" role="function">
 180 <title>pango_tab_array_free ()</title>
 181 <indexterm zone="pango-tab-array-free"><primary sortas="pango_tab_array_free">pango_tab_array_free</primary></indexterm><programlisting><link linkend="void">void</link>                pango_tab_array_free                (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array);</programlisting>
 182 <para>
 183 Frees a tab array and associated resources.</para>
 184 <para>
 185 </para><variablelist role="params">
 186 <varlistentry><term><parameter>tab_array</parameter>&#160;:</term>
 187 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
 188 </simpara></listitem></varlistentry>
 189 </variablelist></refsect2>
 190 <refsect2 id="pango-tab-array-get-size" role="function">
 191 <title>pango_tab_array_get_size ()</title>
 192 <indexterm zone="pango-tab-array-get-size"><primary sortas="pango_tab_array_get_size">pango_tab_array_get_size</primary></indexterm><programlisting><link linkend="gint">gint</link>                pango_tab_array_get_size            (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array);</programlisting>
 193 <para>
 194 Gets the number of tab stops in <parameter>tab_array</parameter>.</para>
 195 <para>
 196 </para><variablelist role="params">
 197 <varlistentry><term><parameter>tab_array</parameter>&#160;:</term>
 198 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
 199 </simpara></listitem></varlistentry>
 200 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of tab stops in the array.
 201 </simpara></listitem></varlistentry>
 202 </variablelist></refsect2>
 203 <refsect2 id="pango-tab-array-resize" role="function">
 204 <title>pango_tab_array_resize ()</title>
 205 <indexterm zone="pango-tab-array-resize"><primary sortas="pango_tab_array_resize">pango_tab_array_resize</primary></indexterm><programlisting><link linkend="void">void</link>                pango_tab_array_resize              (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array,
 206                                                          <link linkend="gint">gint</link> new_size);</programlisting>
 207 <para>
 208 Resizes a tab array. You must subsequently initialize any tabs that
 209 were added as a result of growing the array.</para>
 210 <para>
 211 </para><variablelist role="params">
 212 <varlistentry><term><parameter>tab_array</parameter>&#160;:</term>
 213 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
 214 </simpara></listitem></varlistentry>
 215 <varlistentry><term><parameter>new_size</parameter>&#160;:</term>
 216 <listitem><simpara> new size of the array
 217 </simpara></listitem></varlistentry>
 218 </variablelist></refsect2>
 219 <refsect2 id="pango-tab-array-set-tab" role="function">
 220 <title>pango_tab_array_set_tab ()</title>
 221 <indexterm zone="pango-tab-array-set-tab"><primary sortas="pango_tab_array_set_tab">pango_tab_array_set_tab</primary></indexterm><programlisting><link linkend="void">void</link>                pango_tab_array_set_tab             (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array,
 222                                                          <link linkend="gint">gint</link> tab_index,
 223                                                          <link linkend="PangoTabAlign">PangoTabAlign</link> alignment,
 224                                                          <link linkend="gint">gint</link> location);</programlisting>
 225 <para>
 226 Sets the alignment and location of a tab stop.
 227 <parameter>alignment</parameter> must always be <link linkend="PANGO-TAB-LEFT--CAPS"><type>PANGO_TAB_LEFT</type></link> in the current
 228 implementation.</para>
 229 <para>
 230 </para><variablelist role="params">
 231 <varlistentry><term><parameter>tab_array</parameter>&#160;:</term>
 232 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
 233 </simpara></listitem></varlistentry>
 234 <varlistentry><term><parameter>tab_index</parameter>&#160;:</term>
 235 <listitem><simpara> the index of a tab stop
 236 </simpara></listitem></varlistentry>
 237 <varlistentry><term><parameter>alignment</parameter>&#160;:</term>
 238 <listitem><simpara> tab alignment
 239 </simpara></listitem></varlistentry>
 240 <varlistentry><term><parameter>location</parameter>&#160;:</term>
 241 <listitem><simpara> tab location in Pango units
 242 </simpara></listitem></varlistentry>
 243 </variablelist></refsect2>
 244 <refsect2 id="pango-tab-array-get-tab" role="function">
 245 <title>pango_tab_array_get_tab ()</title>
 246 <indexterm zone="pango-tab-array-get-tab"><primary sortas="pango_tab_array_get_tab">pango_tab_array_get_tab</primary></indexterm><programlisting><link linkend="void">void</link>                pango_tab_array_get_tab             (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array,
 247                                                          <link linkend="gint">gint</link> tab_index,
 248                                                          <link linkend="PangoTabAlign">PangoTabAlign</link> *alignment,
 249                                                          <link linkend="gint">gint</link> *location);</programlisting>
 250 <para>
 251 Gets the alignment and position of a tab stop.</para>
 252 <para>
 253 </para><variablelist role="params">
 254 <varlistentry><term><parameter>tab_array</parameter>&#160;:</term>
 255 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
 256 </simpara></listitem></varlistentry>
 257 <varlistentry><term><parameter>tab_index</parameter>&#160;:</term>
 258 <listitem><simpara> tab stop index
 259 </simpara></listitem></varlistentry>
 260 <varlistentry><term><parameter>alignment</parameter>&#160;:</term>
 261 <listitem><simpara> location to store alignment, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 262 </simpara></listitem></varlistentry>
 263 <varlistentry><term><parameter>location</parameter>&#160;:</term>
 264 <listitem><simpara> location to store tab position, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 265 </simpara></listitem></varlistentry>
 266 </variablelist></refsect2>
 267 <refsect2 id="pango-tab-array-get-tabs" role="function">
 268 <title>pango_tab_array_get_tabs ()</title>
 269 <indexterm zone="pango-tab-array-get-tabs"><primary sortas="pango_tab_array_get_tabs">pango_tab_array_get_tabs</primary></indexterm><programlisting><link linkend="void">void</link>                pango_tab_array_get_tabs            (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array,
 270                                                          <link linkend="PangoTabAlign">PangoTabAlign</link> **alignments,
 271                                                          <link linkend="gint">gint</link> **locations);</programlisting>
 272 <para>
 273 If non-<link linkend="NULL--CAPS"><literal>NULL</literal></link>, <parameter>alignments</parameter> and <parameter>locations</parameter> are filled with allocated
 274 arrays of length <link linkend="pango-tab-array-get-size"><function>pango_tab_array_get_size()</function></link>. You must free the
 275 returned array.</para>
 276 <para>
 277 </para><variablelist role="params">
 278 <varlistentry><term><parameter>tab_array</parameter>&#160;:</term>
 279 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
 280 </simpara></listitem></varlistentry>
 281 <varlistentry><term><parameter>alignments</parameter>&#160;:</term>
 282 <listitem><simpara> location to store an array of tab stop alignments, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 283 </simpara></listitem></varlistentry>
 284 <varlistentry><term><parameter>locations</parameter>&#160;:</term>
 285 <listitem><simpara> location to store an array of tab positions, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
 286 </simpara></listitem></varlistentry>
 287 </variablelist></refsect2>
 288 <refsect2 id="pango-tab-array-get-positions-in-pixels" role="function">
 289 <title>pango_tab_array_get_positions_in_pixels ()</title>
 290 <indexterm zone="pango-tab-array-get-positions-in-pixels"><primary sortas="pango_tab_array_get_positions_in_pixels">pango_tab_array_get_positions_in_pixels</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            pango_tab_array_get_positions_in_pixels
 291                                                         (<link linkend="PangoTabArray">PangoTabArray</link> *tab_array);</programlisting>
 292 <para>
 293 Returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the tab positions are in pixels, <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if they are
 294 in Pango units.</para>
 295 <para>
 296 </para><variablelist role="params">
 297 <varlistentry><term><parameter>tab_array</parameter>&#160;:</term>
 298 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
 299 </simpara></listitem></varlistentry>
 300 <varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> whether positions are in pixels.
 301 </simpara></listitem></varlistentry>
 302 </variablelist></refsect2>
 303
 304 </refsect1>
 305
 306
 307
 308
 309 </refentry>