<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * 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="graphics_entities">
    <refnamediv>
        <refname>Graphics Entities</refname>
        <refpurpose>
            description of the graphics entities data structures
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>
            In Scilab, 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 an <literal>Compound</literal> type which is recursive
            set of entities. The main interest of the graphic mode is to make
            property change 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 an 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/>
        <variablelist>
            <varlistentry>
                <term>Console, root, mouse: </term>
                <listitem>
                    <para>
                        With its menus, the console may be considered as a special graphic windows.
                        Its menus and some graphical meta options may be addressed through its
                        handle as returned by <code>c=get(0)</code>.
                        See <link linkend="console_properties">Console properties</link> for details.
                    </para>
                    <para>
                        The root object is a virtual graphical object used to get the computer
                        screen properties. Its handle is the same as the console's one:
                        <code>r=get(0)</code>, but the screen properties can be addressed only
                        in read-only mode.
                        See <link linkend="root_properties">Root properties</link> for details.
                    </para>
                    <para>
                        On Windows, some additional screen, windowing and mouse parameters may be
                        retrieved through the <link linkend="getsystemmetrics">getsystemmetrics</link>
                        function.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Figure: </term>
                <listitem>
                    <para>
                        The <literal>Figure</literal> entity is the top level of the graphics
                        entities hierarchy. This entity defines the parameters
                        for the figure itself as well as the parameters' default
                        values for the children creation. The figure children
                        are the <literal>Axes</literal> entities.
                    </para>
                    <para>
                        The handle on the current figure (the figure used where
                        the drawing are sent) may be got using
                        <code>get("current_figure")</code> and it may be set
                        using <code>set("current_figure",h)</code>, where
                        <literal>h</literal> is either a handle on a figure or a
                        <literal>figure_id</literal>. In this last case if the
                        figure does not already exists, it is created.
                    </para>
                    <para>
                        See <link linkend="figure_properties">figure properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Axes: </term>
                <listitem>
                    <para>
                        The <literal>Axes</literal> entity is the second level
                        of the graphics entities hierarchy. This entity defines
                        the parameters for the change of coordinates and the
                        axes drawing as well as the parameters' default values
                        for its children creation. See <link linkend="axes_properties">axes properties</link> for
                        details. The handle on the current <literal>Axes</literal> may be got using
                        <code>get("current_axes")</code>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Compound: </term>
                <listitem>
                    <para>
                        The <literal>Compound</literal> entity is just a vector
                        of children and with a single property (visibility
                        property). It is used to glue a set of entities
                        together.
                    </para>
                    <para>
                        See <link linkend="glue">glue</link>, <link linkend="unglue">unglue</link> and
                        <link linkend="Compound_properties">Compound properties</link> functions.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Axis: </term>
                <listitem>
                    <para>
                        The <literal>Axis</literal> entity is a leaf of the
                        graphics entities hierarchy. This entity defines the
                        parameters for axis scaling and appearance.
                    </para>
                    <para>
                        See <link linkend="axis_properties">axis properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Polyline: </term>
                <listitem>
                    <para>
                        The <literal>Polyline</literal> entity is a leaf of the
                        graphics entities hierarchy. It defines 2D and 3D
                        polylines and polylines extensions drawing properties.
                    </para>
                    <para>
                        See <link linkend="polyline_properties">polyline properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Arc: </term>
                <listitem>
                    <para>
                        The <literal>Arc</literal> entity is a leaf of the
                        graphics entities hierarchy. This entity defines the
                        parameters for ellipses and part of ellipses.
                    </para>
                    <para>
                        See <link linkend="arc_properties">arc properties</link>
                        for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Rectangle: </term>
                <listitem>
                    <para>
                        The <literal>Rectangle</literal> entity is a leaf of the
                        graphics entities hierarchy. This entity defines the
                        parameters for rectangles and filled rectangles.
                    </para>
                    <para>
                        See <link linkend="rectangle_properties">rectangle properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Surface: </term>
                <listitem>
                    <para>
                        The <literal>Surface</literal> entity is a leaf of the
                        graphics entities hierarchy. It has subtypes
                        <literal>Fac3d</literal> or <literal>Plot3d</literal>.
                        This entity defines the parameters for 3d surface plots.
                    </para>
                    <para>
                        See <link linkend="surface_properties">surface properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Fec: </term>
                <listitem>
                    <para>
                        The <literal>Fec</literal> entity is a leaf of the
                        graphics entities  hierarchy. It represents 2D finite
                        elements plots.
                    </para>
                    <para>
                        See <link linkend="fec_properties">fec properties</link>
                        for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Grayplot: </term>
                <listitem>
                    <para>
                        The <literal>Grayplot</literal> entity is a leaf of the
                        graphics entities hierarchy. It represents 2D plots of
                        surface using colors and images.
                    </para>
                    <para>
                        See <link linkend="grayplot_properties">grayplot properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Matplot: </term>
                <listitem>
                    <para>
                        The <literal>Matplot</literal> entity is a leaf of the
                        graphics entities hierarchy. It represents 2D plots
                        using integer matrices.
                    </para>
                    <para>
                        See <link linkend="Matplot_properties">Matplot properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Segs: </term>
                <listitem>
                    <para>
                        The <literal>Segs</literal> entity is a leaf of the
                        graphics entities hierarchy. This entity defines the
                        parameters for a set of colored segments or colored
                        arrows.
                    </para>
                    <para>
                        See <link linkend="segs_properties">segs properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Champ: </term>
                <listitem>
                    <para>
                        The <literal>Champ</literal> entity is a leaf of the
                        graphics entities hierarchy. This entity defines the
                        parameters for a 2D vector field.
                    </para>
                    <para>
                        See <link linkend="champ_properties">champ properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Text: </term>
                <listitem>
                    <para>
                        The <literal>Text</literal> entity is a leaf of the
                        graphics entities hierarchy. This entity defines the
                        parameters for string drawing.
                    </para>
                    <para>
                        See <link linkend="text_properties">text properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Label: </term>
                <listitem>
                    <para>
                        The <literal>Label</literal> entity is a child of the
                        <literal>Axes</literal> graphics entity. This entity
                        defines the parameters for the 3 x, y and z labels
                        and title drawn on a graphics window.
                    </para>
                    <para>
                        See <link linkend="label_properties">Label entity properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Legend: </term>
                <listitem>
                    <para>
                        The <literal>Legend</literal> entity is a leaf of the
                        graphics entities hierarchy. This entity defines the
                        parameters for legends drawn below
                        <literal>plot2dx</literal> graphs. This entity requires
                        further developments.
                    </para>
                    <para>
                        See <link linkend="legend_properties">Legend entity properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Light: </term>
                <listitem>
                    <para>
                        Lights in scilab approximates real world lighting where the appearance of
                        a surface is given by interactions between light rays and the material properties of the
                        surface. Because simulate real world lighting is complex
                        and computationally expensive, one uses a simplified model.
                    </para>
                    <para>
                        See <link linkend="light_properties">light entity properties</link> for details.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <refsect3>
            <title>Other entities</title>
            <variablelist>
                <varlistentry>
                    <term>Interactive components (uicontrol)</term>
                    <listitem>
                        <para>
                            Scilab allows to create graphical interactive components like sliders,
                            spinners, editable tables, editable texts on graphics, checkboxes,
                            groups of radio buttons, listboxes, popup menus, push buttons, etc.
                            These objects are direct children of the figure where they are defined.
                            Their properties can be set and tuned through their handles as for
                            any other graphical objects. Please
                            see <link linkend="uicontrol_properties">uicontrol properties</link> for
                            details.
                        </para>
                    </listitem>
                </varlistentry>
                <varlistentry>
                    <term>UI menus</term>
                    <listitem>
                        <para>
                            <link linkend="uimenu">uimenu</link>() allows to add and manage some
                            menus on the menu bar of any graphical figure. <literal>uimenu()</literal>
                            returns a handle through which the contents and properties of the
                            created menu can be addressed. Please see
                            <link linkend="uimenu_properties">uimenus properties</link> for details.
                        </para>
                    </listitem>
                </varlistentry>
            </variablelist>
        </refsect3>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
