プラットフォームコマンドインストラクションリファレンス

プラットフォームコマンドインストラクションのボキャブラリの概要や、要素・属性を解説します。

1. 概要

プラットフォームコマンドインストラクションのボキャブラリの概要を説明します。

1.1. 用途・役割

VCを実行するプラットフォームが提供する機能を実行するためのコマンドインストラクションを記述するボキャブラリです。

1.2. 名前空間URI参照

プラットフォームコマンドインストラクションの名前空間URI参照は http://xmlns.xfy.com/instruction です。以下の説明で、プラットフォームコマンドインストラクションのボキャブラリの要素を記述するときは、instruction:という名前空間接頭辞を使用します。

このほか、以下の説明中に出現するボキャブラリと、そのボキャブラリに使用している名前空間接頭辞は次のとおりです。

2. プラットフォームコマンドインストラクション

2.1. 制御系インストラクション

2.1.1. 変数とパラメータ

コマンドインストラクションで使用する変数を宣言したり、コマンドのパラメータを定義することができます。変数とパラメータの定義に関するインストラクション・要素は以下のとおりです。

instruction:variable インストラクション

コマンドインストラクションで使用する変数を記述するコマンドインストラクション要素です。

<!--
    リストの要素数を変数sizeに割り当てる例。
-->
<xvcd:command name="sample:original-command">
    <instruction:variable name="size" select="count(sample:list/sample:item)"/>
    <instruction:if test="$size = 1">
        <!-- リストの要素数が1の場合の処理 -->
          :
    </instruction:if>
</xvcd:command>
属性：
name （必須）

変数名を設定する属性です。QNameで設定します。

select

変数の値を示すXPath式を設定する属性です。

省略した場合、要素内に記述されたXML文書フラグメントが変数の値となります。

内容：

instruction:variable要素内には、変数の初期値としたい任意のXML文書フラグメントを記述できます。要素内に記述されたXML文書フラグメントがVCによって変換された結果が、変数の初期値となります。select属性も同時に記述された場合は、select属性で指定された内容が優先されます。

instruction:param 要素

コマンドが必要とするパラメータ変数を宣言する要素です。

<!--
    foo という名前のパラメータをとるコマンドの定義例。
-->
<xvcd:command name="sample:original-command">
    <instruction:param name="foo"/>
      :
      :
</xvcd:command>
属性：
name （必須）

パラメータの名前を指定する要素です。QNameで記述します。

select

パラメータの初期値を示すXPath式を設定する属性です。

省略した場合、要素内に記述されたXML文書フラグメントがパラメータの初期値となります。

内容：

instruction:param要素内には、パラメータの初期値となる任意のXML文書フラグメントを記述できます。select属性の指定と同時にXML文書フラグメントが記述された場合は、select属性に指定された値が優先されます。

2.1.2. コマンド呼び出し

XVCDで記述されたコマンドや、プラットフォームが提供するコマンドを呼び出すことができます。コマンド呼び出しに関連するインストラクションは以下のとおりです。

instruction:call インストラクション

XVCDで記述されたコマンドや、プラットフォームが提供するコマンドを実行するコマンドインストラクション要素です。

<!--
    プラットフォーム組み込みコマンドの
    ソース表示コマンドを呼び出す例。
-->
<instruction:call name="command:source"/>
属性：
name （必須）

コマンド名を指定する属性です。 xvcd:command要素のname属性に記述したコマンド名や、プラットフォームが提供するコマンド名をQNameで指定します。属性値テンプレートを記述できます。指定された名前のコマンドが存在しない場合は警告が表示されます。

namespace

コマンドの名前空間を指定する属性です。名前空間URI参照で記述します。属性値テンプレートを記述できます。namespace属性で記述された名前空間は、name属性の名前空間接頭辞による名前空間の指定よりも優先されます。

省略した場合、値が設定されていないと見なされます。

内容：

instruction:call要素内には以下の要素を記述できます。

instruction:post インストラクション

XVCDで記述されたコマンドや、プラットフォームが提供するコマンドを実行キューに登録するコマンドインストラクション要素です。実行キューに登録されたコマンドは、現在実行中のコマンドが終了したあとで、実行されます。

<!--
    instruction:call と instruction:post を混在させた例。
    command-a → command-c → command-b の順で実行される。
-->
<xvcd:command name="sample:original-command">
    <instruction:call name="command-a"/>
    <instruction:post name="command-b"/>
    <instruction:call name="command-c"/>
</xvcd:command>
属性：
name （必須）

コマンド名を指定する属性です。 xvcd:command要素のname属性に記述したコマンド名や、プラットフォームが提供するコマンド名をQNameで指定します。属性値テンプレートを記述できます。指定された名前のコマンドが存在しない場合は警告が表示されます。

namespace

コマンドの名前空間を指定する属性です。名前空間URI参照で記述します。属性値テンプレートを記述できます。namespace属性で記述された名前空間は、name属性の名前空間接頭辞による名前空間の指定よりも優先されます。

省略した場合、値が設定されていないと見なされます。

delay

コマンドの実行を遅らせる時間をミリ秒単位の整数値で指定する属性です。属性値テンプレートを記述できます。

省略した場合、コマンドを実行できる状態になったらすぐに実行されます。

内容：

instruction:post要素内には以下の要素を記述できます。

instruction:post要素のパラメータに指定できる値

instruction:post要素で実行するコマンドには、instruction:with-param要素でパラメータを指定します。instruction:with-param要素で値を指定するときは、次のような制限があります。

  • instruction:variable要素・instruction:param要素・instruction:with-param要素の内容にテンプレートルールを記述して定義された変数を、直接的または間接的に参照することはできません。

次のコマンドを実行する例では、変数を参照できずにエラーになります。

<xvcd:command name="foo">
    <instruction:call name="bar">
        <instruction:with-param name="baz">1</instruction:with-param>
    </instruction:call>
</xvcd:command>

