<?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="drawaxis">
    <refnamediv>
        <refname>drawaxis</refname>
        <refpurpose>draw an axis</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            drawaxis([options]); // options: x,y,dir,sub_int,fontsize,format_n,seg,textcolor,ticscolor,tics
            e = drawaxis([options]);
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>dir=string</term>
                <listitem>
                    <para>
                        used to specify the tics direction. <literal>string</literal> can be chosen among   'u','r','d','l' and 'l' is the default value. the values 'u','r','d','l' stands respectively for up, right, down, left
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>tics=string</term>
                <listitem>
                    <para>
                        A flag which describes how the tics are given.   <literal>string</literal> can be chosen among 'v','r', and 'i', and, 'v' is the default value
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x,y</term>
                <listitem>
                    <para>two vectors which give tics positions.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>val= string matrix</term>
                <listitem>
                    <para>A string matrix, which, when given, gives the string to be drawn along the axis at tics positions.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fontsize=int</term>
                <listitem>
                    <para>
                        specifies the fontsize to use for displaying values along the axis. Default value is <literal>-1</literal> which stands for current fontsize
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>format_n=string</term>
                <listitem>
                    <para>
                        format to use for displaying numbers along the axis, where <literal>string</literal> gives the format according to the C language
                        printf function format syntax (for example <literal>string="%.3f"</literal>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>seg= 1 or 0</term>
                <listitem>
                    <para>A flag which controls the display of the base segment of the axis (default value is 1).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>sub_int=integer</term>
                <listitem>
                    <para>an integer which gives the number of sub-intervals to draw  between large tics.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>textcolor=integer</term>
                <listitem>
                    <para>
                        specify the color to use for displaying values along the axis. Default value is <literal>-1</literal> which stands for current color.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ticscolor=integer</term>
                <listitem>
                    <para>
                        specify the color to use for tics drawing. Default value is <literal>-1</literal> which stands for current color.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>e</term>
                <listitem>
                    <para>
                        handle, the handle of the created axis.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>drawaxis</literal> is used to draw an axis in vertical or horizontal
            direction. This function returns the handle of the created axis.
            The direction of the axis is given by dir
            <literal>dir = 'u'</literal> or <literal>'d'</literal> gives a horizontal axis
            with tics going up (<literal>'u'</literal>) or down (<literal>'d'</literal>).
            <literal>dir = 'r'</literal> or <literal>'l'</literal> give a vertical axis
            with tics going right (<literal>'r'</literal>) or left (<literal>'l'</literal>).
        </para>
        <para>
            <literal>x</literal> and <literal>y</literal> give the axis tics positions.
            If the axis is horizontal then <literal>y</literal>
            must be a scalar or can be omitted and <literal>x</literal>
            is a Scilab vector. The meaning of <literal>x</literal>
            is controlled by <literal>tics</literal>.
        </para>
        <para>
            If <literal>tics='v'</literal> then <literal>x</literal> gives the tics positions along the x-axis.
        </para>
        <para>
            If <literal>tics='r'</literal> then <literal>x</literal> must be of size 3. <literal>x=[xmin,xmax,n]</literal> and
            <literal>n</literal> gives the number of intervals.
        </para>
        <para>
            If <literal>tics='i'</literal> then <literal>x</literal> must be of size 4, <literal>x=[k1,k2,a,n]</literal>.
            then <literal>xmin=k1*10^a</literal>, <literal>xmax=k2*10^a</literal> and <literal>n</literal> gives the number of intervals
        </para>
        <para>
            If <literal>y</literal> is omitted then the axis will be positioned at
            the top of the frame if <literal>dir='u'</literal> or at the bottom if  <literal>dir='d'</literal>
        </para>
        <para>
            By default, numbers are drawn along the axis. They are drawn using
            a default format which can be changed with <literal>format_n</literal>.
            It is also possible to display given strings and not numbers,
            this is done if <literal>val</literal> is provided. The size of <literal>val</literal> must
            match the number of tics.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
plot2d(1:10,1:10,1,"020")
// horizontal axis
e = drawaxis(x=2:7,y=4,dir='u',tics='v')
// horizontal axis on top of the frame
drawaxis(x=2:7,dir='u',tics='v')
// horizontal axis at the bottom of the frame
e = drawaxis(x=2:7,dir='d',tics='v')

// horizontal axis given by a range
drawaxis(x=[2,7,3],y=4,dir='d',tics='r')

// vertical axis
e = drawaxis(x=4,y=2:7,dir='r',tics='v')
e = drawaxis(x=2,y=[2,7,3],dir='l',tics='r')
e = drawaxis(y=2:7,dir='r',tics='v')
e = drawaxis(y=2:7,dir='l',tics='v')

// horizontal axis with strings displayed at tics positions
drawaxis(x=2:7,y=8,dir='u',tics='v',val='A'+string(1:6));
// vertical axis with strings displayed at tics positions
drawaxis(x=8,y=2:7,dir='r',tics='v',val='B'+string(1:6));

// horizontal axis given with a 'i' range.
e = drawaxis(x=[2,5,0,3],y=9,dir='u',tics='i');
e = drawaxis(x=9,y=[2,5,0,3],dir='r',tics='i',sub_int=5);

// horizontal axis again
drawaxis(x=2:7,y=4,dir='u',tics='v',fontsize=10,textcolor=9,ticscolor=7,seg=0,sub_int=20)
 ]]></programlisting>
        <scilab:image>
            plot2d(1:10,1:10,1,"020")
            drawaxis(x=2:7,y=4,dir='u',tics='v')
            drawaxis(x=2:7,dir='u',tics='v')
            drawaxis(x=2:7,dir='d',tics='v')

            drawaxis(x=[2,7,3],y=4,dir='d',tics='r')

            drawaxis(x=4,y=2:7,dir='r',tics='v')
            drawaxis(x=2,y=[2,7,3],dir='l',tics='r')
            drawaxis(y=2:7,dir='r',tics='v')
            drawaxis(y=2:7,dir='l',tics='v')

            drawaxis(x=2:7,y=8,dir='u',tics='v',val='A'+string(1:6));
            drawaxis(x=8,y=2:7,dir='r',tics='v',val='B'+string(1:6));

            drawaxis(x=[2,5,0,3],y=9,dir='u',tics='i');
            drawaxis(x=9,y=[2,5,0,3],dir='r',tics='i',sub_int=5);

            drawaxis(x=2:7,y=4,dir='u',tics='v',fontsize=10,textcolor=9,ticscolor=7,seg=0,sub_int=20)
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="plot_multiscaled">Multiscaled plots</link>
            </member>
            <member>
                <link linkend="axis_properties">axis_properties</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
