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