<xvcd:command name="bar">
    <instruction:param name="baz"/>
    <instruction:variable name="foobar" select="$baz + 1"/>
    <instruction:post name="qux">
        <instruction:with-param name="quux" select="$foobar"/>
    </instruction:post>
</xvcd:command>

この例の場合、instruction:post要素に渡す変数$foobarは、変数$bazを参照しています。変数$bazは、instruction:with-param要素の内容にテンプレートルールとして定義されているので、その値は参照できません。

instruction:with-param 要素

instruction:callインストラクションや instruction:postインストラクションで実行するコマンドがパラメータを必要とするときに、パラメータの値を指定するコマンドインストラクション要素です。 

<!--
    パラメータ付きでコマンド呼び出しをする例。
-->
<xvcd:command name="sample:command">
      :
    <instruction:call name="sample:another-command">
        <instruction:with-param name="foo" select="true()"/>
    </instruction:call>
      :
</xvcd:command>
属性：
name （必須）

パラメータの名前を設定する属性です。QNameで設定します。

select

パラメータの値を示すXPath式を指定する属性です。

省略した場合、要素内に記述されたXML文書フラグメントがパラメータの値となります。

内容：

instruction:with-param要素内には、パラメータの値となる任意のXML文書フラグメントを記述できます。select属性の指定と同時にXML文書フラグメントが記述された場合は、select属性に指定された値が優先されます。

instruction:call-next インストラクション

実行中のコマンドと同じ名前を持ち、優先順位がそのコマンドの次に低いコマンドを実行するインストラクション要素です。コマンドに渡されるパラメータは実行中のコマンドに渡されたパラメータと等しくなります。

たとえば、システムの「保存」コマンドと同じ名前（command:save）のコマンドを xvcd:command要素でオーバーライド定義する場合に、そのコマンド内にこのインストラクションを記述することによりシステムの「保存」コマンドを呼び出すことができます。 

<!--
    保存前に確認メッセージボックスを表示するように、
    システムの保存コマンドを上書き定義する例。
-->
<xvcd:command name="command:save">
    <!-- メッセージボックス表示 -->
    <instruction:message-box
        type="question" option="yes-no" return-to="result">
        保存しますか？
    </instruction:message-box>
    <!-- ［はい］がクリックされた場合のみ保存する。 -->
    <instruction:if test="'yes' = $result/instruction:dialog-result">
        <!-- 元の保存コマンド（command:save）を呼ぶ。 -->
        <instruction:call-next/>
    </instruction:if>
</xvcd:command>
属性：

属性はありません。

内容：

instruction:call-next要素は空要素です。

instruction:command-exists インストラクション

コマンドが存在するかしないかを調べるコマンドインストラクション要素です。

<!--
    foo:bar コマンドが存在するか調べる。
    結果は result という名前の変数に割り当てられる。
-->
<instruction:command-exists name="foo:bar" return-to="result" />

<instruction:if test="$result">
    <!-- foo:bar コマンドが存在する場合の処理 -->
    <instruction:call name="foo:bar"/>
</instruction:if>
属性：
name （必須）

コマンド名を指定する属性です。 xvcd:command要素のname属性に記述したコマンド名や、プラットフォームが提供するコマンド名をQNameで指定します。属性値テンプレートを記述できます。

namespace

コマンドの名前空間を指定する属性です。名前空間URI参照で記述します。属性値テンプレートを記述できます。namespace属性で記述された名前空間は、name属性の名前空間接頭辞による名前空間の指定よりも優先されます。

省略した場合、値が設定されていないと見なされます。

return-to （必須）

コマンドが存在するかしないかを調べた結果を、真偽値で格納する変数の名前を指定する属性です。QNameで記述します。

内容：

instruction:command-exists要素は空要素です。

2.1.3. 条件分岐

instruction:if インストラクション

指定した条件を満たすときだけ、コマンドインストラクション列を実行したいときに使用するコマンドインストラクション要素です。

<instruction:if test="条件式">
    <!--
        条件式が真の場合に実行されるインストラクション列
    -->
</instruction:if>
属性：
test （必須）

条件を表すXPath式を記述する属性です。XPath式の評価結果を真偽値として扱い、真となったときにinstruction:if要素内に記述されたコマンドインストラクション列を実行します。

内容：

instruction:if要素内には、コマンドインストラクション列を記述します。

instruction:choose インストラクション

複数の条件を列記し、最初に満たした条件に対応したコマンドインストラクション列を実行するコマンドインストラクション要素です。 instruction:when要素や instruction:otherwise要素と組にして使用します。 

<instruction:choose>
    <instruction:when test="条件式Ａ">
        <!--
            条件式Ａが真の場合に実行されるインストラクション列
        -->
    </instruction:when>
    <instruction:when test="条件式Ｂ">
        <!--
            条件式Ａが偽で、
            条件式Ｂが真の場合に実行されるインストラクション列
        -->
    </instruction:when>
    <instruction:when test="条件式Ｃ">
        <!--
            条件式ＡもＢも偽で、
            条件式Ｃが真の場合に実行されるインストラクション列
        -->
    </instruction:when>
    <instruction:otherwise>
        <!--
            条件式Ａ・Ｂ・Ｃすべてが偽の場合に
            実行されるインストラクション列
        -->
    </instruction:otherwise>
</instruction:choose>
属性：

属性はありません。

内容：

instruction:choose要素内に記述できる要素は、以下のとおりです。

  • instruction:when要素
    少なくとも１つは記述する必要があります。
    それ以上は、必要な数だけ記述できます。
  • instruction:otherwise要素
    必要に応じて、１つだけ記述できます。
    instruction:otherwise要素を使用するときは、必ずinstruction:choose要素内の最後に記述します。
    省略可能です。

instruction:when 要素

instruction:choose要素内に列挙する条件と、その条件に対応したコマンドインストラクション列を記述するときに使用する要素です。

属性：
test （必須）

