<?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
 * 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="ja" xml:id="figure_properties">
    <refnamediv>
        <refname>figure_properties</refname>
        <refpurpose>グラフィックエンティティプロパティの説明</refpurpose>
    </refnamediv>
    <refsection>
        <title>説明</title>
        <para>
            figureエンティティはグラフィックエンティティ階層の最上位です.
            このエンティティにはScilabグラフィックオブジェクトの表示に
            関する多くの要素を制御するために設計された多くのプロパティが
            含まれています.
            これらのプロパティは,図(figure)自体に関する情報を含むプロパティと,
            子作成時のデフォルト値の設定に関連するプロパティの
            2つのカテゴリに分けることができます.
        </para>
        <variablelist>
            <varlistentry>
                <term>figure プロパティ: </term>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term>children: </term>
                            <listitem>
                                <para>
                                    このハンドルは図(figure)の子のベクトルを表します.
                                    図の子は全て<literal>"Axes"</literal>であることに注意してください.
                                    また,(<link linkend="scf">scf</link> コマンドにより)図のエンティティを作成する際,
                                    同時に
                                    <literal>Axes</literal>エンティティも一つ作成されることも覚えておいてください.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_position: </term>
                            <listitem>
                                <para>
                                    このフィールドはスクリーン上でのグラフィックウインドウのピクセル単位の
                                    位置を保持します.
                                    これはウインドウの左上隅の位置を定義するベクトル<literal>[x,y]</literal>です.
                                    位置 <literal>[0,0]</literal> は画面の左上隅です.
                                </para>
                                <para>
                                    グラフィックウインドウの初期位置はデフォルトの figure エンティティ
                                    (<link linkend="gdf">gdf</link>参照)により指定されます.
                                    唯一の例外は,
                                    デフォルトの図の値<literal>figure_position</literal>が<literal>[-1,-1]</literal>
                                    の場合です.
                                    この場合,グラフィックウインドウの初期位置はウインドウシステムにより自動的に
                                    設定されます.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_size: </term>
                            <listitem>
                                <para>
                                    Vector <literal>[width, height]</literal>, providing the
                                    external size of the graphic window, in screen pixels.
                                </para>
                                <para>
                                <warning>
                                    When the figure is docked (to the Scilab desktop, etc),
                                    .figure_size holds for the whole docked block and should not
                                    be set.
                                </warning>
                                <warning>
                                    The OS window manager defines some minimal sizes. If sizes
                                    smaller than minimal ones are provided, the minimal ones are
                                    actually set.
                                    <para>
                                        On Windows, minimal sizes can be retrieved with
                                        <screen><![CDATA[
--> [getsystemmetrics("SM_CXMIN") getsystemmetrics("SM_CYMIN")]
 ans  =
   158.   45.
]]></screen>
                                    </para>
                                </warning>
                                <warning>
                                    When a figure is created in .auto_resize="on" mode,
                                    the .axes_size value is set as specified, and .figure_size
                                    is set accordingly, not the reverse.
                                </warning>
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>axes_size: </term>
                            <listitem>
                                <para>
                                    Vector <literal>[width, height]</literal> of sizes of the whole
                                    graphical area in the window, in pixels.
                                </para>
                                <warning>
                                    This property should not be modified if the figure is docked
                                    to the Scilab desktop.
                                </warning>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>position: </term>
                            <listitem>
                                <para>
                                    <literal>.position = [x, y, graphics_width, graphics_height]</literal>
                                    or <literal>.position = 'x|y|graphics_width|graphics_height'</literal>
                                    (like '100|150|500|300')
                                    is a pseudo-property allowing to set or querry both
                                    <literal>.figure_position</literal> and <literal>.axes_size</literal>
                                    properties in a once.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>auto_resize: </term>
                            <listitem>
                                <para>
                                    Auto-resizing of children axes when the figure is resized.
                                </para>
                                <para>
                                    When the figure is resized by hand or by setting the
                                    .figure_size property, and .auto_resize is
                                    <table>
                                        <tr>
                                            <th>"on"</th>
                                            <td>Then the .axes_size is updated and axes contents
                                                are zoomed accordingly, without displaying scroll
                                                bars.
                                            </td>
                                        </tr>
                                        <tr>
                                            <th>"off"</th>
                                            <td>Then the .axes_size is kept unchanged. The display
                                                scale of children axes is unchanged. If the window
                                                gets smaller than axes sizes, some scroll bars are
                                                displayed.
                                            </td>
                                        </tr>
                                    </table>
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>viewport: </term>
                            <listitem>
                                <para>図の可視部分の位置.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_name or name:</term>
                            <listitem>
                                <para>
                                    このフィールドは図の名称を保持します.
                                    この名称はグラフィックウインドウ上の最上部に表示される
                                    文字列です.
                                    この名称には文字列<literal>%d</literal>を一つ含めることができ,
                                    この部分は<literal>figure_id</literal>で置換されます.
                                    その他の<literal>%</literal>文字のインスタンスは名称の中で使用できません.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>figure_id: </term>
                            <listitem>
                                <para>
                                    このフィールドは図のIDを保持します.
                                    これは図の生成時に設定される整数で,後で変更することはできません.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>color_map: </term>
                            <listitem>
                                <para>
                                    この図で使用されるカラーマップを定義するプロパティ.
                                    カラーマップは <literal>m</literal> 行 <literal>3</literal>列の行列です.
                                    <literal>m</literal>は色の数です.色番号 i は
                                    <literal>R</literal>, <literal>G</literal>, <literal>B</literal>の3要素で
                                    指定し,それぞれ, 0 から 1の間の赤,緑,青の輝度に対応します.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>pixel_drawing_mode: </term>
                            <listitem>
                                <para>
                                    このフィールドは画面上のピクセルの描画で使用されるビット単位の処理を定義します.
                                    デフォルトのモードは <literal>copy</literal>です.
                                    詳細については,<link linkend="pixel_drawing_mode">ピクセル描画モード参照ページ</link>
                                    を参照ください.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>anti_aliasing: </term>
                            <listitem>
                                <para>
                                    このプロパティはグラフィックの品質を改善する際に使用される
                                    アンチエイリアス処理のレベルを制御します.
                                    このプロパティが "off" に設定された場合,アンチエイリアス処理は無効になります.
                                    アンチエイリアス処理を有効にするには,"2x", "4x", "8x"または "16x"のどれかを
                                    指定することが必要です.
                                    この場合, この値はアンチエイリアスのレベルを意味します.例えば,
                                    例えば, "16x" は "2x"よりも高い品質となります.
                                    より高いアンチエイリアスのレベルを指定することにより画像の品質は改善されますが,
                                    グラフィック性能は低下します.
                                    Please visit the <link linkend="anti_aliasing">dedicated page</link>
                                    to see specific examples.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>immediate_drawing: </term>
                            <listitem>
                                <para>
                                    このプロパティは図の表示を制御します.
                                    この値は
                                    <literal>"on"</literal> (デフォルトモード) または <literal>"off"</literal>です.
                                    (複数の描画や再描画を適用することにより)グラフィックスコマンドが大量に連続する場合に,
                                    表示を遅延させるために使用されます.
                                    <literal>drawlater</literal> または <literal>drawnow</literal> コマンドを
                                    使用した場合, カレントの図のプロパティの値を変更することに注意してください
                                    (それぞれ,この値を<literal>'off'</literal> または
                                    <literal>'on'</literal>に変更します).
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>background: </term>
                            <listitem>
                                <para>
                                    このプロパティは図の背景を制御します.
                                    カレントのカラーマップに関連する添え字を値として指定します.
                                </para>
                            </listitem>
                        </varlistentry>
                       <varlistentry>
                            <term>BackgroundColor</term>
                            <listitem>
                                <para>
                                    This pseudo-property is a set-only one. It is the same as
                                    <literal>background</literal>, but allows to specify the color
                                    as a [r g b] vector of real values of Red Green and Blue
                                    intensities in [0,1] like <literal>[0.1, 0.5, 0.3]</literal>,
                                    or as a unique equivalent 'r|g|b' string like
                                    <literal>'0.1|0.5|0.3'</literal>, using "|" as a separator.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>event_handler</term>
                            <listitem>
                                <para>
                                    文字列. イベントを処理を受け持つScilab 関数の名前.
                                    空の文字列を指定するとイベントハンドラが無効となることに注意してください.
                                    イベントハンドラに関する詳細は
                                    <link linkend="eventhandlerfunctions">イベントハンドラ関数</link> ヘルプを
                                    参照してください.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>event_handler_enable</term>
                            <listitem>
                                <para>イベントハンドラを有効または無効にします. 値は "on" または "off" のどちらかです.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>user_data: </term>
                            <listitem>
                                <para>このフィールドは図のデータ構造に何らかのScilab変数を保存したり,
                                    取得したりするために使用することができます.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>tag: </term>
                            <listitem>
                                <para>このフィールドは一般に制御を識別するための文字列を保存するために使用できます．
                                    これにより"名前"を指定することが可能となります.
                                    主にfindobj()との組み合わせで使用されます.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>resizefcn: </term>
                            <listitem>
                                <para>
                                    このフィールドは,このScilab関数名またはScilab式を文字列として保存する際に使用されます.
                                    この文字列は,ユーザが図をリサイズした際および図の作成時に評価されます.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>closerequestfcn: </term>
                            <listitem>
                                <para>
                                    このフィールドは,このScilab関数名またはScilab式を文字列として保存する際に使用されます.
                                    この文字列は,ユーザが図を右上の十字により図を閉じようとした際に評価されます.
                                </para>
                                <para>
                                    このプロパティが設定された際, "figure closed" イベント (-1000) は
                                    イベントハンドラ関数でトラップされなくなります.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>resize: </term>
                            <listitem>
                                <para>
                                    このプロパティは図の大きさをロックします.
                                    値は,
                                    <literal>"on"</literal> (デフォルト値) または <literal>"off"</literal>
                                    (図は,マウスイベントによりリサイズできません)とします. Resizing the figure
                                    is always possible with <literal>.figure_size</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>menubar_visible: </term>
                            <listitem>
                                <para>
                                    このプロパティは図のメニューバーの可視性を制御します.値は,
                                    <literal>"on"</literal> (デフォルト値) または <literal>"off"</literal>とします.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>toolbar_visible: </term>
                            <listitem>
                                <para>
                                    このプロパティは図のツールバーの可視性を制御します.値は,
                                    <literal>"on"</literal> (デフォルト値) または <literal>"off"</literal>とします.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>infobar_visible: </term>
                            <listitem>
                                <para>
                                    このプロパティは図の図のステータスバーの可視性を制御します.値は,
                                    <literal>"on"</literal> (デフォルト値) または <literal>"off"</literal>とします.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>info_message: </term>
                            <listitem>
                                <para>この文字列はグラフィックウインドウの情報バーに表示されるテキストを指定します.</para>
                                <note>
                                    A multi-line message is possible, using ascii(10) as lines
                                    separator, as with "Line #1"+ascii(10)+"Line #2".
                                    Styling the text is not possible (HTML styles not supported).
                                </note>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>visible: </term>
                            <listitem>
                                <para>
                                    図の <literal>"dockable"</literal> プロパティが <literal>"off"</literal>の場合,
                                    <literal>"Visible"</literal> プロパティを設定すると
                                    ウインドウの装飾を含む図全体に影響します.
                                </para>
                                <para>
                                    図の <literal>"dockable"</literal> プロパティが <literal>"on"</literal>で,
                                    図が同じ親ウインドウの他の図に結合されている場合,
                                    このフィールドは図の子にのみ作用します(以下の関連部分を参照).
                                    図が他の図に結合されていない場合,
                                    <literal>"Visible"</literal> プロパティは
                                    <literal>"dockable"</literal>プロパティが<literal>"off"</literal>に設定された場合と
                                    同様に動作します.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>layout: </term>
                            <listitem>
                                <para>
                                    このプロパティは図の子を並べる際に使用されるレイアウトを設定します.
                                    利用可能なレイアウトに関する詳細については
                                    <link linkend="layout">レイアウト</link> のページを参照ください.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>layout_options: </term>
                            <listitem>
                                <para>
                                    このプロパティは図の子を並べる際に使用されるレイアウトのオプションを設定します.
                                    利用可能なオプションに関する詳細については
                                    <link linkend="layout">レイアウト</link> のページを参照ください.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>icon: </term>
                            <listitem>
                                <para>このフィールドはScilab図のアイコンをカスタマイズする際に使用します.</para>
                                <para>
                                    この値は,アイコンを保持する画像ファイルへの
                                    絶対またはScilab<link linkend="pwd">カレントのワーキングディレクトリ</link>への
                                    相対パスを有する文字列です.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>default_axes: </term>
                            <listitem>
                                <para>
                                    <literal>"on"</literal> (default value) means that the figure has always
                                    a default axes: it is automatically set at the figure creation,
                                    or automatically reset when the last axes of the figure is
                                    intentionally deleted.
                                </para>
                                <para>
                                    <literal>"off"</literal> means that
                                    <itemizedlist>
                                        <listitem>
                                            the newly created figure has no default axes.
                                        </listitem>
                                        <listitem>
                                            for an existing figure, it is possible to actually delete
                                            all its existing axes.
                                        </listitem>
                                    </itemizedlist>
                                    In both cases,
                                    <itemizedlist>
                                        <listitem>
                                            without any axes, the figure can't be the default
                                            target of any plotting instruction. This feature
                                            can be used to protect an interactive interface built in a
                                            figure (like the demos and the ATOMS ones) from being the default
                                            plotting target when there is no other proper opened
                                            graphical figures.
                                        </listitem>
                                        <listitem>
                                            It is still possible to force creating an axes using the
                                            <link linkend="newaxes">newaxes</link> function.
                                        </listitem>
                                    </itemizedlist>
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
        <variablelist>
            <varlistentry>
                <term>子のデフォルト値: </term>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term>visible: </term>
                            <listitem>
                                <para>このフィールドは,
                                    図の内容が再描画されるかどうかを定義します.
                                    この値は <literal>"on"</literal> または
                                    <literal>"off"</literal>となります.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>rotation_style: </term>
                            <listitem>
                                <para>
                                    このフィールドは "3D Rot"(3次元回転) ボタンに関係します.
                                    デフォルトは,選択された3次元プロットのみが回転することを意味する
                                    <literal>unary</literal>となっています.
                                    この値は,全ての3次元プロットが回転することを意味する <literal>multiple</literal>
                                    とすることができます.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
        <variablelist>
            <varlistentry>
                <term>作成関連のプロパティ: </term>
                <para>
                    いくつかのプロパティは,
                    <link linkend="figure">figure</link> 関数により作成時に設定でき,その後は読込み専用となります.
                </para>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term>dockable</term>
                            <listitem>
                                <para>
                                    このプロパティは作成されるウインドウがScilab環境の中で結合できるかどうかを定義します.
                                    この値が<literal>"on"</literal> の場合,
                                    ウインドウにユーザが結合/結合解除することを可能にするバーが追加されます.
                                    そうでない場合,ウインドウは通常のOSウインドウのようになります.
                                    この値は作成時にのみ指定できます.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>menubar</term>
                            <listitem>
                                <para>{"figure"} | "none"</para>
                                <para>
                                    このプロパティは図のメニューバーの型を定義します.
                                    この値が<literal>"none"</literal>の場合,
                                    <link linkend="uimenu">uimenu function</link>によりメニューが追加されるまで
                                    メニューバーが現れなくなります.
                                    そうでない場合,デフォルトの図メニューが作成されます.
                                    この値は作成時にのみ指定できます.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>toolbar</term>
                            <listitem>
                                <para>{"figure"} | "none"</para>
                                <para>
                                    このプロパティは図のツールバーの型を定義します.
                                    この値が<literal>"none"</literal>の場合,ウインドウに
                                    ツールバーが現れなくなります.
                                    そうでない場合,デフォルトのツールバーが作成されます.
                                    この値は作成時にのみ指定できます.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>デフォルト値に関する注記 :</term>
                <listitem>
                    <variablelist>
                        <varlistentry>
                            <term/>
                            <listitem>
                                <para>
                                    上記リストに提示した全てのプロパティとフィールドは,
                                    figureモデルに保存されたデフォルト値から継承されたものです
                                    これらのデフォルト値は,参照したり,変更したりすることができます.
                                    これを行うには,<literal>get("default_figure")</literal>コマンドを
                                    使用してください.これにより,figureモデルのグラフィックウインドウが
                                    取得できます.
                                    このコマンドにより特定のグラフィックウインドウが作成されるわけではない
                                    ことに注意してください.
                                    次に作成される図はこのモデルから継承されます
                                    (下記の例2を参照).
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>例</title>
        <programlisting role="example"><![CDATA[
lines(0) // 垂直ページングを無効に

//例 1
f=get("current_figure") //カレント図のハンドルを取得 :
                        //存在しない場合,図を作成,ハンドルを返す
f.figure_position
f.figure_size=[200,200]
f.background=2
f.children  // axesエンティティが既に存在することを確認
delete(f);
f=gcf(); // マクロショートカット <=> f=get("current_figure")
plot2d() // 画面には何も起こりません...

//例 2 : default_figure 設定
df=get("default_figure") // デフォルト値を取得 (ショートカットは gdf() )
// デフォルトを変更...
df.color_map=hot(128)
df.background= 110 // 背景を黄色に設定 (既存のカラーマップ内の色添字を使用することに注意)
scf(122); // 新規デフォルトで図番122の図を新規作成
plot2d()
scf(214);
t=-%pi:0.3:%pi;
plot3d(t,t,sin(t)'*cos(t),35,45,'X@Y@Z',[15,2,4]);
 ]]></programlisting>
    </refsection>
    <refsection>
        <title>参考</title>
        <simplelist type="inline">
            <member>
                <link linkend="eventhandlerfunctions">event handler functions</link>
            </member>
            <member>
                <link linkend="pixel_drawing_mode">pixel_drawing_mode</link>
            </member>
            <member>
                <link linkend="anti_aliasing">anti_aliasing</link>
            </member>
            <member>
                <link linkend="colormap">colormap</link>
            </member>
            <member>
                <link linkend="scf">scf</link>
            </member>
            <member>
                <link linkend="gcf">gcf</link>
            </member>
            <member>
                <link linkend="gdf">gdf</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="axes_properties">axes_properties</link>
            </member>
            <member>
                <link linkend="getsystemmetrics">getsystemmetrics</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>履歴</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>resizefcn &amp; closerequestfcn プロパティが追加されました.</revremark>
            </revision>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>"visible" プロパティの意味が変更されました (uicontrols が管理し,いくつかのケースでは図全体を不可視にできるようになりました.</listitem>
                        <listitem>"icon" プロパティが追加され,図のアイコンを変更できるようになりました.</listitem>
                        <listitem>"menubar_visible" プロパティ追加.</listitem>
                        <listitem>"toolbar_visible" プロパティ追加.</listitem>
                        <listitem>"infobar_visible" プロパティ追加.</listitem>
                        <listitem>"resize" プロパティ追加.</listitem>
                        <listitem>"dockable" プロパティ追加.</listitem>
                        <listitem>"menubar" プロパティ追加.</listitem>
                        <listitem>"toolbar" プロパティ追加.</listitem>
                        <listitem>"default_axes" プロパティ追加.</listitem>
                        <listitem>"layout" プロパティ追加.</listitem>
                        <listitem>"layout_options" プロパティ追加.</listitem>
                    </itemizedlist>
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
