変換

変換は、ホスト画面の変換方法を制御する HATS リソースです。リッチ・クライアント・アプリケーションでは、変換は com.ibm.hats.rcp.ui.transformations.RcpTransformation クラスから拡張する Java™ クラスです。このクラスは、Standard Widget Toolkit (SWT) コンポジット・クラスから拡張します。SWT コンポジット・クラスは、 他のコントロールを含む UI コントロールです。変換は、SWT ウィジェット、 ホスト・コンポーネント (ComponentRendering コンポジット)、DefaultRendering コンポジット、 グローバル変数コントロール、マクロ・コントロール、ホスト・キー、 およびアプリケーション・キーを含むことができます。変換は SWT コンポジットであるため、 標準の SWT ウィジェットも追加できます。

変換は一般的に、以下のような場合に使用されます。

変換の編集

変換は、「リッチ・クライアント・コンテンツ」>「変換」の下の「HATS プロジェクト」ビュー内にあります。

Java クライアント・アプリケーション・エディター (VE) 機能 (別名 Visual Editor) が Rational® SDP とともにインストールされている場合、これを使用して変換を編集できます。このセクションの情報に加えて、「HATS ユーザーと管理者のガイド」の『リッチ・クライアント・プロジェクトの変換の編集』を参照してください。

Visual Editor でパレット・ビューを使用すると、新しいコントロールを変換に追加できます。標準の SWT コントロールを 追加できるだけでなく、ComponentRendering コンポジットなどの HATS 固有のコントロールを 追加することもできます。パレットからコントロールを追加すると、変換に Java コードが生成されます。生成されたコードは、 選択されたパレット項目に基づいて特定のクラスを 参照します (表 7 を参照)。パレット項目は、 パレットの HATS ドロワーで使用可能です。

表 7. HATS 固有のコントロールおよび対応するクラス
HATS 固有のパレット・ツール コードに生成されるクラス
コンポーネント com.ibm.hats.rcp.transform.ComponentRendering
デフォルト・レンダリング com.ibm.hats.rcp.transform.DefaultRendering
マクロ・キー com.ibm.hats.rcp.transform.MacroKey
グローバル変数 com.ibm.hats.rcp.transform.GlobalVariableControl
ホスト・キー com.ibm.hats.rcp.transform.HostKey
アプリケーション・キー com.ibm.hats.rcp.transform.ApplicationKey

この表に示したクラスについて詳しくは、以降のセクションで説明します。

HATS 固有のコントロール

標準の SWT コントロールを追加するだけでなく、ComponentRendering コンポジットなどの HATS 固有のコントロールを変換に追加することもできます。以下のセクションでは、これらの HATS 固有のコントロールについて説明します。

ComponentRendering クラス

ComponentRendering コンポジットは、指定された コンポーネント、ウィジェット、および設定を使用して指定されたホスト画面領域を 変換する専門化された UI コントロールです。選択された HATS ウィジェットに 基づいて、SWT ウィジェットが生成され、ComponentRendering コンポジットに 置かれます。以下のコード例で、この概念を示します。

ComponentRendering componentRendering = new ComponentRendering(this, SWT.NONE);
   componentRendering.setScreenCapture(<fully qualified transformation 
                                                    class name>.screenCapture);
   componentRendering.setComponent("<fully qualified component class name>");
   componentRendering.setComponentSettings
                            (new com.ibm.hats.common.StringableProperties(""));
   componentRendering.setWidget("<fully qualified widget class name>");
   componentRendering.setWidgetSettings
           (new com.ibm.hats.common.StringableProperties("<widget settings>"));
   componentRendering.setRegion(new com.ibm.hats.transform.regions.
                    BlockScreenRegion(start_row, start_col, end_row, end_col));
   componentRendering.setApplyTextReplacement(true);
   componentRendering.setApplyGlobalRules(true);

注:
setWidgetSettings メソッド および setComponentSettings メソッドは、 パラメーターとして標準の java.util.Properties オブジェクトを 取ります。HATS StringableProperties クラスの 使用とは対照的に、setProperty(String,String) メソッドを 使用して Properties オブジェクトを構成し、データを取り込むことができます。

DefaultRendering クラス