条件を表すXPath式を記述する属性です。XPath式の評価結果を真偽値として扱い、真となったときにinstruction:when要素内に記述されたコマンドインストラクション列を実行します。

内容：

instruction:when要素内には、コマンドインストラクション列を記述できます。

instruction:otherwise 要素

instruction:choose要素内に記述されたすべての instruction:when要素の条件を満たさないときに実行されるコマンドインストラクション列を記述する要素です。

属性：

属性はありません。

内容：

instruction:otherwise要素内には、コマンドインストラクション列を記述できます。

2.1.4. 繰り返し

instruction:for-each インストラクション

変換元の文書に含まれる任意のノードセット内のノードに対して、繰り返し処理を行うときに使用するコマンドインストラクション要素です。

<!--
    リスト中のアイテムを順に処理する例。
-->
<xvcd:command name="sample:original-command">
    <instruction:for-each select="sample:list/sample:item">
        <!-- 各アイテムに対する処理を記述 -->
          :
    </instruction:for-each>
</xvcd:command>
属性：
select （必須）

繰り返し処理の対象となるノードセットを指定する属性です。ノードセットを特定するXPath式を設定します。

内容：

instruction:for-each要素内には以下の内容を記述できます。

  • instruction:sort要素
    必要に応じて、任意の数だけ記述できます。
    省略可能です。記述する場合は、必ずinstruction:for-each要素内の先頭に記述します。
  • コマンドインストラクション列
    実行するコマンドインストラクション列を記述します。

instruction:sort 要素

instruction:for-each要素のselect属性で指定されたノードセットを処理する順をソートするために使用する要素です。 

<!--
    リスト中のアイテムを順に処理する例。
    ただし、処理する順番は各アイテムに設定されたID番号の昇順。
-->
<xvcd:command name="sample:original-command">
    <instruction:for-each select="sample:list/sample:item">
        <!-- アイテムのID番号でソート -->
        <instruction:sort select="@id" data-type="number"/>
        <!-- ソート済みの各アイテムに対する処理を記述 -->
          :
    </instruction:for-each>
</xvcd:command>
属性：
select （必須）

ソートに使用するノードを指定する属性です。ノードを返すXPath式を設定します。

data-type

文字順でソートするか、文字列を数値に変換した値でソートするかを指定する属性です。文字順でソートするときはtextを、数値に変換した値でソートするときはnumberを指定します。属性値テンプレートを記述できます。

省略した場合は、textが指定されたと見なされます。

order

ソート順を指定する属性です。昇順でソートするときはascendingを、降順でソートするときはdescendingを指定します。属性値テンプレートを記述できます。

省略した場合は、ascendingが指定されたと見なされます。

内容：

instruction:sort要素は空要素です。

2.1.5. 例外処理

instruction:try インストラクション

実行時に例外が発生する可能性があるコマンドインストラクション列を囲み、発生した例外の処理や、例外発生の有無にかかわらず実行しなければならない処理を要素内に記述するコマンドインストラクション要素です。 

<instruction:try>
    <!-- 実行時に例外が発生しうるインストラクション列 -->
    :
    <instruction:catch test="$instruction:exception/instruction:exception-name='例外クラス名'">
        <!-- 例外発生時の処理 -->
        :
    </instruction:catch>
    <instruction:finally>
        <!-- 必ず最後に行う処理 -->
        :
    </instruction:finally>
</instruction:try>
属性：

属性はありません。

内容：

instruction:try要素内に記述できる内容は、以下のとおりです。

  • コマンドインストラクション列
    実行時に例外が発生する可能性がある、一連のコマンドインストラクション列を記述します。
  • instruction:catch要素
    必要な数だけ記述できます。
    省略可能です。
  • instruction:finally要素
    必要に応じて、１つだけ記述できます。
    instruction:finally要素を使用するときは、必ずinstruction:try要素内の最後に記述します。
    省略可能です。

instruction:try要素内の末尾には、少なくともinstruction:catch要素とinstruction:finally要素のどちらか１つが記述されている必要があります。

instruction:catch 要素

instruction:try要素内のコマンドインストラクションの実行中に、発生した例外を処理する手続きを記述する要素です。

属性：
test （必須）

発生した例外が処理対象かそうでないかを評価するXPath式を記述する属性です。XPath式は例外オブジェクトをコンテキストノードとして評価されます。XPath式を評価した結果、trueとなったときだけ、要素内に記述されたコマンドインストラクション列が実行されます。 instruction:catch要素が複数記述されている場合は、記述されている順に評価を行い、最初に評価結果がtrueとなったものの内容だけが実行されます。

内容：

instruction:catch要素内にはコマンドインストラクション列を記述できます。

instruction:catch要素内の処理で$instruction:exceptionという名前の変数を使用すると、例外オブジェクトを参照できます。

instruction:finally 要素

instruction:try要素内の一連の処理を終了する前に、必ず実行しなければならないコマンドインストラクション列を記述する要素です。

属性：

属性はありません。

内容：

instruction:finally要素内にはコマンドインストラクション列を記述できます。

instruction:throw インストラクション

XVCDを処理するプロセッサで例外が発生したときに、例外オブジェクトをスローするコマンドインストラクション要素です。例外オブジェクトについての詳細は、「例外オブジェクト」をご覧ください。

属性：
exception （必須）

例外オブジェクトを指定する属性です。通常、 instruction:catch要素でキャッチした例外オブジェクトをそのままスローします。

内容：

instruction:throw要素は空要素です。

2.1.5.1. 例外オブジェクト

例外オブジェクトは、XVCD上では次の要素から成るXML文書フラグメントとして表現されます。

例外オブジェクトを構成する要素は以下のとおりです。

instruction:exception-name 要素

Javaの例外クラス名が、内容として出力される要素です。

属性：

属性はありません。

内容：

instruction:exception-name要素内には、実行中に発生したJavaの例外クラス名が記述されます。

instruction:message 要素

