238537fb86cee8a5f21ca9aa61596a90a8ed9829
[scilab.git] / scilab / modules / graphics / help / en_US / object_editor.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 - Fabrice Leray
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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" 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="object_editor">
17     <refnamediv>
18         <refname>object editor </refname>
19         <refpurpose>
20             description of the graphic object editor capacities
21         </refpurpose>
22     </refnamediv>
23     <refsection>
24         <title>Description</title>
25         <!--para>
26             Scilab graphics allow the user to have interaction with graphics
27             before and after having them drawn. Each graphics window and the
28             drawing it contains are represented by hierarchical entities. The
29             hierarchy top level is the <literal>Figure</literal>. Each
30             <literal>Figure</literal> defines at least one child of type
31             <literal>Axes</literal>. Each <literal>Axes</literal> entity
32             contains a set of leaf entities which are the basic graphics objects
33             like <literal>Polylines</literal>, <literal>Rectangles</literal>,
34             <literal>Arcs</literal>, <literal>Segs</literal>,... It can also
35             contain a <literal>Compound</literal> type which is recursive sets of entities.
36         </para>
37         <para>
38             The main interest of the graphic mode is to make property changes
39             easier. This graphics' mode provides a set of high-level graphing
40             routines (see <link linkend="set">set</link>, <link
41             linkend="get">get</link>) used to control objects'
42             properties such as data, coordinates and scaling, color and
43             appearances without requiring to replay the initial graphics
44             commands.
45         </para>
46         <para>
47             Graphics entities are associated to Scilab variables of type
48             <literal>handle</literal>. The handle is a unique identifier which
49             is associated to each instance of a created graphical entity. Using
50             this handle, it will be possible to reach entities' properties
51             through <function>set</function> and <function>get</function>
52             routines. The handles are also used to manipulate graphics objects,
53             to move them, to make copies or delete them.
54         </para>
55         <para>
56             To complete and use the graphics handle capacity at its maximum, a
57             graphic object editor has been created too. It is a set of Tcl/Tk
58             interfaces available for each kind of graphics objects (see
59             <link linkend="graphics_entities">graphics entities</link> for more
60             details) that can be enabled for each graphic window. To make it
61             work, select the <literal>Edit</literal> menu in the graphic window.
62             Seven graphics editing operations are available :
63         </para-->
64         <para>
65             The graphic Object Editor is a set of visual (GUI) editors, available
66             in the <literal>Edit</literal> menu of graphic windows. They provide graphic editing operations
67             for the different kind of graphics objects (see <link linkend="graphics_entities">graphics entities</link>
68             for more details), including the enabling them, disabling them, and editing their properties,
69             before or after they have been drawn.
70         </para>
71         <para>
72             Internally, each graphic window, and the drawing it contains, are represented by
73             a hierarchy of entities. The hierarchy top level is the <literal>Figure</literal>.
74             Each <literal>Figure</literal> defines at least one child of type <literal>Axes</literal>.
75             Each <literal>Axes</literal> entity contains a set of leaf entities which are the basic graphics
76             objects like <literal>Polylines</literal>, <literal>Rectangles</literal>, <literal>Arcs</literal>, <literal>Segs</literal>,...
77             It can also contain a <literal>Compound</literal> type which is recursive sets of entities.
78             The graphic Object Editor manipulates this hierarchy of entities.
79         </para>
80         <para>
81             In the Scilab language, graphics entities are associated to Scilab variables of type <literal>handle</literal>.
82             The handle is a unique identifier which is associated to each instance of a created graphical entity.
83             Using this handle, it will be possible to reach entities' properties through
84             <function>set</function> and <function>get</function> routines.
85             The handles are also used to manipulate graphics objects, to move them, to make copies or delete them.
86             A set of high-level graphing routines (see <link linkend="set">set</link>, <link
87             linkend="get">get</link>) allow accessing and editing the objects'
88             properties such as data, coordinates and scaling, color and appearances without requiring
89             to replay the initial graphics commands.
90         </para>
91         <para>
92             The graphic Object Editor is implemented using the Tcl/Tk language; it is not available on MacOS,
93             where Tcl/TK is not available.
94         </para>
95         <para>The following editing operations are available in the Object Editor:</para>
96         <para/>
97         <variablelist>
98             <varlistentry>
99                 <term>Select figure as current: </term>
100                 <listitem>
101                     <para>Let this figure be the current one.</para>
102                     <para/>
103                 </listitem>
104             </varlistentry>
105             <varlistentry>
106                 <term>Redraw figure: </term>
107                 <listitem>
108                     <para>Redraw the content of the graphics window.</para>
109                     <para/>
110                 </listitem>
111             </varlistentry>
112             <varlistentry>
113                 <term>Erase figure: </term>
114                 <listitem>
115                     <para>
116                         Erase the content of the graphics window. Its action
117                         corresponds to <function>clf</function> routine.
118                     </para>
119                     <para/>
120                 </listitem>
121             </varlistentry>
122             <varlistentry>
123                 <term>Copy object: </term>
124                 <listitem>
125                     <para>
126                         Using the mouse, it allows the user to select a 2D
127                         object (like a curve, a rectangle...) and put it in the
128                         clipboard. Thus, by a next call to <literal>Paste
129                             object
130                         </literal>
131                         ,the object is copied in the
132                         selected current axes.
133                     </para>
134                     <para/>
135                 </listitem>
136             </varlistentry>
137             <varlistentry>
138                 <term>Paste object: </term>
139                 <listitem>
140                     <para>
141                         Allow the user to paste a previous object put into in
142                         the clipboard inside the selected current axes.
143                     </para>
144                     <para/>
145                 </listitem>
146             </varlistentry>
147             <varlistentry>
148                 <term>Move object: </term>
149                 <listitem>
150                     <para>
151                         Using the mouse, it allows the user to move a 2D object
152                         (like a curve, a rectangle...) inside the selected
153                         current axes.
154                     </para>
155                     <para/>
156                 </listitem>
157             </varlistentry>
158             <varlistentry>
159                 <term>Delete object: </term>
160                 <listitem>
161                     <para>
162                         Using the mouse, it allows the user to pick up a 2D
163                         object (like a curve, a rectangle...) inside the
164                         selected current axes and to delete it instantly.
165                     </para>
166                     <para/>
167                 </listitem>
168             </varlistentry>
169             <varlistentry>
170                 <term>Figure Properties: </term>
171                 <listitem>
172                     <para>
173                         Launch the Tcl/Tk interface for the
174                         <literal>Figure</literal> object applied to the figure
175                         handle of the graphics window.
176                     </para>
177                     <para/>
178                 </listitem>
179             </varlistentry>
180             <varlistentry>
181                 <term>Current Axes Properties: </term>
182                 <listitem>
183                     <para>
184                         Launch the Tcl/Tk interface for the
185                         <literal>Axes</literal> object applied to the current
186                         axes handle of the graphics window.
187                     </para>
188                     <para/>
189                 </listitem>
190             </varlistentry>
191             <varlistentry>
192                 <term>Start Entity Picker: </term>
193                 <listitem>
194                     <para>
195                         Start an event handler on the graphics window to catch
196                         the mouse clicks on graphics objects and launch the
197                         corresponding Tcl/Tk interface. The left mouse-click
198                         allows object edition and the right click performs a
199                         move of the selected object. Note that, for now, this
200                         feature is applied to 2D objects only.
201                     </para>
202                     <para/>
203                 </listitem>
204             </varlistentry>
205             <varlistentry>
206                 <term>Stop Entity Picker: </term>
207                 <listitem>
208                     <para>
209                         Stop the action of the Entity Picker by terminating the
210                         event handler on the graphics window.
211                     </para>
212                     <para/>
213                 </listitem>
214             </varlistentry>
215         </variablelist>
216
217         <para>
218             Once the graphic interface is enabled (using the <literal>Figure Properties</literal> or <literal>Current Axes Properties</literal> options), two main areas appear:
219         </para>
220         <para/>
221         <para/>
222         <variablelist>
223             <varlistentry>
224                 <term>A tree selector: </term>
225                 <listitem>
226                     <para>
227                         Placed on the left side of the graphical editor, a
228                         hierarchical tree selector specifies which object is
229                         currently edited. It can be used to switch from a
230                         graphic object to another provided that they are
231                         in the same graphic window.
232                     </para>
233                 </listitem>
234             </varlistentry>
235         </variablelist>
236         <para>
237             <inlinemediaobject>
238                 <imageobject>
239                     <imagedata fileref="../images/tree.gif"/>
240                 </imageobject>
241             </inlinemediaobject>
242         </para>
243         <para/>
244         <variablelist>
245             <varlistentry>
246                 <term>A notebook: </term>
247                 <listitem>
248                     <para>
249                         The second area represents a notebook composed with
250                         different properties pages (like
251                         <literal>Style</literal>, <literal>Data</literal>,
252                         <literal>Clipping</literal>...) depending on the
253                         selected graphic object. Using this editor, user can
254                         edit more easily the whole properties set of each
255                         graphic object (like through the <function>set</function> and
256                         <function>get</function> routines). Here is an example of the axes' notebook displaying axes properties:
257                     </para>
258                 </listitem>
259             </varlistentry>
260         </variablelist>
261         <para>
262             <inlinemediaobject>
263                 <imageobject>
264                     <imagedata fileref="../images/notebook.gif"/>
265                 </imageobject>
266             </inlinemediaobject>
267         </para>
268         <para/>
269         <para>
270             Furthermore, you can legend/annotate your figure using sample
271             primitives given inside the <literal>Insert</literal> menu in the
272             graphic window. Using the mouse and following the instruction in the message subwindow, you can add a:
273         </para>
274         <para/>
275         <variablelist>
276             <varlistentry>
277                 <term>Line: </term>
278                 <listitem>
279                     <para>
280                         Draw a line between 2 left mouse clicks. The line lives
281                         in the axes where the first point was selected.
282                     </para>
283                 </listitem>
284             </varlistentry>
285         </variablelist>
286         <para/>
287         <variablelist>
288             <varlistentry>
289                 <term>Polyline: </term>
290                 <listitem>
291                     <para>
292                         Draw a polyline by clicking on the left button to define
293                         the line path and right click at last to complete the
294                         drawing. The polyline lives in the axes where the first
295                         point was selected.
296                     </para>
297                 </listitem>
298             </varlistentry>
299         </variablelist>
300         <para/>
301         <variablelist>
302             <varlistentry>
303                 <term>Arrow: </term>
304                 <listitem>
305                     <para>
306                         Draw an arrow between 2 left mouse clicks. The arrow
307                         lives in the axes where the first point was selected.
308                     </para>
309                 </listitem>
310             </varlistentry>
311         </variablelist>
312         <para/>
313         <variablelist>
314             <varlistentry>
315                 <term>Double arrow: </term>
316                 <listitem>
317                     <para>
318                         Draw a double-sided arrow between 2 left mouse clicks.
319                         The double arrow lives in the axes where the first point
320                         was selected.
321                     </para>
322                 </listitem>
323             </varlistentry>
324         </variablelist>
325         <para/>
326         <variablelist>
327             <varlistentry>
328                 <term>Text: </term>
329                 <listitem>
330                     <para>
331                         Open a dialog box to enter the text, then click on the
332                         figure window to place it. The text lives in the axes
333                         where the point was selected.
334                     </para>
335                 </listitem>
336             </varlistentry>
337         </variablelist>
338         <para/>
339         <variablelist>
340             <varlistentry>
341                 <term>Rectangle: </term>
342                 <listitem>
343                     <para>
344                         Draw a rectangle: 2 left mouse clicks define
345                         respectively the upper left corner and the lower-right
346                         corner of the rectangle. The rectangle lives in the axes
347                         where the first point was selected.
348                     </para>
349                 </listitem>
350             </varlistentry>
351         </variablelist>
352         <para/>
353         <variablelist>
354             <varlistentry>
355                 <term>Circle: </term>
356                 <listitem>
357                     <para>
358                         Draw a circle : 2 left mouse clicks define respectively
359                         the upper left corner and the lower-right corner of the
360                         bounding-box where the circle lives. The rectangle lives
361                         in the axes where the first point was selected.
362                     </para>
363                 </listitem>
364             </varlistentry>
365         </variablelist>
366     </refsection>
367     <refsection role="see also">
368         <title>See also</title>
369         <simplelist type="inline">
370             <member>
371                 <link linkend="graphics_entities">graphics_entities</link>
372             </member>
373             <member>
374                 <link linkend="set">set</link>
375             </member>
376             <member>
377                 <link linkend="get">get</link>
378             </member>
379             <member>
380                 <link linkend="clf">clf</link>
381             </member>
382             <member>
383                 <link linkend="plot">plot</link>
384             </member>
385             <member>
386                 <link linkend="ged">ged</link>
387             </member>
388         </simplelist>
389     </refsection>
390 </refentry>