<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 *
 * Copyright (C) INRIA - Djalel Abdemouche
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2019 - Samuel GOUGEON
 *
 * 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="set">
    <refnamediv>
        <refname>set</refname>
        <refpurpose>
            set properties of some graphic objects or uimenus or uicontrol interactive components
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            set(h, prop,val)            // h(prop) = val,  h.prop = val
            set(h, prop,val, prop2,val2, ..)
            set(tagsPath, prop,val)
            set(tagsPath, prop,val, prop2,val2, ..)

            set('current_figure', fig)  // scf(fig)
            set('current_axes', axes)   // sca(axes)
            set('current_entity', h)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>h</term>
                <listitem>
                    Handle of the graphic entity whose properti(es) must be set.
                    <literal>h</literal> can be a vector of handles. In this case, set(..) modifies
                    the property for all <literal>h</literal> components.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>tagsPath</term>
                <listitem>
                    Case-sensitive character string providing the tag or the tags-path leading
                    to the graphic component to process.
                    This path is made of the strings recorded in the <literal>.Tag</literal>
                    property of the parent figure and of the chain of its children down to
                    the target, like <literal>"figuretag"</literal> to target the figure
                    with figure.tag=="figuretag", or <literal>"figuretag/entitytag"</literal>
                    to target one of its children (as for an axes, a main uimenu item, a
                    block of legends,..), or <literal>"figuretag/entity1tag/entity2tag"</literal>,
                    etc. Wildcards can also be used for multi-paths search.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop, prop2, ...</term>
                <listitem>
                    Scalar characters strings: Case-insensitive name of the properties to set.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>val, val2, ...</term>
                <listitem>
                    value to assign to the property. Its type depends on the considered property.
                    If <varname>h</varname> and <varname>val</varname> are vectors or matrices
                    of same size, the multiple settings are done in an element-wise way.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fig</term>
                <listitem>
                    Handle of a graphical figure.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>axes</term>
                <listitem>
                    Handle of an axes.
                    <para/>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            This function can be used to modify the value of a specified property from a graphics
            entity or a GUI object. In this case it is equivalent to use the dot operator on a handle.
            For example, <literal>set(h,"background",5)</literal> is equivalent to
            <literal>h.background = 5</literal>.
        </para>
        <para>
            To get the list of all existing properties, please see the pages of
            <link linkend="graphics_entities">graphics_entities</link> or
            <link linkend="uicontrol_properties">uicontrol_properties</link> for User Interface
            objects.
        </para>
        <para>
            <emphasis role="bold">set(h, prop, val)</emphasis> or
            <emphasis role="bold">h(prop) = val</emphasis> or
            <emphasis role="bold">h.prop = val</emphasis>
            sets the property <varname>prop</varname> of the handle <varname>h</varname> to the
            value <varname>val.</varname>.
        </para>
        <para>
            When <varname>h</varname> is a matrix of handles,
            <itemizedlist>
                <listitem>
                    if <varname>val</varname> is a matrix of same size: assignments are done in a
                    element-wise way: <literal>set(h, prop, val)</literal> sets
                    <literal>h(1)(prop)=val(1)</literal>, <literal>h(2)(prop)=val(2)</literal>, ...,
                    <literal>h($)(prop)=val($)</literal>.
                    Most often, the simpler syntax <literal>h(tag) = val</literal> does it as well.
                </listitem>
                <listitem>
                    otherwise: The same and whole <varname>val</varname> value (that may be scalar
                    or not) is assigned to every <literal>h(i)(prop)</literal> component.
                    <warning>
                        If <varname>val</varname> is a cell array of same size as
                        <varname>h</varname>, it is assigned as a whole as well. For instance,
                        <literal>set([gcf() gca()], "user_data", {"Text", 1})</literal> will do
                        <literal>gcf().user_data = {"Text", 1}, gca().user_data = {"Text", 1}</literal>,
                        not <literal>gcf().user_data = "Text", gca().user_data = 1</literal>.
                    </warning>
                </listitem>
            </itemizedlist>
        </para>
        <para>
            With this syntax, <varname>prop</varname> can't be an array of property names.
            To set multiple properties with a single call to <literal>set(..)</literal>, the
            following syntax must be used.
        </para>
        <para>
            <emphasis role="bold">set(h, prop1,val1, prop2,val2, ..)</emphasis>
            sets the property <varname>prop1</varname> of the handle(s) <varname>h</varname> to the
            value <varname>val1</varname>, its or their property <varname>prop2</varname> to the
            value <varname>val2</varname>, etc. If <varname>h</varname> and some
            <varname>val#</varname> are matrices of same size, element-wise assignments are done
            for the related <varname>prop#</varname> properties, as already described for the
            <literal>set(h, prop, val)</literal> syntax.
        </para>
        <para>
            <emphasis role="bold">set(tagsPath, prop,val)</emphasis> or
            <emphasis role="bold">set(tagsPath, prop,val, prop2,val2, ..)</emphasis>
            identifies the targeted component(s) through their .tag property according to
            <varname>tagsPath</varname>, instead of through their handle,
            and then sets its properties.
        </para>
        <para>
            In case of multiple entities matching the path, only the first one is processed.
            Conversely, finding no matching entity yields an error.
        </para>
        <para>
            <emphasis role="bold">set("current_figure", fig)</emphasis>
            sets the figure of handle <varname>fig</varname> as the active figure. This syntax
            is equivalent to <literal>scf(fig)</literal> or <literal>scf(figure_id)</literal>,
            that are shorter and may be prefered.
        </para>
        <para>
            <emphasis role="bold">set("current_axes", axes)</emphasis>
            sets the axes of handle <varname>axes</varname> as the active one. This syntax
            is equivalent to <literal>sca(axes)</literal> that is shorter and may be prefered.
        </para>
        <para>
            <emphasis role="bold">set("current_entity", h)</emphasis>
            sets the graphical component whose <literal>h(1)</literal> is the handle as the
            current component, as returned by <literal>gce()</literal>. If <varname>h</varname>
            is a vector of handles, other components <literal>h(2:$)</literal> are ignored.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            <programlisting role="example"><![CDATA[
gda().auto_clear = "off";
clf
// Example with a Plot 2D
x = [-.2:0.1:2*%pi]';
plot2d(x-.3, [sin(x-1) cos(2*x)], [1 2] );
a = gca();
p1 = a.children.children(1);
p2 = a.children.children(2);

// set the named properties to the specified values on the objects
p2.thickness = 2;
set(p2, "foreground",13, "polyline_style",2);
a.y_location = "middle";
a.tight_limits = "on";
set(a, "box","off", "sub_tics",[7 0]);
set(p1, "mark_mode","on", "mark_style",3);

plot2d(x-2,x.^2/20);
p3 = a.children(1).children;
set([a p1 p2 p3], "foreground",5);
         ]]></programlisting>
        </para>
        <para>
        With a vector of handles:
        </para>
        <programlisting role="example"><![CDATA[
// With distinct element-wise inputs:
clf, plot2d()
[gcf() gca()].tag
set([gcf() gca()], "tag", ["myFigure" "myAxes"]);
[gcf() gca()].tag
     ]]></programlisting>
        <screen><![CDATA[
--> [gcf() gca()].tag
 ans  =
!  !
!  !

--> set([gcf() gca()], "tag", ["myFigure" "myAxes"]);

--> [gcf() gca()].tag
 ans  =
!myFigure  !
!myAxes    !
]]></screen>
        <para/>
        <programlisting role="example"><![CDATA[
// With the same input for all recipients:
clf, plot()
curves = gce().children;
set([gca() ; curves], "thickness", 2);
curves(1:20).thickness = 1; // shorter than set(curves(1:20), "thickness", 1)
     ]]></programlisting>
        <para>
            Using a tagsPath :
        </para>
        <para>
        <programlisting role="example"><![CDATA[
f = figure("dockable", "off", "menubar", "none", "toolbar", "none", "infobar_visible", "off", "tag", "mainfig");
frameHandle = uicontrol("parent", f, "style", "frame", "position", [200 200 190 100], "tag", "myframe");
btnHandle = uicontrol("parent", frameHandle, "position", [20 20 150 30], "string", "button", "tag", "example");

set("mainfig/myframe/example", "string", "complete path");
get("mainfig/myframe/example", "string")
set("mainfig/*/example", "string", "wildcard path");
get("mainfig/*/example", "string")
set("myframe/example", "string", "partial path");
get("myframe/example", "string")
     ]]></programlisting>
        </para>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="scf">scf</link>
            </member>
            <member>
                <link linkend="sdf">sdf</link>
            </member>
            <member>
                <link linkend="sca">sca</link>
            </member>
            <member>
                <link linkend="sda">sda</link>
            </member>
            <member>
                <link linkend="delete">delete</link>
            </member>
            <member>
                <link linkend="copy">copy</link>
            </member>
            <member>
                <link linkend="move">move</link>
            </member>
            <member>
                <link linkend="graphics_entities">graphics_entities</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>
                            First input argument can now be a path pointing to the graphic entity.
                        </listitem>
                        <listitem>
                            Multiple property setting is now available at once.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
