c084a59599627a48452d49084230ad0eb2cce801
[scilab.git] / scilab / modules / graphics / help / en_US / captions.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
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 version="5.0-subset Scilab" xml:id="captions" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate: 2008-03-26 09:50:39 +0100 (Wed, 26 Mar 2008)
22     $</pubdate>
23   </info>
24
25   <refnamediv>
26     <refname>captions</refname>
27
28     <refpurpose>draw graph captions</refpurpose>
29   </refnamediv>
30
31   <refsynopsisdiv>
32     <title>Calling Sequence</title>
33
34     <synopsis>hl=captions(h, strings [,location])</synopsis>
35   </refsynopsisdiv>
36
37   <refsection>
38     <title>Parameters</title>
39
40     <variablelist>
41       <varlistentry>
42         <term>h</term>
43
44         <listitem>
45           <para>vector of handles on polyline entities.</para>
46         </listitem>
47       </varlistentry>
48
49       <varlistentry>
50         <term>strings</term>
51
52         <listitem>
53           <para>n vector of strings, strings(i) is the caption of the ith
54           polyline</para>
55         </listitem>
56       </varlistentry>
57
58       <varlistentry>
59         <term>hl</term>
60
61         <listitem>
62           <para>a handle of type "<literal>Legend</literal>", points to the
63           structure containing all the captions information (see <link
64           linkend="legend_properties">legend_properties</link>.</para>
65         </listitem>
66       </varlistentry>
67     </variablelist>
68
69     <variablelist>
70       <varlistentry>
71         <term>location</term>
72
73         <listitem>
74           <para>a character string with possible values:</para>
75
76           <itemizedlist>
77             <listitem>
78               <para><literal>"in_upper_right" </literal>: captions are drawn
79               in the upper right corner of the axes box.</para>
80             </listitem>
81
82             <listitem>
83               <para><literal>"in_upper_left"</literal>: captions are drawn in
84               the upper left corner of the axes box.</para>
85             </listitem>
86
87             <listitem>
88               <para><literal>"in_lower_right"</literal>: captions are drawn in
89               the lower right corner of the axes box.</para>
90             </listitem>
91
92             <listitem>
93               <para><literal>"in_lower_left"</literal>: captions are drawn in
94               the lower left corner of the axes box.</para>
95             </listitem>
96
97             <listitem>
98               <para><literal>"out_upper_right"</literal>: captions are drawn
99               at the right of the upper right corner of the axes box.</para>
100             </listitem>
101
102             <listitem>
103               <para><literal>"out_upper_left"</literal>: captions are drawn at
104               the left of the upper left corner of the axes box.</para>
105             </listitem>
106
107             <listitem>
108               <para><literal>"out_lower_right"</literal>: captions are drawn
109               at the right of the lower right corner of the axes box.</para>
110             </listitem>
111
112             <listitem>
113               <para><literal>"out_lower_left"</literal>: captions are drawn at
114               the left of the lower left corner of the axes box.</para>
115             </listitem>
116
117             <listitem>
118               <para><literal>"upper_caption"</literal>: captions are drawn
119               above the upper left corner of the axes box.</para>
120             </listitem>
121
122             <listitem>
123               <para><literal>"lower_caption"</literal>: captions are drawn
124               below the lower left corner of the axes box. This option
125               correspond to the <literal>leg</literal> argument of <link
126               linkend="plot2d">plot2d</link></para>
127             </listitem>
128
129             <listitem>
130               <para><literal>"by_coordinates"</literal>: the upper left corner
131               of the captions box is given by the "position" field of the
132               associated data structure. The <literal>x</literal> and
133               <literal>y</literal> positions are given as fractions of the
134               <literal>axes_bounds sizes.</literal></para>
135             </listitem>
136           </itemizedlist>
137         </listitem>
138       </varlistentry>
139     </variablelist>
140   </refsection>
141
142   <refsection>
143     <title>Description</title>
144
145     <para>Puts captions on the current plot at the in the bottom left corner
146     of the graphic window using the specified strings as labels.
147     <literal>captions</literal> prepends labels by a recall of the
148     corresponding polylines. The type and properties are recovered from the
149     given handles:</para>
150
151     <para>The <literal>captions</literal> function creates a <link
152     linkend="legend_property">Legend</link> data structure.</para>
153
154     <para>There is at most one <literal>Legend</literal> associated with each
155     axes. If the caption function is recalled while a
156     <literal>Legend</literal> still exist the old one is replaced.</para>
157   </refsection>
158
159   <refsection>
160     <title>Examples</title>
161
162     <programlisting role="example">
163
164 t=0:0.1:2*%pi;
165 a=gca();a.data_bounds=[t(1) -1.8;t($) 1.8];
166 a.margins(4)=0.2;
167
168 plot2d(t,[cos(t'),cos(2*t'),cos(3*t')],[1,2 3]);  
169 e=gce();
170 e.children(1).thickness=3;
171 e.children(2).line_style=4;
172
173 hl=captions(e.children,['cos(t)';'cos(2*t)';'cos(3*t)']);
174 hl=captions(e.children,['cos(t)';'cos(2*t)';'cos(3*t)'],'in_upper_right');
175
176 hl.legend_location='in_upper_right'
177 hl.fill_mode='on';
178   </programlisting>
179   </refsection>
180
181   <refsection>
182     <title>See Also</title>
183
184     <simplelist type="inline">
185       <member><link linkend="plot2d">plot2d</link></member>
186
187       <member><link linkend="legend">legend</link></member>
188
189       <member><link
190       linkend="polyline_properties">polyline_properties</link></member>
191
192       <member><link
193       linkend="legend_properties">legend_properties</link></member>
194     </simplelist>
195   </refsection>
196 </refentry>