Javaの例外オブジェクトのメッセージ文字列が内容として出力される要素です。

属性：

属性はありません。

内容：

instruction:message要素内には、Javaの例外オブジェクトの持つメッセージが記述されます。

instruction:cause 要素

その例外オブジェクトが発生する原因となった、例外の履歴が内容として記述される要素です。

属性：

属性はありません。

内容：

instruction:cause要素内には、その例外オブジェクトが発生する原因となった例外の、Javaの例外クラス名の履歴が記述されます。

2.2. UI 系インストラクション

2.2.1. ダイアログボックス

instruction:message-box インストラクション

メッセージボックスを表示するコマンドインストラクション要素です。

<!-- 確認メッセージ［はい］［いいえ］を表示 -->
<instruction:message-box
    title="確認"
    type="question"
    option="yes-no"
    return-to="result">
    ●●してもよろしいですか？
</instruction:message-box>

<instruction:if test="$result = 'yes'">
    <!-- ［はい］がクリックされた場合 -->
      :
</instruction:if>
属性：
title

メッセージボックスのタイトルを指定する属性です。属性値テンプレートを記述できます。

省略した場合、システムで規定されている文字列が使用されます。

type

メッセージボックスの種類を指定する属性です。次の文字列で指定します。

information
情報
error
エラー
warning
警告
question
確認
plain
プレーン

属性値テンプレートを記述できます。

省略した場合、informationが指定されたと見なされます。

option

メッセージボックスに表示するボタンの組み合わせを指定する属性です。次の文字列で指定します。

default
デフォルトの組み合わせ
通常は［OK］だけが表示されます。
yes-no
［Yes］と［No］の組み合わせ
yes-no-cancel
［Yes］・［No］・［Cancel］の組み合わせ
ok-cancel
［OK］と［Cancel］の組み合わせ

属性値テンプレートを記述できます。

省略した場合、defaultが指定されたと見なされます。

initial

メッセージボックスに表示するボタンのうち、初期フォーカスを持つボタンを指定します。ここで指定したボタンはメッセージボックス内でのデフォルトボタンとなります。次の文字列で指定します。

default
先頭にあるボタンに初期フォーカスを設定します。
yes
［Yes］ボタン
no
［No］ボタン
ok
［OK］ボタン
cancel
［Cancel］ボタン

属性値テンプレートを記述できます。

省略した場合、defaultが指定されたと見なされます。

return-to

メッセージボックスでの選択結果を格納する変数の名前を指定する属性です。QNameで記述します。選択結果は、 instruction:dialog-result要素で構成されるXML文書フラグメントで表現されます。

例えば、メッセージボックスで［Yes］が選択された場合は、次のようなXML文書フラグメントが作成されます。

<instruction:dialog-result>yes</instruction:dialog-result>

instruction:dialog-result要素の内容には、次の文字列が設定されます。

yes
［Yes］または［はい］が選択された。
no
［No］または［いいえ］が選択された。
ok
［OK］が選択された。
cancel
［キャンセル］が選択された。または、クローズボックスをクリックしてダイアログボックスが終了された。

省略した場合、実行結果は取得できません。

内容：

instruction:message-box要素内には、メッセージボックスで表示する文字列の元となる任意のXML文書フラグメントを記述できます。記述されたXML文書フラグメントがVCによって変換された結果の文字列が、メッセージボックスに表示されます。

instruction:file-chooser インストラクション

ファイル選択ダイアログボックスを表示し、選択結果をXML文書フラグメントとして返すコマンドインストラクション要素です。

<!--
    1. ファイル選択ダイアログボックスを表示する。
       選択結果は変数 result に格納する。
-->
<instruction:file-chooser return-to="result">
    <instruction:filter pattern="*.*"  label="すべての種類"/>
    <instruction:filter pattern="*.xml"  label="XML ファイル"/>
    <instruction:filter pattern="*.html" label="HTML ファイル"/>
</instruction:file-chooser>
<!--
    2. ［OK］が押された場合、選択されたファイルを別ウィンドウで開く。
-->
<instruction:if test="$result/instruction:dialog-result = 'ok'">
    <instruction:call name="command:open">
        <instruction:with-param name="command:url" select="$result/instruction:file"/>
    </instruction:call>
</instruction:if>
属性：
return-to （必須）

ファイル選択ダイアログボックスでの選択結果を格納する変数の名前を指定する属性です。QNameで記述します。選択結果は、 instruction:dialog-result要素と instruction:file要素で構成されるXML文書フラグメントで表現されます。 

<!-- ファイルを選択したあと、［OK］がクリックされた場合 -->
<instruction:dialog-result>ok</instruction:dialog-result>
<instruction:file>file:/C:/foo/bar/foobar.xml</instruction:file>

ファイルが選択されたときは、instruction:file要素がXML文書フラグメントに含まれます。ファイルの選択が中止されたときは、instruction:file要素はXML文書フラグメントに含まれません。 

<!-- ［Cancel］がクリックされた場合 -->
<instruction:dialog-result>cancel</instruction:dialog-result>
type

ファイル選択ダイアログボックスの種類を指定する属性です。文字列で記述します。値にsaveを指定したときは、ファイル保存用のダイアログボックスが表示されます。それ以外の文字列を値に指定したときは、開くファイルを選択するダイアログボックスが表示されます。

省略した場合、開くファイルを選択するダイアログボックスが表示されます。

title

ファイル選択ダイアログボックスのタイトルを指定する属性です。属性値テンプレートを記述できます。

省略した場合、システムで規定されている文字列が使用されます。

directory

ダイアログボックスを表示するときに、一覧表示されるディレクトリを指定する属性です。エンコード済みURLで記述します。属性値テンプレートを記述できます。

省略した場合、前回ファイルを選択したときのディレクトリの内容が一覧表示されます。前回ファイルを選択しなかった場合は、システムのユーザーホームディレクトリの内容が一覧表示されます。

multi-select

