スクリプト作成

Created: 3月 29, 2023 | Updated: 5月 27, 2024 | Applies to versions: 23, 24 and 25

スクリプトの記述

スクリプトを記述する際には、いくつかの重要な概念と用語があります：

プロセスは、スクリプト内でコマンドを実行するために使用できるコマンド文字列です。
コンポーネントは、Tool Palette パネル上の視覚的な制御オブジェクトで、スクリプトフォームにドラッグアンドドロップしてデザインを操作できます。
スクリプトフォームに配置されたコンポーネントには、メソッド、プロパティ、イベントがあります。
オブジェクトインターフェースは、スクリプトから設計文書のデータを抽出および変更するために使用できる特別なオブジェクトインターフェースです。

スクリプト言語

デフォルトのスクリプト言語はDelphiScript（*.pas）に設定されています。スクリプトエンジン自体はEmbarcadero Delphiで書かれており、ツールパレットパネルはDelphiのVCL（Visual Component Library）に基づいています。

VBScriptやJavaScript（Jscript）で書かれた既存のスクリプトを開いて実行することができます。VBScriptで新しいスクリプトを作成できるようにするには、詳細設定ダイアログでLegacy.Scripts.SupportOldLanguagesオプションを有効にする必要があります。
スクリプティングAPIのドキュメントはこちらで見ることができます：スクリプティングAPIオブジェクト。このドキュメントはAltium Designerの古いバージョン用に最後に更新されたことに注意してください。多くの原則とアプローチは同じままですが、インターフェース、オブジェクト、メソッド、プロパティなどがそれ以降変更されており、ソフトウェアの後のバージョンに完全には反映されていないことを認識してください。

DelphiScriptユニット

基本的なスクリプト演習は、まず新しいプロジェクトとスクリプトファイルを作成することから始めることができます。プロジェクトとスクリプトファイルがDelphiScript言語に設定されていると仮定すると、以下のようにシンプルな「Hello World」スクリプトを入力できます。

Procedure ShowAMessage;
Var
 DefaultMessage;
Begin
 DefaultMessage := 'Hello World!';
 ShowMessage(DefaultMessage);
End;

ドキュメントが編集されると、スクリプトドキュメントの隣にアスタリスクが表示され、Projectsパネルのアイコンが赤く変わります。スクリプトコードの行が編集されると、その行の左マージンに赤いブロックが表示され、行が変更されたことを示します。

手順の中には、DefaultMessage変数で定義された"Hello World"メッセージをダイアログで開く標準のDelphiScript ShowMessage関数があります。

スクリプト内のすべての変数がバリアント型であるため、スクリプト内でDefaultMessage変数の型を定義する必要はありません。

スクリプトの実行

スクリプトを実行するには、メインメニューからFile » Run Scriptを選択し、実行する項目を選択ダイアログから利用可能なスクリプト手順を選択します。バージョンが実行されると、メッセージを表示するダイアログが開きます。

File » Run ScriptメニューからシンプルなHelloWorldスクリプトユニットを実行しています。

このスクリプトにはパラメーターのない手続きがあります。パラメーターを持たない手続きや関数のみがSelect Item To Runダイアログに表示されます。パラメーターを必要とする手続きは、スクリプト内（または別のスクリプトから）から呼び出されますが、パラメーターが渡されない実行する項目を選択ダイアログのような外部システムからは呼び出されません。

スクリプトは、エディターの実行コマンドを使用して実行することもできます。これには、Runボタン（）、F9 ショートカットキー、またはメインメニューからRun » Runを選択することでアクセスできます。

実行コマンド自体とともに、ドロップダウンRUNメニューは、スクリプト制御とデバッグコマンドの範囲を提供します。

Runコマンドが初めて選択されると、実行するアイテムを選択ダイアログが開き、スクリプトのメインプロシージャ（この場合はShowAMessage）を指定できます。一度設定すると、エディターからRunコマンドを使用して繰り返しスクリプトを簡単に実行できます。Run » Set Project Startup Procedureを使用して設定を異なるプロシージャに変更するか、スクリプトプロジェクトを閉じて再度開くことで設定をクリアできます。

実行中のスクリプトを停止するには、停止ボタン（）、メインメニューからRun » Stopを選択するか、Ctrl+F3のショートカットを使用します。

DelphiScriptフォーム

上で作成したHelloWorldプロジェクトを拡張して、フォームユニットを使用した類似のスクリプトを作成できます。スクリプトフォームは、ボタン、メモ、リストボックスなどのさまざまなコントロールをホストできるダイアログウィンドウです。コントロールがイベントを生成したとき、たとえばボタンがクリックされたときに反応するイベントハンドラーを持っています。新しいスクリプトフォームを作成するには、Projectsパネルからプロジェクト名を右クリックし、Add New to Projectオプションを選択し、Script Formを選択します。スクリプトは、メインメニューからFile » Save Asを使用して保存および名前変更できます。

