<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Serge Steer
 *
 * 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="newaxes">
    <refnamediv>
        <refname>newaxes</refname>
        <refpurpose>Creates a new Axes entity</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            a = newaxes()
            a = newaxes(h)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>h</term>
                <listitem>
                  <para>
                    Optional handle of the graphic parent of the new axes,
                    of type <literal>Figure</literal> or
                    <literal>Uicontrol</literal> of style <literal>Frame</literal>.
                    By default, the current figure is used.
                  </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>a</term>
                <listitem>
                    <para>Handle on the newly created Axes entity</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>newaxes()</literal> is used to create a new <literal>Axes</literal> entity (see
            <link linkend="graphics_entities">graphics_entities</link>) in the current figure or in
            the given figure or uicontrol frame.
        </para>
        <para>
            The properties of this entity are inherited from the <literal>default_axes</literal>
            entity (see <link linkend="gda">gda</link>)
        </para>
        <para>
            <literal>newaxes(h)</literal> creates the axes in the frame
            <link linkend="uicontrol">uicontrol</link> or figure whose handle is <literal>h</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
clf()
a1 = newaxes();
a1.axes_bounds = [0,0,1.0,0.5];
t = 0:0.1:20;
plot(t,acosh(t),'r')
a2 = newaxes();
a2.axes_bounds = [0,0.5,1.0,0.5];
x = 0:0.1:4;
plot(x,sinh(x))
legend('sinh')

sca(a1); //make first axes current
plot(t, asinh(t), 'g')
legend(['acosh','asinh'])
 ]]></programlisting>
        <para>
            The following example uses <literal>newaxes(h)</literal>
        </para>
        <programlisting role="example"><![CDATA[
// Create a new figure
f = figure("layout", "gridbag", ...
    "toolbar", "none", ...
    "menubar", "none", ...
    "backgroundcolor", [1 1 1]);

// Create the frames where each graph is put
c = createConstraints("gridbag", [1 1 1 1], [1 1], "both");
top_left = uicontrol(f, "style", "frame","constraints", c);

c.grid = [2 1 1 1];
top_right = uicontrol(f, "style", "frame", "constraints", c);

c.grid = [1 2 2 2];
bottom = uicontrol(f, "style", "frame", "constraints", c);

// Create the axes in each frame
a_tl = newaxes(top_left);
a_tr = newaxes(top_right);
a_bt = newaxes(bottom);

// Plot in the frames
X = (1:100) ./ 50;
plot(a_tl, X, X, "r");
plot(a_tr, X, cos(2 * %pi * 3 * X), "g");
plot(a_bt, X, exp(X), "b");

title(a_tl, "a line");
title(a_tr, "a cosine");
title(a_bt, "the exponential");
    ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="plot_multiscaled">Multiscaled plots</link>
            </member>
            <member>
                <link linkend="subplot">subplot</link>
            </member>
            <member>
                <link linkend="xsetech">xsetech</link>
            </member>
            <member>
                <link linkend="gda">gda</link>
            </member>
            <member>
                <link linkend="sca">sca</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revdescription>newaxes(h) can target a uicontrol frame or a given figure.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
