DelphiScript Support in Altium Designer

このセクションでは、Altium Designer スクリプティングエンジンで使用されるDelphiScript言語について説明し、サポートされているステートメント、関数、および拡張機能の参照詳細を提供します。これらは、Altium Designerと直接制御および通信するために使用される特別な手順です。

この参照にも含まれています：

• DelphiScriptとDelphiの違い
• DelphiScriptキーワード
• DelphiScriptステートメントとオペレーター
• DelphiScript関数
• DelphiScriptフォームとコンポーネント

DelphiScript言語

このDelphiScript参照は、基本的なプログラミング概念およびAltium Designerの基本操作に精通していることを前提としています。スクリプティングシステムは、Embarcadero Delphi™に非常に似たDelphiScript言語をサポートしています。

主な違いは、DelphiScriptが型のない、または未定型のスクリプティング言語であることであり、レコードやクラスを定義したり、関数にポインタをパラメータとして渡すことができないことを意味します。変数はスクリプト内で宣言することができます。

このページとその付随するサブページには、DelphiScriptスクリプティング言語を構成するインターフェース、コンポーネント、グローバルルーチン、タイプ、および変数に関する参照資料が含まれています。

Delphiscriptの主要要素

オブジェクト

DelphiScriptでは、オブジェクトはメソッドを含み、多くの場合、プロパティとイベントも含みます。プロパティはオブジェクトに含まれるデータを表し、メソッドはオブジェクトが実行できるアクションです。イベントはオブジェクトが反応できる条件です。すべてのオブジェクトは、TObjectタイプのトップレベルオブジェクトから派生（および継承）します。

オブジェクトインターフェース

オブジェクトインターフェースは、メソッドを含み、多くの場合プロパティも含みますが、データフィールドを持つことはできません。インターフェースは既存のオブジェクトを表し、各インターフェースにはそれを一意にするGUIDがあります。プロパティは、インターフェースが関連付けられているオブジェクトに含まれるデータを表します。メソッドは、インターフェースが関連付けられているオブジェクト（インターフェースが関連付けられているオブジェクト）が実行できるアクションです。

コンポーネント

コンポーネントは、Tool Paletteパネルからの視覚的オブジェクトであり、設計時に操作することができます。すべてのコンポーネントは、Embarcadero Delphi Visual Component Library (VCL)のTComponentシステムクラスから派生します。

ルーチン

グローバルルーチンは、スクリプティングシステムからの手続きと関数です。これらのルーチンはクラスの一部ではありませんが、スクリプト内のクラスメソッドから直接または間接的に呼び出すことができます。

タイプ

変数タイプは、インターフェースメソッドおよびプロパティ、オブジェクトメソッド、プロパティおよびイベント、およびグローバルルーチンの戻り値およびパラメータタイプとして使用されます。多くの場合、タイプはAPIドキュメントの列挙型セクションで文書化されています。

Altium DesignerとDelphi RTL

スクリプティングシステムは、Embarcadero Delphi Run Time Library (RTL)とAltium Designer APIのサブセットをサポートしています。

DelphiScriptソースファイル

Altium Designerでは、スクリプトプロジェクトがスクリプトドキュメント（スクリプトユニットおよびスクリプトフォーム）を格納するように組織されています。スクリプトは、Altium Designerのメインメニューから利用可能なSelect Item To Runダイアログから、メニューアイテム、ツールバーボタン、またはから実行することができます。

PRJSCR、PAS、およびDFMファイル

スクリプトは、*.PRJSCR拡張子を持つプロジェクトに組織されています。各プロジェクトは、*.pas拡張子を持つファイルで構成されています。ファイルは、スクリプトユニットまたはスクリプトフォームのいずれかであり、各フォームには*.pas拡張子を持つスクリプトファイルと、対応するフォームファイルが*.dfm拡張子を持っています。スクリプトフォームは、Altium Designerの上に実行されるグラフィカルウィンドウ（ダイアログ）であり、異なるユーザーがアクセス可能なコントロールをホストします。

異なるプロジェクトにスクリプトを添付することが可能であり、スクリプトの数とその手続き/関数を管理するために、異なるプロジェクトにスクリプトを組織することを強く推奨します。

スクリプトの例

スクリプト例のコレクションは、Altium Designerでの使用に向けたシンプルなスクリプトを使用して、DelphiScriptプログラミングの基本機能を示しています。

例のスクリプトの選択とその目的の場所は以下の通りです：

• Scripts\DelphiScript Scripts\DXPフォルダ - クライアントおよびシステムAPIを示しています
• Scripts\DelphiScript Scripts\PCBフォルダ - PCB APIを示しています
• Scripts\DelphiScript Scripts\Processesフォルダ - サーバープロセスを示しています
• Scripts\DelphiScript Scripts\Generalフォルダ - DelphiScriptキーワードを示しています
• Scripts\DelphiScript Scripts\Schフォルダ - スケマティックAPIを示しています
• Scripts\DelphiScript Scripts\WSMフォルダ - ワークスペースマネージャAPIを示しています

