[doc] xload() page overhauled
[scilab.git] / scilab / modules / graphics / macros / xload.sci
1 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
2 // Copyright (C) INRIA
3 // Copyright (C) 2012 - 2016 - Scilab Enterprises
4 // Copyright (C) 2018 - Samuel GOUGEON
5 //
6 // This file is hereby licensed under the terms of the GNU GPL v2.0,
7 // pursuant to article 5.3.4 of the CeCILL v.2.1.
8 // This file was originally licensed under the terms of the CeCILL v2.1,
9 // and continues to be available under such terms.
10 // For more information, see the COPYING file which you should have received
11 // along with this program.
12
13 function xload(fil,num)
14
15     if and(argn(2)<>[1 2]) then
16         msg = _("%s: Wrong number of input argument(s): %d or %d expected.\n");
17         error(msprintf(msg, "xload", 1, 2));
18     end
19
20     if ~isfile(fil) then
21         error(msprintf(gettext("%s: file %s does not exist.\n"), "xload", fil));
22     end
23
24     targetFigAlreadyExists = %f
25     wins = winsid();
26     cnum = [];          // id of the current figure
27     if  wins~=[]
28         cnum = gcf().figure_id
29     end
30     if  argn(2)==2 then
31         if or(num==wins)
32             targetFigAlreadyExists = %t
33         end
34     else
35         if cnum~=[]
36             num = cnum
37             targetFigAlreadyExists = %t
38         else
39             num = 0
40         end
41     end
42     if ~targetFigAlreadyExists then
43         h = scf(num)
44         uid = h.uid
45         xloadFigure(fil)
46         if gcf().uid~=uid   // load() has opened a new figure
47             xdel(h.figure_id)
48             gcf().figure_id = num
49         end
50         return
51     end
52
53     // The target figure already exists
54     // ================================
55     // The target figure may be empty (only a default axes). In this case,
56     //  - the loaded figure must impose its properties to the existing target.
57     //  - the default axes will have to be deleted
58     %__f__= scf(num);  // target figure
59     // Is the target figure blank?
60     targetFigWasBlank = length(%__f__.children)==1 && %__f__.children.type=="Axes" && ..
61                         length(%__f__.children.children)==0
62     // Loading the source figure
63     xloadFigure(fil)
64     loadedFig = gcf();
65
66     // Copying main source figure properties to the target when required:
67     if targetFigWasBlank
68         props = "auto_resize,viewport,figure_name,info_message,color_map,"+..
69                 "pixel_drawing_mode,anti_aliasing,background,rotation_style,"+..
70                 "event_handler_enable,event_handler,user_data,resizefcn,"+..
71                 "closerequestfcn,resize,toolbar_visible,menubar_visible,"+..
72                 "infobar_visible,layout,layout_options,icon,tag";
73         // uncopied, imposed by the target:
74         // figure_position, figure_size, axes_size, figure_id, immediate_drawing,
75         // visible, toolbar, menubar, dockable, default_axes
76         props = tokens(props,",")';
77         for p = props
78             %__f__(p) = loadedFig(p);
79         end
80     end
81
82     // Copying contents:
83     if loadedFig ~= %__f__ then
84         for kC = size(loadedFig.children, "*"):-1:1
85             copy(loadedFig.children(kC), %__f__); // Copy axes & uicontrols
86         end
87         delete(loadedFig); // Delete it, returned figure will be the one set as current by xload
88     end
89     if targetFigWasBlank then
90         delete(%__f__.children($));
91     end
92     %__f__.visible="on"
93     %__f__.immediate_drawing="on";
94     scf(%__f__);
95 endfunction
96
97 function xloadFigure(fil)
98     try
99         load(fil)
100     catch
101         error(_("xload: Given file is not a graphic one.")) ;
102     end
103 endfunction