DefaultRendering コンポジットは、レンダリング・セットを使用して指定されたホスト画面領域を変換する、専門化された UI コントロールです。レンダリング・セットは、 プロジェクト設定エディターの「レンダリング」タブで 定義します。レンダリング・セットの定義について詳しくは、 「HATS ユーザーと管理者のガイド」の 『デフォルト・レンダリング』を 参照してください。選択されたレンダリング・セットに基づいて、SWT ウィジェットが 生成され、DefaultRendering コンポジットに置かれます。以下のコード例で、この概念を示します。

DefaultRendering defaultRendering = new DefaultRendering(this, SWT.NONE);
defaultRendering.setScreenCapture(this.screenCapture);
defaultRendering.setRenderingSetName("main");
defaultRendering.setApplyTextReplacement(true);
defaultRendering.setApplyGlobalRules(true);
defaultRendering.setRegion
         (new com.ibm.hats.transform.regions.BlockScreenRegion(1,1,24,80));

MacroKey クラス

com.ibm.hats.rcp.transform.MacroKey クラスは、個々のマクロを ボタン (org.eclipse.swt.widgets.Button クラス) または リンク (org.eclipse.swt.widgets.Link クラス) として 表します。以下のコード例で、 ボタンとして表示される MacroKey を示します。

macroKey = new MacroKey(this, SwtTransformationConstants.BUTTON);
macroKey.setText("macro_1");
macroKey.setMacroName("macro_1");
macroKey.addSelectionListener(new org.eclipse.swt.events.SelectionListener() {
    public void widgetSelected(org.eclipse.swt.events.SelectionEvent e) {
        com.ibm.hats.runtime.services.ISessionService 
                               sessionService = getSessionService();
        if (sessionService != null) {
            sessionService.playMacro(macroKey.getMacroName());
        }
    }
    public void widgetDefaultSelected(org.eclipse.swt.events.SelectionEvent e) {
    }
});

GlobalVariableControl クラス

com.ibm.hats.rcp.transform.GlobalVariableControl クラスは、 グローバル変数を静的テキスト (org.eclipse.swt.widgets.Label クラス) または 入力フィールド (org.eclipse.swt.widgets.Text クラス) として 表します。以下のコード例で、グローバル変数を入力フィールドとして 表示する GlobalVariableControl を示します。

gvControl = new GlobalVariableControl(this, SwtTransformationConstants.TEXT);
gvControl.setInitialValueFromGlobalVariable(true);
gvControl.setUseAllIndices(true);
gvControl.setGlobalVariableName("userName");
gvControl.setShared(false);
gvControl.setSeparator("");
gvControl.setPasswordField(false);
gvControl.setIndex(0);
gvControl.setGlobalVariableIndexed(false);

注:
GlobalVariableControl クラスを使用せずに変換からグローバル変数を 読み取ったり変更したりすることができます。詳しくは、グローバル変数値の設定および検索を参照してください。

HostKey クラス

com.ibm.hats.rcp.transform.HostKey クラスは、個々のホスト・キーを ボタン (org.eclipse.swt.widgets.Button クラス) または リンク (org.eclipse.swt.widgets.Link クラス) として 表します。複数のキーを 1 つの HostKey インスタンスに 組み込むことはできません。複数のキーが必要な場合は、 複数の HostKey インスタンスを定義してください。以下のコード例で、 押されたときにホストに [PF1] を送信する ボタンとして表示される HostKey を示します。

hostKey = new HostKey(this, SwtTransformationConstants.BUTTON);
hostKey.setText("F1");
hostKey.setCommand("[pf1]");
hostKey.addSelectionListener(new org.eclipse.swt.events.SelectionListener() {
    public void widgetSelected(org.eclipse.swt.events.SelectionEvent e) {
        com.ibm.hats.runtime.services.ISessionService 
                                    sessionService = getSessionService();
        if (sessionService != null) {
            sessionService.sendCommand(hostKey.getCommand());
        }
    }
    public void widgetDefaultSelected(org.eclipse.swt.events.SelectionEvent e) {
    }
});

ApplicationKey クラス

これは、個々のアプリケーション・キーをボタンまたはリンクとして 表すクラスです。複数のキーを 1 つの ApplicationKey クラスに 組み込むことはできません。複数のキーが必要な場合は、 複数の ApplicationKey インスタンスを定義してください。以下のコード例で、 クリックされると HATS ランタイムに切断コマンドを 送信するリンクとして表示される ApplicationKey を示します。

