Revision of help pages for Compound properties and graphics entities (en_US).
[scilab.git] / scilab / modules / graphics / help / en_US / graphics_entities.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) INRIA
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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="graphics_entities">
14     <refnamediv>
15         <refname>Graphics Entities</refname>
16         <refpurpose>
17             description of the graphics entities data structures
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>Description</title>
22         <para>
23             In Scilab, graphics window and the drawing it contains are
24             represented by hierarchical entities. The hierarchy top level is the
25             <literal>Figure</literal>. Each <literal>Figure</literal> defines at
26             least one child of type <literal>Axes</literal>. Each
27             <literal>Axes</literal> entity contains a set of leaf
28             entities which are the basic graphics objects like
29             <literal>Polylines</literal>, <literal>Rectangles</literal>,
30             <literal>Arcs</literal>, <literal>Segs</literal>,... It can also
31             contain an <literal>Compound</literal> type which is recursive
32             set of entities. The main interest of the graphic mode is to make
33             property change easier. This graphics' mode provides a set of
34             high-level graphing routines (see <link linkend="set">set</link>,
35             <link linkend="get">get</link>) used to control objects' properties
36             such as data, coordinates and scaling, color and appearances without
37             requiring to replay the initial graphics commands.
38         </para>
39         <para>
40             Graphics entities are associated to Scilab variables of type
41             <literal>handle</literal>. The handle is an unique identifier which
42             is associated to each instance of a created graphical entity. Using
43             this handle, it will be possible to reach entities' properties
44             through <function>set</function> and <function>get</function>
45             routines. The handles are also used to manipulate graphics objects, to move them, to make copies or delete them.
46         </para>
47         <para/>
48         <variablelist>
49             <varlistentry>
50                 <term>Figure: </term>
51                 <listitem>
52                     <para>
53                         The figure entity is the top level of the graphics
54                         entities hierarchy. This entity defines the parameters
55                         for the figure itself as well as the parameters' default
56                         values for the children creation. The figure children
57                         are the <literal>Axes</literal> entities.
58                     </para>
59                     <para>
60                         The handle on the current figure (the figure used where
61                         the drawing are sent) may be got using
62                         <code>get("current_figure")</code> and it may be set
63                         using <code>set("current_figure",h)</code>, where
64                         <literal>h</literal> is either a handle on a figure or a
65                         <literal>figure_id</literal> in this last case if the
66                         figure does not already exists, it is created.
67                     </para>
68                     <para>
69                         See <link linkend="figure_properties">figure properties</link> for details.
70                     </para>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>Axes: </term>
75                 <listitem>
76                     <para>
77                         The <literal>Axes</literal> entity is the second level
78                         of the graphics entities hierarchy. This entity defines
79                         the parameters for the change of coordinates and the
80                         axes drawing as well as the parameters' default values
81                         for its children creation. See <link linkend="axes_properties">axes properties</link> for
82                         details. The handle on the current <literal>Axes</literal> may be got using
83                         <code>get("current_axes")</code>.
84                     </para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>Compound: </term>
89                 <listitem>
90                     <para>
91                         The <literal>Compound</literal> entity is just a vector
92                         of children and with a single property (visibility
93                         property). It is used to glue a set of entities
94                         together.
95                     </para>
96                     <para>
97                         See <link linkend="glue">glue</link>, <link linkend="unglue">unglue</link> and
98                         <link linkend="Compound_properties">Compound properties</link> functions.
99                     </para>
100                 </listitem>
101             </varlistentry>
102             <varlistentry>
103                 <term>Axis: </term>
104                 <listitem>
105                     <para>
106                         The <literal>Axis</literal> entity is a leaf of the
107                         graphics entities hierarchy. This entity defines the
108                         parameters for axis scaling and appearance.
109                     </para>
110                     <para>
111                         See <link linkend="axis_properties">axis properties</link> for details.
112                     </para>
113                 </listitem>
114             </varlistentry>
115             <varlistentry>
116                 <term>Polyline: </term>
117                 <listitem>
118                     <para>
119                         The <literal>Polyline</literal> entity is a leaf of the
120                         graphics entities hierarchy. It defines 2D and 3D
121                         polylines and polylines extensions drawing properties.
122                     </para>
123                     <para>
124                         See <link linkend="polyline_properties">polyline properties</link> for details.
125                     </para>
126                 </listitem>
127             </varlistentry>
128             <varlistentry>
129                 <term>Arc: </term>
130                 <listitem>
131                     <para>
132                         The <literal>Arc</literal> entity is a leaf of the
133                         graphics entities hierarchy. This entity defines the
134                         parameters for ellipses and part of ellipses.
135                     </para>
136                     <para>
137                         See <link linkend="arc_properties">arc properties</link>
138                         for details.
139                     </para>
140                 </listitem>
141             </varlistentry>
142             <varlistentry>
143                 <term>Rectangle: </term>
144                 <listitem>
145                     <para>
146                         The <literal>Rectangle</literal> entity is a leaf of the
147                         graphics entities hierarchy. This entity defines the
148                         parameters for rectangles and filled rectangles.
149                     </para>
150                     <para>
151                         See <link linkend="rectangle_properties">rectangle properties</link> for details.
152                     </para>
153                 </listitem>
154             </varlistentry>
155             <varlistentry>
156                 <term>Surface: </term>
157                 <listitem>
158                     <para>
159                         The <literal>Surface</literal> entity is a leaf of the
160                         graphics entities hierarchy. It has subtypes
161                         <literal>Fac3d</literal> or <literal>Plot3d</literal>.
162                         This entity defines the parameters for 3d surface plots.
163                     </para>
164                     <para>
165                         See <link linkend="surface_properties">surface properties</link> for details.
166                     </para>
167                 </listitem>
168             </varlistentry>
169             <varlistentry>
170                 <term>Fec: </term>
171                 <listitem>
172                     <para>
173                         The <literal>Fec</literal> entity is a leaf of the
174                         graphics entities  hierarchy. It represents 2D finite
175                         elements plots.
176                     </para>
177                     <para>
178                         See <link linkend="fec_properties">fec properties</link>
179                         for details.
180                     </para>
181                 </listitem>
182             </varlistentry>
183             <varlistentry>
184                 <term>Grayplot: </term>
185                 <listitem>
186                     <para>
187                         The <literal>Grayplot</literal> entity is a leaf of the
188                         graphics entities hierarchy. It represents 2D plots of
189                         surface using colors and images.
190                     </para>
191                     <para>
192                         See <link linkend="grayplot_properties">grayplot properties</link> for details.
193                     </para>
194                 </listitem>
195             </varlistentry>
196             <varlistentry>
197                 <term>Matplot: </term>
198                 <listitem>
199                     <para>
200                         The <literal>Matplot</literal> entity is a leaf of the
201                         graphics entities hierarchy. It represents 2D plots
202                         using integer matrices.
203                     </para>
204                     <para>
205                         See <link linkend="Matplot_properties">Matplot properties</link> for details.
206                     </para>
207                 </listitem>
208             </varlistentry>
209             <varlistentry>
210                 <term>Segs: </term>
211                 <listitem>
212                     <para>
213                         The <literal>Segs</literal> entity is a leaf of the
214                         graphics entities hierarchy. This entity defines the
215                         parameters for a set of colored segments or colored
216                         arrows.
217                     </para>
218                     <para>
219                         See <link linkend="segs_properties">segs properties</link> for details.
220                     </para>
221                 </listitem>
222             </varlistentry>
223             <varlistentry>
224                 <term>Champ: </term>
225                 <listitem>
226                     <para>
227                         The <literal>Champ</literal> entity is a leaf of the
228                         graphics entities hierarchy. This entity defines the
229                         parameters for a 2D vector field.
230                     </para>
231                     <para>
232                         See <link linkend="champ_properties">champ properties</link> for details.
233                     </para>
234                 </listitem>
235             </varlistentry>
236             <varlistentry>
237                 <term>Text: </term>
238                 <listitem>
239                     <para>
240                         The <literal>Text</literal> entity is a leaf of the
241                         graphics entities hierarchy. This entity defines the
242                         parameters for string drawing.
243                     </para>
244                     <para>
245                         See <link linkend="text_properties">text properties</link> for details.
246                     </para>
247                 </listitem>
248             </varlistentry>
249             <varlistentry>
250                 <term>Label: </term>
251                 <listitem>
252                     <para>
253                         The <literal>Label</literal> entity is a child of the
254                         <literal>Axes</literal> graphics entity. This entity
255                         defines the parameters for the 3 x, y and z labels
256                         and title drawn on a graphics window.
257                     </para>
258                     <para>
259                         See <link linkend="label_properties">Label entity properties</link> for details.
260                     </para>
261                 </listitem>
262             </varlistentry>
263             <varlistentry>
264                 <term>Legend: </term>
265                 <listitem>
266                     <para>
267                         The <literal>Legend</literal> entity is a leaf of the
268                         graphics entities hierarchy. This entity defines the
269                         parameters for legends drawn below
270                         <literal>plot2dx</literal> graphs. This entity requires
271                         further developments.
272                     </para>
273                     <para>
274                         See <link linkend="legend_properties">Legend entity properties</link> for details.
275                     </para>
276                 </listitem>
277             </varlistentry>
278         </variablelist>
279     </refsection>
280     <refsection>
281         <title>Examples</title>
282         <programlisting role="example"><![CDATA[ 
283 //Play this example line per line
284
285 scf() //create a figure in entity mode
286
287 //get the handle on the Figure entity and display its properties
288 f=get("current_figure") 
289 a=f.children // the handle on the Axes child
290 x=(1:10)';  plot2d(x,[x.^2 x.^1.5])
291 e=a.children //Compound of 2 polylines
292
293 p1=e.children(1) //the last drawn polyline properties
294 p1.foreground=5;  // change the polyline color
295 e.children.thickness=5; // change the thickness of the two polylines
296
297 delete(e.children(2))
298
299 move(e.children,[0,30]) //translate the polyline
300
301 a.axes_bounds=[0 0 0.5 0.5]; 
302
303 subplot(222) //create a new Axes entity
304 plot(1:10);
305 a1=f.children(1); //get its handle
306 copy(e.children,a1); //copy the polyline of the first plot in the new Axes
307 a1.data_bounds=[1 0;10 100]; //change the Axes bounds  
308
309 set("current_figure",10) //create a new figure with figure_id=10
310 plot3d() //the drawing are sent to figure 10
311 set("current_figure",f) //make the previous figure the current one
312 plot2d(x,x^3)  //the drawing are sent to the initial figure
313  ]]></programlisting>
314     </refsection>
315     <refsection role="see also">
316         <title>See Also</title>
317         <simplelist type="inline">
318             <member>
319                 <link linkend="set">set</link>
320             </member>
321             <member>
322                 <link linkend="get">get</link>
323             </member>
324             <member>
325                 <link linkend="move">move</link>
326             </member>
327             <member>
328                 <link linkend="draw">draw</link>
329             </member>
330             <member>
331                 <link linkend="delete">delete</link>
332             </member>
333             <member>
334                 <link linkend="object_editor">object editor</link>
335             </member>
336             <member>
337                 <link linkend="plot">plot</link>
338             </member>
339             <member>
340                 <link linkend="surf">surf</link>
341             </member>
342         </simplelist>
343     </refsection>
344 </refentry>