ファイル選択ダイアログボックスで、ファイルを複数選択できるようにするかしないかを指定する属性です。文字列で記述します。trueを指定すると、ファイルを複数選択できるようになります。それ以外の文字列を指定すると、選択できるファイルは１つだけになります。

省略した場合、true以外の文字列が指定されていると見なされます。

appended-extension

type属性にsaveが指定されたときに、補完する拡張子を指定する属性です。拡張子の補完は、拡張子がないファイル名が指定されたときに、拡張子を自動的に補完する機能です。選択結果のinstruction:file要素の内容には、拡張子が補完されたファイル名が設定されます。属性値テンプレートを記述できます。

省略した場合、拡張子を補完しません。

内容：

instruction:file-chooser要素内には以下の要素を記述できます。

  • instruction:filter要素
    必要に応じて、任意の数だけ記述できます。
    省略可能です。
    省略した場合は、表示できるすべての種類のファイルを表示します。

instruction:filter 要素

ファイル選択ダイアログボックスに表示するファイルの種類を指定する要素です。

属性：
pattern （必須）

ファイル選択ダイアログボックスの一覧に表示するファイルの種類を、パターン文字列で指定する属性です。パターン文字列は、次のように記述します。

ファイル種類は、ワイルドカード（*）と拡張子で表現します。 

*.xml

複数の種類を記述するときは、セミコロン（;）で区切ってつなげます。 

*.xml;*.xvcd;*.xsl

拡張子をワイルドカードとすると、すべてのファイルの種類を表示するパターンになります。

*.*
label

ファイルの種別を表す文字列を指定する属性です。属性値テンプレートを記述できます。

省略した場合、pattern属性で指定された文字列だけが表示されます。

内容：

instruction:filter要素は空要素です。

instruction:directory-chooser インストラクション

ディレクトリ選択ダイアログボックスを表示し、選択結果をXML文書フラグメントとして返すコマンドインストラクション要素です。

<!--
    1. ディレクトリ選択ダイアログボックスを表示する。
       選択結果は変数 result に格納する。
-->
<instruction:directory-chooser return-to="result"/>
<!--
    2. ［OK］が押された場合の処理。
        選択されたディレクトリを新しく別ウィンドウで開く。
-->
<instruction:if test="$result/instruction:dialog-result = 'ok'">
    <instruction:call name="command:open">
        <instruction:with-param
            name="command:url"
            select="$result/instruction:directory"/>
    </instruction:call>
</instruction:if>
属性：
return-to （必須）

ディレクトリ選択ダイアログボックスでの選択結果を格納する変数の名前を指定する属性です。QNameで記述します。選択結果は、 instruction:dialog-result要素と instruction:directory要素で構成されるXML文書フラグメントで表現されます。 

<instruction:dialog-result>ok</instruction:dialog-result>
<instruction:directory>file:/C:/Program%20Files/</instruction:directory>

ディレクトリが選択されたときは、instruction:directory要素がXML文書フラグメントに含まれます。ディレクトリの選択が中止されたときは、instruction:directory要素はXML文書フラグメントに含まれません。 

<instruction:dialog-result>cancel</instruction:dialog-result>
title

ディレクトリ選択ダイアログボックスのタイトルを指定する属性です。属性値テンプレートを記述できます。

省略した場合、システムで規定されている文字列が使用されます。

directory

ディレクトリ選択ダイアログボックスを表示するときに、最初に一覧表示されるディレクトリを指定する属性です。エンコード済みURLで記述します。属性値テンプレートを記述できます。

省略した場合、前回ディレクトリを選択したときのディレクトリの内容が一覧表示されます。前回ディレクトリを選択しなかった場合は、システムのユーザーホームディレクトリの内容が一覧表示されます。

内容：

instruction:directory-chooser要素は空要素です。

instruction:template-chooser インストラクション

XML文書テンプレート選択ダイアログボックスを開き、選択結果をXML文書フラグメントとして返すコマンドインストラクション要素です。

典型的な使用方法としては、 instruction:load-fragmentインストラクションと組み合わせて以下のように使用します。 

<!--
    1. XML文書テンプレート選択ダイアログボックスを表示する。
       選択結果は変数 result に格納する。
-->
<instruction:template-chooser return-to="result"/>
<!--
    2. ［OK］が押された場合の処理
       2.1 選択されたXML文書テンプレートをロードする
       2.2 ロードしたXML文書テンプレート（XML文書フラグメント）を挿入する
-->
<instruction:if test="$result/instruction:dialog-result = 'ok'">
    <instruction:load-fragment
        href="{$result/instruction:template-url}"
        return-to="fragment"/>
    <xvcd:insert ref="$somewhere" select="$fragment"/>
</instruction:if>
属性：
return-to （必須）

XML文書テンプレート選択ダイアログボックスでの選択結果を格納する変数の名前を指定する属性です。QNameで記述します。

選択結果は、 instruction:dialog-result要素、 instruction:template-url要素、 instruction:template-label要素で構成されるXML文書フラグメントで表現されます。 

<instruction:dialog-result>ok</instruction:dialog-result>
<instruction:template-url>new:file:///foo/bar.xml</instruction:template-url>
<instruction:template-label>SAMPLE DOCUMENT TEMPLATE</instruction:template-label>

ただし、instruction:dialog-result要素の内容がokでない場合は、instruction:template-url要素およびinstruction:template-label要素はXML文書フラグメントに含まれません。 

<instruction:dialog-result>cancel</instruction:dialog-result>
title

XML文書テンプレート選択ダイアログボックスのタイトルを指定する属性です。属性値テンプレートを記述できます。

省略した場合、システムで規定されている文字列が使用されます。

内容：

instruction:template-chooser要素は空要素です。

instruction:color-chooser インストラクション

色選択ダイアログボックスを表示し、選択結果をXML文書フラグメントとして返すコマンドインストラクション要素です。

