<?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: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="axis_properties">
    <refnamediv>
        <refname>axis properties</refname>
        <refpurpose>description of the axis entity
            properties
        </refpurpose>
    </refnamediv>
    <refsection role="description">
        <title>Description</title>
        <para>The Axis entity is a leaf of the graphics entities hierarchy. This
            entity defines the parameters for axis scaling and appearance.
        </para>
        <variablelist>
            <varlistentry>
                <term>Axis properties</term>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term>parent: </term>
                            <listitem>
                                <para>This property contains the handle of the parent. The parent of
                                    the axis entity should be of the type <literal>"Axes"</literal> or
                                    <literal>"Compound"</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> . By default, the axis entity is visible, the
                                    value's property is <literal>"on"</literal>. If <literal>"off"</literal>, the
                                    axis is not drawn on the screen.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>tics_direction: </term>
                            <listitem>
                                <para>Specify the direction of the tics drawn under the horizontal
                                    axis and the vertical axis. The possible values of this property
                                    are:
                                </para>
                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            <literal>"top"</literal>. In this case, tics are drawn at the top
                                            of the horizontal axis.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>"bottom"</literal>. In this case, tics are drawn at the
                                            bottom of the horizontal axis.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>"left"</literal>. In this case, tics are going left on
                                            the vertical axis.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>"right"</literal>. In this case, tics are going right on
                                            the vertical axis.
                                        </para>
                                    </listitem>
                                </itemizedlist>
                                <para>
                                    The defaults values are <literal>"top"</literal> for the horizontal
                                    axis and <literal>"right"</literal> for vertical axis.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>xtics_coord: </term>
                            <listitem>
                                <para>This field represents the x-coordinate of the axis. It is a row
                                    vector containing values increasing from left to right which give
                                    tics positions for a horizontal axis. Other case, the entity is a
                                    vertical axis, this property contain a scale which defines the
                                    x-origin of the axis.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>ytics_coord: </term>
                            <listitem>
                                <para>This field represents the y-coordinate of the axis. It is a row
                                    vector containing values increasing from bottom to top which give
                                    tics positions for a vertical axis. Other case, the entity is a
                                    horizontal axis, this property contain a scale which defines the
                                    y-origin of the axis.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>tics_color: </term>
                            <listitem>
                                <para>The value of this properties is index of the color used to
                                    draw the axis'lines and tics.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>tics_segment: </term>
                            <listitem>
                                <para>This field contains a flag which controls the display of the
                                    base segment of the axis. The default is <literal>"on"</literal>, else
                                    if to not display it, the property takes <literal>"off"</literal> as
                                    value.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>tics_style: </term>
                            <listitem>
                                <para>This property describes how the tics are given. It is a string
                                    flag which can have these possible values:
                                </para>
                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            <literal>"v"</literal>. It's the default value, In this case,
                                            tics positions are given by the row factor
                                            <literal>xtics_coord</literal> for horizontal axis
                                            (<literal>ytics_coord</literal> for the vertical one).
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>"r"</literal>. In this case, tics positions are given by
                                            the vector <literal>[min,max,n] </literal> where n is the number of
                                            intervals.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>"i"</literal>. In this case the vector given tics
                                            positions is of size 4, <literal>[k1,k2,a,n]</literal> then values
                                            are increasing between <literal>k1*10^a</literal> and
                                            <literal>k2*10^a</literal>, n is the number of intervals.
                                        </para>
                                    </listitem>
                                </itemizedlist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>sub_tics: </term>
                            <listitem>
                                <para>This field sets the number of tics to draw between two main
                                    tics.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>tics_labels: </term>
                            <listitem>
                                <para>This field is a string matrix, which contains the strings to
                                    be drawn along the axis at tics positions.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>format_n: </term>
                            <listitem>
                                <para>This property is a character string which specifies the floating-point display format of the tics labels numbers,
                                    when relevant. It uses the format syntax of the C language printf function (for example <literal>"%.3f"</literal>).
                                    If equal to <literal>""</literal>, a default display format is used.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>labels_font_color: </term>
                            <listitem>
                                <para>This property determines the color of the tics labels.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>labels_font_size: </term>
                            <listitem>
                                <para>It is a scalar specifying the character size of tics labels.
                                    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>labels_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>fractional_font: </term>
                            <listitem>
                                <para>
                                    This property specifies whether ticks labels are 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>clip_state: </term>
                            <listitem>
                                <para>
                                    This field contains the <literal>clip_state</literal> property value
                                    for the arc. Clip_state value should be :
                                </para>
                                <itemizedlist>
                                    <listitem>
                                        <para>
                                            <literal>"off"</literal> this means that the axis is not
                                            clipped
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>"clipgrf"</literal> this means that the axis is clipped
                                            outside the Axes box.
                                        </para>
                                    </listitem>
                                    <listitem>
                                        <para>
                                            <literal>"on"</literal> this means that the axis is clipped
                                            outside the arc given by property clip_box.
                                        </para>
                                    </listitem>
                                </itemizedlist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>clip_box: </term>
                            <listitem>
                                <para>
                                    This field is to determinate the <literal>clip_box</literal>
                                    property. By Default its value should be an empty matrix if
                                    clip_state is "off". Other cases the vector <literal>[x,y,w,h]</literal>
                                    (upper-left point width height) defines the portions of the axis
                                    to display, however <literal>clip_state</literal> property value will be
                                    changed.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>user_data: </term>
                            <listitem>
                                <para>This field can be used to store any scilab variable in the axis
                                    data structure, and to retrieve it.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="examples">
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
a=get("current_axes");//get the handle of the newly created axes
a.data_bounds=[-1,-1;10,10];

drawaxis(x=2:7,y=4,dir='u');
a1=a.children(1)
a1.xtics_coord=[1 4 5  8 10];
a1.tics_color=2;
a1.labels_font_size=3;
a1.tics_direction="bottom";
a1.tics_labels= [" February" "May"  "june" "August"  "October"];

drawaxis(x=1.2:1:10,y=5,dir='u',textcolor=13);
a2=get("hdl")
a2.sub_tics=0;
a2.tics_segment="off";
a2.ytics_coord=4;

drawaxis(x=-1,y=0:1:7,dir='r',fontsize=10,textcolor=5,ticscolor=6,sub_int=10)
a3=get("hdl");
a3.tics_labels= 'B'  +string(0:7);
a3.tics_direction="left";
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="drawaxis">drawaxis</link>
            </member>
            <member>
                <link linkend="axes_properties">axes_properties</link>
            </member>
            <member>
                <link linkend="graphics_entities">graphics_entities</link>
            </member>
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
