<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Fabrice Leray
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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">
    <refnamediv>
        <refname>graphical editor</refname>
        <refpurpose>
            Interactive edition of hierarchical properties of graphic objects
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <!--para>
            Scilab graphics allow the user to have interaction with graphics
            before and after having them drawn. Each graphics window and the
            drawing it contains are represented by hierarchical entities. The
            hierarchy top level is the <literal>Figure</literal>. Each
            <literal>Figure</literal> defines at least one child of type
            <literal>Axes</literal>. Each <literal>Axes</literal> entity
            contains a set of leaf entities which are the basic graphics objects
            like <literal>Polylines</literal>, <literal>Rectangles</literal>,
            <literal>Arcs</literal>, <literal>Segs</literal>,... It can also
            contain a <literal>Compound</literal> type which is recursive sets of entities.
        </para>
        <para>
            The main interest of the graphic mode is to make property changes
            easier. This graphics' mode provides a set of high-level graphing
            routines (see <link linkend="set">set</link>, <link
            linkend="get">get</link>) used to control objects'
            properties such as data, coordinates and scaling, color and
            appearances without requiring to replay the initial graphics
            commands.
        </para>
        <para>
            Graphics entities are associated to Scilab variables of type
            <literal>handle</literal>. The handle is a unique identifier which
            is associated to each instance of a created graphical entity. Using
            this handle, it will be possible to reach entities' properties
            through <function>set</function> and <function>get</function>
            routines. The handles are also used to manipulate graphics objects,
            to move them, to make copies or delete them.
        </para>
        <para>
            To complete and use the graphics handle capacity at its maximum, a
            graphic object editor has been created too. It is a set of Tcl/Tk
            interfaces available for each kind of graphics objects (see
            <link linkend="graphics_entities">graphics entities</link> for more
            details) that can be enabled for each graphic window. To make it
            work, select the <literal>Edit</literal> menu in the graphic window.
            Seven graphics editing operations are available :
        </para-->
        <para>
            The graphic Object Editor is a set of visual (GUI) editors, available
            in the <literal>Edit</literal> menu of graphic windows. They provide graphic editing operations
            for the different kind of graphics objects (see <link linkend="graphics_entities">graphics entities</link>
            for more details), including the enabling them, disabling them, and editing their properties,
            before or after they have been drawn.
        </para>
        <para>
            Internally, each graphic window, and the drawing it contains, are represented by
            a hierarchy of entities. The hierarchy top level is the <literal>Figure</literal>.
            Each <literal>Figure</literal> defines at least one child of type <literal>Axes</literal>.
            Each <literal>Axes</literal> entity contains a set of leaf entities which are the basic graphics
            objects like <literal>Polylines</literal>, <literal>Rectangles</literal>, <literal>Arcs</literal>, <literal>Segs</literal>,...
            It can also contain a <literal>Compound</literal> type which is recursive sets of entities.
            The graphic Object Editor manipulates this hierarchy of entities.
        </para>
        <para>
            In the Scilab language, graphics entities are associated to Scilab variables of type <literal>handle</literal>.
            The handle is a unique identifier which is associated to each instance of a created graphical entity.
            Using this handle, it will be possible to reach entities' properties through
            <function>set</function> and <function>get</function> routines.
            The handles are also used to manipulate graphics objects, to move them, to make copies or delete them.
            A set of high-level graphing routines (see <link linkend="set">set</link>, <link
            linkend="get">get</link>) allow accessing and editing the objects'
            properties such as data, coordinates and scaling, color and appearances without requiring
            to replay the initial graphics commands.
        </para>
        <para>
            The graphic Object Editor is implemented using the Tcl/Tk language; it is not available on MacOS,
            where Tcl/TK is not available.
        </para>
        <para>The following editing operations are available in the Object Editor:</para>
        <para/>
        <variablelist>
            <varlistentry>
                <term>Select figure as current: </term>
                <listitem>
                    <para>Let this figure be the current one.</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Redraw figure: </term>
                <listitem>
                    <para>Redraw the content of the graphics window.</para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Erase figure: </term>
                <listitem>
                    <para>
                        Erase the content of the graphics window. Its action
                        corresponds to <function>clf</function> routine.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Copy object: </term>
                <listitem>
                    <para>
                        Using the mouse, it allows the user to select a 2D
                        object (like a curve, a rectangle...) and put it in the
                        clipboard. Thus, by a next call to <literal>Paste
                            object
                        </literal>
                        ,the object is copied in the
                        selected current axes.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Paste object: </term>
                <listitem>
                    <para>
                        Allow the user to paste a previous object put into in
                        the clipboard inside the selected current axes.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Move object: </term>
                <listitem>
                    <para>
                        Using the mouse, it allows the user to move a 2D object
                        (like a curve, a rectangle...) inside the selected
                        current axes.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Delete object: </term>
                <listitem>
                    <para>
                        Using the mouse, it allows the user to pick up a 2D
                        object (like a curve, a rectangle...) inside the
                        selected current axes and to delete it instantly.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Figure Properties: </term>
                <listitem>
                    <para>
                        Launch the Tcl/Tk interface for the
                        <literal>Figure</literal> object applied to the figure
                        handle of the graphics window.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Current Axes Properties: </term>
                <listitem>
                    <para>
                        Launch the Tcl/Tk interface for the
                        <literal>Axes</literal> object applied to the current
                        axes handle of the graphics window.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Start Entity Picker: </term>
                <listitem>
                    <para>
                        Start an event handler on the graphics window to catch
                        the mouse clicks on graphics objects and launch the
                        corresponding Tcl/Tk interface. The left mouse-click
                        allows object edition and the right click performs a
                        move of the selected object. Note that, for now, this
                        feature is applied to 2D objects only.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Stop Entity Picker: </term>
                <listitem>
                    <para>
                        Stop the action of the Entity Picker by terminating the
                        event handler on the graphics window.
                    </para>
                    <para/>
                </listitem>
            </varlistentry>
        </variablelist>

        <para>
            Once the graphic interface is enabled (using the <literal>Figure Properties</literal> or <literal>Current Axes Properties</literal> options), two main areas appear:
        </para>
        <para/>
        <para/>
        <variablelist>
            <varlistentry>
                <term>A tree selector: </term>
                <listitem>
                    <para>
                        Placed on the left side of the graphical editor, a
                        hierarchical tree selector specifies which object is
                        currently edited. It can be used to switch from a
                        graphic object to another provided that they are
                        in the same graphic window.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            <inlinemediaobject>
                <imageobject>
                    <imagedata fileref="../images/tree.gif"/>
                </imageobject>
            </inlinemediaobject>
        </para>
        <para/>
        <variablelist>
            <varlistentry>
                <term>A notebook: </term>
                <listitem>
                    <para>
                        The second area represents a notebook composed with
                        different properties pages (like
                        <literal>Style</literal>, <literal>Data</literal>,
                        <literal>Clipping</literal>...) depending on the
                        selected graphic object. Using this editor, user can
                        edit more easily the whole properties set of each
                        graphic object (like through the <function>set</function> and
                        <function>get</function> routines). Here is an example of the axes' notebook displaying axes properties:
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            <inlinemediaobject>
                <imageobject>
                    <imagedata fileref="../images/notebook.gif"/>
                </imageobject>
            </inlinemediaobject>
        </para>
        <para/>
        <para>
            Furthermore, you can legend/annotate your figure using sample
            primitives given inside the <literal>Insert</literal> menu in the
            graphic window. Using the mouse and following the instruction in the message subwindow, you can add a:
        </para>
        <para/>
        <variablelist>
            <varlistentry>
                <term>Line: </term>
                <listitem>
                    <para>
                        Draw a line between 2 left mouse clicks. The line lives
                        in the axes where the first point was selected.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para/>
        <variablelist>
            <varlistentry>
                <term>Polyline: </term>
                <listitem>
                    <para>
                        Draw a polyline by clicking on the left button to define
                        the line path and right click at last to complete the
                        drawing. The polyline lives in the axes where the first
                        point was selected.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para/>
        <variablelist>
            <varlistentry>
                <term>Arrow: </term>
                <listitem>
                    <para>
                        Draw an arrow between 2 left mouse clicks. The arrow
                        lives in the axes where the first point was selected.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para/>
        <variablelist>
            <varlistentry>
                <term>Double arrow: </term>
                <listitem>
                    <para>
                        Draw a double-sided arrow between 2 left mouse clicks.
                        The double arrow lives in the axes where the first point
                        was selected.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para/>
        <variablelist>
            <varlistentry>
                <term>Text: </term>
                <listitem>
                    <para>
                        Open a dialog box to enter the text, then click on the
                        figure window to place it. The text lives in the axes
                        where the point was selected.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para/>
        <variablelist>
            <varlistentry>
                <term>Rectangle: </term>
                <listitem>
                    <para>
                        Draw a rectangle: 2 left mouse clicks define
                        respectively the upper left corner and the lower-right
                        corner of the rectangle. The rectangle lives in the axes
                        where the first point was selected.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para/>
        <variablelist>
            <varlistentry>
                <term>Circle: </term>
                <listitem>
                    <para>
                        Draw a circle : 2 left mouse clicks define respectively
                        the upper left corner and the lower-right corner of the
                        bounding-box where the circle lives. The rectangle lives
                        in the axes where the first point was selected.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="ieditor">ieditor</link>
            </member>
            <member>
                <link linkend="ged">ged</link>
            </member>
            <member>
                <link linkend="graphics_entities">graphics_entities</link>
            </member>
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="plot">plot</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