applicationKey = new ApplicationKey(this, SwtTransformationConstants.LINK);
applicationKey.setText("<a>Disconnect</a>");
applicationKey.setCommand("disconnect");
applicationKey.addSelectionListener(new org.eclipse.swt.events.SelectionListener() {
    public void widgetSelected(org.eclipse.swt.events.SelectionEvent e) {
        com.ibm.hats.runtime.services.ISessionService 
                                     sessionService = getSessionService();
        if (sessionService != null) {
            sessionService.sendCommand(applicationKey.getCommand());
        }
    }
    public void widgetDefaultSelected(org.eclipse.swt.events.SelectionEvent e) {
    }
});

変換クラス

表 8 は、変換クラスでオーバーライド可能なメソッドの一覧を示します。

表 8. RcpTransformation メソッド
メソッド 説明
getApplicationKeypadDisplayInfo() アプリケーション・キーパッドの表示方法と表示するかどうかを 制御する IApplicationKeypadDisplayInfo オブジェクトを 戻します。このメソッドにより、この変換に合わせて アプリケーション・キーパッドをカスタマイズできます。このメソッドからヌルを 戻すと、アプリケーションのデフォルト設定に基づいて デフォルト・アプリケーション・キーパッドを 表示することが示されます。
getAutoAdvanceOrderer() 自動拡張の実行方法と実行するかどうかを 制御する IAutoAdvanceOrderer オブジェクトを戻します。デフォルトのインプリメンテーションでは ヌルが戻され、システムがプロジェクト設定から使用する 自動拡張ハンドラーを決定することが示されます。
getDefaultMonospacedFont() 変換レベルでデフォルトのモノスペース・フォントをオーバーライドできるようにします。このメソッドの使用例については、デフォルトのモノスペース・フォントのオーバーライドを参照してください。
getHostKeypadDisplayInfo() ホスト・キーパッドの表示方法と表示するかどうかを 制御する IHostKeypadDisplayInfo オブジェクトを戻します。このメソッドにより、この変換に合わせて ホスト・キーパッドをカスタマイズできます。このメソッドからヌルを戻すと、 アプリケーションのデフォルト設定に基づいて デフォルト・ホスト・キーパッドを表示することが示されます。このメソッドの 使用例については、ホスト・キーパッドのカスタマイズを参照してください。
getOiaDisplayInfo() OIA の表示方法と表示するかどうかを制御する IOiaDisplayInfo オブジェクトを 戻します。このメソッドにより、この変換に合わせて OIA を カスタマイズできます。このメソッドからヌルを戻すと、 アプリケーションのデフォルト設定に基づいてデフォルト OIA を 表示することが示されます。
getToolbarDisplayInfo() ツールバーの表示方法と表示するかどうかを 制御する IToolbarDisplayInfo オブジェクトを戻します。このメソッドにより、 この変換に合わせてツールバーをカスタマイズできます。このメソッドからヌルを戻すと、 アプリケーションのデフォルト設定に基づいてデフォルトのツールバーを 表示することが示されます。
handlePreSubmit() このメソッドは、コマンドが実行依頼される直前に 呼び出されます。このメソッドの 使用例については、変換の入力の検証を参照してください。
handlePostSubmit() このメソッドは、コマンドが実行依頼された直後に呼び出されます。
isInitialFocusAtCursorPosition() 初期のフォーカスをカーソル位置に置くかどうかを示します。詳しくは、 「HATS ユーザーと管理者のガイド」の 『クライアント設定』にある初期カーソル位置を参照してください。
needsAutoAdvanceSupport() この変換に対して自動拡張機能を使用可能にするかどうかを示します。詳しくは、 「HATS ユーザーと管理者のガイド」の 『クライアント設定』にある自動フィールド進行を使用可能にするを参照してください。
preRender() このメソッドは、render() メソッドの呼び出し前に呼び出されます。
postRender() このメソッドは、render() メソッドが呼び出されて 変換のレンダリングが完了した後に呼び出されます。
setScreenCapture() HATS Toolkit での ComponentRendering および DefaultRendering の編集中に、画面取りを使用するために設定します。componentRendering.setScreenCapture( <fully qualified transformation name>.screenCapture);
needsArrowKeyNavigationSupport() この変換に対して矢印キーを使用したナビゲーションのサポートが有効かどうかを示します。詳しくは、 「HATS ユーザーと管理者のガイド」の 『クライアント設定』にある矢印キー・ナビゲーションのサポートに関する個所を参照してください。

