[doc] xload() page overhauled 91/20991/3
Samuel GOUGEON [Thu, 30 May 2019 02:28:19 +0000 (04:28 +0200)]
  Update after https://codereview.scilab.org/20125

  New version (PDF): http://bugzilla.scilab.org/attachment.cgi?id=4963

  + sometimes the last loaded object was not set as the current one: fixed

Change-Id: I48bf111c7f285ca4473cc6e07cda99e54c30e64b

scilab/modules/graphics/help/en_US/load_save/xload.xml
scilab/modules/graphics/help/images/xload_70p.png [new file with mode: 0644]
scilab/modules/graphics/help/ja_JP/load_save/xload.xml [deleted file]
scilab/modules/graphics/help/pt_BR/load_save/xload.xml [deleted file]
scilab/modules/graphics/macros/xload.sci
scilab/modules/helptools/etc/images_md5.txt

index e43ea32..2597969 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) ENPC - Jean-Philippe Chancelier
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2019 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * along with this program.
  *
  -->
-<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="xload">
+<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="xload">
     <refnamediv>
         <refname>xload</refname>
-        <refpurpose>load a saved graphics</refpurpose>
+        <refpurpose>
+            displays in a given window some graphical component loaded from a file.
+        </refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
-        <synopsis>xload(file_name,[win_num])</synopsis>
+        <synopsis>
+            xload(file_name)
+            xload(file_name, win_num)
+        </synopsis>
     </refsynopsisdiv>
     <refsection>
         <title>Arguments</title>
             <varlistentry>
                 <term>file_name</term>
                 <listitem>
-                    <para>string, name of the file.</para>
+                    <para>string: name of the binary file.</para>
                 </listitem>
             </varlistentry>
             <varlistentry>
                 <term>win_num</term>
                 <listitem>
-                    <para>integer, the graphics window number. If not given, the current
-                        graphics window is used.
+                    <para>integer: the id of the targetted graphic window. By default,
+                        the current graphics window is used.
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            <literal>xload</literal> reloads the graphics contained in the file
-            <literal>file_name</literal> in the graphics window <literal>win_num</literal>.
+            <literal>xload</literal> restores in the graphics window <literal>win_num</literal>
+            (or the current one) the graphics contained in the binary file <literal>file_name</literal> .
+        </para>
+        <para>
+            All saved <link linkend="uimenu">uimenu</link> or <link linkend="uicontrol">uicontrol</link>
+            are also restored.
+        </para>
+        <para>
+            A loaded figure imposes its own properties, noticeably its colormap and axes_size,
+            only if
+            <itemizedlist>
+                <listitem>
+                    the target window is clear,
+                </listitem>
+                <listitem>
+                    and the forthcoming figure is the first graphical component to be loaded.
+                </listitem>
+            </itemizedlist>
+            Otherwise, the target window keeps its properties.
+        </para>
+        <para>
+            The (last) loaded component and its parent figure or/and axes become the current ones.
         </para>
         <para>
-            Since  Scilab 5.0, all <link linkend="uimenu">uimenu</link> or <link linkend="uicontrol">uicontrol</link> handles are also loaded.
+            <emphasis role="bold">Comparing xload() versus load()</emphasis>:
         </para>
         <para>
