<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) ENPC - Jean-Philippe Chancelier
 *
 * 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="xstring">
    <refnamediv>
        <refname>xstring</refname>
        <refpurpose>draw strings</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
          xstring(x, y, str)
          xstring(x, y, str, angle)
          xstring(x, y, str, angle, box)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x,y</term>
                <listitem>
                    <para>real vectors or scalars, coordinates of the lower-left point of the strings.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>str</term>
                <listitem>
                    <para>matrix of strings.</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>angle</term>
                <listitem>
                    <para>real vector or scalar, clockwise angle in degree; default is 0.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>box</term>
                <listitem>
                    <para>integer vector or scalar, default is 0.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            If <literal>x</literal> is a real scalar, it's regarded as a vector with the size of <literal>y</literal> whose elements are set to <literal>x</literal>.
        </para>
        <para>
            If <literal>y</literal> is a real scalar, it's regarded as a vector with the size of <literal>x</literal> whose elements are set to <literal>y</literal>.
        </para>
        <para>
            <literal>xstring</literal> draws n strings at location <literal>(x[i], y[i])</literal> in the current graphic scale.
        </para>
        <para>
            If <literal>str</literal> contain n elements, these n elements are the n drawn strings.
        </para>
        <para>Otherwise, each row of the matrix stands for a line of text and row elements stand for words separated by a white space.</para>
        <para>
            If <literal>angle</literal> is a real scalar, it's regarded as a vector of size n whose elements are set to <literal>angle</literal>.
        </para>
        <para>
            <literal>angle(i)</literal>gives the slope in degree used for drawing the strings at location <literal>(x[i], y[i])</literal>.
        </para>
        <para>
            If <literal>box</literal> is an integer scalar, it's regarded as a vector of size n whose elements are set to <literal>box</literal>.
        </para>
        <para>
            If <literal>box(i)</literal> is 1 and <literal>angle(i)</literal> is 0, a box is drawn around the strings at location <literal>(x[i], y[i])</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
plot2d([0;1],[0;1],0)
xstring(0.5,0.5,["$\overbrace{Scilab}$" "n''est ";"pas" "$\underbrace{Matlab}$"])
// LaTeX rendering (>= Scilab 5.2)

//Other example
alphabet=["a" "b" "c" "d" "e" "f" "g" ..
          "h" "i" "j" "k" "l" "m" "n" ..
          "o" "p" "q" "r" "s" "t" "u" ..
          "v" "w" "x" "y" "z"];
clf()
plot2d([0;1],[0;2],0)
xstring(0.1,1.8,alphabet)     // alphabet
xstring(0.1,1.6,alphabet,0,1) // alphabet in a box
xstring(0.1,1.4,alphabet,20)  // angle
set(gca(), "font_style", 1, "font_size", 1);  // use symbol fonts
xstring(0.1,0.1,alphabet)
xstring(0.1,0.3,alphabet)
gce().font_size = 3;          // change the font size
xstring(0.1,0.6,"a")    //big alpha
gce().font_size = 24;
 ]]></programlisting>
        <scilab:image>
            plot2d([0;1],[0;1],0)
            xstring(0.5,0.5,["$\overbrace{Scilab}$" "n''est ";"pas" "$\underbrace{Matlab}$"])
        </scilab:image>

    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="text_properties">text_properties</link>
            </member>
            <member>
                <link linkend="math_rendering_features_in_graphic">Math mode in strings</link>
            </member>
          <member>
                <link linkend="xnumb">xnumb</link>
            </member>
            <member>
                <link linkend="xtitle">xtitle</link>
            </member>
            <member>
                <link linkend="titlepage">titlepage</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