<!--
    1. 色選択ダイアログボックスを表示する。
       選択結果は変数 result に格納する。
-->
<instruction:color-chooser return-to="result"/>
<!--
    2. ［OK］が押された場合の処理。
-->
<instruction:if test="$result/instruction:dialog-result = 'ok'">
    <!--
        色の選択結果 (RGB値) を利用する部分。
        赤は $result/instruction:color/@red,
        緑は $result/instruction:color/@green,
        青は $result/instruction:color/@blue で参照。
    -->
      :
</instruction:if>
属性：
return-to （必須）

色選択ダイアログボックスでの選択結果を格納する変数の名前を指定する属性です。QNameで記述します。選択結果は、 instruction:dialog-result要素と instruction:color要素で構成されるXML文書フラグメントで表現されます。 

<instruction:dialog-result>ok</instruction:dialog-result>
<instruction:color red="111" green="111" blue="111"/>

色が選択されたときは、instruction:color要素がXML文書フラグメントに含まれます。色の選択が中止されたときは、instruction:color要素はXML文書フラグメントに含まれません。 

<instruction:dialog-result>cancel</instruction:dialog-result>
title

色選択ダイアログボックスのタイトルを指定する属性です。属性値テンプレートを記述できます。

省略した場合、システムで規定されている文字列が使用されます。

内容：

instruction:color-chooser要素は空要素です。

instruction:font-family-chooser インストラクション

フォント選択ダイアログボックスを表示し、選択結果をXML文書フラグメントとして返すコマンドインストラクション要素です。

<!--
    1. フォント選択ダイアログボックスを表示する。
       選択結果は変数 result に格納する。
-->
<instruction:font-family-chooser return-to="result"/>
<!--
    2. ［OK］が押された場合の処理。
-->
<instruction:if test="$result/instruction:dialog-result = 'ok'">
    <!--
        フォントの選択結果を利用する部分。
        選択されたフォント情報は $result/instruction:font-family で参照。
    -->
      :
</instruction:if>
属性：
return-to （必須）

フォント選択ダイアログボックスでの選択結果を格納する変数の名前を指定する属性です。QNameで記述します。選択結果は、 instruction:dialog-result要素と instruction:font-family要素で構成されるXML文書フラグメントで表現されます。 

<instruction:dialog-result>ok</instruction:dialog-result>
<instruction:font-family>'ＭＳ Ｐゴシック',sans-serif</instruction:font-family>

フォントが選択されたときは、instruction:font-family要素が選択結果のXML文書フラグメントに含まれます。フォントの選択が中止されたときは、instruction:font-family要素は選択結果のXML文書フラグメントに含まれません。 

<instruction:dialog-result>cancel</instruction:dialog-result>
title

フォント選択ダイアログボックスのタイトルを指定する属性です。属性値テンプレートを記述できます。

省略した場合、システムで規定されている文字列が使用されます。

font-family

フォント選択ダイアログボックス立ち上がり時の選択状態をCSSのfont-familyプロパティによって指定します。属性値テンプレートを使用できます。

省略した場合、フォントが指定されていない状態でフォント選択ダイアログボックスが表示されます。

内容：

instruction:font-family-chooser要素は空要素です。

instruction:dialog インストラクション

要素の内容に記述されたXML文書フラグメントを元にダイアログボックスを表示し、その実行結果を変数に格納するコマンドインストラクション要素です。ダイアログボックスに表示されるノードセットは、XVCDのテンプレートルールを適用して変換されます。ダイアログボックスを終了したときは、表示に使用したXML文書フラグメントの編集結果を変数に格納します。

instruction:dialogインストラクションを使用したダイアログボックスの作成方法について、詳しくは「XVCDによるダイアログボックスの実装」をご覧ください。

属性：
return-to （必須）

ダイアログボックスを終了したときの結果を格納するための変数を指定する属性です。ダイアログボックスを終了したときは、ダイアログボックスに表示されたVC変換後のXML文書フラグメントの編集結果と、終了したときの状態を表す instruction:dialog-result要素からなるXML文書フラグメントが変数に格納されます。

width

表示するダイアログボックスの幅を記述する属性です。ピクセル単位の整数値で記述します。属性値テンプレートを記述できます。

省略した場合、ダイアログボックス内に表示される内容の幅を元に、適切な幅が設定されます。

height

表示するダイアログボックスの高さを記述する属性です。ピクセル単位の整数値で記述します。属性値テンプレートを記述できます。

省略した場合、ダイアログボックス内に表示される内容の高さを元に、適切な高さが設定されます。

内容：

instruction:dialog要素には、ダイアログボックス内に表示する内容となるXML文書フラグメントを記述できます。記述したXML文書フラグメントは、VCによる変換が行われます。ダイアログボックスには、変換後のXML文書フラグメントが表示されます。

2.2.1.1. ダイアログボックス選択結果

次のコマンドインストラクション要素で表示されたダイアログボックスの結果は、XML文書フラグメントとして返されます。

ダイアログボックスの実行結果を表現するXML文書フラグメントを構成する要素・属性は、以下のとおりです。

instruction:dialog-result 要素

各ダイアログボックスの実行結果を表すために使用される要素です。

属性：
is-closed-with-command （必須）

ダイアログボックスが、 command:dialog-closeコマンドによって終了されたかされなかったかを表すために使用される属性です。真偽値が設定されます。command:dialog-closeコマンドによって終了された場合、trueが設定されます。ダイアログボックスのクローズボックスなどで強制的に終了された場合は、falseが設定されます。

instruction:dialogインストラクションを使用して実行されたダイアログボックスの結果を表現するときに使用されます。

内容：

instruction:dialog-result要素内には、ダイアログボックス内に表示されたXML文書フラグメントの編集結果が記述されます。

instruction:file 要素

instruction:file-chooserインストラクションで選択されたファイルを表現するために使用される要素です。 

<instruction:file>file:/C:/foo/bar/foobar.xml</instruction:file>
属性：

