Bug 9033 fixed: the property auto_dimensionning was not documented
[scilab.git] / scilab / modules / graphics / help / en_US / text / text_properties.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Djalel Abdemouche
5  * Copyright (C) INRIA - Jean-Baptiste silvy
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="text_properties">
15     <refnamediv>
16         <refname>text properties</refname>
17         <refpurpose>description of the Text entity
18             properties
19         </refpurpose>
20     </refnamediv>
21     <refsection>
22         <title>Description</title>
23         <para>The Text entity is a leaf of the graphics entities hierarchy. This
24             entity defines the parameters for string drawing
25         </para>
26         <variablelist>
27             <varlistentry>
28                 <term>parent: </term>
29                 <listitem>
30                     <para>This property contains the handle of the parent. The parent of the
31                         text entity should be of the type <literal>"Axes"</literal> or
32                         <literal>"Compound"</literal>.
33                     </para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>children: </term>
38                 <listitem>
39                     <para>
40                         This property contains a vector with the <literal>children</literal> of
41                         the handle. However, text handles currently do not have any
42                         <literal>children</literal>.
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>visible: </term>
48                 <listitem>
49                     <para>
50                         This field contains the <literal>visible</literal> property value for
51                         the entity . It should be <literal>"on" </literal> or <literal>"off"</literal> .By
52                         default, the text is visible, the value's property is
53                         <literal>"on"</literal>. If <literal>"off"</literal> the text is not displayed on
54                         the screen.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>text: </term>
60                 <listitem>
61                     <para>the matrix containing the strings of the object. The rows of the
62                         matrix are displayed horizontally and the columns vertically.
63                     </para>
64                     <para>
65                         Starting from Scilab 5.2, it is possible to write <link linkend="math_rendering_features_in_graphic">LaTeX or MathML expression</link>.
66                     </para>
67                 </listitem>
68             </varlistentry>
69             <varlistentry>
70                 <term>alignment: </term>
71                 <listitem>
72                     <para>Specify how the strings are aligned in their columns. The value
73                         must be <emphasis role="bold">'left'</emphasis>,<emphasis role="bold"> 'center' </emphasis>or <emphasis role="bold">'right'</emphasis>.
74                     </para>
75                 </listitem>
76             </varlistentry>
77             <varlistentry>
78                 <term>data: </term>
79                 <listitem>
80                     <para>
81                         This field is the vector <literal>[x,y,[z]]</literal> of the origin of
82                         the text in the data units of the axes.
83                     </para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>box: </term>
88                 <listitem>
89                     <para>
90                         This field takes the values <literal>"on"</literal> or
91                         <literal>"off"</literal>. If <literal>"on"</literal> a box is draw around the text
92                         with a line on its edge and a background.
93                     </para>
94                 </listitem>
95             </varlistentry>
96             <varlistentry>
97                 <term>line_mode: </term>
98                 <listitem>
99                     <para>This boolean property allows to draw or not a line around the box
100                         when the <literal>box</literal> property is <literal>"on"</literal>. If
101                         <literal>line_mode</literal> is <literal>"off"</literal>, the line of the box is
102                         not drawn.
103                     </para>
104                 </listitem>
105             </varlistentry>
106             <varlistentry>
107                 <term>fill_mode: </term>
108                 <listitem>
109                     <para>This boolean property allows to draw or not the background of the
110                         box when the <literal>box</literal> property is <literal>"on"</literal>. If
111                         <literal>fill_mode</literal> is <literal>"off"</literal>, the background of the
112                         box is not transparent.
113                     </para>
114                 </listitem>
115             </varlistentry>
116             <varlistentry>
117                 <term>text_box: </term>
118                 <listitem>
119                     <para>A two dimensional vector specifying the size of a rectangle in user coordinates.
120                         The rectangle is used when the text_box_mode property is set to
121                         <emphasis role="bold">'centered'</emphasis> or <emphasis role="bold">'filled'</emphasis>.
122                     </para>
123                 </listitem>
124             </varlistentry>
125             <varlistentry>
126                 <term>text_box_mode: </term>
127                 <listitem>
128                     <para>
129                         May have three different value : <emphasis role="bold">'off'</emphasis>,
130                         <emphasis role="bold">'centered'</emphasis> or <emphasis role="bold">'filled'</emphasis>. If <emphasis role="bold">'off'</emphasis>, the
131                         strings are displayed using the given font and the data field
132                         specifies the position of the lower-left point of the text. If
133                         <emphasis role="bold">'centered'</emphasis>, the text is displayed in the middle of the
134                         rectangle whose size is given by text_box. If <emphasis role="bold">'filled'</emphasis> the
135                         font size of the strings will be expanded to fill the rectangle.
136                     </para>
137                     <para>
138                         When using <emphasis role="bold">'off'</emphasis> or <emphasis role="bold">'centered'</emphasis> modes,
139                         text size remains constant upon zooming. They are the best modes to create annotations
140                         in a graph. On the contrary, when using the <emphasis role="bold">'filled'</emphasis> mode, the text size follow
141                         the graphic scale. It is then possible to zoom upon text objects.
142                     </para>
143                 </listitem>
144             </varlistentry>
145             <varlistentry>
146                 <term>auto_dimensionning: </term>
147                 <listitem>
148                   <para>
149                     auto_dimensionning set to "off" is equivalent to text_box_mode set to "filled". If text_box_mode is "off" or "centered" then it implies that auto_dimensionning is "on".
150                   </para>
151                 </listitem>
152             </varlistentry>
153             <varlistentry>
154                 <term>font_foreground: </term>
155                 <listitem>
156                     <para>This field contains the color used to display the characters of
157                         the text. Its value should be a color index (relative to the current
158                         colormap).
159                     </para>
160                 </listitem>
161             </varlistentry>
162             <varlistentry>
163                 <term>foreground: </term>
164                 <listitem>
165                     <para>This field contains the color used to display the line on the edge
166                         of the box. Its value should be a color index (relative to the current
167                         colormap).
168                     </para>
169                 </listitem>
170             </varlistentry>
171             <varlistentry>
172                 <term>background: </term>
173                 <listitem>
174                     <para>This field contains the color used to fill the box around of the
175                         text. Its value should be a color index (relative to the current
176                         colormap).
177                     </para>
178                 </listitem>
179             </varlistentry>
180             <varlistentry>
181                 <term>font_size: </term>
182                 <listitem>
183                     <para>It is a scalar specifying the displayed characters size.
184                         If <literal>fractional_font</literal> property is <literal>"off"</literal>
185                         only the integer part of the value is used.
186                         For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
187                     </para>
188                 </listitem>
189             </varlistentry>
190             <varlistentry>
191                 <term>font_style: </term>
192                 <listitem>
193                     <para>Specifies the font used to display the character strings.
194                         This is a positive integer referecing one of the loaded fonts.
195                         Its value must be between 0, referecing the first font,
196                         and the number of loaded fonts minus one, referencing the last font.
197                         For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
198                     </para>
199                 </listitem>
200             </varlistentry>
201             <varlistentry>
202                 <term>fractional_font: </term>
203                 <listitem>
204                     <para>
205                         This property specify whether text is displayed using fractional font sizes.
206                         Its value must be either <literal>"on"</literal> or <literal>"off"</literal>.
207                         If <literal>"on"</literal> the floating point value of <literal>font_size</literal>
208                         is used for display and the font is anti-aliased. If <literal>"off"</literal> only the integer part is used
209                         and the font is not smoothed.
210                     </para>
211                 </listitem>
212             </varlistentry>
213             <varlistentry>
214                 <term>font_angle: </term>
215                 <listitem>
216                     <para>This property determines the orientation of the text string.
217                         Specify value of rotation in degrees.
218                     </para>
219                 </listitem>
220             </varlistentry>
221             <varlistentry>
222                 <term>clip_state: </term>
223                 <listitem>
224                     <para>
225                         This field contains the <literal>clip_state</literal> property value for
226                         the text. Its value should be :
227                     </para>
228                     <itemizedlist>
229                         <listitem>
230                             <para>
231                                 <literal>"off"</literal> this means that the text is not
232                                 clipped.
233                             </para>
234                         </listitem>
235                         <listitem>
236                             <para>
237                                 <literal>"clipgrf"</literal> this means that the text is clipped
238                                 outside the Axes box.
239                             </para>
240                         </listitem>
241                         <listitem>
242                             <para>
243                                 <literal>"on"</literal> this means that the text is clipped outside
244                                 the rectangle given by the property <literal>clip_box</literal>.
245                             </para>
246                         </listitem>
247                     </itemizedlist>
248                 </listitem>
249             </varlistentry>
250             <varlistentry>
251                 <term>clip_box: </term>
252                 <listitem>
253                     <para>
254                         This field contains the <literal>clip_box</literal> property. Its value
255                         should be an empty matrix if clip_state is "off" or the vector
256                         <literal>[x,y,w,h</literal>] (upper-left point width height).
257                     </para>
258                 </listitem>
259             </varlistentry>
260             <varlistentry>
261                 <term>user_data: </term>
262                 <listitem>
263                     <para>This field can be use to store any scilab variable in the text
264                         data structure, and to retreive it.
265                     </para>
266                 </listitem>
267             </varlistentry>
268         </variablelist>
269     </refsection>
270     <refsection>
271         <title>Examples</title>
272         <programlisting role="example"><![CDATA[ 
273 a=get("current_axes");
274 a.data_bounds=[0,0;1,1];
275 a.axes_visible = 'on' ;
276
277 xstring(0.5,0.5,"Scilab is not esilaB",0,0)
278
279 t=get("hdl")   //get the handle of the newly created object
280
281 t.font_foreground=6; // change font properties
282 t.font_size=5;
283 t.font_style=5;
284
285
286 t.text=["SCILAB","is";"not","esilaB"] ; // change the text
287 t.font_angle=90 ; // turn the strings
288 t.text_box = [0,0] ;
289 t.text_box_mode = 'centered' ; // the text is now centered on [0.5,0.5].
290 t.alignment = 'center' ;
291 t.box = 'on' ; // draw a box around the text
292
293 // Only valid from Scilab 5.2
294 mathml="<mrow>      <mfrac>        <mrow>          <mi>d</mi>          <mi>y</mi>        </mrow>        <mrow>          <mi>d</mi>          <mi>x</mi>        </mrow>      </mfrac>      <mo>=</mo>      <mfrac>        <mn>1</mn>        <msup>          <mi>y</mi>          <mn>2</mn>        </msup>      </mfrac>    </mrow>";
295 t.text=["SCILAB","can write LaTeX :","$\frac{abc}{xyz}$";"or","MathML :",mathml] ; 
296
297
298  ]]></programlisting>
299         <scilab:image>
300             a=get("current_axes");
301             a.data_bounds=[0,0;1,1];
302             a.axes_visible = 'on' ;
303             
304             xstring(0,0,"Scilab is not esilaB",0,0)
305             
306             t=get("hdl") 
307             
308             t.font_foreground=6; 
309             t.font_size=5;
310             t.font_style=5;
311         </scilab:image>
312     </refsection>
313     <refsection role="see also">
314         <title>See Also</title>
315         <simplelist type="inline">
316             <member>
317                 <link linkend="set">set</link>
318             </member>
319             <member>
320                 <link linkend="get">get</link>
321             </member>
322             <member>
323                 <link linkend="delete">delete</link>
324             </member>
325             <member>
326                 <link linkend="xtitle">xtitle</link>
327             </member>
328             <member>
329                 <link linkend="graphics_entities">graphics_entities</link>
330             </member>
331         </simplelist>
332     </refsection>
333 </refentry>