DelphiScript

В этом разделе описывается язык DelphiScript, используемый движком сценариев Altium Designer, и приводятся справочные сведения о поддерживаемых операторах, функциях и расширениях. Это специальные процедуры, которые используются для управления Altium Designer и прямого взаимодействия с ним.

Также в этой справке:

• Отличия DelphiScript от Delphi
• Ключевые слова DelphiScript
• Операторы и операторы (statements) DelphiScript
• Функции DelphiScript
• Формы и компоненты DelphiScript

Язык DelphiScript

Данная справка по DelphiScript предполагает, что вы знакомы с базовыми концепциями программирования, а также с основами работы в Altium Designer. Система сценариев поддерживает язык DelphiScript, который очень похож на Embarcadero Delphi™.

Ключевое отличие заключается в том, что DelphiScript — это бестиповый (untyped) скриптовый язык, то есть вы не можете определять записи (records) или классы и передавать указатели в качестве параметров функций. При этом переменные по-прежнему можно объявлять в скриптах для улучшения читаемости.

Эта страница и связанные с ней подстраницы содержат справочные материалы по интерфейсам, компонентам, глобальным подпрограммам, типам и переменным, из которых состоит скриптовый язык DelphiScript.

Ключевые элементы Delphiscript

Объекты

В DelphiScript объект состоит из методов и, во многих случаях, свойств и событий. Свойства представляют данные, содержащиеся в объекте; методы — действия, которые объект может выполнять; события — условия, на которые объект может реагировать. Все объекты происходят (и наследуются) от объекта верхнего уровня типа TObject.

Интерфейсы объектов

Интерфейс объекта состоит из методов и, во многих случаях, свойств, но не может содержать поля данных. Интерфейс представляет существующий объект, и каждый интерфейс имеет GUID, который делает его уникальным. Свойства представляют данные, содержащиеся в объекте, с которым связан интерфейс. Методы — это действия, которые может выполнять объект (с которым связан интерфейс).

Компоненты

Компоненты — это визуальные объекты из панели Tool Palette, которыми можно управлять на этапе проектирования. Все компоненты наследуются от системного класса TComponent в библиотеке визуальных компонентов Embarcadero Delphi (VCL).

Подпрограммы

Глобальные подпрограммы — это процедуры и функции из системы сценариев. Эти подпрограммы не являются частью класса, но их можно вызывать как напрямую, так и из методов классов в скрипте.

Типы

Типы переменных используются как типы возвращаемых значений и типы параметров для методов и свойств интерфейсов, методов объектов, свойств и событий, а также для глобальных подпрограмм. Во многих случаях типы документируются в разделах перечислимых типов (Enumerated Types) в документации API.

Altium Designer и Delphi RTL

Система сценариев поддерживает подмножество библиотеки времени выполнения Embarcadero Delphi Run Time Library (RTL) и API Altium Designer.

Исходные файлы DelphiScript

В Altium Designer проект скриптов организован для хранения документов скриптов (модулей Unit и форм Form). Вы можете запускать скрипт из пункта меню, кнопки панели инструментов или из диалога Select Item To Run dialog, доступного из главного меню Altium Designer.

Файлы PRJSCR, PAS и DFM

Скрипты организуются в проекты с расширением *.PRJSCR. Каждый проект состоит из файлов с расширением *.pas. Файлы могут быть либо модулями скриптов (script Units), либо формами скриптов (script Forms) — обратите внимание, что у каждой формы есть файл скрипта с расширением *.pas и соответствующий файл формы с расширением *.dfm. Форма скрипта — это графическое окно (диалог), которое запускается поверх Altium Designer и содержит различные элементы управления, доступные пользователю.

Скрипты можно подключать к разным проектам, и настоятельно рекомендуется организовывать скрипты в разные проекты, чтобы управлять количеством скриптов и их процедурами/функциями.

Примеры скриптов

Коллекция примеров скриптов иллюстрирует базовые возможности программирования на DelphiScript с использованием простых скриптов для Altium Designer.

Ниже перечислены расположение и назначение некоторых примеров скриптов:

• Scripts\DelphiScript Scripts\DXP папка - демонстрирует Client и system API
• Scripts\DelphiScript Scripts\PCпапка B - демонстрирует PCB API
• Scripts\DelphiScript Scripts\Processes папка - демонстрирует процессы сервера (server Processes)
• Scripts\DelphiScript Scripts\General папка - демонстрирует ключевые слова DelphiScript
• Scripts\DelphiScript Scripts\Sch папка - демонстрирует Schematic API
• Scripts\DelphiScript Scripts\WSM папка - демонстрирует Workspace Manager API

Написание скриптов DelphiScript

Соглашения об именовании DelphiScript

В целом ограничений на имена, присваиваемые процедурам, функциям, переменным и константам, нет — при условии соблюдения следующих правил:

• Имя может содержать буквы A–Z, a–z, символ подчёркивания "_" и цифры 0–9.
• Имя должно начинаться с буквы.
• Имя не может быть ключевым словом DelphiScript, директивой или зарезервированным словом.
• При интерпретации имена не чувствительны к регистру. При именовании функции, подпрограммы, переменной или константы можно использовать как верхний, так и нижний регистр, однако интерпретатор не различает символы верхнего и нижнего регистра. Имена, совпадающие во всём, кроме регистра, будут рассматриваться в DelphiScript как одно и то же имя.

В файле DelphiScript функции и процедуры объявляются с помощью блоков Procedure-Begin-End или Function-Begin-End. Оба этих блока операторов требуют указать имя процедуры или функции. DelphiScript позволяет создавать именованные переменные и константы для хранения значений, используемых в текущем скрипте.

Добавление комментариев

В скрипте комментарии — это неисполняемые строки кода, добавляемые для удобства программиста. Комментарии можно размещать практически в любом месте скрипта.

Любой текст после // или заключённый в (* *) или {} игнорируется DelphiScript.

//This whole line is a comment

{This whole line is a comment}

{
These lines are comments
These lines are comments
}

(* This whole line is a comment *)
 
(*
These lines are comments
These lines are comments
*)

Комментарии также можно размещать в той же строке, что и исполняемый код. Например, всё после точки с запятой в следующей строке кода рассматривается как комментарий.

ShowMessage ('Hello World'); //Display Message

Локальные и глобальные переменные

Поскольку все скрипты имеют локальные и глобальные переменные, очень важно обеспечивать уникальность имён переменных в скриптах внутри одного проекта скриптов. Если переменные определены outside любых процедур и функций, они являются глобальными и доступны из любого модуля скрипта в том же проекте.

Если переменные определены inside процедуры или функции, то эти локальные переменные недоступны вне этих процедур/функций.

Example of Local and Global Variables in a Script:

// Note: The Uses keyword is not needed.

{ The global variable from UnitA script (see below) is available to this Script Unit,
  as long UnitA is in the same project as this Script Unit. }

Const
  GlobalVariableFromThisUnit='Global Variable from this unit';

Procedure TestLocal;
var
  Local;
Begin
  Local := 'Local Variable';
  ShowMessage(Local);
End;

Procedure TestGlobal;
Begin
  //ShowMessage(Local); // This line produces an error because the 'Local' variable is not global.
  ShowMessage(GlobalVariableFromThisUnit);
  // A variable from UnitA can be accessed without the Uses keyword.
  ShowMessage(GlobalVariableFromUnitA);
End;

UnitA script:

Const
  GlobalVariableFromUnitA = 'Global Variable from Unit A';

Использование именованных переменных

В скрипте именованные переменные или константы создаются для хранения значений, которые будут использоваться во время выполнения программы. Все переменные в скрипте всегда имеют тип Variant. Приведение типов не применяется, поэтому типы в объявлениях переменных игнорируются и могут быть опущены. Следовательно, эти объявления корректны:

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

Разбиение строки

Каждый оператор кода завершается символом точки с запятой ;, обозначающим конец оператора. DelphiScript позволяет записывать оператор на нескольких строках кода, разбивая длинную инструкцию на две или более строк. Единственное ограничение при разбиении операторов на разные строки — строковый литерал не может занимать несколько строк.

For example:

X.AddPoint( 25, 100);
X.AddPoint( 0, 75);
// is equivalent to:
X.AddPoint( 25, 100); X.AddPoint( 0, 75);

