<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Djalel Abdemouche
 *
 * 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:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:id="legend_properties" xml:lang="en">
    <refnamediv>
        <refname>Legend entity properties</refname>
        <refpurpose>description of the Legend entity properties.</refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>The Legend entity is a leaf of the graphics entities
            hierarchy. This entity defines the parameters for legends drawn
            below <literal>plot2dx</literal> graphs or created by the <link linkend="captions">captions</link> function. For selected line
            plotted, the legend shows a sample of the line type, marker
            symbol, and color.
        </para>
        <variablelist>
            <varlistentry>
                <term>parent:</term>
                <listitem>
                    <para>This property contains the handle of the parent. The
                        parent of the legend entity should be of the type
                        <literal>"Compound"</literal>. This Compound entity contains
                        also the remainder of the graph's entities.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>children:</term>
                <listitem>
                    <para>This property contains a vector with the
                        <literal>children</literal> of the handle. However,
                        <literal>legend</literal> handles currently do not have any
                        <literal>children</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>visible:</term>
                <listitem>
                    <para>
                        This field contains the <literal>visible</literal> property
                        value for the entity . It should be <literal>"on" </literal> or
                        <literal>"off"</literal> . If <literal>"on"</literal> the legend is
                        drawn , If <literal>"off"</literal> the legend is not displayed on
                        the screen.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>text:</term>
                <listitem>
                    <para>This field is the character string vector which contains the
                        legends for each annotated objects.
                    </para>
                    <para>
                        Starting from Scilab 5.2, it is possible to write <link linkend="math_rendering_features_in_graphic">LaTeX or MathML expression</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>font_size:</term>
                <listitem>
                    <para>It is a scalar specifying the displayed characters size.
                        If <literal>fractional_font</literal> property is <literal>"off"</literal>
                        only the integer part of the value is used.
                        For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>font_style:</term>
                <listitem>
                    <para>Specifies the font used to display the legend labels.
                        This is a positive integer referencing one of the loaded fonts.
                        Its value must be between 0, referencing the first font,
                        and the number of loaded fonts minus one, referencing the last font.
                        For more information see <link linkend="graphics_fonts">graphics_fonts</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>font_color</term>
                <listitem>
                    <para>A color index, this property determines the color of the
                        text.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fractional_font:</term>
                <listitem>
                    <para>This property specify whether text is displayed using
                        fractional font sizes. Its value must be either
                        <literal>"on"</literal> or <literal>"off"</literal>. If
                        <literal>"on"</literal> the floating point value of
                        <literal>font_size</literal> is used for display and the
                        font is anti-aliased. If <literal>"off"</literal> only the
                        integer part is used and the font is not smoothed.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>links:</term>
                <listitem>
                    <para>A row array of handles. They refer to the associated
                        polylines.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>legend_location</term>
                <listitem>
                    <para>A character string, specifies the location of the
                        Legend.
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>"in_upper_right" </literal>: captions are drawn
                                in the upper right corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"in_upper_left"</literal>: captions are drawn in
                                the upper left corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"in_lower_right"</literal>: captions are drawn in
                                the lower right corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"in_lower_left"</literal>: captions are drawn in
                                the lower left corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"out_upper_right"</literal>: captions are drawn
                                at the right of the upper right corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"out_upper_left"</literal>: captions are drawn at
                                the left of the upper left corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"out_lower_right"</literal>: captions are drawn
                                at the right of the lower right corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"out_lower_left"</literal>: captions are drawn at
                                the left of the lower left corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"upper_caption"</literal>: captions are drawn
                                above the upper left corner of the axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"lower_caption"</literal>: captions are drawn
                                below the lower left corner of the axes box. This option
                                correspond to the <literal>leg</literal> argument of <link linkend="plot2d">plot2d</link>
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"by_coordinates"</literal>: the upper left
                                corner of the captions box is given by the "position"
                                field of the associated data structure. The
                                <literal>x</literal> and <literal>y</literal>
                                positions are given as fractions of the
                                <literal>axes_bounds</literal>.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>position</term>
                <listitem>
                    <para>The coordinates of the upper left corner of the
                        legend. The <literal>x</literal> and <literal>y</literal>
                        positions are given as fractions of the
                        <literal>axes_bounds</literal> sizes. This field may be set
                        if <literal>legend_location=="by_coordinates"</literal> or
                        get for the other legend_location settings.
                    </para>
                    <para>
                        The following instructions can be used to transform these
                        coordinates (<literal>position</literal>) to user
                        coordinates ((<literal>x_user</literal>,
                        <literal>y_user</literal>) or conversely.
                    </para>
                    <programlisting role="user coordinates"><![CDATA[
as=get(gcf(),"axes_size");//size of the canvas in pixels
bnds=get(gca(),"axes_bounds");//bounds of the current axes rectangle in figure size ratio.
//from legend coordinates to user coordinates
[x_user,y_user]=xchange(position(1)*as(1)*bnds(3)+as(1)*bnds(1),...
               position(2)*as(2)*bnds(4)+as(2)*bnds(2),"i2f")
//from   user coordinates to legend coordinates
[x1,y1]=xchange(x_user,y_user,'f2i')
position=[(x1-as(1)*bnds(1))/(as(1)*bnds(3)),...
          (y1-as(2)*bnds(2))/(as(2)*bnds(4))];

 ]]></programlisting>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_width</term>
                <listitem>
                    <para>This field specifies the width (in axes coordinates) of the line shown in the legend.
                        This value is a real between 0 and 1.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_mode</term>
                <listitem>
                    <para>This field specifies if a rectangle is drawn around the legend
                        or not. It should be <literal>"on"</literal> or
                        <literal>"off"</literal>. If <literal>"on"</literal> the rectangle
                        is drawn using the following properties.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>thickness</term>
                <listitem>
                    <para>This property is a positive real specifying the surrounding rectangle shape width
                        in pixels. The displayed width is actually determined by rounding the supplied width
                        to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
                        value is considered.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>foreground</term>
                <listitem>
                    <para>This field gives the color index of the line used to draw the
                        rectangle shape.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fill_mode</term>
                <listitem>
                    <para>This field specifies if the legend background is painted or
                        not. It should be <literal>"on"</literal> or
                        <literal>"off"</literal>. If <literal>"on"</literal> the background
                        is painted using the color index set in the
                        <literal>background</literal> field.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>background</term>
                <listitem>
                    <para>This field gives the color index of the line used to paint the
                        rectangle area.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>marks_count</term>
                <listitem>
                    <para>This property is an integer between 0 and 3 which specifies the number of marks to show in the legend.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_state:</term>
                <listitem>
                    <para>
                        This field contains the default <literal>clip_state</literal>
                        property value for all objects. Its value should be :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>"off"</literal> this means that all objects
                                created after that are not clipped (default value).
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"clipgrf"</literal> this means that all objects
                                created after that are clipped outside the Axes
                                boundaries.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"on"</literal> this means that all objects
                                created after that are clipped outside the rectangle given by
                                property clip_box.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_box:</term>
                <listitem>
                    <para>
                        This field contains the default <literal>clip_box</literal>
                        property value for all objects. Its value should be an empty matrix
                        if clip_state is <literal>"off"</literal>. Other case the clipping
                        is given by the vector <literal>[x,y,w,h]</literal> (upper-left
                        point width height).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>user_data:</term>
                <listitem>
                    <para>This field can be use to store any scilab variable in the text
                        data structure, and to retrieve it.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// x initialisation
x=[0:0.1:2*%pi]';
plot2d(x,[sin(x) sin(2*x) sin(3*x)],..
  [1,2,3],leg="L1@L2@L3")
a=get("current_axes");
l=a.children(2);
l.links
l.text=["sin(x)";"sin(2*x)";"sin(3*x)"];
l.visible="off"; // invisible
l.font_size = 2;
l.font_style = 5;
l.visible='on';
// Starting from Scilab 5.2, Latex:
l.text=["$\sin(x)$";"$\sin(2*x)$";"$\sin(3*x)$"];
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="plot2d">plot2d</link>
            </member>
            <member>
                <link linkend="graphics_entities">graphics_entities</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>line_width and marks_count properties added.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