DelphiScriptスクリプトの作成

DelphiScript命名規則

一般的に、手続き、関数、変数、および定数に与えられる名前に制限はありませんが、次のルールに従う限りです：

• 名前には、AからZ、aからz、アンダースコア文字"_"、および数字0から9を含めることができます。
• 名前は文字で始まる必要があります。
• 名前はDelphiScriptキーワード、ディレクティブ、または予約語であってはなりません。
• 名前は解釈されるときに大文字と小文字を区別しません。関数、サブルーチン、変数、または定数の命名には上記および小文字を使用できますが、インタープリタは大文字と小文字の文字を区別しません。大文字と小文字が異なるだけの名前は、DelphiScriptでは同じ名前として扱われます。

DelphiScriptファイルでは、関数と手続きはProcedure-Begin-EndまたはFunction-Begin-Endブロックを使用して宣言されます。これらのステートメントブロックには、手続きまたは関数に名前を付ける必要があります。DelphiScriptでは、現在のスクリプトで使用される値を保持するために、名前付き変数および定数を作成することができます。

コメントの含め方

スクリプトでは、プログラマーのために含まれる実行不可能なコード行がコメントです。コメントはスクリプトのほぼどこにでも含めることができます。

//に続くテキストや、(* *)または{}で囲まれたテキストは、DelphiScriptによって無視されます。

//この行全体はコメントです

{この行全体はコメントです}

{
これらの行はコメントです
これらの行はコメントです
}

(* この行全体はコメントです *)
 
(*
これらの行はコメントです
これらの行はコメントです
*)

コメントは、実行されるコードの同じ行にも含めることができます。たとえば、次のコード行のセミコロンの後にあるすべてがコメントとして扱われます。

ShowMessage ('Hello World'); //メッセージを表示

ローカルおよびグローバル変数

スクリプトにはローカル変数とグローバル変数があるため、スクリプトプロジェクト内のスクリプトで一意の変数名を持つことが非常に重要です。変数が手続きや関数の外側で定義されている場合、それらはグローバルであり、同じプロジェクト内の任意のスクリプトユニットからアクセスできます。

変数が手続きや関数の内側で定義されている場合、これらのローカル変数はこれらの手続き/関数の外側からはアクセスできません。

スクリプト内のローカル変数とグローバル変数の例:

// 注意: Usesキーワードは必要ありません。

{ UnitAスクリプトのグローバル変数（下記参照）は、このスクリプトユニットと同じプロジェクト内にUnitAがある限り、このスクリプトユニットから利用可能です。 }

Const
  GlobalVariableFromThisUnit='このユニットからのグローバル変数';

Procedure TestLocal;
var
  Local;
Begin
  Local := 'ローカル変数';
  ShowMessage(Local);
End;

Procedure TestGlobal;
Begin
  //ShowMessage(Local); // この行はエラーを発生させます。なぜなら'Local'変数はグローバルではありません。
  ShowMessage(GlobalVariableFromThisUnit);
  // UnitAの変数はUsesキーワードなしでアクセスできます。
  ShowMessage(GlobalVariableFromUnitA);
End;

UnitAスクリプト:

Const
  GlobalVariableFromUnitA = 'Unit Aからのグローバル変数';

名前付き変数の使用

スクリプトでは、プログラム実行中に使用される値を格納するために、名前付き変数や定数が作成されます。スクリプト内のすべての変数は常にVariant型です。型キャストは適用されないため、変数宣言の型は無視され、省略することができます。したがって、これらの宣言は正しいです：

Var a : integer;
Var b : integer;
Var c, d;

行の分割

各コード文はセミコロン;文字で終了し、文の終わりを示します。DelphiScriptでは、長い命令を2行以上のコード行に分割して記述することができます。異なる行にプログラミング文を分割する唯一の制限は、文字列リテラルが複数の行にまたがってはならないということです。

例えば：

X.AddPoint( 25, 100);
X.AddPoint( 0, 75);
// は以下と同等です：
X.AddPoint( 25, 100); X.AddPoint( 0, 75);

しかし...

'Hello World!'
\\は以下と同等ではありません
'Hello
World!'

DelphiScriptはスクリプト内の単一行のコードの長さに実際的な制限を設けていませんが、読みやすさとデバッグの容易さのために、画面上または印刷形式で簡単に読めるようにコード行の長さを制限することが良い習慣です。

コード行が非常に長い場合は、この行を複数の行に分割することができ、このコードはDelphiScriptインタープリタによって単一行に書かれたかのように扱われます。

整形式でないコード例:

If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,'Choose first corner','Choose final corner',x1,y1,x2,y2)) Then Exit; 

整形式のコード例:

If Not (PcbApi_ChooseRectangleByCorners(BoardHandle,
'Choose first corner',
'Choose final corner',
x1,y1,x2,y2)) Then Exit;

大文字と小文字の区別

