<?xml version="1.0" encoding="UTF-8"?>
<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="gridbag_constraints_properties">
    <refnamediv>
        <refname>Gridbag Constraints Properties</refname>
        <refpurpose>Description of the gridbag constraints set of properties.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            constraints = createConstraints("gridbag")
            constraints = createConstraints("gridbag", grid)
            constraints = createConstraints("gridbag", grid, weight)
            constraints = createConstraints("gridbag", grid, weight, fill)
            constraints = createConstraints("gridbag", grid, weight, fill, anchor)
            constraints = createConstraints("gridbag", grid, weight, fill, anchor, padding)
            constraints = createConstraints("gridbag", grid, weight, fill, anchor, padding, preferredsize)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>grid</term>
                <listitem>
                    <para>
                        <literal>[pos_x, pos_y, width, height]</literal> a 1-by-4 matrix of double, [0, 0, 0, 0] by default.
                    </para>
                    <para>
                        <literal>pos_x</literal> and <literal>pos_x</literal> are the coordinates of the element on a virtual grid.
                    </para>
                    <para>
                        <literal>width</literal> and <literal>height</literal> are the width and height of the element on the virtual grid.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>weight</term>
                <listitem>
                    <para>
                        <literal>[weight_x, weight_y]</literal> a 1-by-2 matrix of doubles, [0, 0] by default.
                    </para>
                    <para>The weights applied for the resize on either axes.</para>
                    <para>A larger value means the element will get more space during resize.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fill</term>
                <listitem>
                    <para>A string</para>
                    <para>{"none"} | "horizontal" | "vertical" | "both"</para>
                    <para>Indicates how to fill the available space during resize on either direction (or both).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>anchor</term>
                <listitem>
                    <para>A string</para>
                    <para>{"center"} | "upper" | "upper_right" | "right" | "lower_right" | "lower" | "lower_left" | "left" | "upper_left"</para>
                    <para>Tells where to anchor the element when it is smaller than the area it is nested in.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>padding</term>
                <listitem>
                    <para>
                        <literal>[pad_x, pad_y]</literal> a 1-by-2 matrix of doubles, [0 0] by default
                    </para>
                    <para>Padding between this element and elements around it.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>preferred_size</term>
                <listitem>
                    <para>
                        <literal>[p_size_x, p_size_y]</literal> a 1-by-2 matrix of doubles, [-1 -1] by default
                    </para>
                    <para>Preferred size in pixel when not constrained, used to avoid changing the size when resizing the nesting frame.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>constraints</term>
                <listitem>
                    <para>The created constraints.</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
          //Creates the figure with a gridbag layout
          f = figure( ...
          "dockable"        , "off",...
          "infobar_visible" , "off",...
          "toolbar"         , "none",...
          "menubar_visible" , "off",...
          "menubar"         , "none",...
          "default_axes"    , "off",...
          "layout"          , "gridbag",...
          "visible"         , "on");

         redf_grid   = [1, 1, 2, 1]; //Red frame is placed at 1x1 and is a 2x1 rectangle
         greenf_grid = [3, 1, 1, 2]; //Green frame is at 3x1 and is a 1x2 rectangle
         bluef_grid  = [1, 2, 1, 1]; //Blue frame is at 2x1 and is a 1x1 rectangle
         yelf_grid   = [1, 3, 2, 2]; //Yellow frame is at 1x3 and is a 2x2 rectangle
         magf_grid   = [3, 4, 1, 1]; //Magenta frame is at 3x4 and is a 1x1 rectangle
         cyanf_grid  = [2, 2, 1, 1]; //Cyan is at 2x2 and is a 1x1 rectangle
         whitf_grid  = [3, 3, 1, 1]; //White is at 3x3 and is a 1x1 rectangle

         c = createConstraints("gridbag",[1, 1, 1, 1], [1, 1], "both", "center", [0, 0], [50, 50]);

         c.grid = redf_grid;
         u_grid1 = uicontrol(f , ...
         "style"               , "frame"                     , ...
         "backgroundcolor"     , [1 0 0]                     , ...
         "constraints"         , c);

         sleep(500);
         c.grid = greenf_grid;
         c.weight = [0.1,1]; //Last column will fill horizontal space 10 times less thanother columns
         u_grid2 = uicontrol(f , ...
         "style"               , "frame"                     , ...
         "backgroundcolor"     , [0 1 0]                     , ...
         "constraints"         , c);

         sleep(500);
         c.grid = bluef_grid;
         c.weight = [1,1];
         c.fill = "none" //This will force the blue square to be at the preferred size
         u_grid3 = uicontrol(f , ...
         "style"               , "frame"                     , ...
         "backgroundcolor"     , [0 0 1]                     , ...
         "constraints"         , c);

         sleep(500);
         c.grid = cyanf_grid;
         c.fill = "vertical" // this will fill the empty space with cyan vertically
         c.anchor = "right" //this will position the cyan stripe on the right
         c.padding = [100,0] //this will extend the cyan stripe horizontally up to 100 pixel if space is available
         u_grid1 = uicontrol(f , ...
         "style"               , "frame"                     , ...
         "backgroundcolor"     , [0 1 1]                     , ...
         "constraints"         , c);

         sleep(500);
         c.grid = yelf_grid;
         c.fill = "both";
         c.anchor ="center";
         c.padding = [0,0];
         u_grid4 = uicontrol(f , ...
         "style"               , "frame"                     , ...
         "backgroundcolor"     , [1 1 0]                     , ...
         "constraints"         , c);

         sleep(500);
         c.grid = whitf_grid;
         c.weight = [0.1,1]
         u_grid1 = uicontrol(f , ...
         "style"               , "frame"                     , ...
         "backgroundcolor"     , [1 1 1]                     , ...
         "constraints"         , c);

         sleep(500);
         c.grid = magf_grid;
         c.weight = [0.1,1]
         u_grid5 = uicontrol(f , ...
         "style"               , "frame"                     , ...
         "backgroundcolor"     , [1 0 1]                     , ...
         "constraints"         , c);
         ]]></programlisting>
    </refsection>
     <refsection>
        <title>Description</title>
        <para>
            This functions creates the gridbag constraints to set the uicontrols <literal>constraints</literal> attribute.
        </para>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="layout">layout</link>
            </member>
            <member>
                <link linkend="uicontrol">uicontrol</link>
            </member>
            <member>
                <link linkend="uicontrol_properties">uicontrol_properties</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>
                    Function <function>createBorder</function> introduced.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
