Typo: legeng ==> legend
[scilab.git] / scilab / modules / graphics / help / en_US / annotation / legend_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  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:id="legend_properties" xml:lang="en">
14     <refnamediv>
15         <refname>Legend entity properties</refname>
16         <refpurpose>description of the Legend entity properties.</refpurpose>
17     </refnamediv>
18     <refsection>
19         <title>Description</title>
20         <para>The Legend entity is a leaf of the graphics entities
21             hierarchy. This entity defines the parameters for legends drawn
22             below <literal>plot2dx</literal> graphs or created by the <link linkend="captions">captions</link> function. For selected line
23             plotted, the legend shows a sample of the line type, marker
24             symbol, and color.
25         </para>
26         <variablelist>
27             <varlistentry>
28                 <term>parent:</term>
29                 <listitem>
30                     <para>This property contains the handle of the parent. The
31                         parent of the legend entity should be of the type
32                         <literal>"Compound"</literal>. This Compound entity contains
33                         also the remainder of the graph's entities.
34                     </para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>children:</term>
39                 <listitem>
40                     <para>This property contains a vector with the
41                         <literal>children</literal> of the handle. However,
42                         <literal>legend</literal> handles currently do not have any
43                         <literal>children</literal>.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>visible:</term>
49                 <listitem>
50                     <para>
51                         This field contains the <literal>visible</literal> property
52                         value for the entity . It should be <literal>"on" </literal> or
53                         <literal>"off"</literal> . If <literal>"on"</literal> the legend is
54                         drawn , If <literal>"off"</literal> the legend is not displayed on
55                         the screen.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>text:</term>
61                 <listitem>
62                     <para>This field is the character string vector which contains the
63                         legends for each annotated objects.
64                     </para>
65                     <para>
66                         Starting from Scilab 5.2, it is possible to write <link linkend="math_rendering_features_in_graphic">LaTeX or MathML expression</link>.
67                     </para>
68                 </listitem>
69             </varlistentry>
70             <varlistentry>
71                 <term>font_size:</term>
72                 <listitem>
73                     <para>It is a scalar specifying the displayed characters size.
74                         If <literal>fractional_font</literal> property is <literal>"off"</literal>
75                         only the integer part of the value is used.
76                         For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>font_style:</term>
82                 <listitem>
83                     <para>Specifies the font used to display the legend labels.
84                         This is a positive integer referecing one of the loaded fonts.
85                         Its value must be between 0, referecing the first font,
86                         and the number of loaded fonts minus one, referencing the last font.
87                         For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
88                     </para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>font_color</term>
93                 <listitem>
94                     <para>A color index, this property determines the color of the
95                         text.
96                     </para>
97                 </listitem>
98             </varlistentry>
99             <varlistentry>
100                 <term>fractional_font:</term>
101                 <listitem>
102                     <para>This property specify whether text is displayed using
103                         fractional font sizes. Its value must be either
104                         <literal>"on"</literal> or <literal>"off"</literal>. If
105                         <literal>"on"</literal> the floating point value of
106                         <literal>font_size</literal> is used for display and the
107                         font is anti-aliased. If <literal>"off"</literal> only the
108                         integer part is used and the font is not smoothed.
109                     </para>
110                 </listitem>
111             </varlistentry>
112             <varlistentry>
113                 <term>links:</term>
114                 <listitem>
115                     <para>A row array of handles. They refer to the associated
116                         polylines.
117                     </para>
118                 </listitem>
119             </varlistentry>
120             <varlistentry>
121                 <term>legend_location</term>
122                 <listitem>
123                     <para>A character string, specifies the location of the
124                         Legend.
125                     </para>
126                     <itemizedlist>
127                         <listitem>
128                             <para>
129                                 <literal>"in_upper_right" </literal>: captions are drawn
130                                 in the upper right corner of the axes box.
131                             </para>
132                         </listitem>
133                         <listitem>
134                             <para>
135                                 <literal>"in_upper_left"</literal>: captions are drawn in
136                                 the upper left corner of the axes box.
137                             </para>
138                         </listitem>
139                         <listitem>
140                             <para>
141                                 <literal>"in_lower_right"</literal>: captions are drawn in
142                                 the lower right corner of the axes box.
143                             </para>
144                         </listitem>
145                         <listitem>
146                             <para>
147                                 <literal>"in_lower_left"</literal>: captions are drawn in
148                                 the lower left corner of the axes box.
149                             </para>
150                         </listitem>
151                         <listitem>
152                             <para>
153                                 <literal>"out_upper_right"</literal>: captions are drawn
154                                 at the right of the upper right corner of the axes box.
155                             </para>
156                         </listitem>
157                         <listitem>
158                             <para>
159                                 <literal>"out_upper_left"</literal>: captions are drawn at
160                                 the left of the upper left corner of the axes box.
161                             </para>
162                         </listitem>
163                         <listitem>
164                             <para>
165                                 <literal>"out_lower_right"</literal>: captions are drawn
166                                 at the right of the lower right corner of the axes box.
167                             </para>
168                         </listitem>
169                         <listitem>
170                             <para>
171                                 <literal>"out_lower_left"</literal>: captions are drawn at
172                                 the left of the lower left corner of the axes box.
173                             </para>
174                         </listitem>
175                         <listitem>
176                             <para>
177                                 <literal>"upper_caption"</literal>: captions are drawn
178                                 above the upper left corner of the axes box.
179                             </para>
180                         </listitem>
181                         <listitem>
182                             <para>
183                                 <literal>"lower_caption"</literal>: captions are drawn
184                                 below the lower left corner of the axes box. This option
185                                 correspond to the <literal>leg</literal> argument of <link linkend="plot2d">plot2d</link>
186                             </para>
187                         </listitem>
188                         <listitem>
189                             <para>
190                                 <literal>"by_coordinates"</literal>: the upper left
191                                 corner of the captions box is given by the "position"
192                                 field of the associated data structure. The
193                                 <literal>x</literal> and <literal>y</literal>
194                                 positions are given as fractions of the
195                                 <literal>axes_bounds</literal>.
196                             </para>
197                         </listitem>
198                     </itemizedlist>
199                 </listitem>
200             </varlistentry>
201             <varlistentry>
202                 <term>position</term>
203                 <listitem>
204                     <para>The coordinates of the upper left corner of the
205                         legend. The <literal>x</literal> and <literal>y</literal>
206                         positions are given as fractions of the
207                         <literal>axes_bounds</literal> sizes. This field may be set
208                         if <literal>legend_location=="by_coordinates"</literal> or
209                         get for the other legend_location settings.
210                     </para>
211                     <para>
212                         The following instructions can be used to transform these
213                         coordinates (<literal>position</literal>) to user
214                         coordinates ((<literal>x_user</literal>,
215                         <literal>y_user</literal>) or conversely.
216                     </para>
217                     <programlisting role="user coordinates"><![CDATA[ 
218 as=get(gcf(),"axes_size");//size of the canvas in pixels
219 bnds=get(gca(),"axes_bounds");//bounds of the current axes rectangle in figure size ratio.
220 //from legend coordinates to user coordinates
221 [x_user,y_user]=xchange(position(1)*as(1)*bnds(3)+as(1)*bnds(1),...
222                position(2)*as(2)*bnds(4)+as(2)*bnds(2),"i2f") 
223 //from   user coordinates to legend coordinates
224 [x1,y1]=xchange(x_user,y_user,'f2i')
225 position=[(x1-as(1)*bnds(1))/(as(1)*bnds(3)),...
226           (y1-as(2)*bnds(2))/(as(2)*bnds(4))];
227  
228  ]]></programlisting>
229                 </listitem>
230             </varlistentry>
231             <varlistentry>
232                 <term>line_mode</term>
233                 <listitem>
234                     <para>This field specifies if a rectangle is drawn around the legend
235                         or not. It should be <literal>"on"</literal> or
236                         <literal>"off"</literal>. If <literal>"on"</literal> the rectangle
237                         is drawn using the following properties.
238                     </para>
239                 </listitem>
240             </varlistentry>
241             <varlistentry>
242                 <term>thickness</term>
243                 <listitem>
244                     <para>This property is a positive real specifying the surrounding rectangle shape width
245                         in pixels. The displayed width is actually determined by rounding the supplied width
246                         to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
247                         value is considered.
248                     </para>
249                 </listitem>
250             </varlistentry>
251             <varlistentry>
252                 <term>foreground</term>
253                 <listitem>
254                     <para>This field gives the color index of the line used to draw the
255                         rectangle shape.
256                     </para>
257                 </listitem>
258             </varlistentry>
259             <varlistentry>
260                 <term>fill_mode</term>
261                 <listitem>
262                     <para>This field specifies if the legend background is painted or
263                         not. It should be <literal>"on"</literal> or
264                         <literal>"off"</literal>. If <literal>"on"</literal> the background
265                         is painted using the color index set in the
266                         <literal>background</literal> field.
267                     </para>
268                 </listitem>
269             </varlistentry>
270             <varlistentry>
271                 <term>background</term>
272                 <listitem>
273                     <para>This field gives the color index of the line used to paint the
274                         rectangle area.
275                     </para>
276                 </listitem>
277             </varlistentry>
278             <varlistentry>
279                 <term>clip_state:</term>
280                 <listitem>
281                     <para>
282                         This field contains the default <literal>clip_state</literal>
283                         property value for all objects. Its value should be :
284                     </para>
285                     <itemizedlist>
286                         <listitem>
287                             <para>
288                                 <literal>"off"</literal> this means that all objects
289                                 created after that are not clipped (default value).
290                             </para>
291                         </listitem>
292                         <listitem>
293                             <para>
294                                 <literal>"clipgrf"</literal> this means that all objects
295                                 created after that are clipped outside the Axes
296                                 boundaries.
297                             </para>
298                         </listitem>
299                         <listitem>
300                             <para>
301                                 <literal>"on"</literal> this means that all objects
302                                 created after that are clipped outside the rectangle given by
303                                 property clip_box.
304                             </para>
305                         </listitem>
306                     </itemizedlist>
307                 </listitem>
308             </varlistentry>
309             <varlistentry>
310                 <term>clip_box:</term>
311                 <listitem>
312                     <para>
313                         This field contains the default <literal>clip_box</literal>
314                         property value for all objects. Its value should be an empty matrix
315                         if clip_state is <literal>"off"</literal>. Other case the clipping
316                         is given by the vector <literal>[x,y,w,h]</literal> (upper-left
317                         point width height).
318                     </para>
319                 </listitem>
320             </varlistentry>
321             <varlistentry>
322                 <term>user_data:</term>
323                 <listitem>
324                     <para>This field can be use to store any scilab variable in the text
325                         data structure, and to retreive it.
326                     </para>
327                 </listitem>
328             </varlistentry>
329         </variablelist>
330     </refsection>
331     <refsection>
332         <title>Examples</title>
333         <programlisting role="example"><![CDATA[ 
334 // x initialisation 
335 x=[0:0.1:2*%pi]';
336 plot2d(x,[sin(x) sin(2*x) sin(3*x)],..
337   [1,2,3],leg="L1@L2@L3")
338 a=get("current_axes");
339 l=a.children(2);
340 l.links
341 l.text=["sin(x)";"sin(2*x)";"sin(3*x)"];
342 l.visible="off"; // invisible
343 l.font_size = 2;
344 l.font_style = 5;
345 l.visible='on';
346 // Starting from Scilab 5.2, Latex:
347 l.text=["$\sin(x)$";"$\sin(2*x)$";"$\sin(3*x)$"];
348  ]]></programlisting>
349     </refsection>
350     <refsection role="see also">
351         <title>See Also</title>
352         <simplelist type="inline">
353             <member>
354                 <link linkend="plot2d">plot2d</link>
355             </member>
356             <member>
357                 <link linkend="graphics_entities">graphics_entities</link>
358             </member>
359         </simplelist>
360     </refsection>
361 </refentry>