ウィジェットのプロパティーと関数

多くの場合、Rich UI ウィジェットは EGL ハンドラー・パーツであり、ステレオタイプ RUIWidget です。 例外として、Tooltip、DataGridTooltip、および TreeTooltip などがあります。これらすべてはステレオタイプ RUIHandler であり、それぞれが外部型に基づく Dojo ウィジェットです。

以下のいずれかの方法でウィジェット・タイプに使用可能なプロパティーと関数について説明します。

特定の関数またはプロパティー (例えば、myWidget.myFunction()myWidget.myProperty) にアクセスするには、常にドット構文を使用してください。

ほとんどのウィジェットで使用可能なプロパティー

大部分の EGL プロパティーは EGL システム・コードでのみ使用可能で、実行時には使用できません。ただし、ウィジェット・プロパティーは、実行時にコードで使用可能なフィールドです。

classstyle などのスタイル関連プロパティーは、IBM 提供のすべてのウィジェットで使用可能です。スタイルについて詳しくは、『ウィジェット・スタイル』を参照してください。

ビジネス・アプリケーションの開発では、以下のプロパティーが役立ちます。
  • children は、従属ウィジェットがある場合に、それらのウィジェットの配列へのアクセスを可能にします。詳細については、後のセクションを参照してください。
  • class は、ウィジェットを表示するときに使用するカスケーディング・スタイル・シート (CSS) クラスを識別します。
  • disabled は、ウィジェットが使用不可かどうかを示すブール値を取ります。 使用不可になっているウィジェットは、イベントに応答できず、ほとんどのブラウザーでそのテキストはぼかし表示されます。
  • id は、特定のウィジェットの ID を割り当てるか取得するために使用されるストリングを取ります。カスケーディング・スタイル・シート (CSS) 内の ID を使用して、そのウィジェットの表示特性を識別できます。 また、EGL を JavaScript ライブラリーと統合する場合は、このプロパティーを使用すると、JavaScript ロジックで使用する ID を割り当てることができます。

    ウィジェット (例えば、box) が、特定の DOM 要素ではなく DOM サブツリーに対応する場合、この ID は、サブツリー内の最上位の DOM 要素の ID です。DOM の概要については『ブラウザーによる Rich UI アプリケーションの処理方法の説明』を参照してください。

  • position は、ウィジェットの x 座標と y 座標の意味を指定して、以下のいずれかの値を取ります。
    static
    ウィジェットの x 座標と y 座標は無視されます。これは、デフォルトの動作です。 position 値が static である場合に最初に x 値と y 値を設定して、次に position 値を変更すると、表示される位置が変更されます。
    absolute
    ウィジェットの x 座標と y 座標は、割り当てる値と取得する値が異なります。
    • 割り当てる値は、最も近い静的ではない親の、左上部の起点を基準とした位置にする必要があります。これらの座標は alignment 値の影響を受けません。
    • ウィジェットから取得するウィジェットの x 座標と y 座標の値は、スクロール・バーの高さを含め、ブラウザーを基準とした位置のままになります。
    relative
    ウィジェットの x 座標と y 座標、親の左上部を基準とした位置です。 ウィジェットの親が文書要素である場合は、座標は、ブラウザーの表示可能域の左上部を基準とした位置です。
  • tabIndex は、タブ順序でウィジェットの配置を識別する整数を取ります。例えば、tabIndex 値として 2 を割り当てられているウィジェットは、tabIndex 値が 1 のウィジェットからユーザーがタブ移動した後でフォーカスを受けます。(1 や 2 ではなく) 10 や 20 などの数値を使用すると、他のウィジェットを後で追加できます。

    デフォルトのタブ順序は、ブラウザー固有です。

  • x 値と y 値は、ウィジェットの x 座標から y 座標を参照する整数です。その座標の意味は、position プロパティーの値によって異なります。 position プロパティーの説明で推奨されているように、グラフィカルな起点 は、ブラウザー・ウィンドウの左上部か、親ウィジェットの左上部のいずれかです。以下の規則が適用されます。
    • x 値は、起点の右側に対して正で、左側に対して負です。
    • y 値は起点の下では正で、上では負です。

    ウィジェットは、その親の外部や、場合によっては表示可能域の外部に配置できます。

  • zIndex は、同じ x と y の位置にあるその他のウィジェットとの関係でウィジェットの位置 (前面に対する近さ) を識別する整数を取ります。zIndex 値が比較的大きい (例えば、4) ウィジェットは、zIndex 値が比較的小さい (例えば、2) ウィジェットより前面に近くなります。position の値が静的である場合は、zIndex 値は無効です。
