DelphiScript
Краткий обзор
- Разберитесь с нетипизированными переменными DelphiScript, правилами именования, областью видимости и чувствительностью к регистру.
- Узнайте, как модули и формы скриптов организованы в проектах и как запускать скрипты.
- Найдите справочные материалы по поддерживаемым возможностям языка, API Altium Designer и примеры скриптов, включая замечания об устаревших примерах.
В этом разделе описывается язык DelphiScript, используемый механизмом выполнения скриптов Altium Designer, и приводится справочная информация о поддерживаемых операторах, функциях и расширениях. Это специальные процедуры, используемые для управления Altium Designer и непосредственного взаимодействия с ним.
Также в этом справочнике:
- Различия между DelphiScript и Delphi
- Ключевые слова DelphiScript
- Операторы и операции DelphiScript
- Функции DelphiScript
- Формы и компоненты DelphiScript
Язык DelphiScript
Этот справочник по DelphiScript предполагает, что вы знакомы с основными понятиями программирования и основами работы в Altium Designer. Система выполнения скриптов поддерживает язык DelphiScript, который очень похож на Embarcadero Delphi™.
Основное отличие заключается в том, что DelphiScript — это бестиповый язык скриптов, то есть в нем нельзя определять записи или классы и передавать указатели в качестве параметров функций. При этом для удобства чтения кода переменные в скриптах по-прежнему можно объявлять.
Эта страница и ее подразделы содержат справочные материалы об интерфейсах, компонентах, глобальных подпрограммах, типах и переменных, составляющих язык скриптов DelphiScript.
Основные элементы DelphiScript
Объекты
В DelphiScript объект состоит из методов, а во многих случаях также из свойств и событий. Свойства представляют данные, содержащиеся в объекте, методы — действия, которые объект может выполнять, а события — условия, на которые объект может реагировать. Все объекты являются потомками объекта верхнего уровня типа TObject и наследуют его возможности.
Интерфейсы объектов
Интерфейс объекта состоит из методов и во многих случаях свойств, но не может содержать поля данных. Интерфейс представляет существующий объект, и каждому интерфейсу назначен уникальный идентификатор GUID. Свойства представляют данные, содержащиеся в объекте, с которым связан интерфейс. Методы — это действия, которые может выполнять объект, связанный с интерфейсом.
Компоненты
Компоненты — это визуальные объекты из панели Tool Palette, с которыми можно работать на этапе проектирования. Все компоненты являются потомками системного класса TComponent из библиотеки визуальных компонентов Embarcadero Delphi (VCL).
Подпрограммы
Глобальные подпрограммы — это процедуры и функции системы выполнения скриптов. Эти подпрограммы не входят в состав класса, но могут вызываться как напрямую, так и из методов классов в скрипте.
Типы
Типы переменных используются в качестве типов возвращаемых значений и параметров для методов и свойств интерфейсов, методов, свойств и событий объектов, а также глобальных подпрограмм. Во многих случаях типы описаны в разделах, посвященных перечисляемым типам, в документации по API.
Altium Designer и библиотека Delphi RTL
Система выполнения скриптов поддерживает подмножество библиотеки времени выполнения Embarcadero Delphi (RTL) и API Altium Designer.
Исходные файлы DelphiScript
В Altium Designer для хранения документов скриптов (модулей и форм скриптов) используется проект скриптов. Запустить скрипт можно с помощью пункта меню, кнопки панели инструментов или диалогового окна Select Item To Run, доступного из главного меню Altium Designer.
Файлы PRJSCR, PAS и DFM
Скрипты объединяются в проекты с расширением *.PRJSCR. Каждый проект состоит из файлов с расширением *.pas. Файлы могут быть модулями или формами скриптов. Обратите внимание, что каждая форма имеет файл скрипта с расширением *.pas и соответствующий файл формы с расширением *.dfm. Форма скрипта — это графическое окно (диалоговое окно), которое открывается поверх Altium Designer и содержит различные элементы управления, доступные пользователю.
Скрипты можно подключать к разным проектам. Настоятельно рекомендуется распределять скрипты по разным проектам, чтобы было проще управлять множеством скриптов и их процедурами и функциями.
Примеры скриптов
Коллекция примеров скриптов демонстрирует основные возможности программирования на DelphiScript на простых скриптах для Altium Designer.
Ниже перечислены расположение и назначение некоторых примеров скриптов:
-
Scripts\DelphiScript Scripts\DXPпапка — демонстрирует Client API и системный API -
Scripts\DelphiScript Scripts\PCПапка B — демонстрирует PCB API -
Scripts\DelphiScript Scripts\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 поддерживает два вида методов: процедуры и функции. Единственное различие между функцией и процедурой заключается в том, что функция возвращает значение.
Скрипт может содержать как минимум одну процедуру, определяющую основной код программы. При этом можно определить и другие процедуры и функции, которые будут вызываться из вашего кода.
Как и в 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;
Советы по написанию скриптов
Обращение к скриптам в проекте скриптов
Код одного скрипта может вызывать процедуру из другого скрипта в том же проекте скриптов. Любая глобальная переменная любого скрипта доступна в пределах одного проекта.
Локальные и глобальные переменные
Поскольку в скриптах есть локальные и глобальные переменные, важно использовать уникальные имена переменных в скриптах одного проекта. Если переменные определены вне процедур и функций, они являются глобальными и доступны из любого модуля того же проекта. Если переменные определены внутри процедуры или функции, такие локальные переменные недоступны за пределами этой процедуры или функции.
Рекомендуется объединять в одном проекте скрипты схожего назначения и ограничивать их количество, чтобы проект оставался удобным для работы: отслеживание глобальных переменных во множестве скриптов может стать проблемой. Хранить скрипты в проекте скриптов необязательно, поскольку их можно размещать и в проектах других типов.
Уникальные идентификаторы и переменные
При использовании форм скриптов убедитесь, что у всех форм уникальные имена. В одном проекте скриптов все формы могут называться, например, form1. В этом случае при выполнении формы скрипта система исполнения скриптов не сможет однозначно определить, какую форму следует отобразить.
Имя формы скрипта можно изменить с помощью Object Inspector. Имя будет автоматически изменено как в файле модуля скрипта, так и в файле формы скрипта.
Процедуры и функции без параметров
Скрипты следует писать так, чтобы в диалоговом окне Выбор элементов для запуска отображались только процедуры, которые необходимо вызывать для запуска скрипта. Чтобы другие процедуры и функции не отображались в диалоговом окне 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
Error |
Description |
|---|---|
|
В скрипте использована неверная строка. |
|
В скрипте использована неверная строка. |
|
Наличие в коде нескольких функций с одинаковым именем не допускается. Переименуйте остальные функции с таким же именем. |
|
Неизвестный идентификатор. Перед использованием этого идентификатора его необходимо объявить. |
|
В скрипте указан недопустимый или неизвестный тип переменной. |
|
Наличие нескольких модулей с одинаковыми именами не допускается. Убедитесь, что имена модулей скриптов уникальны. |
|
Объявление модуля задано некорректно. |
|
В скрипте отсутствует функция. |
|
DelphiScript не удается связать скрипт с необходимыми внутренними компонентами. |
|
В скрипте несколько раз встречается одна и та же метка. Убедитесь, что метки в скрипте уникальны. |
|
Блок объявлений задан некорректно. |
|
Метка перехода Goto не определена. |
|
В скрипте несколько раз объявлены одни и те же переменные. Убедитесь, что имена переменных уникальны. |
|
Ошибка в блоке объявления переменных. Объявления некорректны или не распознаются системой исполнения скриптов. |
|
Переменная не была определена, поэтому система исполнения скриптов не может ее определить. |
|
Недопустимая сигнатура метода. |
|
Для метода указаны неверные параметры. |
|
Свойства объекта не распознаются системой исполнения скриптов. |
|
Предпринята попытка объявить сущности, отличные от классов. |
|
В скрипте обнаружена ошибка объявления. |
|
В скрипте произошла синтаксическая ошибка |
|
Недопустимое имя идентификатора, например дублирующееся имя. Задайте другое имя идентификатора. |
|
Недопустимый идентификатор. Задайте новый идентификатор |
|
Функция используется в скрипте некорректно |
|
Процедура используется в скрипте некорректно |
|
Некорректно объявлено значение шестнадцатеричной константы. |
|
Перед выполнением скрипт необходимо скомпилировать. Внутренняя ошибка. |
|
Ошибка объявления константы вещественного типа. |
|
Ошибка объявления константы строкового типа. |
|
Система выполнения скриптов сообщила о неизвестном типе параметра. |
|
Для указанной строки в скрипте не найдено результирующее значение переменной. |
|
В скрипте отсутствует процедура. |
|
В скрипте отсутствует параметр. |
|
Внутренняя ошибка. |
|
Объявление и реализация одной и той же процедуры или функции различаются. Проверьте соответствие параметров. |
|
Один из параметров метода, функции или процедуры имеет некорректный тип Variant. |
|
Попытка присвоить значение свойству, доступному только для чтения, либо несуществующему свойству. |
|
Аргументы, переданные процедуре или функции, недопустимы для скрипта. |
|
Отсутствует значение параметра. |
|
Использован неверный тип параметра. |
|
Этот интерфейс не объявлен или не определён. |
|
Отсутствует обязательный параметр метода, функции или процедуры. |
|
DelphiScript обнаружил неизвестную ошибку скрипта, не указанную в таблице внутренних ошибок. |
|
DelphiScript обнаружил недопустимый код операции. |