* Bugs 7724 13766 fixed [doc]: figure_properties/figure fixed/improved
[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"
3           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
4           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
5           xml:lang="en" xml:id="figure">
6     <refnamediv>
7         <refname>figure</refname>
8         <refpurpose>create a figure</refpurpose>
9     </refnamediv>
10     <refsynopsisdiv>
11         <title>Syntax</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 role="arguments">
25         <title>Arguments</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>
37                         character string: Name of a property to set,
38                         among <link linkend="figure_properties">all existing ones</link>.
39                     </para>
40                     <warning>
41                         <itemizedlist>
42                             <listitem>
43                                 <literal>'dockable'</literal>, <literal>'toolbar'</literal> and
44                                 <literal>'menubar'</literal> properties can be set only at figure's
45                                 creation.
46                             </listitem>
47                             <listitem>
48                                 <literal>'resizefcn'</literal>: when it is set at figure's creation,
49                                 the callback is first executed while building the initial figure.
50                                 Hence it must already be defined and callable.
51                             </listitem>
52                         </itemizedlist>
53                     </warning>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>PropertyValue{1, ..., N}</term>
58                 <listitem>
59                     <para>scilab object value to give to the corresponding property.</para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>f</term>
64                 <listitem>
65                     <para>handle of the newly created window.</para>
66                 </listitem>
67             </varlistentry>
68         </variablelist>
69     </refsection>
70     <refsection>
71         <title>Examples</title>
72         <programlisting role="example"><![CDATA[
73 // Create figure having figure_id==3
74 h=figure(3);
75 // Add a text uicontrol in figure 3
76 uicontrol(h, "style", "text", ...
77              "string", "This is a figure", ...
78              "position", [50 70 100 100], ...
79              "fontsize",15);
80
81 // Create figure having figure_id==1
82 figure();
83 // Add a text uicontrol in figure 1
84 uicontrol("style", "text", ...
85           "string", "Another figure", ...
86           "position", [50 70 100 100], ...
87           "fontsize", 15);
88
89 // Close current figure (ie figure 1)
90 close();
91 // close figure 3
92 close(h);
93  ]]></programlisting>
94     </refsection>
95     <refsection role="see also">
96         <title>See also</title>
97         <simplelist type="inline">
98             <member>
99                 <link linkend="scf">scf</link>
100             </member>
101             <member>
102                 <link linkend="gcf">gcf</link>
103             </member>
104             <member>
105                 <link linkend="createWindow">createWindow</link>
106             </member>
107             <member>
108                 <link linkend="figure_properties">figure_properties</link>
109             </member>
110             <member>
111                 <link linkend="close">close</link>
112             </member>
113         </simplelist>
114     </refsection>
115 </refentry>