<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Farid Belahcene
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2016, 2019 - 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="title">
    <refnamediv>
        <refname>title</refname>
        <refpurpose>displays a title above a graphic axes, or updates its properties.
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            title(text)
            title(text, property_name, property_value,...)
            title(property_name, property_value,...)
            title(axes_handle,...)
        </synopsis>
    </refsynopsisdiv>
    <refsection role="parameters">
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>text</term>
                <listitem>
                    <para>
                        Matrix of text of the title. A title can have multiple rows or/and
                        columns of text. Leading and trailing blanks are trimmed.
                        In their columns, texts are left-justified.
                        <link linkend="math_rendering_features_in_graphic">LaTeX expressions</link>
                        delimited with "$...$" are supported.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>axes_handle</term>
                <listitem>
                    <para>
                        Handle of the axes whose title must be set or updated.
                        By default, the current axes is processed. Otherwise, the given axes
                        is set as and remains the current one after returning from
                        <literal>title()</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>property_name, property_value,...</term>
                <listitem>
                    <para>
                        unlimited series of pairs of property name (word) and the respective value
                        to assign to it. The available properties are related to
                        <link linkend="label_properties">labels properties</link>). Some of them
                        have an alias that can be used as well with <literal>title()</literal>:
                    </para>
                    <para>
                        <table border="1">
                            <tr>
                                <th align="left">visible</th>
                                <th></th>
                                <td>
                                    <literal>"on"</literal> or <literal>"off"</literal>.
                                    If <literal>"off"</literal>, the title (and its box) still
                                    exists but is not displayed.
                        </td>
                            </tr>
                            <tr>
                                <th align="left">fontsize</th>
                                <th align="left">font_size</th>
                                <td>
                                    Scalar positive number specifying the size of displayed
                                    characters. default = 1. For any non-integer size, the font is
                                    scaled accordingly and anti-aliased (made a bit foggy).
                                </td>
                            </tr>
                            <tr>
                                <th align="left">fontname</th>
                                <th align="left">font_style</th>
                                <td>
                                    Ten font names are available (case and space unsensitive string),
                                    or their related id number:
                                    <table>
                                        <tr>
                                            <td>0</td><td>"courrier"</td><td></td>
                                            <td>2</td><td>"times"</td><td></td>
                                            <td>6</td><td>"helvetica"</td>
                                        </tr>
                                        <tr>
                                            <td>1</td><td>"symbol"</td><td></td>
                                            <td>3</td><td>"times italic"</td><td></td>
                                            <td>7</td><td>"helvetica italic"</td>
                                        </tr>
                                        <tr>
                                            <td></td><td></td><td></td>
                                            <td>4</td><td>"times bold"</td><td></td>
                                            <td>8</td><td>"helvetica bold"</td>
                                        </tr>
                                        <tr>
                                            <td></td><td></td><td></td>
                                            <td>5</td><td>"times bold italic"</td><td></td>
                                            <td>9</td><td>"helvetica bold italic"</td>
                                        </tr>
                                    </table>
                                    <para>
                                        For instance, 3, "3", "times italic", "timesitalic" or
                                        "TimesItalic" are equivalent.
                                    </para>
                                    <para>
                                        Other fonts can be loaded with <literal>xlfont()</literal>
                                        and used.
                                    </para>
                                </td>
                            </tr>
                            <tr>
                                <th align="left">color</th>
                                <th align="left">font_foreground</th>
                                <td>
                                    Color of the text of the title (*).
                                </td>
                            </tr>
                            <tr>
                                <th align="left">position</th>
                                <th></th>
                                <td>
                                    Vector of coordinates of the title's anchor, in data unit.
                                    The anchor is the lower-left corner of the box of
                                    the title (when horizontal). Note: This property can't be set
                                    with a console-oriented syntax.
                                </td>
                            </tr>
                            <tr>
                                <th align="left">rotation</th>
                                <th align="left">font_angle</th>
                                <td>
                                    Direct (anti-clockwise) angle of the title's block, in degrees,
                                    horizontal = 0°.
                                    The lower-left corner of the box bounding the horizontal title
                                    is used as pivot (fixed point).
                                </td>
                            </tr>
                            <tr>
                                <th align="left">box</th>
                                <th></th>
                                <td>
                                    "off" | "on": hides or displays a box around the block of text
                                    of the title.
                                </td>
                            </tr>
                            <tr>
                                <th align="left">edgecolor</th>
                                <th align="left">foreground</th>
                                <td>
                                    Color of the border of the box (if any)(*).The box is then
                                    automatically turned "on".
                                </td>
                            </tr>
                            <tr>
                                <th align="left">background</th>
                                <th align="left">backgroundcolor</th>
                                <td>
                                    Filling color of the box background, behind the text (*).
                                    The box is then automatically turned "on".
                                </td>
                            </tr>
                            <tr>
                                <th align="left">tag</th>
                                <th></th>
                                <td>
                                    String or matrix of strings: Custom literal identifier of the title.
                                </td>
                            </tr>
                        </table>
                    </para>
                    <para>
                        (*) Any color can be specified by any of the following:
                        <itemizedlist>
                            <listitem>
                                Its numerical or literal index in the current colormap
                                (like 13 or "13"). Special values whatever is the colormap:
                                -1 for black, -2 for white.
                            </listitem>
                            <listitem>
                                Its name as a string, if it is a predefined
                                <link linkend="color_list">listed color</link>. For colors among
                                the short list
                                ["red","green","blue","cyan","magenta","yellow","black","white"],
                                shortened names are supported, like "m" for magenta or "k"
                                for "black".
                            </listitem>
                            <listitem>
                                Its "#RRGGBB" hexadecimal code, as a string.
                            </listitem>
                            <listitem>
                                the [r,g,b] row of its Red/Green/Blue 0 ≤ r,g,b ≤ 1 intensities.
                                This syntax can't be used in console-oriented mode.
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            title() is used to set and display a title at the top of the current or given axes,
            or to change properties of the existing title.
        </para>
        <para>
            <literal>title()</literal> can be called with a functional syntax like
            <literal>title("My title", "fontsize", 3)</literal> or with an equivalent
            console-oriented syntax like <literal>title "My title" fontsize 3</literal>.
            However, [r,g,b] row color and [x,y] coordinates specifications can't be used
            in console-oriented syntaxes.
        </para>
        <warning>
            When an axes handle is specified as the target axes, it becomes the current axes
            and remains as is after leaving title().
        </warning>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
