DelphiScript

Краткий обзор

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

- Разберитесь с нетипизированными переменными DelphiScript, правилами именования, областью видимости и чувствительностью к регистру.
- Узнайте, как модули и формы скриптов организованы в проектах и как запускать скрипты.
- Найдите справочные материалы по поддерживаемым возможностям языка, API Altium Designer и примеры скриптов, включая замечания об устаревших примерах.
Узнайте больше с ИИ:

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

Также в этом справочнике:

Язык DelphiScript

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

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

Подробнее о различиях между Delphi и DelphiScript см. в разделе Различия между DelphiScript и Delphi.

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

Основные элементы DelphiScript

Объекты

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

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

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

Компоненты

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

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

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

Типы

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

Например, перечисляемые типы Client для объектной модели DXP подробно описаны на странице System API.

Altium Designer и библиотека Delphi RTL

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

Обзор возможностей использования API в скриптах см. в разделе Использование API Altium Designer в скриптах.

Более подробные сведения см. в документации по 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
Из-за постоянного обновления API Altium Designer некоторые устаревшие примеры скриптов могут работать не так, как было задумано изначально. Тем не менее примеры скриптов служат полезным ресурсом и справочным материалом для создания собственных скриптов.

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

Правила именования в DelphiScript

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

  • Имя может содержать буквы от A до Z и от a до z, символ подчеркивания «_» и цифры от 0 до 9.
  • Имя должно начинаться с буквы.
  • Имя не может совпадать с ключевым словом, директивой или зарезервированным словом DelphiScript.
  • При интерпретации регистр букв в именах не учитывается. В именах функций, подпрограмм, переменных и констант можно использовать как прописные, так и строчные буквы, однако интерпретатор не будет их различать. Имена, отличающиеся только регистром, в 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;
  • Подробные сведения об операторах выражений DelphiScript см. на странице Операторы и операции DelphiScript.
  • Подробные сведения о функциях и подпрограммах DelphiScript, таких как подпрограммы файлового ввода-вывода и математические подпрограммы, см. на странице Функции DelphiScript.
  • Обзор использования диалоговых форм и визуальных компонентов DelphiScript см. на странице Формы и компоненты скриптов DelphiScript.

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

Обращение к скриптам в проекте скриптов

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

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

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

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

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

При использовании форм скриптов убедитесь, что у всех форм уникальные имена. В одном проекте скриптов все формы могут называться, например, 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

%s expected but %s found

В скрипте использована неверная строка.

%s or %s expected

В скрипте использована неверная строка.

Function %s is already defined

Наличие в коде нескольких функций с одинаковым именем не допускается. Переименуйте остальные функции с таким же именем.

Unknown identifier: %s

Неизвестный идентификатор. Перед использованием этого идентификатора его необходимо объявить.

Unknown variable type during writing program

В скрипте указан недопустимый или неизвестный тип переменной.

Unit %s already defined

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

Unit declaration error

Объявление модуля задано некорректно.

Function %s not found

В скрипте отсутствует функция.

Link Error

DelphiScript не удается связать скрипт с необходимыми внутренними компонентами.

Label <%s> already defined

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

Error in declaration block

Блок объявлений задан некорректно.

Label <%s> not defined

Метка перехода Goto не определена.

Variable <%s> already defined

В скрипте несколько раз объявлены одни и те же переменные. Убедитесь, что имена переменных уникальны.

Error in variable declaration block

Ошибка в блоке объявления переменных. Объявления некорректны или не распознаются системой исполнения скриптов.

Variable <%s> not defined

Переменная не была определена, поэтому система исполнения скриптов не может ее определить.

Method declaration error

Недопустимая сигнатура метода.

Method parameters declaration error

Для метода указаны неверные параметры.

Properties are not supported

Свойства объекта не распознаются системой исполнения скриптов.

Only class declarations allowed

Предпринята попытка объявить сущности, отличные от классов.

%s declaration error

В скрипте обнаружена ошибка объявления.

Syntax error at Line: %d Char: %d'#13#10'%s

В скрипте произошла синтаксическая ошибка
: недопустимый оператор, пропущенный символ или нераспознанное ключевое слово.

Bad identifier name <%s>

Недопустимое имя идентификатора, например дублирующееся имя. Задайте другое имя идентификатора.

Bad identifier <%s>

Недопустимый идентификатор. Задайте новый идентификатор

Invalid function usage

Функция используется в скрипте некорректно
— например, указаны недопустимые параметры.

Invalid procedure usage

Процедура используется в скрипте некорректно
— например, указаны недопустимые параметры.

Hex constant declaration error

Некорректно объявлено значение шестнадцатеричной константы.

Compile before run

Перед выполнением скрипт необходимо скомпилировать. Внутренняя ошибка.

Real constant declaration error

Ошибка объявления константы вещественного типа.

String constant declaration error

Ошибка объявления константы строкового типа.

Unsupported parameter type

Система выполнения скриптов сообщила о неизвестном типе параметра.

Variable Result not found for %s

Для указанной строки в скрипте не найдено результирующее значение переменной.

Procedure %s not found

В скрипте отсутствует процедура.

Parameter %S not found

В скрипте отсутствует параметр.

Unknown reader type

Внутренняя ошибка.

Wrong number of params

Объявление и реализация одной и той же процедуры или функции различаются. Проверьте соответствие параметров.

One of the params is not a valid variant type

Один из параметров метода, функции или процедуры имеет некорректный тип Variant.

Property does not exist or is readonly

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

Named arguments are not supported

Аргументы, переданные процедуре или функции, недопустимы для скрипта.

Parameter not found

Отсутствует значение параметра.

Parameter type mismatch

Использован неверный тип параметра.

Unknown interface

Этот интерфейс не объявлен или не определён.

A required parameter was omitted

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

Unknown error

DelphiScript обнаружил неизвестную ошибку скрипта, не указанную в таблице внутренних ошибок.

Invalid operation code

DelphiScript обнаружил недопустимый код операции.

AI-LocalizedЛокализовано с помощью ИИ
Если вы обнаружили проблему, выделите текст/изображение и нажмитеCtrl + Enter, чтобы отправить нам свой отзыв.
Меню
Contents
Доступность функций

Доступные вам функции зависят от того, какое решение Altium вы используете: Altium Develop, Altium Agile Teams, Altium Agile Enterprise или Altium Designer (при активной подписке).

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

Устаревшая документация

Документация Altium Designer больше не разделена по версиям ПО. Если вам необходим доступ к документации по старым версиям Altium Designer, посетите раздел Устаревшая документация на странице Прочие установщики.

Contents