<?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
 *
 * 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="legends">
    <refnamediv>
        <refname>legends</refname>
        <refpurpose>draw graph legend</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>legends(strings,style,&lt;opt_args&gt;)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>strings</term>
                <listitem>
                    <para>n vector of strings, strings(i) is the legend of the ith curve</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>style</term>
                <listitem>
                    <para>integer row vector of size n (the plot styles, third parameter of plot2d) or an integer 2 x n matrix, style(1,k) contains the plot style for the kth curve and style(2,k) contains the line style (if style(1,k)&gt;0) or mark color (if style(1,k)&lt;0).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>This represents a sequence of statements
                        <literal>key1=value1,key2=value2</literal>,... where <literal>key1</literal>,
                        <literal>key2,...</literal> can be one of the following:
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>opt</term>
                            <listitem>
                                <para>specify where to draw the legends; this parameter may be an integer
                                    flag (or equivalently a string flag) or a vector [x,y] which gives the coordinates
                                    of the upper left corner of the legend box. In the first case the possible values
                                    are:
                                </para>
                                <variablelist>
                                    <varlistentry>
                                        <term>1 or "ur"</term>
                                        <listitem>
                                            <para> the legends are drawn in the upper right-hand corner.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>2 or "ul"</term>
                                        <listitem>
                                            <para> the legends are drawn in the upper left-hand corner.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>3 or "ll"</term>
                                        <listitem>
                                            <para> the legends are drawn in the lower left-hand corner.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>4 or "lr"</term>
                                        <listitem>
                                            <para> the legends are drawn in the lower right-hand corner.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>5 or "?"</term>
                                        <listitem>
                                            <para> interactive placement with the mouse  (default).</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>6 or "below"</term>
                                        <listitem>
                                            <para> the legends are drawn under the graph (which is resized accordingly).</para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>with_box</term>
                            <listitem>
                                <para>a boolean (default value %t) which sets ot not the drawing of the box.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>font_size</term>
                            <listitem>
                                <para>an integer (default value 1) which sets the size of the font used for the names in the legend. </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            Puts a legend on the current plot using the specified strings as
            labels.
        </para>
        <para>
            In the interactive placement (opt=5 or opt="?") move the legend box with the
            mouse and press the left button to release it.
        </para>
        <para>
            This function allows more flexible placement of the legends than the
            leg plot2d argument.
        </para>
    </refsection>
    <refsection>
        <title>Sample</title>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// Example 1
t=0:0.1:2*%pi;
plot2d(t,[cos(t'),cos(2*t'),cos(3*t')],[-1,2 3]);
legends(['cos(t)';'cos(2*t)';'cos(3*t)'],[-1,2 3],opt="lr")
 ]]></programlisting>
        <scilab:image>
            t=0:0.1:2*%pi;
            plot2d(t,[cos(t'),cos(2*t'),cos(3*t')],[-1,2 3]);
            legends(['cos(t)';'cos(2*t)';'cos(3*t)'],[-1,2 3],opt="lr")
        </scilab:image>
        <programlisting role="example"><![CDATA[
t=0:0.1:2*%pi;
gca().line_style = 2;
plot2d(t,cos(t),style=5);
gca().line_style = 4;
plot2d(t,sin(t),style=3);
legends(["sin(t)";"cos(t)"],[[5;2],[3;4]], with_box=%f, opt="?")
 ]]></programlisting>
        <programlisting role="example"><![CDATA[
// Example 2
scf() ;
subplot(221)
t=0:0.1:2*%pi;
plot2d(t,[cos(t'),cos(2*t'),cos(3*t')],[-1,2 3]);
legends(['cos(t)';'cos(2*t)';'cos(3*t)'],[-1,2 3], opt=3 )

subplot(222)
gca().line_style = 2;
plot2d(t,cos(t),style=5);
gca().line_style = 4;
plot2d(t,sin(t),style=3);
legends(["sin(t)";"cos(t)"],[[5;2],[3;4]], with_box=%f, opt=6 )

subplot(223)
gca().line_style = 2;
plot2d(t,cos(t),style=5);
gca().line_style = 4;
plot2d(t,sin(t),style=3);
legends(["sin(t)";"cos(t)"],[[5;2],[3;4]], with_box=%f, opt=1, font_size=2 )

subplot(224)
t=0:0.1:2*%pi;
plot2d(t,[cos(t'),cos(2*t'),cos(3*t')],[-1,2 3]);
legends(['cos(t)';'cos(2*t)';'cos(3*t)'],[-1,2 3], opt=2, font_size=1 )
 ]]></programlisting>
        <scilab:image>
            subplot(221)
            t=0:0.1:2*%pi;
            plot2d(t,[cos(t'),cos(2*t'),cos(3*t')],[-1,2 3]);
            legends(['cos(t)';'cos(2*t)';'cos(3*t)'],[-1,2 3], opt=3 )

            subplot(222)
            gca().line_style = 2;
            plot2d(t,cos(t),style=5);
            gca().line_style = 4;
            plot2d(t,sin(t),style=3);
            legends(["sin(t)";"cos(t)"],[[5;2],[3;4]], with_box=%f, opt=6 )

            subplot(223)
            gca().line_style = 2;
            plot2d(t,cos(t),style=5);
            gca().line_style = 4;
            plot2d(t,sin(t),style=3);
            legends(["sin(t)";"cos(t)"],[[5;2],[3;4]], with_box=%f, opt=1, font_size=2 )

            subplot(224)
            t=0:0.1:2*%pi;
            plot2d(t,[cos(t'),cos(2*t'),cos(3*t')],[-1,2 3]);
            legends(['cos(t)';'cos(2*t)';'cos(3*t)'],[-1,2 3], opt=2, font_size=1 )
        </scilab:image>

    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="plot2d">plot2d</link>
            </member>
            <member>
                <link linkend="xstring">xstring</link>
            </member>
            <member>
                <link linkend="xtitle">xtitle</link>
            </member>
            <member>
                <link linkend="legend">legend</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
