<?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:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="champ_properties">
    <refnamediv>
        <refname>champ properties</refname>
        <refpurpose>description of the 2D vector
            field entity properties
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>The Champ entity is a leaf of the graphics entities hierarchy. This
            entity defines the parameters for a 2D vector field.
        </para>
        <variablelist>
            <varlistentry>
                <term>visible: </term>
                <listitem>
                    <para>
                        This properties contains the <literal>visible</literal> property value
                        for the entity . It should be <literal>"on" </literal> or <literal>"off"</literal>
                        . If <literal>"on" </literal> the vector field is drawn, If
                        <literal>"off"</literal> the vector field is not displayed on the
                        screen.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>data: </term>
                <listitem>
                    <para>
                        This field defines a <literal>tlist</literal> data structure of type
                        <literal>"champdata"</literal> composed of a row and column indices of each
                        element : the x and y grid coordinates are contained respectively in
                        <literal>data.x </literal> and <literal>data.y</literal>. The complementary fields
                        named <literal>data.fx</literal> and <literal>data.fy</literal> are matrices which
                        describe respectively the <literal>x</literal> and <literal>y</literal> component
                        of the vector field at point <literal>(x(i),y(j))</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>user_data: </term>
                <listitem>
                    <para>This field can be use to store any scilab variable in the
                        champ data structure, and to retrieve it.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_style: </term>
                <listitem>
                    <para>
                        The <literal>line_style</literal> property value should be an integer in
                        [1 10]. 1 stands for solid, the other value stands for a selection of
                        dashes (see <link linkend="axes_properties">getlinestyle</link>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>thickness: </term>
                <listitem>
                    <para>This property is a positive real specifying the arrow width
                        in pixels. The displayed width is actually determined by rounding the supplied width
                        to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
                        value is considered.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>colored: </term>
                <listitem>
                    <para>
                        If this this property value is <literal>"on"</literal>, fields vectors
                        are drawn using a color proportional to the intensity of the
                        field.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>arrow_size: </term>
                <listitem>
                    <para>
                        This property is a double specifying the size of the arrow.
                        The value can be positive or negative:
                        <itemizedlist>
                            <listitem>
                                <para>
                                    <literal>arrow_size &lt; 0</literal>: the arrows size
                                    is proportional to the average norm of the vectors.
                                </para>
                            </listitem>
                            <listitem>
                                <para>
                                    <literal>arrow_size &gt; 0</literal>: the arrows size
                                    is proportional to the windows dimensions.
                                </para>
                            </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_state: </term>
                <listitem>
                    <para>
                        This field contains the <literal>clip_state</literal> property value for
                        the champ. It should be :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>"off"</literal> this means that the vector field is not
                                clipped
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"clipgrf"</literal> this means that the vector field is
                                clipped outside the Axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"on"</literal> this means that the vector field is clipped
                                outside the rectangle given by property clip_box.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_box: </term>
                <listitem>
                    <para>
                        This property contains the <literal>clip_box</literal> property. 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 vector field to display, however
                        <literal>clip_state</literal> property value will be changed.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>parent: </term>
                <listitem>
                    <para>This property contains the handle of the parent. The parent of the
                        2D vector field entity should be of the type <literal>"Axes"</literal> or
                        <literal>"Compound"</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
a = get("current_axes");   // get the handle of the newly created axes
a.data_bounds = [-10,-10 ; 10,10];
champ(-5:5, -5:5, rand(11,11), rand(11,11))

c = a.children
set(c, "colored","on", "thickness",2, "arrow_size",-1);
c.data    // display the tlist of type "champdata"
a.data_bounds = [-5,-5 ; 5,5];
 ]]></programlisting>
        <scilab:image><![CDATA[
        a=get("current_axes");
        a.data_bounds=[-10,-10;10,10];
        champ(-5:5,-5:5,rand(11,11),rand(11,11));
        c=a.children;
        c.colored="on";
        c.thickness=2;
        c.arrow_size=-1;
        a.data_bounds=[-5,-5;5,5];
        ]]></scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="delete">delete</link>
            </member>
            <member>
                <link linkend="champ">champ</link>
            </member>
            <member>
                <link linkend="graphics_entities">graphics_entities</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>line_style value 0 is obsolete, use 1 instead (both are equivalent for SOLID). Using value 0 will produce an error in Scilab 5.4.1.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