-            For files containing graphics, the <literal>load</literal> function can
-            be used instead of <literal>xload</literal>. <literal>xload</literal> does not restore
-            the window number, the window size nor the window dimensions.
+            <table border="1">
+                <tr>
+                    <th></th>
+                    <th>load() behavior</th>
+                    <th>xload() behavior</th>
+                </tr>
+                <tr>
+                    <td>In addition to the rendering of graphics...</td>
+                    <td>the variables in the file are loaded in the environment, including the
+                        ones that are not graphic handles. They may overwrite existing variables
+                        not related to graphics.
+                    </td>
+                    <td>the environment is kept free of any new variables. There is no overwritting
+                        hazard.
+                    </td>
+                </tr>
+                <tr>
+                    <td>The file contains only one graphic, that is a figure.</td>
+                    <td>It is displayed in a new graphic window, whose number n+1 increments the
+                        maximal existing figure's number n.
+                    </td>
+                    <td>It is displayed in the current or given graphic window.</td>
+                </tr>
+                <tr>
+                    <td>The file contains only one graphics, that is a component of a figure.</td>
+                    <td>It is displayed in a new graphic window #n+1.</td>
+                    <td>It is merged in the current or given graphic window.</td>
+                </tr>
+                <tr>
+                    <td>
+                        The file contains several graphic figures or/and figures components.
+                    </td>
+                    <td>
+                        They are all loaded. Each figure is displayed in a new dedicated
+                        graphic window. Other loaded components that are figures children are
+                        displayed in the (last) current figure, according to their loading order.
+                    </td>
+                    <td>
+                        Only the last figure and the separate graphical components following it are
+                        displayed and merged in the current or given graphic window.
+                    </td>
+                </tr>
+            </table>
         </para>
+        <warning>
+            <para>
+                When the file contains several variables being graphic handles or any other
+                variables of any types, the loading order of variables (and so of related
+                graphics) is the <emphasis>alphabetical order of the variables names</emphasis>.
+                So, it is usually NOT the order the variables (among which the handles) have
+                been listed in the save() statement!
+            </para>
+            <para>
+                This may yield some unexpected results when several saved graphic handles
+                have the same parent figure or are parent or children of each others, but with
+                variables names whose alphabetical order does not match the order of their
+                graphical hierarchy.
+            </para>
+        </warning>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-t=0:0.01:10;
-subplot(211),plot2d(t,sin(t))
-subplot(212),plot2d(t,sin(3*t))
-xsave(TMPDIR + "/foo.scg", gcf())
-clf()
-xload(TMPDIR + "/foo.scg")
+path = TMPDIR+"/xload/";
+mkdir(path);
+graypolar = path + "graypolar.dat";
+plotAxes  = path + "plotAxes.scg";
+clf reset
+subplot(1,2,1), plot3d()
+plotA = gca();
+save(plotAxes, "plotA"); // does not record the actual colormap used
+                         // that is a figure's property, not an Axes one.
+f = scf();
+graypolarplot();        // imposes its colormap <> the default colormap
+gca().axes_bounds = [0.5 0 0.5 1];  // puts the grayplot as subplot(1,2,2)
+gcf().axes_size = [700 350];
+save(graypolar, "f");   // records the actual colormap, as a figure's property
 
-a=gca();
-curve=a.children.children; //handle on the curve
-save(TMPDIR + "/foo.scg", "curve")
-delete(curve)
-load(TMPDIR + "/foo.scg")
+xdel(winsid())
+xload(graypolar, 7) // The first restored element is a figure in a clean window
+                    // => It imposes its colormap & axes_size.. to the figure
+xload(plotAxes)
+
+xload(plotAxes, 5) // => The default colormap is used
+xload(graypolar)   // This loaded figure does not impose its own properties: too late!
+gcf().axes_size = [700 350];
+
+scf(20)
+subplot(1,2,1), plot3d() // => The figure is no longer clear => its properties are now set.
+xload(graypolar)         // This new figure does not impose its properties: too late!
+gcf().axes_size = [700 350];
  ]]></programlisting>
+        <para/>
+        <inlinemediaobject>
+            <imageobject>
+                <imagedata fileref="../../images/xload_70p.png"/>
+            </imageobject>
+        </inlinemediaobject>
     </refsection>
+
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
-                <link linkend="xsave">xsave</link>
+                <link linkend="load">load</link>
             </member>
             <member>
-                <link linkend="load">load</link>
+                <link linkend="copy">copy</link>
+            </member>
+            <member>
+                <link linkend="xsave">xsave</link>
             </member>
             <member>
                 <link linkend="save">save</link>
             </member>
         </simplelist>
     </refsection>
