XMLリファレンス

このチュートリアルはユーザインターフェース定義のXML表現，つまりGUIKitXMLについての文書である．

DTD

これは現行の GUIKit XML定義を表すDTDである．

<?xml encoding="UTF-8"?>

<!--
   GUIKit` XML Markup Language, GUIKitXML DTD
   Copyright 2004, Wolfram Research, Inc.
-->

<!ENTITY % common-elems "widget|group|string|integer|double|null|true|false|invokemethod|property|script|space|fill|align">
<!ENTITY % invokemethod-valued-elems "%common-elems;">
<!ENTITY % bindevent-valued-elems "widget|script|invokemethod|property|bindevent">
<!ENTITY % stmt-elems "%common-elems;|bindevent">

<!-- layout can exist as either a simple attribute or as a subelement
       on widget and group.  The subelement trumps the attribute if
       both exist 
    -->

<!ELEMENT widget (layout?,args?,expose*,(%stmt-elems;)*)>
<!ATTLIST widget
  src NMTOKEN #IMPLIED
  ref CDATA #IMPLIED
  class NMTOKEN #IMPLIED
  id CDATA #IMPLIED
  layout CDATA #IMPLIED>

<!ELEMENT group (layout?,(%stmt-elems;)*)>
<!ATTLIST group
  layout CDATA #IMPLIED
  id CDATA #IMPLIED
  root CDATA #IMPLIED>
  
<!--  value should be in integer pixel units -->
<!ELEMENT space EMPTY >
<!ATTLIST space
  value CDATA #REQUIRED>
  
<!ELEMENT fill EMPTY >

<!--  ref should be a widget reference string
        from and to can be either "Before" or "After"
 -->
<!ELEMENT align EMPTY >
<!ATTLIST align
  ref CDATA #IMPLIED
  from CDATA #IMPLIED
  to CDATA #IMPLIED>
  
<!ELEMENT layout (grouping?,alignment?,stretching?,spacing?,border?)>

<!--  grouping either specifies a simple attribute type of
        None, Automatic, Column, Row, Grid  or a
        subelement that resolves to a Java layout manager widget
        equivalent to just using a "layout" property on the container
 -->
<!ELEMENT grouping (%common-elems;) >
<!ATTLIST grouping
  type CDATA #IMPLIED>

<!-- alignment type can be Automatic, Left, Center, Right, Top or Bottom
       and can specify different values for both axes such as
       "Automatic, Top" or "Left,Center"
    -->
<!ELEMENT alignment EMPTY >
<!ATTLIST alignment
  type CDATA #REQUIRED>
  
<!-- stretching type can be Automatic, None, WidgetAlignments, True, Maximize
       and can specify different values for both axes such as
       "None,True"
    -->
<!ELEMENT stretching EMPTY >
<!ATTLIST stretching
  type CDATA #REQUIRED>
  
<!--  value should be in integer pixel units -->
<!ELEMENT spacing EMPTY >
<!ATTLIST spacing
  value CDATA #REQUIRED>
  
<!ELEMENT border (((border+)|%common-elems;)?) >
<!ATTLIST border
  type CDATA #IMPLIED
  title CDATA #IMPLIED
  left CDATA #IMPLIED
  right CDATA #IMPLIED
  top CDATA #IMPLIED
  bottom CDATA #IMPLIED>
  
<!-- Versions:

        Create and configure a widget:
        
         <widget src="filename | URL" [id="name-to-register-as"]> ... </widget>
         <widget src="class:a.b.C" [id="name-to-register-as"]> ... </widget>
         <widget class="a.b.C" [id="name-to-register-as"]> ... </widget>
         
         src="class:className" is identical to using class="className".
         The arguments define the constructor args.
         The arguments to the inner GUIKitXML file can be accessed via the names:
         "#1", "#2", ..., "#n".

        Configure an existing widget:
       
         <widget ref="name-to-look-up" [class="a.b.C"] > ... </widget>
         
       The class attrib is optional because the API does not need it,
       but a possible compiler may.
     If id attribute is present then register the widget. 
 -->

<!-- constructor arguments -->
<!ELEMENT args (%common-elems;)*>
<!ATTLIST args
  ref CDATA #IMPLIED>
<!-- Versions:
      <args ref=""/> provides a way of referencing a 
      vector or collection of widgets to use as arguments.
      
      Most importantly, used with <args ref="##"/>
      to specify that the array of arguments passed to the script
      should be used as arguments to the constructor of the wrapping widget.
      A useful pattern for building reusable GUIKit widgets in 
      self-contained files.
      
 -->
     
<!ELEMENT property (%common-elems;)?>
<!ATTLIST property
  target CDATA #IMPLIED
  name NMTOKEN #REQUIRED
  index NMTOKEN #IMPLIED
  value CDATA #IMPLIED
  id CDATA #IMPLIED
  invokeThread NMTOKEN #IMPLIED
  invokeWait NMTOKEN #IMPLIED>
<!-- Versions:
       Get: <property [target="t"] name="foo" [index="num"] [id="name"]/>
       Set: <property [target="t"] name="foo" [index="num"] [id="name"]>
               some-element
            </property>
            or
            <property [target="t"] name="foo" [index="num"] value="stuff"
                      [id="name"]/>
            where stuff is either one of the valid elements.
     If index is given, then property is an indexed property.
     XML and Wolfram Language is 1-based, Java is 0-based
     Set version of property returns nothing (i.e., void) and hence only
     makes sense as a direct child of <widget>. If id attribute is present
     then register the property value. -->

<!ELEMENT bindevent (%bindevent-valued-elems;)+>
<!ATTLIST bindevent
  target CDATA #IMPLIED
  name NMTOKEN #REQUIRED
  filter NMTOKEN #IMPLIED
  id CDATA #IMPLIED
  invokeThread NMTOKEN #IMPLIED
  invokeWait NMTOKEN #IMPLIED>

<!-- Versions:
       <bindevent [target="t"] name="e" [filter="f"]>
         <widget ... />
       </bindevent>

     This is the conventional event binding. The target t is the
     target of the binding, not the target of the actual firing of
     the event. Bind the child widget as a listener for e events from
     target t. The child widget must implement the appropriate listener
     interface. The filter f is optional and used in rare cases only if (e = propertyChange or
     vetoableChange) as that allows property
     and vetoable change listeners to register for specific properties
     rather than any property. The filter will name a property in
     these cases. 
     name="mouse" filter="mouseEntered" can instead just be specified by name="mouseEntered" now
     
     Missing target attribute makes the context widget be
     the target.


       <bindevent [target="t"] name="e" [filter="f"]>
         <script [language="mathematica"]>
       ...
         </script>
       </bindevent>

     When event e occurs in source, process the script. If
     filter is specified, then only events delivered which match
     that filter cause the script to be processed. In general, the
     filter attribute is used to name a method in a listener type
     that has multiple methods (e.g., WindowEvent in AWT). For event
     name = propertyChange or vetoableChange, the filter is the name
     of the property for which the binding should be done. JDK1.2
     has direct support for these types of property and vetoable
     change listeners, but others will require the
     propchange/vetochange event processor to do the filtering work.
     Missing target attribute makes the context widget be the target.
     See the <script> element for a description of how to access the
     arguments to the script (such as an event widget, or any
     arbitrary list of event arguments).-->


<!ELEMENT script (#PCDATA|%stmt-elems;)*>
<!ATTLIST script
  language NMTOKEN #IMPLIED
  src NMTOKEN #IMPLIED>
<!--
     The script contained in the element is processed by a scripting
     engine capable of processing the language described by the language
     attribute. The value of the language attribute can be anything
     supported by the widget scripting framework. The src attribute can
     give a URL or relative file from which the script is to be loaded.

     The arguments to the <script> element can be accessed via the names:
     "#1", "#2", "#3", ..., "#n"

     Example:
       <widget class="java.awt.Button">
         <bindevent name="action">
           <script>
               <invokemethod target="demomgr" name="load">
                 <property target="#1" name="actionCommand"/>
               </invokemethod>
         **************************************************
         above will call the "load" method of the widget named
         "demomgr" with the "actionCommand" property of the
         actionevent widget generated by the event source.
         Note that the widget "#0" in this case will be
         java.lang.String("actionPerformed"), which is the
         name of the method via which the event was delivered.
          **************************************************
              </script>
         </bindevent>
       </widget>
     -->


<!-- call a method -->
<!ELEMENT invokemethod (%invokemethod-valued-elems;)*>
<!ATTLIST invokemethod
  target CDATA #IMPLIED
  name NMTOKEN #REQUIRED
  id CDATA #IMPLIED
  invokeThread NMTOKEN #IMPLIED
  invokeWait NMTOKEN #IMPLIED>
<!-- The arguments to the method are the children widgets and the signature
     of the method to call is defined by the children's types.
     If id attribute is present then register the return value. -->


<!ELEMENT string (#PCDATA)>
<!ATTLIST string
  value CDATA #IMPLIED
  id CDATA #IMPLIED>
<!-- treat the pcdata as a string. empty <string/> is 'new String("")'.
     If id attribute is present then register the string. -->

<!ELEMENT integer (#PCDATA)>
<!ATTLIST integer
  value CDATA #IMPLIED
  id CDATA #IMPLIED>
<!-- treat the pcdata as a integer.
     If id attribute is present then register the integer. -->
     
<!ELEMENT double (#PCDATA)>
<!ATTLIST double
  value CDATA #IMPLIED
  id CDATA #IMPLIED>
<!-- treat the pcdata as a double.
     If id attribute is present then register the double. -->
     
<!ELEMENT null (#PCDATA)>
<!ATTLIST null
  class CDATA #IMPLIED
  id CDATA #IMPLIED>
<!-- null. If id attribute is present then register the Null. -->
    
<!ELEMENT true EMPTY>
<!-- Boolean.TRUE -->
<!ELEMENT false EMPTY>
<!-- Boolean.FALSE  -->
     
<!ELEMENT expose EMPTY >
<!ATTLIST expose
  ref CDATA #REQUIRED
  as CDATA #IMPLIED>
  
<!-- expose can be child elements of <widget class="*.xml"> to expose 
     widgets registered in the child xml document to the parent documents
     widget registry, optionally using a different ref than the child by
     specifying an attribute. -->

<args>

<args>要素を使って，含んでいるウィジェットが親<widget>の新たなインスタンスオブジェクトコンストラクタの引数として使われるように指定する．

ウィジェットセットがウィジェット名のリファレンスを使うように指定することは<args>要素の非常に一般的な使い方である．

<widget class="javax.swing.JButton">
    <args ref="##"/>
</widget>

以下では，オブジェクトのコンストラクタの引数を使って，フレームのタイトルを指定する．

<widget src="Frame">
  <args>
    <string value="Calc with Wolfram Language"/>
  </args>
  ...

<bindevent>

<bindevent>要素を使ってターゲットウィジェットからイベントがトリガされたときにスクリプトコードあるいは他のメソッド呼出しが起るように関連付ける．次はイベントアクションとの2つの形式の関連付けコードである．

<bindevent [target="t"] name="e" [filter="f"]>
  <script>
  ...
  </script>
</bindevent>

イベントeが起ると，スクリプトが処理される．フィルタが指定されていれば，フィルタにマッチするイベントだけが配信されスクリプトが処理されるようにする．一般に，フィルタの属性が複数のメソッドを持つ（AWTのWindowEvent等の）リスナタイプのメソッドの指定に使われる．name="propertyChange"あるいはname="vetoableChange"のイベントに関しては，フィルタはバインディングが行われるべき属性の名前である．ターゲットの属性がない場合はラッピングコンテキスト<widget>がターゲットになる．スクリプトの引数へのアクセスのし方についての説明は<script>要素を見よ．これには"##"，"#1"，"#2"等のウィジェットレジストリ中の特別な名前が含まれる．

<bindevent [target="t"] name="e" [filter="f"]>
  <widget ... />
</bindevent>

前のケースでは，<widget>が適切なリスナインスタンスを実装するウィジェットに分解されなければならない．

次の例では，スクリプトが<bindevent>要素内のスクリプトがトリガされるたびに定義される，MouseEventインスタンスに分解される"#"のような特別に登録されたイベントオブジェクトを利用する．

<widget src="MathCanvas" id="canvas">
  <bindevent name="mouseDragged">
    <script>
      mouseDraggedFunc[ 
        WidgetReference["#"] @  getX[], 
        WidgetReference["#"] @ getY[] ];
     </script>
  </bindevent>
</widget>

次は簡単なスクリプトを一般的なButtonアクションイベントにバインドする．

<widget src="Button">
  <bindevent name="action">
    <script>incrementFieldValue[];</script>
  </bindevent>
</widget>

<invokemethod>

<invokemethod>要素を使ってウィジェットに対してメソッドの呼出しを行う．これは，メソッドが名前属性だけで指定される簡単な引数を持たない呼出しでも，メソッドの引数を表す子要素を含むものでもよい．

次は簡単な引数を持たないメソッドの呼出しである．

<invokemethod name="doLayout"/>

次はメソッドの呼出しに引数を指定する子要素を必要とする例である．ターゲットとなる属性が存在しない場合には，メソッド呼出しのターゲットは<invokemethod>のラッピングウィジェットインスタンスとなる．

  <invokemethod target="frame" name="setSize">
      <integer value="400"/>
      <integer value="400"/>
  </invokemethod>

<expose>

含まれたインターフェース定義からのウィジェットへの外部アクセスを許容したい場合は <expose>要素を使う．他の定義をラップしている場合は，通常はルートウィジェットだけが自動的に使用可能である． <expose>は他のウィジェットへのアクセスを浸透させるだけでなく，ラッピングインスタンスで検索に使われるウィジェットの参照名も再定義する．参照の名前を変えるのは，同じインスタンスを複数公開する必要はないが各インスタンスに異なる名前でアクセスを提供する場合にその名前を公開する際に特に便利である．

この例における定義では，通常"frame"で参照されるトップレベルのコンポーネントのみがこの定義のユーザに使用可能である．外部定義の "progressbar2base"もまた"bar"という識別名で参照される別のウィジェット参照を含んでいると分かっている場合は，この定義内で<expose>要素を使って"bar"という名前で検索でされる"progressbar2base"内のユーザのウィジェットへのアクセスを許可することができる．

<?xml version="1.0"?>
<widget src="progressbar2base" id="frame">
   <args>
    <string value="Wrapped Progress" />
    <string  value="Wrapped complete:" />
    <integer value="20" />
  </args>
  <expose ref="bar"/>
</widget>

オプションas= attributeを使い，"progressBar"という名前のウィジェットにアクセスを許すように，"bar"ウィジェットを異なる名前で公開することを選ぶこともできる．

<?xml version="1.0"?>
<widget src="progressbar2base" id="frame">
   <args>
    <string value="Wrapped Progress" />
    <string  value="Wrapped complete:" />
    <integer value="20" />
  </args>
  <expose ref="bar" as="progressBar"/>
</widget>

<group>

<group>要素はウィジェットグループをネストさせインターフェースがどのように表示されるかをカスタマイズするのに用いられる．今後，さらに例題を追加する予定である．

<group>
 <widget src="Button">
  <property name="label" value="++"/>
  </widget>
 <widget src="Button">
  <property name="label"  value="--"/>
 </widget>
</group>

<widget>

<widget>要素は，<widget>要素のコンテンツに基づいて作られる新たなインスタンスの定義とref="name"属性を使って既存のウィジェットインスタンスへの参照を指定することの両方に用いられる．

次は，新たなインスタンスを作る場合に使われるいくつかのパターンである．

<widget src="filename | URL" [id="name-to-register-as"]> 
  ... 
</widget>

<widget src="class:a.b.C" [id="name-to-register-as"]> 
  ...
</widget>

<widget class="a.b.C" [id="name-to-register-as"]> 
  ... 
</widget>

src="class:a.b.C"とclass="a.b.C"という2つの形は，互換性を持つ同じ機能の2つの形に過ぎない．

次は，既存のウィジェットインスタンスを設定したり検索したりする場合に使われるパターンである．

<widget ref="name-to-look-up"> 
  ... 
</widget>

この定義は，最終的なウィジェットクラスとして何を作るかを定義するリソースを見付けるためにsrc属性を使って新たなウィジェットインスタンスを作る．

<widget src="Button">
  <property name="label" value="++"/>
</widget>

次は， FileDialogの新たなインスタンスを構築する際にこの定義中の別の"frame"という名前のウィジェットを引数として参照している．

<widget src="FileDialog">
  <args>
    <widget ref="frame"/>
    <string value="Save As"/>
    <property  target="class:java.awt.FileDialog" name="SAVE"/>
  </args>
</widget>

<property>

<property>要素を使ってウィジェットの特性値を得るか，あるいは特性値を設定する．子要素あるいはvalue="" 属性とともに<property>要素を使って特性値を設定する．

次は特性値を得るパターンである．

<property [target="t"] name="foo" [index="num"] [id="name"]/>

これら2つのパターンのどちらも特性値の設定に使うことができる．

<property [target="t"] name="foo" [index="num"] [id="name"]>
  some-element
</property>

<property [target="t"] name="foo" [index="num"] value="stuff" [id="name"]/>

ターゲットの属性が存在しない場合は，特性要求のターゲットはラッピングウィジェットインスタンスである．

Wolfram言語およびXML Widget定義の指標は1ベースであるのに対し，J/Link を使ったJavaおよびJavaオブジェクトへの直接呼び出しは0ベースのJava変換であることに注意．

次は，value属性を使ってテキストフィールドのテキスト特性を設定する．

<widget src="TextField" id="textField">
  <property name="text" value="1"/>
</widget>

この場合は，"layout"特性の値は<property>要素の子要素から作られる．

<property name="layout">
  <widget src="GridLayout"/>
</property>

<script>

<script>要素を使って，スクリプトコードをウィジェット定義が読まれたときに実行する一般コードとして，あるいは，特定のイベントとバインドされている場合は，そのイベントが起るたびに実行されるものとして関連付ける．デフォルトで，<script>要素の言語は他の言語が指定されていない限りWolfram言語コードである．language="xml" を使って<script>要素のGUIKitXML子要素が事項するコードを定義するように指定することができる．

スクリプト言語は通常XMLと互換のシンタックスにはなっていないので，<script>要素のテキストコンテンツをCDATAセクションでラップすることを考えてみる．

この場合，ウィジェットのインスタンスが作られた場合に定義を設定するトップレベルの<script>を定義する．

<widget src="Frame">
  <property name="layout">
    <widget  src="GridLayout"/>
  </property>
  
  <script><![CDATA[
  
    incrementFieldValue[] :=
       SetPropertyValue[{"textField", "text"},
        ToString[  ToExpression[PropertyValue[{"textField", "text"}]] + 1, InputForm] ]

   ]]></script>
</widget>

次は，ボタンアクションがトリガされるたびに実行されるようにいくつかのスクリプトコードをバインドする．

<widget src="Button">
  <bindevent name="action">
    <script>incrementFieldValue[];</script>
  </bindevent>
 </widget>

<string>

<string>要素は，子PCDATAとしても値属性を使っても，文字列のインスタンスを定義する便利な方法を提供することができる． <string/>の使用は""の使用に等しい．

次は，同じ文字列インスタンスの代替可能な2通りの形である．

<string value="content"/>
<string>content</string>

使用可能な<string>要素を作ることは，文字列を定義するだけの<widget>要素の使用と同時に<args>要素がPCDATAと他の要素を同時に取ろうとするために生じる問題を，空白スペースの微妙な問題とともに除去する．