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