新しいスクリプトプロジェクトを設立したら、プロジェクトに新しいスクリプトを追加します。

スクリプトフォームは2つのファイルを作成します：*.dfm ファイルはフォームウィンドウの要素とハンドルを定義し、*.pas ファイルはフォームのイベントハンドラや手続き、または関数をホストします。

現在フォーカスされているフォームやそのコンポーネントのプロパティ値を見たり編集したりするには、Object Inspectorパネルを開きます。Object Inspectorパネルは、フォームのプロパティを変更し、現在のフォームに関連付けられたイベントハンドラーにコードを挿入するために使用されます。

オブジェクトインスペクターパネルで示されるスクリプトフォームのウィンドウ構成とプロパティ。
オブジェクトインスペクターパネルで示されるスクリプトフォームのウィンドウ構成とプロパティ。

スクリプトフォームには、文書の下部にCode タブとFormタブの2つのタブがあります。

Code タブには、上記のようなイベントハンドラや手続きが含まれています。一方、Formタブはダイアログを表し、コントロールと関連するイベントハンドラがあります。タブを使用するか、F12ショートカットキーを使用して2つのタブ間を切り替えます。

このガイドでは、「ダイアログ」と「スクリプトフォーム」は説明的に等価です。「フォーム」という用語は、スクリプティングシステムでリアルタイムに設計されているウィンドウを指し、ダイアログはソフトウェア内のアクティブなフォームで、ユーザーからのフィードバックを待っており、ダイアログボタンやコントロールがクリックされたときにアクションを起こします。

Object Inspectorパネルを使用すると、アクティブスクリプトフォーム内のコンポーネントのプロパティとイベントを調査し、編集することができます。デザインエディターウィンドウのアクティブスクリプトフォーム上で単一のコンポーネントをクリックすると、そのコンポーネントが選択され、Object Inspectorパネルに関連付けられた属性が表示されます。または、パネルの上部にあるドロップダウンフィールドを使用して、現在アクティブフォーム上に配置されているすべてのコンポーネントのリストから選択することもできます。フォーム自体も含まれています。

フォームダイアログとそのアクションを設定するために、オブジェクトインスペクターパネルを使用します。

情報はProperties とEventsの2つのタブに表示されます：

パネルのProperties タブには、選択されたコンポーネントのすべてのプロパティ属性がリストされています。利用可能な属性の正確なリストは、現在調査中の特定のタイプのコンポーネントによって異なります。プロパティとは、その可視性の振る舞いまたは操作に影響を与えるオブジェクトの特性です。例えば、Behaviorサブカテゴリー内のVisibleプロパティは、オブジェクトが配置されているスクリプトフォーム上に表示されるかどうかを決定します。コンポーネントのプロパティは必要に応じて変更できます。プロパティの右側にあるフィールド内をクリックし、直接入力するか、チェックボックスを切り替えるか、または適切な場合はドロップダウンからエントリを選択します。
パネルの Eventsタブは、現在選択されているコンポーネントが反応できるすべてのイベントのリストを提供します。ここでも、利用可能なイベントの正確なリストは、現在調査中の特定のタイプのコンポーネントによって異なります。フォーム上のボタンがクリックされるなどのイベントが発生すると、コード内でイベントの処理手順が定義されている場合、スクリプトは適切なアクションを取ります。このタイプの手順はイベントハンドラと呼ばれます。

イベントハンドラの基本骨格は、オブジェクトインスペクターパネル内からスクリプトドキュメントのコードに追加することができます。イベントを定義したいコンポーネントを選択し、特定のタイプのイベントを選び、その後イベントの右側のフィールド内をダブルクリックします。イベントの名前が作成され、イベント処理手続きの名前の定義に使用されます - FormName.EventName。その後、イベント処理手続きの基本骨格コードがメインスクリプトコードに追加され、デザインスペースのアクティブなタブになります。イベントが発生し、実行中のスクリプトによって検出されたときに望ましい反応を提供するために、イベント処理手続きの「充填」をコーディングすることができます。

パネルの下部には、利用可能な場合、現在選択されているプロパティまたはイベントの要約説明が表示されます。