//Play this example line per line

// Creates a figure in entity mode, gets its handle, displays its properties
f = scf()
a = f.children // the handle on the Axes child
x = (1:10)';  plot2d(x,[x.^2 x.^1.5])
e = a.children //Compound of 2 polylines

p1 = e.children(1)  //the last drawn polyline properties
p1.foreground = 5;  // change the polyline color
e.children.thickness = 5; // change the thickness of the two polylines

delete(e.children(2))

move(e.children,[0,30]) //translate the polyline

a.axes_bounds = [0 0 0.5 0.5];

subplot(222) //create a new Axes entity
plot(1:10);
a1 = f.children(1);  // get its handle
copy(e.children,a1); // copy the polyline of the first plot in the new Axes
a1.data_bounds = [1 0;10 100]; //change the Axes bounds

scf(10); // create a new figure with figure_id=10
plot3d() // the drawing are sent to figure 10
scf(f);  // makes the previous figure the current one
plot2d(x,x^3)  //the drawing are sent to the initial figure
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="move">move</link>
            </member>
            <member>
                <link linkend="delete">delete</link>
            </member>
            <member>
                <link linkend="ged">ged</link>
            </member>
            <member>
                <link linkend="object_editor">object editor</link>
            </member>
            <member>
                <link linkend="plot">plot</link>
            </member>
            <member>
                <link linkend="surf">surf</link>
            </member>
            <member>
                <link linkend="getsystemmetrics">getsystemmetrics</link>
            </member>
            <member>
                <link linkend="setlookandfeel">setlookandfeel</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
