<?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: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="polyline_properties">
    <refnamediv>
        <refname>polyline properties</refname>
        <refpurpose>description of the Polyline
            entity properties
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>The Polyline entity is a leaf of the graphics entities hierarchy. This
            entity defines the parameters for polylines.
        </para>
        <variablelist>
            <varlistentry>
                <term>parent: </term>
                <listitem>
                    <para>This field contains the handle of the parent. The parent of the
                        polyline entity should be of the type <literal>"Axes"</literal> or
                        <literal>"Compound"</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>children: </term>
                <listitem>
                    <para>
                        This property contains a vector with the <literal>children</literal> of
                        the handle. However, polyline handles currently do not have any
                        <literal>children</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>visible: </term>
                <listitem>
                    <para>
                        This field contains the <literal>visible</literal> property value for
                        the entity . It should be <literal>"on" </literal> or <literal>"off"</literal> .
                        By default, the polyline is visible, the value's property is
                        <literal>"on" </literal>. If <literal>"off"</literal> the polyline is not drawn on
                        the screen.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>data: </term>
                <listitem>
                    <para>This field contains the values for the x and y coordinates.
                        Component Z is to be added in the case of three-dimensional axes. It
                        is a two (three) column matrix <literal>[x,y,[z]]</literal> of points.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>closed: </term>
                <listitem>
                    <para>This field determines whether the polyline is closed or not: its
                        value can be <literal>"on"</literal> or <literal>"off"</literal> (no default
                        value, it depends on the primitive used to create the polyline).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_mode: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>line_mode</literal> property
                        value for the polyline. Its value should be <literal>"on" </literal>(line
                        drawn) or <literal>"off"</literal> (no line drawn).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fill_mode: </term>
                <listitem>
                    <para>
                        If the <literal>polyline_style</literal> field is different of 5, fill
                        the background of the curve with color defined by the
                        <literal>background</literal> property.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_style: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>line_style</literal>
                        property value for Segs, Arcs, Rectangle and Polyline objects.
                        <literal>line_style</literal> selects the type of line to be used to
                        draw lines . Its value should be an integer in [1 10]. 1
                        stand for solid, the other values stand for a selection of dashes
                        (dash, dash dot, longdash dot, bigdash dot, bigdash longdash, dot, double dot, longblank dot, bigblank dot).
                        See example below.
                    </para>
                    <scilab:image>
                        plot2d([1 10], [1 1]'*(1:10), 2*ones(1,10));
                        a = gca();
                        a.children.children.line_style = (1:10)';
                        a.children.children.thickness = 2;
                        set(a, "axes_visible",["off" "on" "off"], "sub_ticks",[1 0]);
                        a.margins(1) = 0.15;
                        a.y_ticks=tlist(["ticks"  "locations"  "labels"],1:10,msprintf("%d\n",(10:-1:1)')')
                        ylabel("line_style value", "fontsize", 3)
                        gcf().axes_size = [300 185];
                    </scilab:image>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>thickness: </term>
                <listitem>
                    <para>This property is a positive real specifying the line 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>arrow_size_factor: </term>
                <listitem>
                    <para>This integer allows to set the size of arrows drawn on the
                        polyline. The actual size of arrows is the product of the
                        <literal>thickness</literal> and the size factor.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>polyline_style: </term>
                <listitem>
                    <para>This property sets several polyline drawing mode:</para>
                    <itemizedlist>
                        <listitem>
                            <para>If the value is 0 or 1 lines are drawn between two
                                consecutives points.
                            </para>
                        </listitem>
                        <listitem>
                            <para>If the value is 2 the polyline produces a staircase plot. Two
                                consecutives points are linked by a horizontal line followed by a
                                vertical line.
                            </para>
                        </listitem>
                        <listitem>
                            <para>If the value is 3 the polyline produces a bar plot. For each
                                given point (x,y) a vertical line is drawn from (x,y) to
                                (x,0).
                            </para>
                        </listitem>
                        <listitem>
                            <para>If the value is 4 arrows are drawn between two consecutives
                                points.
                            </para>
                        </listitem>
                        <listitem>
                            <para>If the value is 5 the polyline is filled (patch).</para>
                        </listitem>
                        <listitem>
                            <para>If the value is 6 the polyline is a Matlab-like bar object.
                                The properties <literal>bar_shift</literal> and <literal>bar_width</literal>
                                command its appearance.
                            </para>
                        </listitem>
                    </itemizedlist>
                    <para>
                        <inlinemediaobject>
                            <imageobject>
                                <imagedata fileref="../../images/polyline_style.svg"/>
                            </imageobject>
                        </inlinemediaobject>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>foreground: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>foreground</literal> property
                        used to draw the polyline. Its value should be a color index (relative
                        to the current colormap).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>background: </term>
                <listitem>
                    <para>This field contains the color used to fill the background of the
                        polyline. Its value should be a color index (relative to the current
                        colormap).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>interp_color_vector: </term>
                <listitem>
                    <para>This field contains the vector of color indices used to fill in
                        the polyline when the <literal>interp_color_mode</literal> property is set
                        to <literal>"on"</literal>. It defines the intervals of colormap indices
                        used to fill each segment. For instance, the first segment will be
                        filled by every colors whose index is between the first two elements
                        of the vector. It is only applicable if the polyline is defined by 3 or
                        4 points. Therefore, the size of the vector must match this
                        dimension.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>interp_color_mode: </term>
                <listitem>
                    <para>This field determines if we are using the interpolated shading
                        mode to fill the polyline : its value can be <literal>"on"</literal> or
                        <literal>"off"</literal>. Note that an <literal>interp_color_vector</literal> must
                        be defined before switching to "on" value (see above).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_mode: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>mark_mode</literal> property
                        value for the polyline. Its value should be <literal>"on"</literal> (marks
                        drawn) or <literal>"off"</literal> (no marks drawn).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_style: </term>
                <listitem>
                    <para>
                        The <literal>mark_style</literal> property value is used to select the
                        type of mark to use when <literal>mark_mode</literal> property is
                        <literal>"on"</literal>. The value should be an integer in <literal>[0 20]</literal> which
                        stands for: dot, plus, cross, star, filled diamond, diamond, triangle
                        up, triangle down, diamond plus, circle, asterisk, square, triangle right,
                        triangle left, pentagram, triangle up/down/right/left centered on the tip, horizontal line (minus), vertical line.
                        The figure below shows the aspects of the marks depending on the <literal>mark_style</literal>
                        and the <literal>mark_foreground</literal> and <literal>mark_background</literal> properties.
                    </para>
                    <para>
                        <inlinemediaobject>
                            <imageobject>
                                <imagedata fileref="../../images/marks.svg"/>
                            </imageobject>
                        </inlinemediaobject>
                        <!-- Scilab code to generate marks.svg -->
                        <!-- Cannot be generated using scilab:image tag since referenced in other pages (build order matters) -->
                        <!--
                            function plotDot(coord, style, fg, bg)
                                plot(coord(1), coord(2));
                                e = gce().children(1);
                                e.mark_size = 15;
                                e.mark_style = style;
                                e.mark_foreground = fg
                                e.mark_background = bg
                            endfunction

                            f = figure("visible", "off", "background", -2, "axes_size", [800 125]);
                            for i = 0:20
                                if log10(i) >= 1 then
                                    xnumb((i+1)*25-6, 13, i);
                                else
                                    xnumb((i+1)*25-3, 13, i);
                                end
                                plotDot([(i+1)*25 10], i, 1, 0);
                                plotDot([(i+1)*25 5], i, 2, 7);
                            end

                            a = gca();
                            a.axes_visible = "off";
                            a.margins = [0 0 0 0];
                            a.data_bounds = [0 0; 550 25];
                            a.margins = [0,0,-0.25,0];
                            a.tight_limits(1) = "on";
                            f.visible = "on";

                            xs2svg(f, "SCI/modules/graphics/help/images/marks.svg")
                        -->
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_size_unit: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>mark_size_unit</literal>
                        property value. If <literal>mark_size_unit</literal> is set to
                        <literal>"point"</literal>, then the <literal>mark_size</literal> value is
                        directly given in points. When <literal>mark_size_unit</literal> is set to
                        <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed relative
                        to the font size array: therefore, its value should be an integer in
                        [0 5] which stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt. Note that
                        <link linkend="plot2d">plot2d</link> and pure scilab functions use
                        <literal>tabulated</literal> mode as default ; when using <link linkend="plot">plot</link>
                        function, the <literal>point</literal> mode is automatically enabled.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_size: </term>
                <listitem>
                    <para>
                        This property specifies the size of the marks displayed when the
                        <literal>mark_mode</literal> property is <literal>"on"</literal>.
                        If its value is scalar, the same mark size is set for all points of the curve.
                        Otherwise it must be a row with as many elements as there are points in the curve.
                        The type of values depends on the <literal>mark_size_unit</literal> property.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_foreground: </term>
                <listitem>
                    <para>
                        This property specifies the color of the edges or details of marks. Acceptable
                        values are indices of colors in the current figure's colormap, or -2 for white,
                        -1 for black, or 0 for transparent edges. If its value is scalar, the same
                        specified color is used for the marks of all points of the curve.
                        Otherwise it must be a row with as many elements as there are points in the curve.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_background: </term>
                <listitem>
                    <para>
                        This property specifies the color filling the background of marks. Acceptable
                        values are indices of colors in the current figure's colormap, or -2 for white,
                        -1 for black, or 0 for transparent edges. If its value is scalar, the same
                        specified color is used for the marks of all points of the curve.
                        Otherwise it must be a row with as many elements as there are points in the curve.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_offset: </term>
                <listitem>
                    <para>
                        This field contains the <literal>mark_offset</literal> property
                        value which is the offset to use to draw the first mark. Its value should be an integer
                        greater or equal to 0 (default value is 0).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_stride: </term>
                <listitem>
                    <para>
                        This field contains the <literal>mark_stride</literal> property
                        value which is the stride to use to draw the marks (i.e. stride-1 points are skipped
                        between two consecutive marks). Its value should be integer greater or equal to 1 (default value is 1).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x_shift: </term>
                <listitem>
                    <para>This field contains the offset computed by a call to the
                        <link linkend="bar">bar</link> function (or re-computed by a call to
                        <link linkend="barhomogenize">barhomogenize</link>) and is used to perform a nice vertical bar
                        representation. Note that this offset is also taken into account for
                        all the other <literal>polyline_style</literal>. The unit is expressed in
                        user coordinates.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y_shift: </term>
                <listitem>
                    <para>This field contains the offset computed by a call to the
                        <link linkend="bar">bar</link> function (or re-computed by a call to
                        <link linkend="barhomogenize">barhomogenize</link>) and is used to perform a nice horizontal
                        bar representation. Note that this offset is also taken into account
                        for all the other <literal>polyline_style</literal>. The unit is expressed
                        in user coordinates.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>z_shift: </term>
                <listitem>
                    <para>This field contains the offset the user may specify. Note that
                        this offset is taken into account for all the
                        <literal>polyline_style</literal>. The unit is expressed in user
                        coordinates.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>bar_width: </term>
                <listitem>
                    <para>This field determines the width of the selected polyline when its
                        <literal>polyline_style</literal> is set to bar mode (case 6) : the unit is
                        expressed in user coordinates.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_state: </term>
                <listitem>
                    <para>
                        This field contains the <literal>clip_state</literal> property value for
                        the polyline. It should be :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>"off"</literal> this means that the polyline is not
                                clipped.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"clipgrf"</literal> this means that the polyline is clipped
                                outside the Axes box.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"on"</literal> this means that the polyline is clipped
                                outside the rectangle given by property clip_box.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_box: </term>
                <listitem>
                    <para>
                        This field is to determinate the <literal>clip_box</literal> property.
                        By Default 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 polyline to display, however
                        <literal>clip_state</literal> property value will be changed.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>user_data: </term>
                <listitem>
                    <para>This field can be use to store any scilab variable in the polyline
                        data structure, and to retrieve it.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>datatips: </term>
                <listitem>
                    <para>
                        This property contains a vector of the <literal>datatips</literal> handles related to the polyline.
                        However, polyline handles currently do not have any <literal>children</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>datatip_display_mode:</term>
                <listitem>
                    <para>
                        The value can be one of the following:
                        <itemizedlist>
                          <listitem>
                            <literal>"always"</literal>: the datatip is always displayed (default mode).
                          </listitem>
                          <listitem>
                            <literal>"mouseclick"</literal>: clicking on the anchor of the datatip
                             on the line toogles its display. The anchor is always displayed.
                          </listitem>
                          <listitem>
                            <literal>"mouseover"</literal>: setting the mouse pointer over the
                            datatip anchor on the line displays the datatip. When going away, the
                            datatip is masked. Its anchor remains displayed.
                          </listitem>
                        </itemizedlist>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>display_function: </term>
                <listitem>
                    <para>
                        A character string that contains a function name. This function syntax must
                        be <literal>str=fun(datatipHandle)</literal> where
                        <literal>datatipHandle</literal> is the handle of the datatip to be displayed.
                        This function must return a string or a vector of strings in str.
                    </para>
                    <para>
                        This function can be overloaded by setting the similar property on a datatip itself.
                    </para>
                    <para>
                        Some datatips formatting functions are predefined:
                        <table border="1">
                          <tr valign="top">
                            <th align="left">polar_datatip_display()</th>
                            <td>: set by polarplot()</td>
                          </tr>
                          <tr valign="top">
                            <th align="left">formatBodePhaseTip()</th>
                            <td>: set by bode()</td>
                          </tr>
                        </table>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>display_function_data: </term>
                <listitem>
                    <para>
                        Any Scilab data needed by the <literal>display_function</literal> function.
                    </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=[-2,-2;2,2];

xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
p=get("hdl"); //get handle on current entity (here the polyline entity)
p.foreground=2;
p.thickness=3;
p.mark_style=9;
d=p.data;d(1,:)=[0 0];p.data=d;
a.rotation_angles=[0 45];
 ]]></programlisting>
        <scilab:image>
            a=get("current_axes")
            a.data_bounds=[-2,-2;2,2];
            xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
            p=get("hdl");
            p.foreground=2;
            p.thickness=3;
            p.mark_style=9;
            d=p.data;d(1,:)=[0 0];p.data=d;
            a.rotation_angles=[0 45];
        </scilab:image>
        <programlisting role="example"><![CDATA[
xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
p=get("hdl"); //get handle on current entity (here the polyline entity)
p.data=[(-2:0.1:2)' sin((-2:0.1:2)*%pi)']
p.mark_mode="off";
p.polyline_style=3;
p.line_style=4;
 ]]></programlisting>
        <scilab:image>
            xpoly(sin(2*%pi*(0:5)/5),cos(2*%pi*(0:5)/5),"lines",0)
            p=get("hdl");
            p.data=[(-2:0.1:2)' sin((-2:0.1:2)*%pi)']
            p.mark_mode="off";
            p.polyline_style=3;
            p.line_style=4;
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="champ_properties">champ_properties</link>
            </member>
            <member>
                <link linkend="param3d_properties">param3d_properties</link>
            </member>
            <member>
                <link linkend="plot">plot</link>
            </member>
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="xpoly">xpoly</link>
            </member>
            <member>
                <link linkend="xfpoly">xfpoly</link>
            </member>
            <member>
                <link linkend="xpolys">xpolys</link>
            </member>
            <member>
                <link linkend="xfpolys">xfpolys</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).
                  New line_style values 9 and 10 added.
                </revremark>
            </revision>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>
                <itemizedlist>
                    <listitem>
                        <literal>.mark_stride</literal> and <literal>.mark_offset</literal>
                        properties added.
                    </listitem>
                    <listitem>
                        <literal>.datatips</literal> property added.
                    </listitem>
                    <listitem>
                        <literal>.display_function</literal> and
                        <literal>.display_function_data</literal> properties added.
                    </listitem>
                </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>6.0.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>
                            New property <literal>.datatip_display_mode</literal> introduced.
                        </listitem>
                        <listitem>
                            <literal>.mark_foreground</literal>, <literal>.mark_background</literal>
                            and <literal>.mark_size</literal> can now be row vectors: Each point
                            can have its own individual mark colors and size.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>2023.0.0</revnumber>
                <revremark>
                  line_style value 0 is no more available.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