複数のコンポーネントを選択して同時に編集することができます。選択されたすべてのコンポーネントに共通するプロパティ/イベントはパネルに表示されます。コンポーネント間で異なる値を持つプロパティ/イベントは空白として表示されます。必要に応じてプロパティやイベントを編集するだけで、変更は選択した各コンポーネントに即座に反映されます。たとえば、複数のボタンに使用されるテキストを特定のフォントに変更したい場合があります。すべてのボタンを選択し、必要に応じてフォントカテゴリの下にリストされているプロパティを変更します。すべてのボタンが同じフォントを使用してテキストを表示するように更新されます。

このフォームスクリプトでは、オブジェクトインスペクターパネルのフォームのCaptionプロパティをHelloWorldFormからHello World!に変更します。これらの文字列は、以下に示される例のイベントハンドラーと手続きコードで使用されているものと一致します。

コンポーネントとそのプロパティ、メソッド、イベントに関する詳細情報については、コンポーネントカテゴリページを参照してください。

コントロールの追加と設定

基本的なフォームが設定されたら、ツールパレットパネルにアクセスして、必要に応じてダイアログにコントロールを追加できます。ツールパレットは、Delphiのビジュアルコンポーネントライブラリに基づいており、ウィンドウコントロールの広範な範囲を提供するコンポーネントパレットで、コンポーネントカテゴリとして整理されています（詳細については、スクリプティンググラフィカルコンポーネントおよびコンポーネントカテゴリページを参照してください）。

ツールパレットのパネルセクションは、リージョン見出しのタブを使用して展開および折りたたむことができます。

パネルの上部にあるコントロール、カテゴリ名、右クリックメニューを使用して、パネル内のコントロールの表示を設定します：カテゴリの展開/折りたたみ、パレットアイテムの表示変更など。

パネルで使用されるすべてのコンポーネントは、Borland Delphi Visual Component LibraryのTComponentから派生しています。

「Hello World」プロジェクトのダイアログバージョンでは、フォームにDisplayとCloseの2つのボタンがあります。Standard領域のTool PaletteパネルでTButtonをクリックします。

これを2回行って、フォームに2つのボタンを配置します。1つのボタンは別のダイアログで「Hello World!」メッセージを表示するために使用され、もう1つのボタンはメインダイアログを閉じるために使用されます。

コンポーネントは、ツールパレットパネルでコンポーネントをダブルクリックするか、コンポーネントを一度クリックしてから、コンポーネントを表示したいフォーム上でクリックすることで配置できます。

パネル内のすべてのコンポーネントには、関連する Properties、Methods、およびEventsがあります。

Propertyは、オブジェクトの目に見える動作または操作に影響を与えるオブジェクトの特性です。たとえば、Visible プロパティは、スクリプトフォームでオブジェクトを表示できるかどうかを決定します。
Methodは、常にオブジェクトに関連付けられている手続きであり、そのオブジェクトの振る舞いを定義します。
Eventは、スクリプトによって検出されるアクションまたは発生です。スクリプトでは、プログラマーはマウスクリックなどの特定のイベントをキャプチャするように設計された各イベントハンドラーのためのコードを書きます。

コンポーネントのpropertiesとeventsは、配置後にObject Inspectorパネルを使用して調査および変更することができます。

Object Inspectorパネルを使用すると、2つのボタンの設定をデフォルトの名前やキャプションから変更することができます。

最初のボタンの名前をbDisplayに、キャプションをDisplayに設定してください。2番目のボタンの名前をbCloseに、キャプションをCloseに設定してください。これは、以下に示される例のイベントハンドラーコードに合わせるためです。
コンポーネントを選択し、Object Inspectorパネルでそのプロパティを編集します。

Object Inspectorパネルの下部にあるコメントボックスは、ハイライト表示されたプロパティの説明を提供します。

イベントハンドラのコードは、フォーム上のコントロールを直接参照することで構築できます。この例では、Displayボタンが既存のフォームの上にShowMessageダイアログを起動し、Closeボタンのアクションでこのフォームを閉じます。

イベントハンドラコード

Displayボタンをダブルクリックすると、コードビューでフォームが開き、そのイベントハンドラのスケルトンコードが作成されます。または、ボタンを選択してから、Object InspectorパネルのEventsタブをダブルクリックします。パネルでOnClickイベントをダブルクリックすると、上記のようにコードビューが開きます。コードビュー内で、以下のリストに示すように、イベントハンドラにShowMessage文を含めることができます。

Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
　ShowMessage('Hello World!');
End;
 

スクリプトフォーム上の任意のコンポーネントに対して事前に定義されたイベントハンドラを表示するには、コンポーネントを選択し、次にオブジェクトインスペクターパネルのイベントタブをクリックします。同様に、閉じるボタンのイベントハンドラは、Close（フォーム）ステートメントを適用するOnClickイベントを生成することによって定義できます：

Procedure THelloWorldForm.bCloseClick(Sender: TObject);

