<?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) 2013, 2016 - Samuel GOUGEON
 *
 * This file must be used under the terms of the CeCILL.
 * This source file is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at
 * https://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
    xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
    xmlns:scilab="http://www.scilab.org" xml:id="replot" xml:lang="pt">
    <refnamediv>
        <refname>replot</refname>
        <refpurpose>reformula a área de exibição de um ou mais gráficos
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>
            replot()
            replot(area)
            replot(idAxes)
            replot(area, idAxes)
            replot(.., tight_limits)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>area</term>
                <listitem>
                    <para>
                        matrix <literal>[xmin xmax ; ymin ymax]</literal> or
                        <literal>[xmin xmax ; ymin ymax ; zmin zmax]</literal>, or row
                        <literal>[xmin ymin xmax ymax]</literal> or
                        <literal>[xmin ymin zmin xmax ymax zmax]</literal>: new bounds of the area
                        to be reframed.
                        <note>
                            <itemizedlist>
                                <listitem>
                                    <literal>%nan</literal> can be used to keep a bound as is.
                                </listitem>
                                <listitem>
                                    <literal>%inf</literal> can be used to set
                                    a bound to the position of the most marginal
                                    graphical component existing in the axes,
                                    for the considered direction.
                                </listitem>
                            </itemizedlist>
                        </note>
                        The default area is [%inf %inf %inf %inf]
                        for a 2D axes, or [%inf %inf %inf %inf %inf %inf] for a
                        3D one.
                    </para>
                    <para>If N axes are identified in <literal>idAxes</literal>,
                        <literal>area</literal> may be a matrix with N rows and
                        4 or 6 columns. The row #i is then related to the axes #i
                         of <literal>idAxes</literal>.
                        If <literal>area</literal> is only a vector of 4 or 6
                        bounds, these ones are used for all axes to be reframed.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>idAxes</term>
                <listitem>
                    <para>Vector of graphic handles, expected to be of Axes type
                          or to have direct children of type Axes, such as Figures
                          or some frame uicontrols.
                          <literal>idAxes</literal> specifies direct or children
                          Axes to crop. If no axes is found, nothing is done.
                    </para>
                    <para>By default, the current Axes is considered.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>tight_limits</term>
                <listitem>
                    <para>
                    Single word <literal>"tight"</literal> or <literal>"on"</literal> or
                    <literal>"off"</literal>, or vector of 2 (in 2D)
                    or 3 (in 3D) words <literal>"tight"</literal> or <literal>"on"</literal> or
                    <literal>"off"</literal>. If a single word is provided,
                    it is used for every axis. This option forces the
                    <literal>.tight_limits</literal> attribute of considered
                    axes to the specified <literal>"on"</literal> or
                    <literal>"off"</literal> values. By default,
                    current limits modes are unchanged.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            <literal>replot</literal> is used to reframe the (set of) axes specified
            with <literal>idAxes</literal> -- or by default the current axes --
            with new boundaries defined in 2D by
            <literal>[xmin xmax ; ymin ymax]</literal> or
            <literal>[xmin xmax ; ymin ymax ; zmin zmax]</literal>,
            or in 3D by
            <literal>[xmin ymin xmax ymax]</literal> or
            <literal>[xmin ymin zmin xmax ymax zmax]</literal>.
        </para>
        <para>
            It changes the <literal>data_bounds</literal> attribute of processed axes.
        </para>
        <para>
            When a specified bound is infinite (%inf and -%inf are equivalent),
            <literal>replot</literal> looks for the most marginal graphical object
            and sets the actual related bound to its position, taking also
            objects sizes into account. This ensures not clipping any object
            that would be beyond the targeted side of the axes.
        </para>
        <para>
            When the <literal>tight_limits</literal> option is provided,
            its value is assigned to the <literal>.tight_limits</literal>
            attribute of each considered axes, in an axis-wise way.
        </para>
        <important>
            gca() always refers to the same axes before and after calling replot(..).
        </important>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <programlisting role="example"><![CDATA[
// primeiro exemplo
x=[0:0.1:2*%pi]';
plot2d(x,sin(x))
replot([-1,-1,10,2])
 ]]></programlisting>
        <scilab:image>
            x=[0:0.1:2*%pi]';
            plot2d(x,sin(x))
            replot([-1,-1,10,2])
        </scilab:image>

        <programlisting role="example"><![CDATA[
// segundo exemplo
close(winsid());
plot() // plot demo
f=gcf();
replot([-1,-1,10,2],f.children(1)) // especificando o valor do manipulador dos eixos
replot([-3,-2,8,4],f.children(2))
 ]]></programlisting>
        <scilab:image>
            close(winsid());
            plot()
            f2=gcf();
            replot([-1,-1,10,2],f2.children(1))
            replot([-3,-2,8,4],f2.children(2))
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Os fronteiras indicadas pelo valor %nan não são alterados:
x = linspace(0,360,200).';
clf
plot2d(x,[sind(x) tand(x)])
ax = gca();
ax.data_bounds              // Fronteiras iniciais
replot([%nan,-10,%nan,10])  // Ymin e Ymax só são modificados
ax.data_bounds              // novas fronteiras
     ]]></programlisting>
        <para></para>
        <programlisting role="example"><![CDATA[
// 3D Fronteiras Z também pode ser modificadas :
clf
x = linspace(-4,4,100);
X = meshgrid(x);
R = (X-0.5).^2 + (X.'+0.7).^2;
Z = sinc(R);
surf(x-0.5,x+0.7,Z)
f = gcf();
f.color_map = autumn(100);
ax = gca();
ax.data_bounds
sleep(3000)
replot([-5 0 -0.4 0 5 0.5])
ax.data_bounds
     ]]></programlisting>
        <para></para>
        <programlisting role="example"><![CDATA[
// Diversos gráficos podem ser cortadas simultaneamente :
clf
x = linspace(-%pi,%pi,400);
subplot(2,2,1)
plot2d(x,sin(1 ./sqrt(abs(x))))
ax1 = gca();
subplot(2,2,2)
plot2d(x,sinh(sqrt(abs(x))))
subplot(2,1,2)
plot2d(x,cos(1 ./sqrt(abs(x))))
ax2 = gca();
sleep(4000)
f = gcf();
replot([-1 %nan 1.5 %nan], [ax1 ax2])
      ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="zoom_rect">zoom_rect</link>
            </member>
            <member>
                <link linkend="rubberbox">rubberbox</link>
            </member>
            <member>
                <link linkend="axes_properties">axes_properties</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>Histórico</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>
                            <para>Extensão para o 3D</para>
                        </listitem>
                        <listitem>
                            <para>Vários coordenadas gráficos podem agora ser redimensionadas simultaneamente</para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>%nan</literal> pode ser usado para manter um limite como está.
                            </para>
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>
                            Handles of frame uicontrols having Axes children are
                            now accepted.
                        </listitem>
                        <listitem>
                            %inf can now be used to set a bound to the position
                            of most marginal contents.
                        </listitem>
                        <listitem>
                            replot() as replot([%inf %inf %inf %inf]) is added.
                        </listitem>
                        <listitem>
                            Option tight_limits added.
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
