<?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="ja" xml:id="polyline_properties">
    <refnamediv>
        <refname>polyline_properties</refname>
        <refpurpose>Polylineエンティティプロパティの説明
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>説明</title>
        <para>Polylineエンティティはグラフィックエンティティ階層の葉です. このエンティティは
            ポリラインのパラメータを定義します.
        </para>
        <variablelist>
            <varlistentry>
                <term>parent: </term>
                <listitem>
                    <para>このフィールドには親のハンドルが含まれます.
                        polylineエンティティの親は<literal>"Axes"</literal> 型または
                        <literal>"Compound"</literal>型です.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>children: </term>
                <listitem>
                    <para>
                        このプロパティにはこのハンドルの<literal>children</literal>
                        のベクトルが含まれます.
                        しかし,現在,polylineには<literal>children</literal>がありません.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>visible: </term>
                <listitem>
                    <para>
                        このフィールドはこのエンティティの<literal>visible</literal>
                        プロパティの値を有します.
                        値は<literal>"on" </literal> または <literal>"off"</literal>となります.
                        デフォルトで polyline は可視であり,プロパティの値は
                        <literal>"on" </literal>となります. <literal>"off"</literal> の場合,
                        このポリラインは画面に描画されません.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>data: </term>
                <listitem>
                    <para>このフィールドはxおよびy座標の値を有します.
                        3次元軸の場合にはZ要素が追加されます.
                        この値は,各点の座標を含む2(3)列の行列<literal>[x,y,[z]]</literal>です.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>closed: </term>
                <listitem>
                    <para>このフィールドはポリラインが閉じているかどうかを定義します:
                        値は <literal>"on"</literal> または <literal>"off"</literal>となります
                        (デフォルト値はなく,ポリラインを作成する際に使用されたプリミティブに
                        依存します).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_mode: </term>
                <listitem>
                    <para>
                        このフィールドはポリラインの<literal>line_mode</literal>プロパティの
                        デフォルト値を有します. この値には <literal>"on" </literal>(線を描画
                        ) または <literal>"off"</literal> (線を描画しない)を指定します.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fill_mode: </term>
                <listitem>
                    <para>
                        <literal>polyline_style</literal>フィールドが  5ではない場合, 曲線の
                        背景が<literal>background</literal> プロパティで定義した色で塗られます.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_style: </term>
                <listitem>
                    <para>
                        このフィールドは,Segs, Arcs, Rectangle および Polylineオブジェクトの
                        <literal>line_style</literal>のデフォルト値を有します.
                        <literal>line_style</literal>は,線を描画する際に使用される
                        線の型を選択します.この値は, [1 10]の範囲の整数となります.
                        1 は実線を意味し, 他の値は破線
                        (破線, 一点鎖線, 長一点鎖線, 大鎖線, 大長一点鎖線, 点線, 2重点線, 長空白点線, 大空白点線)
                        の選択を意味します. 以下の例を参照ください.
                    </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>このプロパティはピクセル単位で線幅を指定する正の実数です.
                        実際の表示幅は指定された幅を最も近い整数に丸めることで定義されます.
                        唯一の例外はベクトル単位のエキスポートで,この場合は全体の
                        <literal>thickness</literal>の値が考慮されます.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>arrow_size_factor: </term>
                <listitem>
                    <para>この整数によりポリラインに描かれる矢印の大きさを設定することができます.
                        実際の矢印の大きさは<literal>thickness</literal>とこのsize factorの
                        積となります.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>polyline_style: </term>
                <listitem>
                    <para>このプロパティは以下の各種のポリライン描画モードを設定します:</para>
                    <itemizedlist>
                        <listitem>
                            <para>値が 0または1の場合,連続する2つの点の間に線が描画されます.</para>
                        </listitem>
                        <listitem>
                            <para>値が2の場合,ポリラインは階段プロットとなります.
                                連続する2つの点は水平線の後に垂直線が続く線により結合されます.
                            </para>
                        </listitem>
                        <listitem>
                            <para>値が3の場合,ポリラインは棒グラフとなります.
                                指定された各(x,y)について, (x,y) から
                                (x,0)に垂直線が引かれます.
                            </para>
                        </listitem>
                        <listitem>
                            <para>値が 4の場合,連続する2つの点の間に矢印が描かれます.</para>
                        </listitem>
                        <listitem>
                            <para>値が5の場合,ポリラインは塗りつぶされます (パッチ).</para>
                        </listitem>
                        <listitem>
                            <para>値が 6の場合,ポリラインはMatlabに似たbarオブジェクトとなります.
                                プロパティ<literal>bar_shift</literal> および<literal>bar_width</literal>
                                がその外観を規定します.
                            </para>
                        </listitem>
                    </itemizedlist>
                    <para>
                        <inlinemediaobject>
                            <imageobject>
                                <imagedata fileref="../../images/polyline_style.svg"/>
                            </imageobject>
                        </inlinemediaobject>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>foreground: </term>
                <listitem>
                    <para>このフィールドにはポリラインを描画する際に使用される
                        <literal>foreground</literal>プロパティのデフォルト値が含まれます.
                        その値には(カレントのカラーマップに沿った)色インデックスを指定します.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>background: </term>
                <listitem>
                    <para>このフィールドはポリラインの背景を塗りつぶす際に使用される色を有します.
                        その値には(カレントのカラーマップに沿った)色インデックスを指定します.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>interp_color_vector: </term>
                <listitem>
                    <para>このフィールドは,
                        <literal>interp_color_mode</literal>プロパティが<literal>"on"</literal>に設定された
                        際にポリラインを塗る際に使用される色インデックスの
                        ベクトルを有します.
                        これは,各セグメントを塗る際に使用される
                        カラーマップインデックスの間隔を定義します.
                        例えば,最初のセグメントは,
                        インデックスがベクトルの最初の2つの要素の間にある各色により塗りつぶされます.
                        これはポリラインが 3 または 4つの点で定義されている場合のみ適用可能です.
                        このため,ベクトルの大きさはこの次元に一致している必要があります.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>interp_color_mode: </term>
                <listitem>
                    <para>このフィールドはポリラインを塗る際に補間影モードを
                        使用するかどうかを定義します:
                        この値は<literal>"on"</literal> または<literal>"off"</literal>となります.
                        "on"に値を切り替える前に <literal>interp_color_vector</literal>を
                        定義する必要があります (上記参照).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_mode: </term>
                <listitem>
                    <para>
                        このフィールドはポリラインの<literal>mark_mode</literal>
                        プロパティのデフォルト値を有します.
                        この値は<literal>"on"</literal> (マーカを描画
                        drawn) または <literal>"off"</literal> (マーカを描画しない)となります.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_style: </term>
                <listitem>
                    <para>
                        <literal>mark_style</literal>プロパティの値は
                        <literal>mark_mode</literal>プロパティが<literal>"on"</literal>の場合に,
                        使用するマーカの種類を選択するために使用されます.
                        この値は[0 14]の範囲の整数で,それぞれ以下の意味があります :
                        ドット,プラス,十字,星,塗りつぶした菱形,
                        上向き三角形, 下向き三角形, 菱形プラス,円,アスタリスク,
                        正方形,右向き三角形,左向き三角形およびペンタグラム.
                        以下の図は,マーカのアスペクトが<literal>mark_style</literal>,
                        <literal>mark_foreground</literal> および
                        <literal>mark_background</literal>プロパティに依存する
                        ことを示します.
                    </para>
                    <para>
                        <inlinemediaobject>
                            <imageobject>
                                <imagedata fileref="../../images/marks.svg"/>
                            </imageobject>
                        </inlinemediaobject>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_size_unit: </term>
                <listitem>
                    <para>
                        このフィールは<literal>mark_size_unit</literal>プロパティのデフォルト値
                        を有します.<literal>mark_size_unit</literal>が<literal>"point"</literal>
                        に設定された場合,<literal>mark_size</literal>の値はポイント単位で直接
                        指定されます.
                        <literal>mark_size_unit</literal> に<literal>"tabulated"</literal>が
                        指定された場合,<literal>mark_size</literal>はfont size配列に相対的に
                        計算されます: この場合,この値は,
                        8pt, 10pt, 12pt, 14pt, 18pt および 24pt を意味する
                        [0 5]の範囲の整数とします.
                        <link linkend="xrect">xrect</link>および Scilabのネーティブ関数は
                        <literal>tabulated</literal>モードをデフォルトとします;
                        <link linkend="plot">plot</link>関数を使用する場合,
                        <literal>point</literal> モードが自動的に有効となります.
                    </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>
                        このフィールドは,
                        最初の記号を描画する際に使用されるオフセットである
                        <literal>mark_offset</literal> プロパティの値を有します.
                        この値は, 0 以上の整数とする必要があります (デフォルト値は 0).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_stride: </term>
                <listitem>
                    <para>
                        このフィールドは,
                        記号を描画する際に使用するストライド
                        (すなわち, 2つの連続する記号の間で stride-1 個の点がスキップされます)
                        である <literal>mark_stride</literal> プロパティの値を有します.
                        この値は, 1以上の整数とする必要があります (デフォルト値は 1).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x_shift: </term>
                <listitem>
                    <para>
                        このフィールドは関数<link linkend="bar">bar</link>をコールする
                        ことにより計算される
                        (または<link linkend="barhomogenize">barhomogenize</link>を
                        コールすることにより再計算される)オフセットを有し,
                        見栄えの良い垂直棒グラフを作成するために使用されます.
                        このオフセットは他の<literal>polyline_style</literal>にも
                        適用されることに注意してください.
                        単位はユーザ座標で表されます.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>y_shift: </term>
                <listitem>
                    <para>
                        このフィールドは関数<link linkend="bar">bar</link>をコールする
                        ことにより計算される
                        (または<link linkend="barhomogenize">barhomogenize</link>を
                        コールすることにより再計算される)オフセットを有し,
                        見栄えの良い水平棒グラフを作成するために使用されます.
                        このオフセットは他の<literal>polyline_style</literal>にも
                        適用されることに注意してください.
                        単位はユーザ座標で表されます.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>z_shift: </term>
                <listitem>
                    <para>このフィールドはユーザが指定する
                        オフセットを有します
                        このオフセットは他の<literal>polyline_style</literal>にも
                        適用されることに注意してください.
                        このユニットはユーザ座標で表されています.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>bar_width: </term>
                <listitem>
                    <para>このフィールドは,
                        <literal>polyline_style</literal> が棒グラフモード (ケース 6)に
                        せていされている場合に,
                        選択されたポリラインの幅を定義します:
                        単位はユーザ座標で表されます.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_state: </term>
                <listitem>
                    <para>
                        このフィールドはポリラインの<literal>clip_state</literal>プロパティの
                        値を有します. 値は以下となります:
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>"off"</literal> ポリラインはクリップされません.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"clipgrf"</literal> ポリラインはAxesボックスの外側でクリップ
                                されます.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"on"</literal>ポリラインはclip_boxプロパティで
                                指定された矩形の外側でクリップされます.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_box: </term>
                <listitem>
                    <para>
                        このフィールドは<literal>clip_box</literal>プロパティを定義します.
                        clip_state が "off" の場合, デフォルトで,この値は空の行列です.
                        その他の場合, ベクトル　<literal>[x,y,w,h]</literal> (左上の点 幅 高さ)
                        は表示するポリラインの部分を定義しますが,
                        <literal>clip_state</literal>プロパティの値が変更されます.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>user_data: </term>
                <listitem>
                    <para>このフィールドはpolylineデータ構造体に任意のScilab変数を
                        保存し,再度取得する際に使用できます.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>datatips: </term>
                <listitem>
                    <para>
                        このプロパティは,ポリラインに関係する<literal>datatips</literal>のハンドルの
                        ベクトルを有します.
                        しかし, ポリラインのハンドルは現在<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>
                        関数名を有する文字列. この関数の呼び出し手順は,
                        <literal>str=fun(datatipHandle)</literal> とします.
                        ただし,  <literal>datatipHandle</literal> は表示するdatatipの
                        ハンドルです.
                        この関数は, 文字列または文字列ベクトルを str に返します.
                    </para>
                    <para>
                        この関数は, datatip本体に類似のプロパティを設定することで,
                        オーバーロードできます.
                    </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>
                        <literal>display_function</literal>関数で必要とされる全Scilabデータ.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>例</title>
        <programlisting role="example"><![CDATA[
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"); //カレントのエンティティ(ここではpolylineエンティティ)のハンドルを取得
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>参照</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>履歴</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>line_style = 0 は廃止予定です.代わりに 1 を使用してください
                    (両者は等価で,共に実線を意味します). 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>