Begin

Close;

End;

イベントハンドラが定義されたら、ソフトウェアからダイアログを呼び出す際の開始点として使用されるスクリプト内の手順が必要です。これはコードスクリプトの最後に追加されます。

フォーム名がHelloWorldFormで、手続き名がRunHelloWorldであることに注意してください。同じスクリプト内でフォーム名の衝突を避けるためには、ユニークなフォーム名を持つことが重要です。

Procedure RunHelloWorld;

Begin

　HelloWorldForm.ShowModal;

End;

スクリプトは保存され、メインメニュー（File» Run Script）からRunHelloWorld手続き項目を実行することにより、HelloWorldDialogエントリの下で実行できます。

あるいは、Run コマンド/ボタン () に手順を割り当てることができます。これは、Run » Set Startup Project Procedure メニューから設定します。

HelloWorld フォームスクリプトを実行しているところ。フォームの Display ボタンが ShowMessage ダイアログを起動します。

オブジェクトインスペクターパネルを使用すると、フォームユニットのプロパティやイベントを簡単に変更できます。たとえば、ワークスペース内のフォームの位置を変更するには、パネルを使用してフォームの位置プロパティのpoScreenCenter値を変更します。スクリプトを実行すると、ダイアログはデスクトップ画面の中央に配置されます。

Hello Worldプロジェクトスクリプトの参照バージョンは、ダウンロード可能なスクリプトコレクションのScripts\Delphiscript Scripts\Generalフォルダにあります。これらはレガシー参照デザインであり、更新されていないことに注意してください。

プロシージャの呼び出し

上記のように、プロジェクト内の任意のスクリプト（同じ言語セットを使用）は、グローバル変数や手続きにアクセスできるため、あるスクリプトの手続きがプロジェクト内の別のスクリプトの手続きを呼び出すことができます。これは、HelloWorldの例プロジェクトに追加された`ShowAParametricMessage`コードセクションで示されます：

Procedure ShowAParametricMessage(S : String);

Var

DefaultMessage;

Begin;

　DefaultMessage := 'Hello World!';

　If S = '' Then ShowMessage(DefaultMessage)

　　　　　　　　　Else ShowMessage(S);

End;

これにより、`ShowAParametricMessage`手続きに渡すことができる文字列変数`S`が確立されます。

渡された文字列は、ShowMessage ダイアログ関数を使用して表示されますが、単純な If-Then-Else メソッドにより、文字列が空の場合はデフォルトの 'Hello World!' メッセージが表示されます。

これを実際に見るために、サンプルプロジェクト (HelloWorld.PrjScr) を開き、以下に示すように、HelloWorldDialog スクリプト（HelloWorld スクリプトではない）に灰色でハイライトされた行を追加してください。

...

Procedure THelloWorldForm.bDisplayClick(Sender: TObject);

Begin;

　Showmessage('Hello World!');

End;

Procedure THelloWorldForm.bCloseClick(Sender: TObject);

Begin;

ShowAParametricMessage('Goodbye World');

　　　close;

End;

...

HelloWorldDialogスクリプトが実行され、Closeボタンがクリックされると、HelloWorldスクリプトからグローバルShowAParametricMessageプロシージャが呼び出されます。

HelloWorldスクリプト内のパラメトリック手続きがHelloWorldDialogスクリプトから呼び出されます。

この呼び出しでは、「Goodbye World」というメッセージ文字列がShowAParametricMessage手続きに渡され、その結果、フォームを閉じる前にクローズボタンをクリックするとこのメッセージが表示されます。

上記に示されたスクリプト呼び出しは、HelloWoldDialogフォームのクローズ手順に指定されたメッセージを挿入します。

渡された文字列パラメータが空の場合、`ShowAParametricMessage(''),` で定義されている通り、デフォルトの 'Hello World!' メッセージが表示されます。

スクリプトの記述とデバッグのプロセスを効率化するためのショートカットキーのリストについては、Script Editor Toolsページを参照してください。

コードエクスプローラーパネルを使用したスクリプト識別子の閲覧

Code Explorerパネルは、アクティブなスクリプトドキュメントで使用されているすべての識別子（変数、関数、および手続き）の視覚的な要約を提供します。

Code Explorerパネル

パネルに表示される識別子情報は、次のトップレベルフォルダーの下にグループ化されます：

手続き & 関数 – アクティブなスクリプトドキュメントで宣言されたすべての手続きと関数を含みます。各手続き/関数について、その手続き/関数に渡されたパラメーターや、その中でローカルに宣言された変数もリストアップされます。
変数 – アクティブなスクリプトドキュメントで宣言されたすべてのグローバル変数を含みます。