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