* Bug 16333: tree_show(xcos_block) crashed
[scilab.git] / scilab / modules / data_structures / help / en_US / tree_show.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) 2008 - INRIA
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="tree_show">
20     <refnamediv>
21         <refname>tree_show</refname>
22         <refpurpose>
23             Displays a tree view of a list, tlist, mlist, cell or structure array, Xcos diagram or block
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>
29             tree_show(x)
30             tree_show(x, rootTitle)
31             tree_show(x, rootTitle, styles)
32             tree_show(x, rootTitle, styles, arrayByFields)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>x</term>
40                 <listitem>
41                     <para>
42                     Container to display. Supported containers: list, mlist, tlist, array of cells,
43                     array of structures, identifier of an Xcos diagram or block.
44                     Other containers may be nested in <varname>x</varname>.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>rootTitle</term>
50                 <listitem>
51                     <para>
52                         Single string: explicit label of the tree's root, for instance the name of
53                         the <varname>x</varname> variable in the calling environment. Default = "".
54                     </para>
55                     <note>
56                         HTML.4 styling tags can be used to change the style of the root's title.
57                         Example: "<literal>&lt;html>&lt;font color="red">&lt;b>The title&lt;/b></literal>"
58                         will display <emphasis>The title</emphasis> in bold red.
59                     </note>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>styles</term>
64                 <listitem>
65                     <para>
66                         Single string = HTML.4 styling tag, including the "$" character that will
67                         be replaced with the address (fields names, lists indices..) of each data.
68                     </para>
69                     <para>
70                         The <varname>styles</varname> option can be used to customize the style
71                         either of addresses, or of related contents, or both. Examples:
72                         <itemizedlist>
73                             <listitem>
74                                 <literal>"&lt;b>$&lt;/b>"</literal> : address in bold, content in
75                                 normal black.
76                             </listitem>
77                             <listitem>
78                                 <literal>"$&lt;i>"</literal> : address in normal black, content
79                                 in italic.
80                             </listitem>
81                             <listitem>
82                                 <literal>"&lt;i>$"</literal> : both address and content in italic.
83                             </listitem>
84                             <listitem>
85                                 <literal>"&lt;font color=''grey''>$&lt;/font>&lt;i>"</literal> :
86                                 address in grey, content in italic.
87                             </listitem>
88                         </itemizedlist>
89                     </para>
90                     <para>
91                         Default =
92                         <literal>"&lt;font color=""blue"">$&lt;/font>"</literal>
93                         (address in blue, content in black).
94                     </para>
95                     <para>
96                         Setting <literal>""</literal> removes styling.
97                     </para>
98                 </listitem>
99             </varlistentry>
100             <varlistentry>
101                 <term>arrayByFields</term>
102                 <listitem>
103                     <para>
104                         Single boolean, used only for arrays of structures:
105                         <table>
106                             <tr><th>%T :</th>
107                                 <td>For each field of the struct, the array of its values is displayed.
108                                 </td>
109                             </tr>
110                             <tr><th>%F :</th>
111                                 <td>
112                                     For each structure of the array, its fields and their values
113                                     are displayed.
114                                 </td>
115                             </tr>
116                         </table>
117                     </para>
118                     <para>
119                         The chosen display mode is used as well for every nested array of structures,
120                         at any depths.
121                     </para>
122                 </listitem>
123             </varlistentry>
124         </variablelist>
125     </refsection>
126     <refsection>
127         <title>Description</title>
128         <para>
129             Creates a window and displays a tree view of the given container.
130         </para>
131         <warning>
132             The window has no handle.
133         </warning>
134     </refsection>
135     <refsection>
136         <title>Examples</title>
137         <para>
138             <emphasis role="bold">list(), including a cells array</emphasis> :
139         </para>
140         <table>
141             <tr>
142                 <td>
143                     <programlisting role="example"><![CDATA[
144             films = struct("Title", "A.I. Artificial Intelligence",..
145                            "Year", 2001, ..
146                            "Director", "Steven Spielberg", ..
147                            "Duration", 140);
148             L = list([%t %f %f],                ..
149                      $:-1:3,                    ..
150                      int8([1 2 3 ; 4 5 6]),     ..
151                      [-%inf, -1, 0, %i, 7.1, 3.3e20, %inf, %nan], ..
152                      sparse([0 1 2; 3 0 4]),    ..
153                      ["This" "is" "some" "text"], ..
154                      ,              ..
155                      sin,           ..
156                      logspace,      ..
157                      iolib,         ..
158                      {%pi, "abcd" ;
159                       list(,)(1),(%i-%s)^3},    ..
160                       {},           ..
161                      films);
162             tree_show(L)
163              ]]></programlisting>
164                 </td>
165                 <td>
166                     <inlinemediaobject>
167                         <imageobject>
168                             <imagedata fileref="../images/tree_show_list.png"/>
169                         </imageobject>
170                     </inlinemediaobject>
171                 </td>
172             </tr>
173         </table>
174
175         <para>
176             <emphasis role="bold">
177                 Using the <emphasis>rootTitle</emphasis> and <emphasis>styles</emphasis> options
178             </emphasis> :
179         </para>
180         <programlisting role="example"><![CDATA[
181 // Data to display:
182 clear films
183 films(1) = struct("Title", "A.I. Artificial Intelligence",..
184                   "Year", 2001, ..
185                   "Director", "Steven Spielberg", ..
186                   "Duration", 140);
187 films(2,2) = struct("Title", "I, robot", ..
188                     "Year", 2004, ..
189                     "Director", "Alex Proyas", ..
190                     "Duration", 120);
191
192 // Styling both the addresses and the contents:
193 mainTitle = "<html><b>Films (A)</b>";
194 tree_show(films, mainTitle , "<font color=""red"">$</font><i>");
195
196 // Styling only the contents:
197 mainTitle = "<html><b>Films (B)</b>";
198 tree_show(films([1 4]), mainTitle, "$<font color=""green"">", %t);
199      ]]></programlisting>
200         <para/>
201         <inlinemediaobject>
202             <imageobject>
203                 <imagedata fileref="../images/tree_show_styling.png"/>
204             </imageobject>
205         </inlinemediaobject>
206
207         <para>
208             <emphasis role="bold">Array of structures</emphasis> :
209         </para>
210         <programlisting role="example"><![CDATA[
211 clear films
212 films(1) = struct("Title", "A.I. Artificial Intelligence",..
213               "Year", 2001, ..
214               "Director", "Steven Spielberg", ..
215               "Duration", 140);
216 films(2) = struct("Title", "I, robot", ..
217               "Year", 2004, ..
218               "Director", "Alex Proyas", ..
219               "Duration", 120);
220 films(1,2) = struct("Title", "Gravity", ..
221                 "Year", 2013, ..
222                 "Director", "Alfonso CuarĂ³n", ..
223                 "Duration", 100);
224 films(2,2) = struct("Title", "2001: A space odyssey", ..
225                 "Year", 1968, ..
226                 "Director", "Stanley Kubrick", ..
227                 "Duration", 141);
228
229 tree_show(films(:),"Films (I)");
230 tree_show(films   ,"Films (II)");
231 tree_show(films(:),"Films (III)", , %t);
232 tree_show(films   ,"Films (IV)" , , %t);
233      ]]></programlisting>
234         <screen><![CDATA[
235 2x2 struct array with fields:
236    Title
237    Director
238    Year
239    Duration
240 ]]></screen>
241         <inlinemediaobject>
242             <imageobject>
243                 <imagedata fileref="../images/tree_show_2x2.png"/>
244             </imageobject>
245         </inlinemediaobject>
246         <para>
247             <emphasis role="bold">With a custom tlist or mlist</emphasis> :
248         </para>
249         <programlisting role="example"><![CDATA[
250 // For a mlist:
251 str = ['a','b','c','d','e','f','g','h'];
252 n = matrix(str, [2,2,2]);
253 v = matrix(1:8, [2,2,2]);
254 Mm = mlist(['V','name','value'],n,v);
255 tree_show(Mm);
256
257 // For a tlist:
258 Mt = tlist(['V','name','value'],['a','b','c'],[1 2 3]);
259 tree_show(Mt);
260      ]]></programlisting>
261         <para/>
262         <para>
263             <emphasis role="bold">For an Xcos diagram or block</emphasis> :
264         </para>
265         <programlisting role="example"><![CDATA[
266 loadXcosLibs();
267
268 filename = SCI+"/modules/xcos/demos/demo_Datatype.xmi";
269 xcosDiag = scicosDiagramToScilab(filename);
270 tree_show(xcosDiag)
271
272 blk = BIGSOM_f("define");
273 tree_show(blk)
274      ]]></programlisting>
275     </refsection>
276
277     <refsection role="see also">
278         <title>See Also</title>
279         <simplelist type="inline">
280             <member>
281                 <link linkend="uiDisplayTree">uiDisplayTree</link>
282             </member>
283             <member>
284                 <link linkend="uiDumpTree">uiDumpTree</link>
285             </member>
286             <member>
287                 <link linkend="prettyprint">prettyprint</link>
288             </member>
289             <member>
290                 <link linkend="editvar">editvar</link>
291             </member>
292             <member>
293                 <link linkend="browsevar">browsevar</link>
294             </member>
295         </simplelist>
296     </refsection>
297
298     <refsection role="history">
299         <title>History</title>
300         <revhistory>
301             <revision>
302                 <revnumber>6.1.0</revnumber>
303                 <revdescription>
304                     <itemizedlist>
305                         <listitem>
306                             rootTitle, styles, and arrayByFields input options added.
307                         </listitem>
308                         <listitem>
309                             Input containers including void elements are now supported.
310                         </listitem>
311                     </itemizedlist>
312                 </revdescription>
313             </revision>
314         </revhistory>
315     </refsection>
316 </refentry>