サンプル

ボタンからのキーの送信

パレットを使用して、SWT ボタン・ウィジェットを変換に追加します。RcpTransformation クラスの postRender() メソッドを指定変更します。

注:
postRender() メソッドをオーバーライドするには、 以下のステップを実行します。
  1. ソース・エディター・ペインで右クリックします。
  2. 「ソース」 > 「メソッドのオーバーライド/実装」 を選択します。
  3. RcpTransformation の下にある postRender() にチェック・マークを付けます。
  4. 「OK」をクリックします。

postRender() メソッドに、以下のコードを追加してください。

final RcpContextAttributes attrs = (RcpContextAttributes) getContextAttributes();
		button.addSelectionListener(new SelectionListener()
		{
			public void widgetDefaultSelected(SelectionEvent event) {				
			}
			
			public void widgetSelected(SelectionEvent event) {
				attrs.getSessionService().sendCommand("[enter]");
			}
		});

ユーザーによる SWT リスト・ウィジェット項目選択後の入力フィールドの更新

パレットを使用して、SWT リスト・ウィジェットを変換に追加します。RcpTransformation クラスの postRender() メソッドを指定変更します。postRender() メソッドに、以下のコードを追加してください。

//retrieve a model adapter that is bound to a host field at position 1527.
//assuming that the list widget will update the field at this position on the host.
final IModelAdapter modelAdapter = factory.getFieldAdapter(1527);

		list.addSelectionListener(new SelectionListener()
		{
			public void widgetDefaultSelected(SelectionEvent event) {				
			}
			
      //when an item in the list is selected, update the field at position 1527 
      //with the value of selected item.
			public void widgetSelected(SelectionEvent event) {
				modelAdapter.setValue(list.getData(list.
                  getItem(list.getSelectionIndex())).toString());
			}
		});

変換からのグローバル変数の値の設定

以下のコード・サンプルは、カスタマー番号をプロンプトで問い合わせる場合に、ユーザーに値の入力依頼を行うプロンプトの出し方、そして次に customerNumber グローバル変数をこの値に設定する方法を示しています。

Button button = new Button(this, SWT.NONE);
button.setText("Prompt for command");
button.addSelectionListener(new org.eclipse.swt.events.SelectionAdapter() {

public void widgetSelected(org.eclipse.swt.events.SelectionEvent e) {
    InputDialog dialog = new InputDialog(getShell(), "Prompt", 
                                         "Enter a customer number:", "", null);
    if (dialog.open() == InputDialog.OK) {
        String value = dialog.getValue();
        getSessionService().getParameterDataAccessService().
                setParameterValue("hatsgv_customerNumber",value);
    }
}
 });

注:
HATS ランタイムは、フォームが送信されるまで、setParameterValue() メソッド呼び出しによって設定された新規グローバル変数の値を認識しません。

グローバル変数値の設定および検索

以下の例では、「myGlobalVariable」という名前の非共用グローバル変数に値を設定します。

getSessionService().getParameterDataAccessService().setParameterValue
                              ("hatsgv_myGlobalVariable", "some new value");

以下の例では、同じ名前の非共用グローバル変数から値を取得します。

// This will return some string or null
String str = getSessionService().getParameterDataAccessService().
                                getParameterValue("hatsgv_myGlobalVariable"); 

注:
グローバル変数を共用する場合は、 前記の例の hatsgv_myGlobalVariable を hatssharedgv_myGlobalVariable で 置き換えてください。

変換の入力の検証

すべての HATS リッチ・クライアント変換では、com.ibm.hats.rcp.transform.IPrePostSubmitHandler インターフェースをインプリメントします。これにより、特定の変換が表示されるとき、HATS ランタイムに対する要求の直前や直後に発生する状況を制御できるようになります。このインターフェースの 1 次機能によって、HATS ランタイムへの要求が発行される前に、ユーザーから変換に提供された値を検証することができます。1 つ以上のユーザーの応答に問題が見つかった場合、ユーザーは、要求のキャンセル、パラメーターの変更、コマンドの変更、およびユーザーへのメッセージの表示を行うことができます。

