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