1 <refentry id="pango-Tab-Stops">
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>
9 <refname>Tab Stops</refname>
10 <refpurpose>Structures for storing tab stops</refpurpose>
13 <refsynopsisdiv id="pango-Tab-Stops.synopsis" role="synopsis">
14 <title role="synopsis.title">Synopsis</title>
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,
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);
57 <refsect1 id="pango-Tab-Stops.description" role="desc">
58 <title role="desc.title">Description</title>
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>.
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>
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.
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 ())
79 The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoTabArray"><type>PangoTabArray</type></link>.
81 <refsect2 id="PangoTabAlign" role="enum">
82 <title>enum PangoTabAlign</title>
83 <indexterm zone="PangoTabAlign"><primary sortas="PangoTabAlign">PangoTabAlign</primary></indexterm><programlisting>typedef enum
87 /* These are not supported now, but may be in the
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>
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())
110 The <link linkend="GObject"><type>GObject</type></link> type for <link linkend="PangoTabAlign"><type>PangoTabAlign</type></link>.
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>
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>
121 </para><variablelist role="params">
122 <varlistentry><term><parameter>initial_size</parameter> :</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> :</term>
126 <listitem><simpara> whether positions are in pixel units
127 </simpara></listitem></varlistentry>
128 <varlistentry><term><emphasis>Returns</emphasis> :</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>
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>
145 </para><variablelist role="params">
146 <varlistentry><term><parameter>size</parameter> :</term>
147 <listitem><simpara> number of tab stops in the array
148 </simpara></listitem></varlistentry>
149 <varlistentry><term><parameter>positions_in_pixels</parameter> :</term>
150 <listitem><simpara> whether positions are in pixel units
151 </simpara></listitem></varlistentry>
152 <varlistentry><term><parameter>first_alignment</parameter> :</term>
153 <listitem><simpara> alignment of first tab stop
154 </simpara></listitem></varlistentry>
155 <varlistentry><term><parameter>first_position</parameter> :</term>
156 <listitem><simpara> position of first tab stop
157 </simpara></listitem></varlistentry>
158 <varlistentry><term><parameter>...</parameter> :</term>
159 <listitem><simpara> additional alignment/position pairs
160 </simpara></listitem></varlistentry>
161 <varlistentry><term><emphasis>Returns</emphasis> :</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>
169 Copies a <link linkend="PangoTabArray"><type>PangoTabArray</type></link></para>
171 </para><variablelist role="params">
172 <varlistentry><term><parameter>src</parameter> :</term>
173 <listitem><simpara> <link linkend="PangoTabArray"><type>PangoTabArray</type></link> to copy
174 </simpara></listitem></varlistentry>
175 <varlistentry><term><emphasis>Returns</emphasis> :</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>
183 Frees a tab array and associated resources.</para>
185 </para><variablelist role="params">
186 <varlistentry><term><parameter>tab_array</parameter> :</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>
194 Gets the number of tab stops in <parameter>tab_array</parameter>.</para>
196 </para><variablelist role="params">
197 <varlistentry><term><parameter>tab_array</parameter> :</term>
198 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
199 </simpara></listitem></varlistentry>
200 <varlistentry><term><emphasis>Returns</emphasis> :</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>
208 Resizes a tab array. You must subsequently initialize any tabs that
209 were added as a result of growing the array.</para>
211 </para><variablelist role="params">
212 <varlistentry><term><parameter>tab_array</parameter> :</term>
213 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
214 </simpara></listitem></varlistentry>
215 <varlistentry><term><parameter>new_size</parameter> :</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>
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>
230 </para><variablelist role="params">
231 <varlistentry><term><parameter>tab_array</parameter> :</term>
232 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
233 </simpara></listitem></varlistentry>
234 <varlistentry><term><parameter>tab_index</parameter> :</term>
235 <listitem><simpara> the index of a tab stop
236 </simpara></listitem></varlistentry>
237 <varlistentry><term><parameter>alignment</parameter> :</term>
238 <listitem><simpara> tab alignment
239 </simpara></listitem></varlistentry>
240 <varlistentry><term><parameter>location</parameter> :</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>
251 Gets the alignment and position of a tab stop.</para>
253 </para><variablelist role="params">
254 <varlistentry><term><parameter>tab_array</parameter> :</term>
255 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
256 </simpara></listitem></varlistentry>
257 <varlistentry><term><parameter>tab_index</parameter> :</term>
258 <listitem><simpara> tab stop index
259 </simpara></listitem></varlistentry>
260 <varlistentry><term><parameter>alignment</parameter> :</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> :</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>
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>
277 </para><variablelist role="params">
278 <varlistentry><term><parameter>tab_array</parameter> :</term>
279 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
280 </simpara></listitem></varlistentry>
281 <varlistentry><term><parameter>alignments</parameter> :</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> :</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>
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>
296 </para><variablelist role="params">
297 <varlistentry><term><parameter>tab_array</parameter> :</term>
298 <listitem><simpara> a <link linkend="PangoTabArray"><type>PangoTabArray</type></link>
299 </simpara></listitem></varlistentry>
300 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> whether positions are in pixels.
301 </simpara></listitem></varlistentry>
302 </variablelist></refsect2>