plot2d([], [], 0, "011", " ", [0 0 1 1])
// display a title with its default properties
title 'my title'

// change the color for the font
title color blue

// change the color for the edge of the surrounding box, and displays the box
title edgecolor red

// change the position of the title
title('position', [0.3 0.8]);

// change the size of the font
title fontsize 3

// a rotation
title rotation 90

// We can do all these modifications with just the below instruction:
title('my title','color','blue','edgecolor','red','fontsize',3,'rotation',90,'position',[0.3 0.8]);
 ]]></programlisting>
        <scilab:image>
            plot2d([], [], 0, "011", " ", [0 0 1 1])
            title 'my title'  color blue  edgecolor red  fontsize 3  rotation 90
            title('position', [0.3 0.8])
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="label_properties">label_properties</link>
            </member>
            <member>
                <link linkend="titlepage">titlepage</link>
            </member>
            <member>
                <link linkend="xtitle">xtitle</link>
            </member>
            <member>
                <link linkend="xlabel">x|y|zlabel</link>
            </member>
            <member>
                <link linkend="ieditor">Interactive editor</link>
            </member>
            <member>
                <link linkend="xstring">xstring</link>
            </member>
            <member>
                <link linkend="color_list">color_list</link>
            </member>
            <member>
                <link linkend="color">color</link>
            </member>
            <member>
                <link linkend="xlfont">xlfont</link>
            </member>
            <member>
                <link linkend="set">set</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.1.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>
                            The <literal>text</literal> becomes optional, to update only properties.
                        </listitem>
                        <listitem>
                            The full list of Scilab predefined colors names can now be used,
                            as well as hexadecimal #RRGGBB colors codes.
                        </listitem>
                        <listitem>
                            Console-oriented usages are now possible, specifying any color index,
                            font id, font size, or box angle as a string like "13" instead of 13,
                            excepted for [r,g,b] and [x,y,z] position.
                        </listitem>
                        <listitem>
                            When a non-integer font size is specified,
                            <literal>.fractional_font</literal> is now automatically turned "on".
                            It is conversely forced to "off" for any input integer font size.
                        </listitem>
                        <listitem>
                            Any specified font name is now space-insensitive.
                        </listitem>
                        <listitem>
                            New property <literal>box="on"|"off"</literal> added.
                        </listitem>
                        <listitem>
                            New property <literal>tag</literal> added.
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