スクリプトの記述に使用されるDelphiScript言語は大文字と小文字を区別しません。つまり、キーワード、文、変数名、関数名、手続き名は、大文字または小文字を使用しても構いません。大文字と小文字の文字は同等とみなされます。

例えば、変数名myVarはmyvarおよびMYVARと同等です。DelphiScriptはこれらの名前を同じ変数として扱います。

この例外は、ダイアログ定義のタイトル文字列や文字列変数の値などのリテラル文字列にあります。これらの文字列は大文字と小文字の違いを保持します。

スペース文字

スクリプト文内のキーワードを区切るためにスペースが使用されます。しかし、DelphiScriptは文内の追加の空白を無視します。

例えば：

X   = 5
// は以下と同等です
X =5

スクリプトをより読みやすくするために空白を使用することができます。

スクリプト内の関数と手続き

DelphiScriptインタープリタは、手続き（プロシージャ）と関数の2種類のメソッドを許可します。関数と手続きの唯一の違いは、関数が値を返すことです。

スクリプトには、メインプログラムコードを定義する手続きが少なくとも1つ含まれている必要があります。ただし、コードから呼び出すことができる他の手続きや関数を定義することもできます。

Embarcadero Delphiと同様に、手続きと関数はBegin-End文ブロック内で定義されます。関数または手続きを呼び出すには、組み込みのDelphiScript関数や手続きを使用するときと同じ方法で、関数または手続きの名前を文に含めます。関数または手続きがパラメータを必要とする場合は、これらを呼び出し文に含める必要があります。関数と手続きの両方がパラメータを受け入れるように定義することができますが、関数のみが呼び出し文に値を返すように定義することができます。

関数と手続きには、それが標準のDelphiScript命名規則に従っている限り、任意の名前を割り当てることができます。

典型的なDelphiScript手続き:

Procedure CreateSchObjects;
Begin
  If SchServer = Nil Then Exit;
  SchDoc := SchServer.GetCurrentSchDocument;
 
  If SchDoc = Nil Then Exit;
  PlaceSchematicObjects;
  SchDoc.GraphicallyInvalidate;
End;

典型的なDelphiScript関数:

Function BooleanToString(AValue : Boolean) : String;
Begin
  If (AValue) Then Result := 'True'
  Else   Result := 'False';
End;

関数の名前はその戻り値を設定するために使用することはできません。Resultキーワードを使用する必要があります。

Var, Begin-Endグローバルブロック:

Var
  A, B, C;
Begin
  B := 10;
  C := 20;
  A := B + C;
  ShowMessage(IntToStr(A));
End;

スクリプトのヒント

スクリプトプロジェクト内のスクリプトの参照

あるスクリプトのコードは、同じスクリプトプロジェクト内の別のスクリプトの手続きを呼び出すことができます。任意のスクリプト内の任意のグローバル変数は、同じプロジェクト内でアクセスできます。

ローカル変数とグローバル変数

スクリプトにローカル変数とグローバル変数があるため、スクリプトプロジェクト内のスクリプトで一意の変数名を持つことが重要です。変数が手続きや関数の外側で定義されている場合、それらはグローバルであり、同じプロジェクト内の任意のユニットからアクセスできます。変数が手続きや関数の内側で定義されている場合、これらのローカル変数はこれらの手続き/関数の外側からはアクセスできません。

プロジェクト内のスクリプトの数を管理しやすいサイズに保ち、類似性のある性質のスクリプトをプロジェクトに配置することをお勧めします。多くのスクリプトでグローバル変数を追跡することは問題になる可能性があります。スクリプトをスクリプトプロジェクトに格納することは必須ではありません。スクリプトは他のプロジェクトタイプに配置することもできます。

一意の識別子と変数

スクリプトフォームを使用する場合、すべてのスクリプトフォームに一意のフォーム名があることを確認してください。例えば、同じスクリプトプロジェクト内で全てのスクリプトフォームをform1と命名することは可能です。この場合、スクリプトフォームが実行されたときに正しいフォームを表示しようとすると、スクリプティングシステムが競合してしまいます。

スクリプトフォーム名はオブジェクトインスペクタを使用して変更できます。名前はスクリプトユニットとスクリプトフォームファイルの両方で自動的に変更されます。

パラメータレスの手続きと関数

スクリプトを実行するために呼び出す必要がある手続きは、Select Items to Run ダイアログにのみ表示されるようにスクリプトを記述するべきです。他の手続き/関数がSelect Items to Runダイアログに表示されないようにするためには、メソッド名の隣に(Dummy : Integer)パラメータを挿入できます。下記の例を参照してください。

// この関数はSelect Items to Runダイアログに表示されないようにされています。
Function TSineWaveform.CreateShape(Dummy : Integer);
Begin
    //何かをする
End;
{..................................................}
 
{..................................................}
Procedure TSineWaveform.bCloseClick(Sender: TObject);
var
  I : integer;
Begin
     //何かをする
Close;
End;
{..................................................}
 
{..................................................}
procedure DrawSine;
Begin
    SineWaveform.showmodal;
End;

DelphiScript エラーコード