注:
検証は、変換クラスの handlePreSubmit メソッドで実行する必要があります。これは、HATS ランタイムへの要求が発行される直前に、このメソッドが呼び出されるためです。要求が一度発行されると、その変更もキャンセルも行えません。

次のサンプルでは、ユーザーが行った入力に対する検証の実行方法を示しています。無効値が指定された場合、実行依頼はキャンセルされ、ユーザーに対してメッセージが表示されます。

handlePreSubmit メソッドが変換クラスで指定変更されていない場合、以下のステップを実行してください。

  1. (Java エディターで) 変換のソースを右クリックして、「ソース」>「メソッドのオーバーライド/実装」を選択します。
  2. RcpTransformation ノードを拡張して、handlePreSubmit(CommandEvent) の横にチェック・マークを付け、「OK」をクリックします。
  3. 変換ソースにスタブ・メソッドを挿入します (Java コード・スタイルの設定によっては、 コード例が下記のようにならない場合があります)。
        public void handlePreSubmit(CommandEvent event) {
            // TODO Auto-generated method stub
            super.handlePreSubmit(event);
        }

次のコード・サンプルは、仮想部分数量 (hypothetical part quantity) フィールドの範囲検査を実行する方法を示しています。ユーザーが指定した数量が 500 以下の場合、メッセージが表示され、実行依頼はキャンセルされます。このフィールドは、この変換によって変換されるホスト画面の 4 行目、20 カラム目にあると想定します。既存の handlePreSubmit(CommandEvent) メソッドを以下のコードで置き換えます。

    public void handlePreSubmit(CommandEvent event) {
        // Avoid validation if the user is attempting to disconnect the session
        if (event.getCommand().equals(RuntimeConstants.CMD_DISCONNECT)) {
            return;
        }

        // Retrieve the value of the "quantity" field using the 
        // IHostScreenDataAccessService interface
        // (which is accessed by calling the getHostScreenDataAccessService() 
        // method on the session service)
        // The getFieldValue() method takes a linear screen position and a 
        // length. The 
        // Component.convertRowColToPos() method converts a row, column value 
        // into a linear screen position. 
        // "5" indicates the length of the field.
        String quantityString = getSessionService().
                            getHostScreenDataAccessService().
                            getFieldValue(Component.convertRowColToPos(4, 20, 
                            getHostScreen().getSizeCols()), 5);

        // Convert the numeric string into an int
        int quantity = 0;
        try {
            quantity = Integer.parseInt(quantityString);
        } catch (Exception ex) {
        }

        // Check to ensure the quantity entered is greater than 500
        if (quantity < 500) {
            // Display a message to the user indicating what the problem is
            MessageDialog.openError(getShell(), 
                            getSessionService().getApplication().getName(),
                    "You must order at least 500 units.");

            // Cancel the event (this prevents the request from being made)
            event.setCanceled(true);
        }
    }

ホスト・キーパッドのカスタマイズ

アプリケーション・キーパッドのカスタマイズ

変換の getApplicationKeypadDisplayInfo() メソッドをオーバーライドし、IApplicationKeypadDisplayInfo タイプのオブジェクトを戻すことで、アプリケーション・キーパッドを変換レベルでカスタマイズすることが可能です。

以下に示すコード例は、getApplicationKeypadDisplayInfo() メソッドをオーバーライドすることで、アプリケーション・キーパッド上に「Page down」および「Page up」を変換の適用時表示します。

public IApplicationKeypadDisplayInfo getApplicationKeypadDisplayInfo() {
 // Define the extra keys
 	KeypadKey[] extraKeys = new KeypadKey[] { 
                          new KeypadKey(ECLConstants.PAGEDWN_STR, "Page Down"), 
                          new KeypadKey(ECLConstants.PAGEUP_STR, "Page Up") };

// Construct a new ApplicationKeypadDisplayInfo object using the project-level 
// settings and the new keys
   Application app = getSessionService().getApplication();
   Properties appKeypadSettings = app.getDefaultSettings
      (ApplicationKeypadConstants.SETTINGS_ID);
   ApplicationKeypadDisplayInfo info = new ApplicationKeypadDisplayInfo
      (appKeypadSettings, extraKeys);

  return info;
}