属性はありません。

内容：

instruction:file要素内には、選択されたファイルの絶対URLが記述されます。URLはエンコード済みURLです。

instruction:directory 要素

instruction:directory-chooserインストラクションで選択されたディレクトリを表現するために使用される要素です。 

<instruction:directory>file:/C:/Program%20Files/</instruction:directory>
属性：

属性はありません。

内容：

instruction:directory要素内には、選択されたディレクトリの絶対URLが記述されます。URLはエンコード済みURLです。

instruction:template-url 要素

instruction:template-chooserインストラクションで選択されたドキュメントテンプレートのURLを表現するために使用される要素です。

属性：

属性はありません。

内容：

instruction:template-url要素内には、選択されたドキュメントテンプレートのURLが絶対URLで記述されます。URLはエンコード済みURLです。

instruction:template-label 要素

instruction:template-chooserインストラクションで選択されたドキュメントテンプレートのラベルを表現するために使用される要素です。

属性：

属性はありません。

内容：

instruction:template-label要素内には、選択されたドキュメントテンプレートのラベル文字列が記述されます。

instruction:color 要素

instruction:color-chooserインストラクションで選択された色を表現するために使用される要素です。 

<instruction:color red="0" green="0" blue="0"/>
属性：
red （必須）

選択された色をRGB値で表現したときの赤（Red）の値が設定される属性です。 0 - 255の間の値が設定されます。

green （必須）

選択された色をRGB値で表現したときの緑（Green）の値が設定される属性です。 0 - 255の間の値が設定されます。

blue （必須）

選択された色をRGB値で表現したときの青（Blue）の値が設定される属性です。 0 - 255の間の値が設定されます。

内容：

instruction:color要素は空要素です。

instruction:font-family 要素

instruction:font-family-chooserインストラクションで選択されたフォントを表現するために使用される要素です。 

<instruction:font-family>'ＭＳ Ｐゴシック',sans-serif</instruction:font-family>
属性：

属性はありません。

内容：

instruction:font-family要素内にはCSSのfont-familyプロパティの値が記述されます。

2.2.2. UI操作

instruction:show-popup インストラクション

要素内に記述された内容に基づいて、ポップアップメニューを表示するコマンドインストラクション要素です。要素内にはXVCDのテンプレートルールを記述することができます。 

<xvcd:action event="event:*[@popup-trigger='true']">
    <instruction:param name="event:event"/>
    <instruction:show-popup
        x="{$event:event/*/@area-x}"
        y="{$event:event/*/@area-y}">
        <ui:ui version="1.0">
            <ui:context-menu>
                <ui:menu-item label="Foo" command="command:foo"/>
            </ui:context-menu>
        </ui:ui>
    </instruction:show-popup>
</xvcd:action>
属性：
x （必須）

表示するポップアップメニューの左上のx座標を指定する属性です。ピクセル単位の実数値で指定します。属性値テンプレートを記述できます。 座標は文書表示領域の左上からの相対位置で指定します。

y （必須）

表示するポップアップメニューの左上のy座標を指定する属性です。ピクセル単位の実数値で指定します。属性値テンプレートを記述できます。 座標は文書表示領域の左上からの相対位置で指定します。

内容：

instruction:show-popup要素内には、XVCDのテンプレートルールを記述します。要素内に記述したテンプレートルールの評価結果は、以下の要素になる必要があります。

instruction:show-status-message インストラクション

ステータスバーにメッセージを出力する要素です。

<ctrl:trigger>
    <!-- ポインタがボタン上へ移動したときに、ステータスバーにメッセージを出力 -->
    <xvcd:action event="event:mouse-entered">
        <instruction:show-status-message message="設定ボタンです"/>
    </xvcd:action>
    <!-- ポインタがボタンの外へ移動したときに、ステータスバーに空のメッセージを出力 -->
    <xvcd:action event="event:mouse-exited">
        <instruction:show-status-message message=""/>
    </xvcd:action>
    <ctrl:label>設定</ctrl:label>
</ctrl:trigger>
属性：
message （必須）

ステータスバーに出力するメッセージを指定します。属性値テンプレートを記述できます。

内容：

instruction:show-status-message要素は空要素です。

instruction:tooltip インストラクション

ツールチップで表示する文字列を設定する要素です。ツールチップはポインタが一定時間停止しているときに表示されます。

例えば、 ctrl:trigger要素を使用したボタンコントロールでツールチップを使用する場合、次のイベントを受け取ったときにツールチップの文字列を設定します。

  • ポインタがボタンコントロール上へ移動したとき
    ツールチップに表示する文字列を設定します。
  • ポインタがボタンコントロールの外へ移動したとき
    ツールチップに表示されている文字列を消去します。
<ctrl:trigger>
    <!-- ポインタがボタン上へ移動したときに、ツールチップ文字列を設定 -->
    <xvcd:action event="event:mouse-entered">
        <instruction:tooltip>設定ボタンです</instruction:tooltip>
    </xvcd:action>
    <!-- ポインタがボタンの外へ移動したときに、ツールチップ文字列を消去 -->
    <xvcd:action event="event:mouse-exited">
        <instruction:tooltip />
    </xvcd:action>
    <ctrl:label>設定</ctrl:label>
</ctrl:trigger>
属性：

属性はありません。

内容：

instruction:tooltip要素内には、XVCDのテンプレートルールを記述します。要素内に記述されたテンプレートルールを評価した結果を、ツールチップで表示する文字列とします。文字列に改行文字があるときは、ツールチップの文字列は改行文字の位置で改行します。

空要素の場合は、ツールチップに設定された文字列が消去されます。このとき、ツールチップが表示されていると、ツールチップが非表示となります。

2.3. I/O系（入出力系）インストラクション

2.3.1. 文書操作

XML文書の作成・読込・保存に関するインストラクションの定義は以下のとおりです。

instruction:create-document インストラクション

指定されたXML文書フラグメントを元に、XML文書を作成するコマンドインストラクション要素です。

