[doc] xload() page overhauled
[scilab.git] / scilab / modules / graphics / help / en_US / load_save / xload.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) ENPC - Jean-Philippe Chancelier
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2019 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="xload">
20     <refnamediv>
21         <refname>xload</refname>
22         <refpurpose>
23             displays in a given window some graphical component loaded from a file.
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             xload(file_name)
30             xload(file_name, win_num)
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>file_name</term>
38                 <listitem>
39                     <para>string: name of the binary file.</para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>win_num</term>
44                 <listitem>
45                     <para>integer: the id of the targetted graphic window. By default,
46                         the current graphics window is used.
47                     </para>
48                 </listitem>
49             </varlistentry>
50         </variablelist>
51     </refsection>
52     <refsection>
53         <title>Description</title>
54         <para>
55             <literal>xload</literal> restores in the graphics window <literal>win_num</literal>
56             (or the current one) the graphics contained in the binary file <literal>file_name</literal> .
57         </para>
58         <para>
59             All saved <link linkend="uimenu">uimenu</link> or <link linkend="uicontrol">uicontrol</link>
60             are also restored.
61         </para>
62         <para>
63             A loaded figure imposes its own properties, noticeably its colormap and axes_size,
64             only if
65             <itemizedlist>
66                 <listitem>
67                     the target window is clear,
68                 </listitem>
69                 <listitem>
70                     and the forthcoming figure is the first graphical component to be loaded.
71                 </listitem>
72             </itemizedlist>
73             Otherwise, the target window keeps its properties.
74         </para>
75         <para>
76             The (last) loaded component and its parent figure or/and axes become the current ones.
77         </para>
78         <para>
79             <emphasis role="bold">Comparing xload() versus load()</emphasis>:
80         </para>
81         <para>
82             <table border="1">
83                 <tr>
84                     <th></th>
85                     <th>load() behavior</th>
86                     <th>xload() behavior</th>
87                 </tr>
88                 <tr>
89                     <td>In addition to the rendering of graphics...</td>
90                     <td>the variables in the file are loaded in the environment, including the
91                         ones that are not graphic handles. They may overwrite existing variables
92                         not related to graphics.
93                     </td>
94                     <td>the environment is kept free of any new variables. There is no overwritting
95                         hazard.
96                     </td>
97                 </tr>
98                 <tr>
99                     <td>The file contains only one graphic, that is a figure.</td>
100                     <td>It is displayed in a new graphic window, whose number n+1 increments the
101                         maximal existing figure's number n.
102                     </td>
103                     <td>It is displayed in the current or given graphic window.</td>
104                 </tr>
105                 <tr>
106                     <td>The file contains only one graphics, that is a component of a figure.</td>
107                     <td>It is displayed in a new graphic window #n+1.</td>
108                     <td>It is merged in the current or given graphic window.</td>
109                 </tr>
110                 <tr>
111                     <td>
112                         The file contains several graphic figures or/and figures components.
113                     </td>
114                     <td>
115                         They are all loaded. Each figure is displayed in a new dedicated
116                         graphic window. Other loaded components that are figures children are
117                         displayed in the (last) current figure, according to their loading order.
118                     </td>
119                     <td>
120                         Only the last figure and the separate graphical components following it are
121                         displayed and merged in the current or given graphic window.
122                     </td>
123                 </tr>
124             </table>
125         </para>
126         <warning>
127             <para>
128                 When the file contains several variables being graphic handles or any other
129                 variables of any types, the loading order of variables (and so of related
130                 graphics) is the <emphasis>alphabetical order of the variables names</emphasis>.
131                 So, it is usually NOT the order the variables (among which the handles) have
132                 been listed in the save() statement!
133             </para>
134             <para>
135                 This may yield some unexpected results when several saved graphic handles
136                 have the same parent figure or are parent or children of each others, but with
137                 variables names whose alphabetical order does not match the order of their
138                 graphical hierarchy.
139             </para>
140         </warning>
141     </refsection>
142     <refsection>
143         <title>Examples</title>
144         <programlisting role="example"><![CDATA[
145 path = TMPDIR+"/xload/";
146 mkdir(path);
147 graypolar = path + "graypolar.dat";
148 plotAxes  = path + "plotAxes.scg";
149 clf reset
150 subplot(1,2,1), plot3d()
151 plotA = gca();
152 save(plotAxes, "plotA"); // does not record the actual colormap used
153                          // that is a figure's property, not an Axes one.
154 f = scf();
155 graypolarplot();        // imposes its colormap <> the default colormap
156 gca().axes_bounds = [0.5 0 0.5 1];  // puts the grayplot as subplot(1,2,2)
157 gcf().axes_size = [700 350];
158 save(graypolar, "f");   // records the actual colormap, as a figure's property
159
160 xdel(winsid())
161 xload(graypolar, 7) // The first restored element is a figure in a clean window
162                     // => It imposes its colormap & axes_size.. to the figure
163 xload(plotAxes)
164
165 xload(plotAxes, 5) // => The default colormap is used
166 xload(graypolar)   // This loaded figure does not impose its own properties: too late!
167 gcf().axes_size = [700 350];
168
169 scf(20)
170 subplot(1,2,1), plot3d() // => The figure is no longer clear => its properties are now set.
171 xload(graypolar)         // This new figure does not impose its properties: too late!
172 gcf().axes_size = [700 350];
173  ]]></programlisting>
174         <para/>
175         <inlinemediaobject>
176             <imageobject>
177                 <imagedata fileref="../../images/xload_70p.png"/>
178             </imageobject>
179         </inlinemediaobject>
180     </refsection>
181
182     <refsection role="see also">
183         <title>See also</title>
184         <simplelist type="inline">
185             <member>
186                 <link linkend="load">load</link>
187             </member>
188             <member>
189                 <link linkend="copy">copy</link>
190             </member>
191             <member>
192                 <link linkend="xsave">xsave</link>
193             </member>
194             <member>
195                 <link linkend="save">save</link>
196             </member>
197         </simplelist>
198     </refsection>
199
200     <refsection role="history">
201         <title>History</title>
202         <revhistory>
203             <revision>
204                 <revnumber>5.0</revnumber>
205                 <revdescription>
206                     Saved uimenus and uicontrols are now restored as well.
207                 </revdescription>
208             </revision>
209         </revhistory>
210     </refsection>
211 </refentry>