変換ビューのクラスである "MainView" の getApplicationKeypadDisplayInfo() クラスを上書きすることで、アプリケーション・レベルでのアプリケーション・キーパッドのカスタマイズが可能です。詳細については、変換ビューを参照してください。

デフォルトのモノスペース・フォントのオーバーライド

このコード例を使用すると、ホスト画面が標準の 80 列ではなく 132 列である場合は、小さいフォント・サイズが使用されます。

public Font getDefaultMonospacedFont() {
    if (getHostScreen() != null) {
        if (getHostScreen().getSizeCols() == 132) {
            return FontManager.getInstance(getDisplay()).getFont("Courier New", 8, 0);
        }
    }

    return null;
}

他のユーザー・インターフェース・ウィジェットの統合

本セクションのサンプルでは、ユーザーは、org.eclipse.emf.common プラグインをリッチ・クライアント・プロジェクトの依存関係リストに追加する必要があります。これを行うには、以下を実行します。

  1. プロジェクト用のプラグイン・マニフェスト・ファイルを開きます。
  2. 「依存関係」タブで、「追加」をクリックし、「org.eclipse.emf.common」を選択します。
  3. ファイルを保管します。

SWT スライダー・ウィジェットのホスト入力フィールドへの結合

スライダーは、ユーザーが値の範囲から数値を選択できるようにするコントロールです。例えば、OS/400® のメインメニューでは、スライダーを使用して選択を行えます。

パレットを使用して、SWT スライダー・ウィジェットを変換に追加します。RcpTransformation クラスの postRender() メソッドを指定変更します。postRender() メソッドに、以下のコードを追加してください。

// The following code creates 2 adapters :  a FieldAdapter that adapts to a 
// Host Screen field located at a specific position, an IControlAdapter that 
// adapts to a Slider widget, and bind these 2 adapters so that when slider 
// selection is changed, its selection value is updated in the model, and 
// when the data in the model is changed, the slider selection is updated.
// In this example, we bind to the a host screen field located at 
// position (20,007).
    final RcpContextAttributes attrs = (RcpContextAttributes) 
                                                    getContextAttributes();
		HostScreenDataModelManager dataModelManager = attrs.
                                           getHostScreenDataModelManager();
		HostScreenModelAdapterFactory factory = (HostScreenModelAdapterFactory) 
                                  dataModelManager.getModelAdapterFactory();
		final IModelAdapter modelAdapter = factory.getFieldAdapter(1527);
		IControlAdapter sliderAdapter = new SliderWidgetAdapter(slider,dataModelManager);
		dataModelManager.bindControlToModel(sliderAdapter, modelAdapter);

SliderWidgetAdapter クラスの例

//This class allows the slider widget to update a host field with its values and
//also update its value from a host field.
public class SliderWidgetAdapter implements IControlAdapter {

	private Slider slider;  //the target slider widget.
	private IDataModelManager dataModelManager; //handles updating values in the model
     	 
	public SliderWidgetAdapter(Slider slider,IDataModelManager dataModelManager) {
		this.slider = slider;
		this.dataModelManager = dataModelManager;

		//create a SelectionListener such that when the value of the slider
		//is changed, it updates the host field.
		this.slider.addSelectionListener(new SelectionListener()
		{
			public void widgetDefaultSelected(SelectionEvent event) {
			}

			public void widgetSelected(SelectionEvent event) {
				updateModel();
			}		 		 		 
		});
	}
     	 
	//this method calls the updateModel from the IDataModelManager to
	//update the host field.
	private void updateModel() {
		if ( dataModelManager != null )
			dataModelManager.updateModel(this);
	}
     	 
	//return the value of slider selection.
	public String getValue() {
		return slider.getSelection() + "";
	}

	//this method updates the slider selection from a value. This method
	// is called when the value of a host field is changed.
	public void setValue(String value) {	
		try {		 		 		 		 		 
			slider.setSelection(Integer.parseInt(value));
		}
		catch ( NumberFormatException e ) {
			slider.setSelection(0);
		}
	}
}