<?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="xsetech">
    <refnamediv>
        <refname>xsetech</refname>
        <refpurpose>
            set the sub-window of a graphics window for plotting
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            xsetech(wrect, [frect, logflag])
            xsetech(wrect=[...], frect=[..], logflag="..", arect=[...])
            xsetech()
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>wrect</term>
                <listitem>
                    <para>
                        a vector of size 4, defining the sub-window to use.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>frect</term>
                <listitem>
                    <para>
                        a vector of size 4.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>logflag</term>
                <listitem>
                    <para>
                        a string of size 2 <literal>"xy"</literal>, where
                        <literal>x</literal> and <literal>y</literal> can be
                        <literal>"n"</literal> or <literal>"l"</literal>.
                        <literal>"n"</literal> stands for  normal and "l" stands
                        for logscale. <literal>x</literal> stands for the x-axis
                        and <literal>y</literal> stands for the y-axis.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>arect</term>
                <listitem>
                    <para>a vector of size 4.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <function>xsetech</function> is mainly used to set the sub-window of
            the graphics window which will be used for plotting. The sub-window
            is specified with the parameter <literal>wrect=[x,y,w,h]</literal>
            (upper-left point, width, height). The values in
            <varname>wrect</varname> are specified using proportion of
            the width or height of the current graphic window. For instance
            <literal>wrect=[0, 0, 1, 1]</literal> means that the whole graphics
            window will be used, and <literal>wrect=[0.5, 0, 0.5, 1]</literal>
            means that the graphics region will be the right half of the
            graphics window.
        </para>
        <para>
            <function>xsetech</function> also set the current graphics scales
            for 2D plotting and can be used in conjunction with graphics
            routines which request the current graphics scale (for instance
            <literal>strf="x0z"</literal> or <literal>frameflag=0</literal> in
            <function>plot2d</function>).
        </para>
        <para>
            <literal>frect=[xmin, ymin, xmax, ymax]</literal> is used to set the
            graphics scale and is just like the <varname>rect</varname> argument
            of <function>plot2d</function>. If <varname>frect</varname> is not
            given the current value of the graphic scale remains unchanged. the
            default value of <varname>rect</varname> is <literal>[0,0,1,1]</literal>
            (at window creation, when switching back to default value with
            <code>clf('reset')</code> or when clearing graphic recorded
            events <code>clf()</code>).
        </para>
        <para>
            <literal>arect=[x_left, x_right,y_up,y_down]</literal> is used to
            set the graphic frame inside the sub-window. The graphic frame is
            specified (like <varname>wrect</varname>) using proportion of the
            width or height of the current graphic sub-window.  Default value is
            <literal>1/8*[1,1,1,1]</literal>. If <varname>arect</varname> is not
            given, current value remains unchanged.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// To get a graphical explanation of xsetech parameters enter:
exec('SCI/modules/graphics/demos/xsetechfig.sce');

// Here xsetech is used to split the graphics window in two parts
// first xsetech is used to set the first sub-window
// and the graphics scale
xsetech([0,0,1.0,0.5],[-5,-3,5,3])
// we call plot2d with the "001" option to use the graphics scale
// set by xsetech
plot2d([1:10]',[1:10]',1,"001"," ")
// then xsetech is used to set the second sub-window
xsetech([0,0.5,1.0,0.5])
// the graphics scale is set by xsetech to [0,0,1,1] by default
// and we change it with the use of the rect argument in plot2d
plot2d([1:10]',[1:10]',1,"011"," ",[-6,-6,6,6])
 ]]></programlisting>
        <programlisting role="example"><![CDATA[
// Four plots on a single graphics window
clf()
set(gca(),"font_style",2,"font_size",0);
xsetech([0,0,0.5,0.5]);
plot3d()
xsetech([0.5,0,0.5,0.5]);
plot2d()
xsetech([0.5,0.5,0.5,0.5]);
grayplot()
xsetech([0,0.5,0.5,0.5]);
histplot()
// back to default values for the sub-window
xsetech([0,0,1,1])
 ]]></programlisting>
        <scilab:image>
            set(gca(),"font_style",2,"font_size",0);
            xsetech([0,0,0.5,0.5]);
            plot3d()
            xsetech([0.5,0,0.5,0.5]);
            plot2d()
            xsetech([0.5,0.5,0.5,0.5]);
            grayplot()
            xsetech([0,0.5,0.5,0.5]);
            histplot()
            xsetech([0,0,1,1])
        </scilab:image>

        <programlisting role="example"><![CDATA[
// One plot with changed arect
clf()
xsetech(arect=[0,0,0,0])
x=1:0.1:10;plot2d(x',sin(x)')
 ]]></programlisting>
        <scilab:image>
            xsetech(arect=[0,0,0,0])
            x=1:0.1:10;plot2d(x',sin(x)')
        </scilab:image>
        <programlisting role="example"><![CDATA[
clf()
xsetech(arect=[1/8,1/8,1/16,1/4])
x=1:0.1:10;plot2d(x',sin(x)')
clf()
 ]]></programlisting>
        <scilab:image>
            xsetech(arect=[1/8,1/8,1/16,1/4])
            x=1:0.1:10;plot2d(x',sin(x)')
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="subplot">subplot</link>
            </member>
            <member>
                <link linkend="isoview">isoview</link>
            </member>
            <member>
                <link linkend="replot">replot</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