以下のプロパティーは、ステレオタイプ RUIWidget に基づく新規ウィジェット・タイプの開発で特に有用です。
  • innerHTML は、div、floatLeft、または floatRight の各ウィジェットなど、コンテナー内の HTML を割り当てるか取得するために使用されるストリングです。
  • innerText は、コンテナー内のテキストを割り当てるか取得するために使用されるストリングです。innerText を使用して、そのタイプに固有のテキスト・プロパティーを提供できます。
  • logicalParent は、タイプがコンテナーのウィジェットを開発するために使用されます。子をコンテナーに追加するコードを作成する際に、適切な親 DOM 要素を参照するように、logicalParent プロパティーを設定します。DOM の概要については『ブラウザーによる Rich UI アプリケーションの処理方法の説明』を参照してください。

    例えば、ボックスの子については、parent プロパティーは、ボックスではなく、DOM テーブル要素内の DOM TD 要素を参照します。ただし、logicalParent プロパティーは、ボックスを表し、DOM テーブル要素の親である DOM Div 要素を参照します。

    parent は、ウィジェット・タイプの開発用で、DOM 要素にアクセスできるようにします。DOM の概要については『ブラウザーによる Rich UI アプリケーションの処理方法の説明』を参照してください。
以下のプロパティーは、アラビア語またはヘブライ語を読むユーザーと対話するためのものです。
  • numericSwap は、ヒンディ数字をアラビア語で使用できるようにするストリング (「Yes」または「No」) を取ります。ヒンディ数字を使用するには、numericSwapreverseTextDirection を「Yes」に設定します。
  • reverseTextDirection は、ウィジェットでの文字方向を逆にするかどうかを示すストリング (「Yes」または「No」) を取ります。
  • symmetricSwap は、表示されるテキストの論理的な意味を保存するために特殊文字のペアを置換するかどうかを示すストリング (「Yes」または「No」) を取ります。値が「Yes」である場合は、<、>、[、および { などの文字のペアは >、<、]、および } に置き換えられます。
  • textLayout は、「Visual」または「Logical」の 2 つのストリングのいずれか 1 つを取ります。
    • 設定が「Visual」のときに、ユーザーが「A」を入力してから「B」を入力すると (また、「A」と「B」が双方向言語の文字である場合)、表示される文字は「AB」になります。表示順序は入力順序 (左から右) となり、これはデータがローカル・メモリーに格納される順序にもなります。
    • 設定が「Logical」である場合は、表示される文字は「BA」です。

    ほとんどの場合、z/OS® または IBM® i が稼働するマシンから派生したアラビア語またはヘブライ語のコンテンツには設定「Visual」が適しています。

  • widgetOrientation はアラビア語とヘブライ語のテキスト用です。 このプロパティーは、「LTR」(左から右) または「RTL」(右から左) の 2 つのストリングのいずれか 1 つを取ります。「LTR」を指定すると、ウィジェットは、標準の非双方向ウィジェットとして機能します。「RTL」を指定した場合、ウィジェットの動作は逆になります。つまり、ドロップダウン・リストのスクロール・バーは左側に表示され、入力フィールドのテキスト入力方向は右から左になり、テキストは右揃えになります。
以下のプロパティーによって、アクセシビリティーが追加されます。
  • ariaLive は、支援技術 (つまり、画面領域でユーザーに更新を通知できるスクリーン・リーダー) のために提供されるサポートのレベルを示します。そのような技術の仕様は以下のとおりです。

    http://www.w3.org/TR/wai-aria

    ariaLive 値は、引用符付きストリング ("off"、"polite"、"assertive"、または "rude") で、それぞれプロパティー: live に関する指定のセクションで説明します。

  • ariaRole は、支援技術に使用される、ウィジェットに指定された役割を示します。詳細については、前述した仕様を参照してください。

    ariaRole 値は、"button" や "listbox" などの引用符付きストリングで、それぞれ役割 に関する指定のセクションで説明します。

ほとんどのウィジェットで使用可能な関数