+
+    <refsection role="history">
+        <title>History</title>
+        <revhistory>
+            <revision>
+                <revnumber>5.0</revnumber>
+                <revdescription>
+                    Saved uimenus and uicontrols are now restored as well.
+                </revdescription>
+            </revision>
+        </revhistory>
+    </refsection>
 </refentry>
diff --git a/scilab/modules/graphics/help/images/xload_70p.png b/scilab/modules/graphics/help/images/xload_70p.png
new file mode 100644 (file)
index 0000000..a84a59e
Binary files /dev/null and b/scilab/modules/graphics/help/images/xload_70p.png differ
diff --git a/scilab/modules/graphics/help/ja_JP/load_save/xload.xml b/scilab/modules/graphics/help/ja_JP/load_save/xload.xml
deleted file mode 100644 (file)
index 286e0fe..0000000
+++ /dev/null
@@ -1,184 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!--
-
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-
- * Copyright (C) ENPC - Jean-Philippe Chancelier
-
- *
-
-
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
-
- *
-
- -->
-
-<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="ja" xml:id="xload">
-
-    <refnamediv>
-
-        <refname>xload</refname>
-
-        <refpurpose>保存されたグラフィックをロードする</refpurpose>
-
-    </refnamediv>
-
-    <refsynopsisdiv>
-
-        <title>呼び出し手順</title>
-
-        <synopsis>xload(file_name,[win_num])</synopsis>
-
-    </refsynopsisdiv>
-
-    <refsection>
-
-        <title>パラメータ</title>
-
-        <variablelist>
-
-            <varlistentry>
-
-                <term>file_name</term>
-
-                <listitem>
-
-                    <para>文字列, ファイル名.</para>
-
-                </listitem>
-
-            </varlistentry>
-
-            <varlistentry>
-
-                <term>win_num</term>
-
-                <listitem>
-
-                    <para>整数, グラフィックウインドウの番号. 指定されない場合,
-
-                        カレントのグラフィックウインドウが使用されます.
-
-                    </para>
-
-                </listitem>
-
-            </varlistentry>
-
-        </variablelist>
-
-    </refsection>
-
-    <refsection>
-
-        <title>説明</title>
-
-        <para>
-
-            <literal>xload</literal> はファイル <literal>file_name</literal>
-
-            に含まれるグラフィックを
-
-            グラフィックウインドウ <literal>win_num</literal>に
-
-            リロードします.
-
-        </para>
-
-        <para>
-
-            Scilab 5.0以降, 全ての <link linkend="uimenu">uimenu</link>または
-
-            <link linkend="uicontrol">uicontrol</link>ハンドルも
-
-            ロードされます.
-
-        </para>
-
-        <para>
-
-            グラフィックを含むファイルに関して,<literal>load</literal>
-
-            関数は<literal>xload</literal>の代わりに使用されます.
-
-            <literal>xload</literal> はウインドウ番号,
-
-            ウインドウの大きさ,ウインドウの次元を回復しません.
-
-        </para>
-
-    </refsection>
-
-    <refsection>
-
-        <title>例</title>
-
-        <programlisting role="example"><![CDATA[
-
-t=0:0.01:10;
-
-subplot(211),plot2d(t,sin(t))
-
-subplot(212),plot2d(t,sin(3*t))
-
-xsave(TMPDIR + "/foo.scg", gcf())
-
-clf()
-
-xload(TMPDIR + "/foo.scg")
-
-
-
-a=gca();
-
-curve=a.children.children; //handle on the curve
-
-save(TMPDIR + "/foo.scg", "curve")
-
-delete(curve)
-
-load(TMPDIR + "/foo.scg")
-
- ]]></programlisting>
-
-    </refsection>
-
-    <refsection role="see also">
-
-        <title>参照</title>
-
-        <simplelist type="inline">
-
-            <member>
-
-                <link linkend="xsave">xsave</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="load">load</link>
-
-            </member>
-
-            <member>
-
-                <link linkend="save">save</link>
-
-            </member>
-
-        </simplelist>
-
-    </refsection>
-
-</refentry>
-
diff --git a/scilab/modules/graphics/help/pt_BR/load_save/xload.xml b/scilab/modules/graphics/help/pt_BR/load_save/xload.xml
deleted file mode 100644 (file)
index 650e039..0000000
+++ /dev/null
@@ -1,91 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) ENPC - Jean-Philippe Chancelier
- *
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="xload" xml:lang="pt">
-    <refnamediv>
-        <refname>xload</refname>
-        <refpurpose>carrega gráficos salvos</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Seqüência de Chamamento</title>
-        <synopsis>xload(file_name,[win_num])</synopsis>
-    </refsynopsisdiv>
-    <refsection>
-        <title>Parâmetros</title>
-        <variablelist>
-            <varlistentry>
-                <term>file_name</term>
-                <listitem>
-                    <para>string, o nome do arquivo</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>win_num</term>
-                <listitem>
-                    <para>inteiro, o número da janela de gráficos. Se não for fornecido,
-                        a janela de gráficos corrente é utilizada
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection>
-        <title>Descrição</title>
-        <para>
-            <literal>xload</literal> recarrega os gráficos contidos no arquivo
-            <literal>file_name</literal> na janela de gráficos
-            <literal>win_num</literal>.
-        </para>
-        <para>
-            Desde o Scilab 5.0, todos os manipuladores <link linkend="uimenu">uimenu</link> ou <link linkend="uicontrol">uicontrol</link> são também carregados.
-        </para>
-        <para>Para arquivos contendo novos gráficos, a função
-            <literal>load</literal> pode ser utilizada ao invés de
-            <literal>xload</literal>. <literal>xload</literal> não recupera o número
-            da janela, nem seu tamanho ou dimensões.
-        </para>
-    </refsection>
-    <refsection>
-        <title>Exemplos</title>
-        <programlisting role="example"><![CDATA[
-t=0:0.01:10;
-subplot(211),plot2d(t,sin(t))
-subplot(212),plot2d(t,sin(3*t))
-xsave(TMPDIR + "/foo.scg", gcf())
-clf()
-xload(TMPDIR + "/foo.scg")
-
-a=gca();
-curve=a.children.children; //handle on the curve
-save(TMPDIR + "/foo.scg", "curve")
-delete(curve)
-load(TMPDIR + "/foo.scg")
- ]]></programlisting>
-    </refsection>
-    <refsection role="see also">
-        <title>Ver Também</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="xsave">xsave</link>
-            </member>
-            <member>
-                <link linkend="load">load</link>
-            </member>
-            <member>
-                <link linkend="save">save</link>
-            </member>
-        </simplelist>
-    </refsection>
-</refentry>
index 1b77c03..89e7825 100644 (file)
@@ -91,6 +91,7 @@ function xload(fil,num)
     end
     %__f__.visible="on"
     %__f__.immediate_drawing="on";
+    scf(%__f__);
 endfunction
 
 function xloadFigure(fil)
index 5969e72..dc18f73 100644 (file)
@@ -302,7 +302,7 @@ _LaTeX_floor.xml_ru_RU_1.png=1d5ba78bbbafd3226f371146bc348363
 _LaTeX_grand.xml_1.png=dd59088e24bed7a6af5a6ccd16e58616
 _LaTeX_grand.xml_2.png=4065036eed5d60beaa7f246c013cbff0
 _LaTeX_hank.xml_1.png=fc6c604bc8c86af20a8f0673047332db
-_LaTeX_histc.xml_1.png=f1c5acc5939d55326dfab4af50e13f97
+_LaTeX_histc.xml_1.png=1db429279b06e231c9795e1e83601db1
 _LaTeX_histplot.xml_1.png=f1c5acc5939d55326dfab4af50e13f97
 _LaTeX_implicitplot.xml_1.png=43ca5ad9e1f094a31392f860ef481e5c
 _LaTeX_interp.xml_1.png=b99c07a3557a83033fdeedd84352b082