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