以下の関数は、RUIWidget 型であるすべての IBM 提供のウィジェットで使用可能です。
  • 関数 fadeIn を使用すると、ウィジェットはフェードイン (ゆっくり表示される) し、関数 fadeOut を使用すると、ウィジェットはフェードアウト (ゆっくり非表示になる) します。
    fadeIn (duration int in, callback EffectCallback)
    fadeOut (duration int in, callback EffectCallback)
    それぞれの関数は、以下の 2 つのパラメーターを取ります。
    duration
    ウィジェットがフェードインするかフェードアウトするかどうかのプロセスの開始と終了の間のミリ秒数。
    callback
    ウィジェットがフェードインまたはフェードアウトするとすぐに呼び出される関数への参照。この関数はパラメーターを取らず、戻り値を持ちません。関数を指定しない場合は、この引数を null に設定します。
    以下に例を示します。
    myButton.fadeOut(1000, null);
  • 関数 focus を使用すると、ウィジェットはフォーカスを受けます。
    focus()

    例えば、フォーカスを受けているボタンが強調表示され、ユーザーが ENTER キーを押す操作は、ユーザーがボタンをクリックする操作に相当します。同様に、フォーカスを受けているテキスト・フィールド (読み取り専用ではない場合) には、ユーザーが最初にフィールドにタブ移動せずに印刷可能文字を入力することによってデータを入力できるように、カーソルが表示されます。

    ユーザーは、TAB を繰り返し押して、使用可能なフィールドの間を循環できます。キーを押すたびに、フォーカスは次のアプリケーション・フィールドまたはブラウザー上のフィールド (例えば、Web アドレス・フィールド) のいずれかに移ります。

    以下に、focus の呼び出しの例を示します。
    myButton.focus();
  • 関数 morph を使用すると、徐々にウィジェットの表示を変更できます。この関数は、関数の 1 つを繰り返し呼び出します。この方法では、ランタイム呼び出しによって引き起こされる動作をコードで指定します。
    morph (duration int in, callback EffectCallback, morphFunction MorphFunction )
    この関数は、以下の 3 つのパラメーターを取ります。
    duration
    プロセスの開始と終了の間のミリ秒数。
    callback
    プロセスが完了するとすぐに呼び出される関数への参照。この関数はパラメーターを取らず、戻り値を持ちません。関数を指定しない場合は、この 2 番目の引数を null に設定します。
    customMorphFunction
    カスタム morph 関数 への参照。これは、前述した期間の間に繰り返し呼び出される関数です。カスタムの morph 関数は 2 つのパラメーター (変更されるウィジェットと、EGL ランタイムによって割り当てられる浮動小数点) を取ります。浮動小数点は、0 と 1 の間の小数部で、期間の終わりに向けての進行を反映します。(カスタムの morph 関数を呼び出すたびに、浮動小数点の値は大きくなります。) この小数部は、カスタム・ロジックを実行するために可能な期間と必要な時間が指定されている場合は、カスタムの morph 関数が呼び出される回数の計算に基づいています。 カスタムの morph 関数には戻り値はありません。
    以下に例を示します。
    myButton.morph(1000, null, myCustomMorphFunction);
  • 関数 resize を使用すると、徐々にウィジェットのサイズを変更できます。
    resize (width int in, height int in,
           duration int, callback EffectCallback)
    この関数は、以下の 4 つのパラメーターを取ります。
    width
    必要な最終的な幅 (ピクセル単位)。
    height
    必要な最終的な高さ (ピクセル単位)。
    duration
    プロセスの開始と終了の間のミリ秒数。
    callback
    プロセスが完了するとすぐに呼び出される関数への参照。この関数はパラメーターを取らず、戻り値を持ちません。関数を指定しない場合は、この引数を null に設定します。
    以下に例を示します。
    myButton.resize(100, 100, 1000, myFunction);

子プロパティーと関連する関数

「Rich UI ウィジェット」では、 ウィジェットのサブセットが「コンテナー・ウィジェット」として分類されます。そのようなウィジェットには、従属ウィジェットの配列を指定する children プロパティーが含まれています。配列内のすべての要素は、以下で説明されているように、名前付きウィジェットまたは匿名のウィジェットを参照します。
  • 名前付きウィジェットは、以下のコードにおけるすべてのウィジェットの場合と同様に、子配列の外部で宣言されます。
    myInTextField TextField{};
    myButton Button{ text = "Input to Output", onClick ::= click };
    myOutTextField TextField{};
    
    myBox Box{ columns = 3, 
                 children = [ myInTextField,  myButton, myOutTextField ]};

    配列が名前付きウィジェットを複数回参照する場合は、最後の参照のみが使用され、その他の参照は無視されます。

  • anonymous 宣言 は、キーワード new で始まり、どのコードでも参照できません。この宣言では、ウィジェットの配置を検討するときにウィジェットを作成できます。
    myInTextField TextField{};
    myTextOutField TextField{};
    
    myBox box{columns=3, 
              children=[myInTextField,
                        new Button{ text = "Input to Output", onClick ::= click},
                        myOutTextField]};
多くの場合、親ウィジェットのタイプは Box または Div で、子ウィジェットの配置は、次のようにして親タイプの影響を受けます。
  • Box ウィジェットには、columns プロパティーが含まれており、このプロパティーの値によって、children 配列にリストされている各ウィジェットのデフォルトの配置が指定されます。例えば、columns=1 の場合は、配列にリストされているウィジェットは、垂直方向の単一の列に表示されます。 同様に、columns=2 の場合は、2 番目のウィジェットはすべて 2 番目の列に表示され、後続のウィジェット (例えば、配列の 3 番目) は、新規行の最初の列に表示されます。

    通常、columns の値が n である場合は、配列の位置 n+1 にあるウィジェットは、新規行の最初の列に表示されます。columns 値を指定しないと、Box ウィジェットの子は右側に拡張されます。

  • 表示可能域の右側に拡張されたウィジェットへのアクセスを可能にするために、Div ウィジェットの子は、(必要に応じて) 水平スクロール・バーを使用して右側に拡張されます。

