ActiveX コントロールとは、Natural ダイアログに統合できるサードパーティ製のカスタムコントロールです。
このドキュメントでは、次のトピックについて説明します。
ActiveX コントロールと Natural とでは、以下のように異なる用語を使用します。
| ActiveX コントロール | Natural |
|---|---|
| プロパティ | 属性 |
| メソッド | PROCESS GUI ステートメントアクション
|
ActiveX コントロールのハンドルは、組み込みダイアログエレメントと同様に定義しますが、二重山カッコ（<< と >>）内にコーディングする点が異なります。
例：
01 #OCX-1 HANDLE OF <<OCX-Table.TableCtrl.1 [Table Control]>>
上記の例では、"Table.TableCtrl.1" が、ActiveX コントロールがシステムレジストリに登録される際のプログラム ID（ProgID）です。 接頭語 "OCX-" は、ActiveX コントロールであることを示します。 "[Table Control]" は定義オプションで、識別名を示します。
ActiveX コントロールのインスタンスを作成するには、PROCESS GUI ステートメントの ADD アクションを使用します。 そのためには、TYPE 属性の値は、二重山カッコで囲まれた、接頭語 "OCX-" で始まる ActiveX コントロールの ProgID である必要があります。 ProgID とは、ActiveX コントロールがシステムレジストリに登録される際の名前です。 また、識別名を角カッコ（[ と ]）内に指定できます。 また、ActiveX
コントロールのプロパティだけでなく、RECTANGLE-X などの Natural 属性も設定できます。 プロパティ名の前に文字列 "PROPERTY-" を付けて、この組み合せを二重山カッコで囲む必要があります。 ActiveX コントロールのイベントを抑制することもできます。 抑制するには、イベント名の前に文字列 "SUPPRESS-EVENT" を付けて、この組み合せを二重山カッコで囲む必要があります。 SUPPRESS-EVENT プロパティの値は、Natural キーワードの "SUPPRESSED" か "NOT-SUPPRESSED" のどちらかです。
例：
PROCESS GUI ACTION ADD
WITH PARAMETERS
HANDLE-VARIABLE = #OCX-1
TYPE = <<OCX-Table.TableCtrl.1 [Table Control]>>
PARENT = #DLG$WINDOW
RECTANGLE-X = 44
RECTANGLE-Y = 31
RECTANGLE-W = 103
RECTANGLE-H = 46
<<PROPERTY-HeaderColor>> = H'FF0080'
<<PROPERTY-Rows>> = 16
<<PROPERTY-Columns>> = 4
<<SUPPRESS-EVENT-RowMoved>> = SUPPRESSED
<<SUPPRESS-EVENT-ColMoved>> = SUPPRESSED
END-PARAMETERS
単純なプロパティとは、パラメータを持たないプロパティのことです。 ActiveX コントロールの単純なプロパティは、組み込みコントロールの属性と同様に指定します。 属性名を指定するには、プロパティ名の前に接頭語 "PROPERTY-" を付けて、山カッコで囲みます。コンポーネントブラウザに ActiveX コントロールのプロパティが表示されます。 以下の例は、単純なプロパティ CurrentRow および CurrentCol を持つ ActiveX コントロール #OCX-1 を示しています。
例：
* Get the value of a property. #MYROW := #OCX-1.<<PROPERTY-CurrentRow>> * Put the value of a property. #OCX-1.<<PROPERTY-CurrentCol>> := 17
ActiveX コントロールプロパティのデータタイプは、OLE オートメーションによって定義されるデータタイプです。 Natural では、これらのデータタイプは、それぞれ対応する Natural データタイプにマップされます。 以下の表は、OLE オートメーションのデータタイプと Natural データタイプとのマップ関係を示しています。
この表の見方：ActiveX コントロール #OCX-1 が "Size" というプロパティを持っており、このプロパティのデータタイプが VT_R8 であるとします。 この場合、Natural では式 #OCX-1.<<PROPERTY-SIZE>> のデータタイプは F8 になります。
注意:
コンポーネントブラウザでは、対応する Natural データタイプが直接表示されます。
いくつかの特殊なデータタイプは、それぞれ以下のようにみなされます。
カラータイプのプロパティは、Natural では B3 値として表されます。 B3 値は RGB カラー値として解釈されます。 3 バイトのうちの各バイトが、それぞれ赤、緑、および青の要素を示します。 例えば、H'FF0000' は赤に、H'00FF00' は緑に、そして H'0000FF' は青に相当します。
例：
... 01 #COLOR-RED (B3) ... #COLOR-RED := H'FF0000' #OCX-1.<<PROPERTY-BackColor>> := #COLOR-RED ...
画像タイプのプロパティは、Natural では HANDLE OF OBJECT として表されます。 代わりに、画像タイプのプロパティに文字値を割り当てることもできます。 この場合、文字値はビットマップファイル（拡張子が .bmp）のファイル名を含む必要があります。
例：画像タイプのプロパティの使用方法
... 01 #MYPICTURE HANDLE OF OBJECT ... * Assign a Bitmap file name to a Picture property. #OCX-1.<<PROPERTY-Picture>>:= '11100102.bmp' * * Get it back as an object handle. #MYPICTURE := #OCX-1.<<PROPERTY-Picture>> * * Assign the object handle to a Picture property of another control. #OCX-2.<<PROPERTY-Picture>>:= #MYPICTURE ...
フォントタイプのプロパティは、Natural では HANDLE OF OBJECT として表されます。 代わりに、フォントタイプのプロパティに HANDLE OF FONT を割り当てることもできます。 また、文字値を割り当てることもできます。 この場合、文字値は、HANDLE OF FONT の STRING 属性によって返される形式のフォント指定を含む必要があります。
例1：HANDLE OF OBJECT の使用方法
... 01 #MYFONT HANDLE OF OBJECT ... * Create a Font object. CREATE OBJECT #MYFONT OF CLASS 'StdFont' #MYFONT.Name := 'Wingdings' #MYFONT.Size := 20 #MYFONT.Bold := TRUE * * Assign the Font object as value to a Font property. #OCX-1.<<PROPERTY-TitleFont>> := #MYFONT ...
例2：HANDLE OF FONT の使用方法
...
01 #FONT-TAHOMA-BOLD-2 HANDLE OF FONT
...
* Create a Font handle.
PROCESS GUI ACTION ADD WITH PARAMETERS
HANDLE-VARIABLE = #FONT-TAHOMA-BOLD-2
TYPE = FONT
PARENT = #DLG$WINDOW
STRING = '/Tahoma/Bold/0 x -27/ANSI VARIABLE SWISS DRAFT/W/2/3/'
END-PARAMETERS GIVING *ERROR
...
* Assign the Font handle as value to a Font property.
#OCX-1.<<PROPERTY-TitleFont>> := #FONT-TAHOMA-BOLD-2
...
例3：フォント指定文字列の使用方法
...
01 #FONT-TAHOMA-BOLD-2 HANDLE OF FONT
...
* Create a Font handle.
PROCESS GUI ACTION ADD WITH PARAMETERS
HANDLE-VARIABLE = #FONT-TAHOMA-BOLD-2
TYPE = FONT
PARENT = #DLG$WINDOW
STRING = '/Tahoma/Bold/0 x -27/ANSI VARIABLE SWISS DRAFT/W/2/3/'
END-PARAMETERS GIVING *ERROR
...
* Assign the font specification as value to a Font property.
#OCX-1.<<PROPERTY-TitleFont>> := #FONT-TAHOMA-BOLD-2.STRING
...
バリアントタイプのプロパティは任意の Natural データタイプと互換性があります。 このことは、"Value" がバリアントタイプのプロパティの場合、式 #OCX-1.<<PROPERTY-Value>> はコンパイラによってタイプチェックされないことを意味します。 そのため、変数 #MYVAL のタイプに関係なく、式 #OCX-1.<<PROPERTY-Value >> := #MYVAL と #MYVAL := #OCX-1.<<PROPERTY-Value >> を使用できます。 ただし、ランタイム時に特定のプロパティ値を受け入れるかどうか、または要求されたフォーマットで値を提供をするかどうかは、ActiveX コントロールによって判断されます。 認めない場合は通常、ActiveX コントロールによって例外が起こされます。
この例外は、Natural プログラムに Natural エラーコードとして返されます。 Natural エラーコードは、ON ERROR ブロックで通常の方法で処理できます。 バリアントタイプの特定のプロパティに実際に認められているデータフォーマットについては、ActiveX コントロールのドキュメントを確認してください。
#OCX-1.<<PROPERTY-Value>>（"Value" はバリアントタイプのプロパティ）のような式は、あらゆるステートメントでソースオペランドとして使用できます。 ただし、割り当てステートメントでだけはターゲットオペランドとして使用できます。
例：バリアントタイプのプロパティの使用方法
"Value" は、ActiveX コントロール #OCX-1 のバリアントタイプのプロパティだとします。
... 01 #STR1 (A100) 01 #STR2 (A100) ... * These statements are allowed, because the Variant property is used * as source operand (its value is read). #STR1 := #OCX-1.<<PROPERTY-Value>> COMPRESS #OCX-1.<<PROPERTY-Value>> 'XYZ' to #STR2 ... * This leads to an error at compiletime, because the Variant * property is used as target operand (its value is modified) in * a statement other than an assignment. COMPRESS #STR1 "XYZ" to #OCX-1.<<PROPERTY-Value>> ... * This statement is allowed, because the Variant property is used * as target operand in an assignment. COMPRESS #STR1 'XYZ' to #STR2 #OCX-1.<<PROPERTY-Value>> := #STR2 ...
最大 3 次元の SAFEARRAY タイプのプロパティは、Natural プログラムでは、同じ次元数、次元ごとのオカレンス数、および対応するフォーマットを持つ配列として表されます （3 次元を超える SAFEARRAY タイプのプロパティは Natural プログラムでは使用できません）。配列タイプのプロパティの次元数およびオカレンス数は、コンパイル時ではなくランタイム時にのみ決められます。 これは、この情報は変数で、コンパイル時には定義されていないためです。 ただし、フォーマットはコンパイル時にチェックされます。
配列タイプのプロパティは、常に全体としてアクセスされます。 したがって、配列タイプのプロパティでは添字表記は不要なため、許可されていません。
例：配列タイプのプロパティの使用方法
"Values" は、ActiveX コントロール #OCX-1 のプロパティで、VT_I4 の SAFEARRAY タイプだとします。
... 01 #VAL-L (L/1:10) 01 #VAL-I (I4/1:10) ... * This statement is allowed, because the format of the property * is data transfer compatible with the format of the receiving array. * However, if it turns out at runtime that the dimension count or * occurrence count per dimension do not match, a runtime error will * occur. VAL-I(*) := #OCX-1.<<PROPERTY-Values>> ... * This statement leads to an error at compiletime, because * the format of the property is not data transfer compatible with * the format of the receiving array. VAL-L(*) := #OCX-1.<<PROPERTY-Values>> ...
ActiveX コントロールのメソッドは PROCESS GUI ステートメントのアクションとして呼び出されます。 ActiveX コントロールの複雑なプロパティ（つまり、パラメータを持つプロパティ）の場合も同様です。 コンポーネントブラウザに ActiveX コントロールのメソッドとプロパティが表示されます。
このセクションでは、次のトピックについて説明します。
ActiveX コントロールのメソッドを実行するには、PROCESS GUI ステートメントを使用します。 対応する PROCESS GUI のアクション名を、メソッド名の前に接頭語 "METHOD-" を付けて山カッコで囲んで指定します。 ActiveX コントロールハンドルおよびメソッドパラメータ（存在する場合）は、PROCESS GUI ステートメントの WITH 節を使用して渡します。 メソッドの戻り値（存在する場合）は、PROCESS GUI ステートメントの USING 節で指定した変数で受け取ります。
つまり、メソッドを実行するには、以下のようにステートメントを入力します。
PROCESS GUI ACTION <<METHOD-methodname>> WITHhandlename [parameter]...
|
[USING method-return-operand]..
|
例：
* Performing a method without parameters: PROCESS GUI ACTION <<METHOD-AboutBox>> WITH #OCX-1 * Performing a method with parameters: PROCESS GUI ACTION <<METHOD-CreateItem>> WITH #OCX-1 #ROW #COL #TEXT * Performing a method with parameters and a return value: PROCESS GUI ACTION <<METHOD-RemoveItem>> WITH #OCX-1 #ROW #COL USING #RETURN
コンポーネントブラウザに表示されるように、コンパイル時にメソッドのパラメータおよび戻り値のフォーマットと長さがメソッドの定義と比較チェックされます。
パラメータを持つプロパティの値を取得するには、対応する PROCESS GUI のアクション名を、プロパティ名の前に接頭語 "GET-PROPERTY-" を付けて山カッコで囲んで指定します。 ActiveX コントロールハンドルおよびプロパティパラメータ（存在する場合）が、PROCESS GUI ステートメントの WITH 節で渡されます。 プロパティの値は、PROCESS GUI ステートメントの USING 節で受け取ります。
つまり、パラメータを持つプロパティの値を取得するには、以下のようにステートメントを入力します。
PROCESS GUI ACTION <<GET-PROPERTY-propertyname>> WITHhandlename [parameter]
|
... USING get-property-operand |
例：
PROCESS GUI ACTION <<GET-PROPERTY-ItemHeight>> WITH #OCX-1 #ROW #COL USING #ITEMHEIGHT
プロパティパラメータのフォーマットおよび長さとプロパティ値が、コンパイル時にメソッドの定義（コンポーネントブラウザに表示されます）と照合されます。
パラメータを持つプロパティの値を設定するには、対応する PROCESS GUI のアクション名を、プロパティ名の前に接頭語 "PUT-PROPERTY-" を付けて山カッコで囲んで指定します。 ActiveX コントロールハンドルおよびプロパティパラメータ（存在する場合）が、PROCESS GUI ステートメントの WITH 節で渡されます。 プロパティの値は、PROCESS GUI ステートメントの USING 節で渡します。
つまり、パラメータを持つプロパティの値を設定するには、以下のようにステートメントを入力します。
PROCESS GUI ACTION <<PUT-PROPERTY-propertyname>> WITHhandlename [parameter]
|
... USING put-property-operand |
例：
PROCESS GUI ACTION <<PUT-PROPERTY-ItemHeight>> WITH #OCX-1 #ROW #COL USING #ITEMHEIGHT
プロパティパラメータのフォーマットおよび長さとプロパティ値が、コンパイル時にメソッドの定義（コンポーネントブラウザに表示されます）と照合されます。
ActiveX コントロールのメソッドは、オプションパラメータを持つことができます。 これは、パラメータを持つプロパティにも該当します。 メソッドが呼び出される場合は、オプションのパラメータを指定する必要はありません。 1 つのオプションパラメータを省略するには、PROCESS GUI ステートメントにプレースホルダ 1X を使用します。 n オプションパラメータを省略するには、プレースホルダ nX を使用します。
以下の例は、ActiveX コントロール #OCX-1 のメソッド SetAddress のパラメータ FirstName、MiddleInitial、LastName、Street、および City のうち、MiddleInitial、Street、および City がオプションである場合を示しています。 以下に、正しいステートメントを示します。
* Specifying all parameters. PROCESS GUI ACTION <<METHOD-SetAddress>> WITH #OCX-1 FirstName MiddleInitial LastName Street City * Omitting one optional parameter. PROCESS GUI ACTION <<METHOD-SetAddress>> WITH #OCX-1 FirstName 1X LastName Street City * Omitting the optional parameters at end explicitly. PROCESS GUI ACTION <<METHOD-SetAddress>> WITH #OCX-1 FirstName MiddleInitial LastName 2X * Omitting the optional parameters at end implicitly. PROCESS GUI ACTION <<METHOD-SetAddress>> WITH #OCX-1 FirstName MiddleInitial LastName
オプションでない（必須）パラメータを省略すると構文エラーになります。
従来どおりに PROCESS GUI ステートメントの GIVING 節を使用してエラー条件を処理できます。 ユーザー変数にエラーコードを獲得して処理するか、または通常の Natural エラー処理を起動して ON ERROR ブロックで処理できます。
例：
DEFINE DATA LOCAL 1 #RESULT-CODE (N7) ... END-DEFINE ... * Catching the error code in a user variable: PROCESS GUI ACTION <<METHOD-RemoveItem>> WITH #OCX-1 #ROW #COL USING #RETURN GIVING #RESULT-CODE * * Triggering the Natural error handling: PROCESS GUI ACTION <<METHOD-RemoveItem>> WITH #OCX-1 #ROW #COL USING #RETURN GIVING *ERROR-NR ...
ActiveX コントロールのメソッドの実行中に発生する特定のエラー条件は以下のとおりです。
メソッドパラメータ、メソッドの戻り値またはプロパティ値を、ActiveX コントロールが期待するデータフォーマットに変換できなかった場合 （通常、このフォーマットチェックはコンパイル時にすでに行われているので、 ランタイム時には発生しません。 ただし、バリアントとして定義されたメソッドパラメータ、メソッドの戻り値またはプロパティ値は、コンパイル時にチェックされません。 配列および複数の Natural データタイプにマップ可能なデータタイプも同様です）。
メソッドの検索および実行中に COM またはオートメーションエラーが発生した場合。
ActiveX コントロールがメソッドの実行中に例外を発生させた場合。
このような場合、エラーメッセージには ActiveX コントロールによって提供される追加情報が設定されます。この情報を ActiveX コントロールのドキュメントで調べることによって、エラーの原因を把握できます。
ActiveX コントロールによって送られるイベントは、パラメータを持つことができます。 コントロールのイベントハンドラセクションで、これらのパラメータをクエリできます。 参照によって渡されるパラメータも変更できます。 コンポーネントブラウザに、ActiveX コントロールのイベント、パラメータの名前とデータタイプ、およびパラメータが値と参照のどちらで渡されるかの区分のすべてが表示されます。
ActiveX コントロールのイベントパラメータは組み込みコントロールの属性と同様に指定します。 属性名を指定するには、パラメータ名の前に接頭語 "PARAMETER-" を付けて山カッコで囲みます。 代わりに、位置で指定することもできます。 この場合、属性名を指定するには、パラメータの番号の前に接頭語 "PARAMETER-" を付けて山カッコで囲みます。 イベントの最初のパラメータの番号が 1、2 番目が 2、のように続きます。 これらの属性名は、特定イベントのイベントハンドラ内だけで有効です。
以下の例は、ActiveX コントロール #OCX-1 の特定のイベントがパラメータ KeyCode および Cancel を持つことを想定したものです。 この場合、イベントハンドラは以下のステートメントを含むことができます。
* Querying a parameter by name: #PRESSEDKEY := #OCX-1.<<PARAMETER-KeyCode>> * Querying a parameter by position: #PRESSEDKEY := #OCX-1.<<PARAMETER-1>>
参照によって渡されるパラメータはイベントハンドラで変更できます。 以下の例は、Cancel パラメータが参照によって渡され、変更可能であると想定したものです。 イベントハンドラは以下のステートメントを含むことができます。
* Modifying a parameter by name: #OCX-1.<<PARAMETER-Cancel>>:= TRUE * Modifying a parameter by position: #OCX-1.<<PARAMETER-2>>:= TRUE
ActiveX コントロールのイベントをランタイム時に抑制または抑制解除するには、コントロールの対応する抑制イベント属性を変更します。 抑制イベント属性名を指定するには、イベント名の前に接頭語 "SUPPRESS-EVENT-" を付けて山カッコで囲みます。 コンポーネントブラウザに ActiveX コントロールのイベントが表示されます。
以下の例は、ActiveX コントロール #OCX-1 がイベント ColMoved を持っていると想定したものです。
* Suppress the event. #OCX-1.<<SUPPRESS-EVENT-ColMoved>> := SUPPRESSED * Unsuppress the event. #OCX-1.<<SUPPRESS-EVENT-ColMoved>> := NOT-SUPPRESSED