however...

'Hello World!'
\\is not equivalent to
'Hello
World!'

DelphiScript не накладывает практических ограничений на длину одной строки кода в скрипте, однако ради читаемости и удобства отладки рекомендуется ограничивать длину строк кода так, чтобы их было легко читать на экране или в распечатанном виде.

Если строка кода очень длинная, вы можете разбить её на несколько строк, и интерпретатор DelphiScript будет обрабатывать этот код так, как если бы он был написан в одну строку.

Unformatted code example:

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

Formatted code example:

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
// is equivalent to
X =5

Вы можете использовать пробелы, чтобы сделать скрипт более читаемым.

Функции и процедуры в скрипте

Интерпретатор DelphiScript поддерживает два вида методов (подпрограмм): процедуры (Procedures) и функции (Functions). Единственное различие между функцией и процедурой состоит в том, что функция возвращает значение.

Скрипт может содержать как минимум одну процедуру, определяющую основной код программы. Однако вы можете определить и другие процедуры и функции, которые будут вызываться вашим кодом.

Как и в Embarcadero Delphi, процедуры и функции определяются внутри блока оператора Begin-End. Чтобы вызвать функцию или процедуру, включите имя функции или процедуры в оператор — так же, как при использовании встроенных функций и процедур DelphiScript. Если функции или процедуре требуются параметры, их необходимо указать в операторе вызова. И функции, и процедуры могут быть определены с параметрами, но только функции могут быть определены так, чтобы возвращать значение в вызывающий оператор.

Функциям и процедурам при определении можно присваивать любые имена, если они соответствуют стандартным соглашениям об именовании DelphiScript.

Typical DelphiScript Procedure:

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

Typical DelphiScript Function:

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

Имя функции нельзя использовать для задания её возвращаемого значения. Вместо этого необходимо использовать ключевое слово Result.

Var, Begin-End global block:

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

Советы по написанию скриптов

Ссылки на скрипты в проекте скриптов

Код в одном скрипте может вызывать процедуру из другого скрипта в рамках того же проекта скриптов. Любая глобальная переменная в любом скрипте может быть доступна в пределах одного и того же проекта.

Локальные и глобальные переменные

Поскольку в скриптах есть локальные и глобальные переменные, важно, чтобы имена переменных в скриптах внутри проекта скриптов были уникальными. Если переменные определены вне любых процедур и функций, они являются глобальными и могут быть доступны из любого модуля (unit) в том же проекте. Если переменные определены внутри процедуры или функции, то эти локальные переменные недоступны за пределами этих процедур/функций.

Рекомендуется объединять в проект скрипты схожего назначения и поддерживать количество скриптов в проекте на управляемом уровне — отслеживание глобальных переменных во множестве скриптов может стать проблемой. Хранить скрипты именно в проекте скриптов не обязательно, так как скрипты можно размещать и в проектах других типов.

Уникальные идентификаторы и переменные

При использовании форм скриптов убедитесь, что у всех форм скриптов уникальные имена форм. Возможно, чтобы все формы скриптов в одном проекте скриптов назывались form1 (например). В этом случае система скриптинга начинает конфликтовать при попытке отобразить правильную форму при выполнении формы скрипта.

Имя формы скрипта можно изменить с помощью Object Inspector. Имя будет автоматически изменено как в файле модуля скрипта, так и в файле формы скрипта.

Процедуры и функции без параметров

Скрипты следует писать так, чтобы процедуры, которые требуется вызывать для запуска скрипта, отображались только в диалоге Select Items to Run dialog. Чтобы другие процедуры/функции не появлялись в диалоге Select Items to Run, рядом с именем метода можно вставить параметр (Dummy : Integer). См. пример ниже.

// This function is prevented from appearing in the Select Items to Run dialog.
Function TSineWaveform.CreateShape(Dummy : Integer);
Begin
    //Do something
End;
{..................................................}
 
{..................................................}
Procedure TSineWaveform.bCloseClick(Sender: TObject);
var
  I : integer;
Begin
     //Doing something
Close;
End;
{..................................................}
 
{..................................................}
procedure DrawSine;
Begin
    SineWaveform.showmodal;
End;

Коды ошибок DelphiScript