add CDATA + role in the gui module
[scilab.git] / scilab / modules / gui / help / en_US / figure.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <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" version="5.0-subset Scilab" xml:lang="en" xml:id="figure">
3   <info>
4     <pubdate>$LastChangedDate$</pubdate>
5   </info>
6   <refnamediv>
7     <refname>figure</refname>
8     <refpurpose> create a figure</refpurpose>
9   </refnamediv>
10   <refsynopsisdiv>
11     <title>Calling Sequence</title>
12     <synopsis>
13     f = figure(num);
14     f = figure("PropertyName1", Propertyvalue1, ..., ..., "PropertyNameN", PropertyvalueN); 
15     </synopsis>
16   </refsynopsisdiv>
17   <refsection>
18     <title>Description</title>
19     <para>
20     This routine creates a figure. If an ID is given, the figure corresponding to this ID is created.
21     Otherwise, the window is created with the first free ID, that is the lowest integer not already used by a window.
22     </para>
23   </refsection>
24   <refsection>
25     <title>Parameters</title>
26     <variablelist>
27       <varlistentry>
28         <term>num</term>
29         <listitem>
30           <para>ID of the window to create. If not specified, the first free ID is used.</para>
31         </listitem>
32       </varlistentry>
33       <varlistentry>
34         <term>PropertyName{1, ..., N}</term>
35         <listitem>
36           <para>character string name of a property to set. One of the property names listed below.</para>
37         </listitem>
38       </varlistentry>
39       <varlistentry>
40         <term>PropertyValue{1, ..., N}</term>
41         <listitem>
42           <para>scilab object value to give to the corresponding property.</para>
43         </listitem>
44       </varlistentry>
45       <varlistentry>
46         <term>f</term>
47         <listitem>
48           <para>handle of the newly created window.</para>
49         </listitem>
50       </varlistentry>
51     </variablelist>
52   </refsection>
53   <refsection>
54     <title>Properties</title>
55     <variablelist>
56       <varlistentry>
57         <term>BackgroundColor</term>
58         <listitem>
59           <para>[1,3] real vector or string Background color of the figure. A
60         color is specified as Red, Green and Blue values. Those values are
61         real in [0,1]. The color can be given as a real vector, ie [R,G,B] or
62         a string where each value is separated by a "|", ie "R|G|B"</para>
63         </listitem>
64       </varlistentry>
65       <varlistentry>
66         <term>Figure_name</term>
67         <listitem>
68           <para>character string, allows to set the title of the figure.
69            </para>
70         </listitem>
71       </varlistentry>
72       <varlistentry>
73         <term>ForegroundColor</term>
74         <listitem>
75           <para>[1,3] real vector or string Foreground color of the figure. A
76         color is specified as Red, Green and Blue values. Those values are
77         real in [0,1]. The color can be given as a real vector, ie [R,G,B] or
78         a string where each value is separated by a "|", ie "R|G|B"</para>
79         </listitem>
80       </varlistentry>
81       <varlistentry>
82         <term>Position</term>
83         <listitem>
84           <para>allows to control the geometrical aspect of the figure.
85     It is a [1,4] real vector [x y width height] where the letters stand for the x
86     location of the top left corner, the y location of the top left corner, the width and the height of the virtual graphics window
87     (the part of the figure which contains uicontrols and graphics).
88     See the <emphasis role="bold">axes_size</emphasis> property description in <link linkend="figure_properties">figure properties</link> help page.
89     One can also set this property by giving a string where the fields are separated by a "|", ie "x|y|width|height".
90            </para>
91         </listitem>
92       </varlistentry>
93       <varlistentry>
94         <term>Tag</term>
95         <listitem>
96           <para>string this property is generally used to identify the figure. It
97         allows to give it a "name". Mainly used in conjontion with findobj().
98           </para>
99         </listitem>
100       </varlistentry>
101       <varlistentry>
102         <term>Userdata</term>
103         <listitem>
104           <para>this can be used to associate some Scilab objects to a fugure.</para>
105         </listitem>
106       </varlistentry>
107     </variablelist>
108   </refsection>
109   <refsection>
110     <title>Examples</title>
111     <programlisting role="example"><![CDATA[ 
112 // Create figure having figure_id==3
113 h=figure(3);
114 // Add a text uicontrol in figure 3
115 uicontrol(h, "style", "text", ...
116              "string", "This is a figure", ...
117              "position", [50 70 100 100], ...
118              "fontsize",15);
119
120 // Create figure having figure_id==1
121 figure();
122 // Add a text uicontrol in figure 1
123 uicontrol("style", "text", ...
124           "string", "Another figure", ...
125           "position", [50 70 100 100], ...
126           "fontsize", 15);
127
128 // Close current figure (ie figure 1)
129 close();
130 // close figure 3
131 close(h);
132  ]]></programlisting>
133   </refsection>
134   <refsection>
135     <title>See Also</title>
136     <simplelist type="inline">
137       <member>
138         <link linkend="close">close</link>
139       </member>
140       <member>
141         <link linkend="gcf">gcf</link>
142       </member>
143     </simplelist>
144   </refsection>
145   <refsection>
146     <title>Authors</title>
147     <para>Bertrand Guiheneuf</para>
148     <para>V.C.</para>
149   </refsection>
150 </refentry>