別のウィジェットの子である Div ウィジェットは、前のウィジェットの下に垂直に表示されます。

任意の関数で children の値を再割り当てすることで、Web ページを変更できます。(同様に、構成中の関数で initialUI の値を再割り当てできます。) 例えば、指定されたウィジェットを宣言したと仮定すると、次の構文が有効です。
   myBox.children = [myInTextField, myButton02, myOutTextField];
children (または initialUI) を再割り当てできますが、appendElement などの動的配列関数または演算子 ::= を使用して変更を行わないでください。代わりに、ウィジェット固有の関数 appendChildappendChildrenremoveChild、および removeChildren を使用してください。以下に、指定されたウィジェットを宣言したと仮定した場合の例を示します。
Function myFirstFunction(){} 
   myBox.appendChild(myOtherButton);
   myBox.appendChildren([myOtherTextField, myOtherButton02]);
   myBox.removeChild(myOtherButton);
   myBox.removeChildren();
end
同様に、以下に示すように、上部の DOM 要素で子を追加または除去できます。
document.body.appendChild(myOtherButton);
document.body.appendChildren([myOtherTextField, myOtherButton02]);
document.body.removeChild(myOtherButton);
document.body.removeChildren(); 

関数 appendChildremoveChild はそれぞれ、単一のウィジェットを受け入れます。appendChildren は、ウィジェットの配列を受け入れます。また、removeChildren は引数を取りません。appendChild または appendChildren の場合は、ウィジェット宣言は匿名または名前付きにできます。removeChild の場合は、ウィジェット宣言は名前付きである必要があります。

注: アプリケーションで removeChild 関数または removeChildren 関数を使用しても、メモリー割り振りに効果はありません。この潜在的に重要な問題について詳しくは、『Rich UI メモリー管理』を参照してください。

異なる親にウィジェットを割り当てることの影響

特定のウィジェットは、 別の 1 つのウィジェット (または、後の例に示すように文書本体) の子にのみすることができます。ウィジェットが親を持つ場合は、 そのウィジェットを別の親の子にさせることができます。この再割り当てを 子ウィジェットの親の再指定 と呼びます。

次の myTopBox の宣言について考えます。このボックスは他の 2 つのボックスの親です。
   myTopBox Box{padding = 8, columns = 1, backgroundColor = "Aqua",
      children =[myBox02, myBox03 ]};
この宣言が、myBox03initialUI 配列に含まれる唯一の要素にする Rich UI ハンドラーに含まれているとします。
handler MyTest type RUIhandler{initialUI =[myBox03]}

実行時に initialUI の代入は、myTopBox の宣言より後で処理されます。この影響により、myBox03 が文書本体の親に再指定され、この結果 myTopBox の子は myBox02 1 つのみになります。

コードでは、ユーザーのボタン・クリックなどの実行時イベントに対応して myTopBox を Web ページに追加できます。その効果は、 次のコードを実行し、ボタンをクリックすることにより確認できます。
import com.ibm.egl.rui.widgets.Box;
import com.ibm.egl.rui.widgets.Button;
import com.ibm.egl.rui.widgets.TextField;
import egl.ui.rui.Event;

handler MyTest type RUIhandler{initialUI =[myBox03]}
 
   myTopBox Box{padding = 8, columns = 1, backgroundColor = "Aqua", 
      children =[myBox02, myBox03 ]};
 
   myBox02 Box{padding = 8, columns = 2, backgroundColor = "DarkGray", 
      children =[myHelloField ]};
 
   myBox03 Box{padding = 8, columns = 3, backgroundColor = "CadetBlue", 
      children =[myInTextField, myButton, myOutTextField] };
 
   myHelloField TextField{readOnly = true, text = "Hello"};
   myInTextField TextField{};
   myButton Button{text = "Input to Output", onClick ::= click};
   myOutTextField TextField{};
 
   function click(e EVENT in)
      document.body.appendChildren([myTopBox]);		
   end
end

文書本体からすべての子を削除した場合の影響

次のステートメントについて考えます。
   document.body.removeChildren();
次の 2 つの影響があります。
  • すべての子ウィジェットが Web ページから削除されます。
  • 外部スタイル・シートへのアクセスがある場合は削除されます。スタイル・シートに ついては『ウィジェット・スタイル』を参照してください。)
外部スタイル・シートへのアクセスを削除することなく文書本体から子を削除するには、次のステートメントのように、個別の子を削除します。
   document.body.removeChild(myBox);

フィードバック