<instruction:create-document href="{function:generate-url('sample.xml')}">
    <html>
        <head>
            <title>sample</title>
        </head>
        <body>
            <p>sample</p>
        </body>
    </html>
</instruction:create-document>
属性：
href （必須）

作成したXML文書に割り当てるURLを記述する属性です。エンコード済みURLで記述します。属性値テンプレートを記述できます。

select

作成するXML文書の元となるフラグメントを指定する属性です。

省略した場合、要素の内容が作成するXML文書の元となるXML文書フラグメントとして扱われます。

内容：

instruction:create-document要素内には、作成するXML文書の元となる任意のXML文書フラグメントを記述できます。記述されたXML文書フラグメントは、VCによって変換されます。select属性も同時に記述された場合は、select属性で指定された内容が優先されます。

instruction:load-document インストラクション

URLで指定された文書へリンクジャンプするコマンドインストラクション要素です。

<!--
    編集中のXML文書と同じディレクトリにある
    "sample.xml"というファイルを開く。
-->
<instruction:load-document href="{function:generate-url('sample.xml')}"/>
属性：
href （必須）

リンク先の文書のURLを指定する属性です。エンコード済みURLで記述します。属性値テンプレートを記述できます。

target

リンク先の文書を読み込んで表示するフレームを指定する属性です。フレームを識別するID値を記述します。指定したフレームがリンクジャンプ機能のターゲットフレームにならない場合、リンク元の文書が表示されているフレームの親フレームに読み込まれます。詳細は、「フレーム記述リファレンス」のframes:frame要素をご覧ください。

省略した場合、リンク元の文書が表示されているフレームに読み込まれます。

内容：

instruction:load-document要素は空要素です。

instruction:load-fragment インストラクション

URLで指定された文書を読み込み、XML文書フラグメントとして返すコマンドインストラクション要素です。

<!--
    1. XML文書テンプレート選択ダイアログボックスを表示する。
       選択結果は変数 result に格納する。
-->
<instruction:template-chooser return-to="result"/>
<!--
    2. ［OK］が押された場合の処理
       2.1 選択されたXML文書テンプレートをロードする
       2.2 ロードしたXML文書テンプレート（XML文書フラグメント）を挿入する
-->
<instruction:if test="$result/instruction:dialog-result = 'ok'">
    <instruction:load-fragment
        href="{$result/instruction:template-url}"
        return-to="fragment"/>
    <xvcd:insert ref="$somewhere" select="$fragment"/>
</instruction:if>
属性：
href （必須）

読み込む文書のURLを指定する属性です。エンコード済みURLで記述します。属性値テンプレートを記述できます。

return-to （必須）

読み込まれたXML文書フラグメントを格納する変数の名前を指定する属性です。QNameで記述します。

内容：

instruction:load-fragment要素は空要素です。

instruction:save-document インストラクション

XML文書の文書ノードを、指定されたURLにファイル保存するコマンドインストラクション要素です。 このコマンドインストラクションの実行後も、XML文書全体の保存先URLは変更されません。 

<!--
    編集中のXML文書と同じディレクトリにある
    "sample.xml"というファイルを読み込み、
    "test.xml"という名前で保存する
-->
<!-- 文書ノード -->
<instruction:variable
    name="doc"
    select="function:document(function:generate-url('sample.xml'))"/>
<!-- 保存先 URL -->
<instruction:variable
    name="save-url"
    select="function:generate-url('test.xml')"/>
<!-- 保存する -->
<instruction:save-document href="{$save-url}" select="$doc"/>
属性：
href （必須）

ファイルの保存先URLを指定する属性です。エンコード済みURLで記述します。属性値テンプレートを記述できます。

select

ファイルに保存する文書ノードを指定する属性です。XPath式で記述します。

省略した場合、コンテキストノードの祖先である文書ノードが保存されます。

内容：

instruction:save-document要素は空要素です。

2.4. ツール系インストラクション

2.4.1. 開発・デバッグ

XVCDでスクリプトを開発するときの、動作確認やデバッグに使用するインストラクションの定義は以下のとおりです。

instruction:message インストラクション

XVCDを処理するプロセッサに対して、メッセージを出力するコマンドインストラクション要素です。要素内に記述されたXML文書フラグメントがXVCDを処理するプロセッサによって処理されたあと、その文字列値がメッセージとして出力されます。

XVCDでスクリプトを開発するときの、動作確認やデバッグに使用するインストラクションです。

属性：

属性はありません。

内容：

instruction:message要素内には、出力するメッセージの元となる任意のXML文書フラグメントを記述できます。記述されたXML文書フラグメントがVCによって変換された結果の文字列が、メッセージに表示されます。

instruction:tree-message インストラクション

XVCDを処理するプロセッサに対して、XML文書フラグメントを出力するコマンドインストラクション要素です。要素内に記述されたXML文書フラグメントがXVCDを処理するプロセッサによって処理されたあと、その結果のXML文書フラグメントが階層に合わせて字下げされて出力されます。

XVCDでスクリプトを開発するときの、動作確認やデバッグに使用するインストラクションです。

属性：

属性はありません。

内容：

instruction:tree-message要素内には、出力するメッセージの元となる任意のXML文書フラグメントを記述できます。記述されたXML文書フラグメントはVCによって変換されます。メッセージには変換された結果のXML文書フラグメントが出力されます。

2.4.2. その他

instruction:beep インストラクション

ブザーを鳴らすときに使用するコマンドインストラクション要素です。

<!--
    ボタンがクリックされたときにブザーを鳴らす
-->
<ctrl:trigger>
    <ctrl:label>ボタン</ctrl:label>
    <xvcd:action event="ctrl:triggered">
        <instruction:beep/>
    </xvcd:action>
</ctrl:trigger>
属性：

属性はありません。

内容：

instruction:beep要素は空要素です。

(C)2006 株式会社ジャストシステム