DelphiScript

W skrócie

Poznaj obsługę DelphiScript w Altium Designer — od najważniejszych różnic względem Delphi po elementy języka i konwencje skryptowe używane do interakcji z Altium Designer. Ten przewodnik omawia organizację projektów skryptowych, zmienne, komentarze, formatowanie, funkcje i procedury oraz zawiera odnośniki do dokumentacji API i przykładowych skryptów. Czytaj dalej, aby poszerzyć swoją wiedzę i z większą pewnością tworzyć własne skrypty DelphiScript.

- Poznaj zmienne bez określonego typu w DelphiScript, zasady nazewnictwa, zakres widoczności oraz rozróżnianie wielkości liter.
- Dowiedz się, jak moduły skryptowe i formularze są zorganizowane w projektach oraz jak uruchamiać skrypty.
- Znajdź materiały referencyjne dotyczące obsługiwanych funkcji języka, interfejsów API Altium Designer i przykładowych skryptów, w tym uwagi dotyczące starszych przykładów.
Zagłęb się w temat dzięki AI:

W tej sekcji opisano język DelphiScript używany przez silnik skryptowy Altium Designer oraz przedstawiono szczegółowe informacje o obsługiwanych instrukcjach, funkcjach i rozszerzeniach. Są to specjalne procedury służące do sterowania programem Altium Designer i bezpośredniej komunikacji z nim.

W tej dokumentacji również:

Język DelphiScript

W tej dokumentacji języka DelphiScript założono, że znasz podstawowe pojęcia programistyczne oraz podstawy obsługi Altium Designer. System skryptowy obsługuje język DelphiScript, który jest bardzo podobny do Embarcadero Delphi™.

Najważniejsza różnica polega na tym, że DelphiScript jest językiem skryptowym bez typowania, co oznacza, że nie można definiować rekordów ani klas oraz przekazywać wskaźników jako parametrów funkcji. W skryptach nadal można deklarować zmienne w celu poprawy czytelności.

Szczegółowe informacje o różnicach między Delphi a DelphiScript można znaleźć w sekcji Różnice między DelphiScript a Delphi.

Ta strona i powiązane z nią podstrony zawierają informacje referencyjne dotyczące interfejsów, komponentów, procedur i funkcji globalnych, typów oraz zmiennych, które składają się na język skryptowy DelphiScript.

Podstawowe elementy DelphiScript

Obiekty

W DelphiScript obiekt składa się z metod, a w wielu przypadkach także z właściwości i zdarzeń. Właściwości reprezentują dane zawarte w obiekcie, metody to działania, które obiekt może wykonywać, a zdarzenia to warunki, na które obiekt może reagować. Wszystkie obiekty wywodzą się z obiektu najwyższego poziomu typu TObject i dziedziczą po nim.

Interfejsy obiektów

Interfejs obiektu składa się z metod, a w wielu przypadkach także z właściwości, ale nie może zawierać pól danych. Interfejs reprezentuje istniejący obiekt, a każdy interfejs ma identyfikator GUID, który jednoznacznie go identyfikuje. Właściwości reprezentują dane zawarte w obiekcie powiązanym z interfejsem. Metody to działania, które może wykonywać obiekt powiązany z interfejsem.

Komponenty

Komponenty to obiekty wizualne z panelu Tool Palette, którymi można manipulować na etapie projektowania. Wszystkie komponenty wywodzą się z klasy systemowej TComponent w bibliotece Visual Component Library (VCL) środowiska Embarcadero Delphi.

Procedury i funkcje

Globalne procedury i funkcje pochodzą z systemu skryptowego. Nie należą do żadnej klasy, ale można je wywoływać w skrypcie bezpośrednio lub z poziomu metod klas.

Typy

Typy zmiennych są używane jako typy zwracanych wartości i parametrów metod i właściwości interfejsów, metod, właściwości i zdarzeń obiektów oraz globalnych procedur i funkcji. W wielu przypadkach typy są opisane w sekcjach dotyczących typów wyliczeniowych w dokumentacji API.

Na przykład typy wyliczeniowe klienta dla modelu obiektowego DXP opisano szczegółowo na stronie System API.

Altium Designer i biblioteka RTL Delphi

System skryptowy obsługuje podzbiór biblioteki wykonawczej Embarcadero Delphi Run Time Library (RTL) oraz API Altium Designer.

Ogólne informacje o korzystaniu z API w skryptach można znaleźć w sekcji Korzystanie z API Altium Designer w skryptach.

Bardziej szczegółowe informacje można znaleźć w dokumentacji API Altium Designer.

Pliki źródłowe DelphiScript

W Altium Designer projekt skryptowy służy do przechowywania dokumentów skryptowych (modułów i formularzy skryptowych). Skrypt można uruchomić za pomocą pozycji menu, przycisku na pasku narzędzi lub okna dialogowego Select Item To Run dostępnego z menu głównego Altium Designer.

Pliki PRJSCR, PAS i DFM

Skrypty są zorganizowane w projekty z rozszerzeniem *.PRJSCR. Każdy projekt składa się z plików z rozszerzeniem *.pas. Pliki mogą być modułami lub formularzami skryptowymi — należy pamiętać, że każdy formularz ma plik skryptu z rozszerzeniem *.pas oraz odpowiadający mu plik formularza z rozszerzeniem *.dfm. Formularz skryptowy to okno graficzne (okno dialogowe) wyświetlane nad oknem Altium Designer i zawierające różne elementy sterujące dostępne dla użytkownika.

Skrypty można dołączać do różnych projektów. Zdecydowanie zaleca się organizowanie skryptów w osobne projekty, aby ułatwić zarządzanie skryptami oraz ich procedurami i funkcjami.

Przykładowe skrypty

Zbiór przykładowych skryptów ilustruje podstawowe możliwości programowania w DelphiScript na podstawie prostych skryptów przeznaczonych do użytku w Altium Designer.

Pobierz zbiór przykładowych skryptów.

Poniżej podano lokalizacje i przeznaczenie wybranych przykładowych skryptów:

  • Scripts\DelphiScript Scripts\DXP folder — demonstruje API klienta i systemu
  • Scripts\DelphiScript Scripts\PCB folder — demonstruje API PCB
  • Scripts\DelphiScript Scripts\Processes folder — demonstruje procesy serwera
  • Scripts\DelphiScript Scripts\General folder — demonstruje słowa kluczowe DelphiScript
  • Scripts\DelphiScript Scripts\Sch folder — demonstruje API edytora schematów
  • Scripts\DelphiScript Scripts\WSM folder — demonstruje API menedżera przestrzeni roboczej
Ze względu na ciągłe aktualizacje API Altium Designer niektóre starsze przykładowe skrypty mogą nie działać zgodnie z pierwotnym zamierzeniem. Mimo to przykładowe skrypty stanowią przydatne źródło wiedzy i punkt odniesienia podczas tworzenia własnych skryptów.

Tworzenie skryptów DelphiScript

Konwencje nazewnictwa w DelphiScript

Zasadniczo nie ma ograniczeń dotyczących nazw nadawanych procedurom, funkcjom, zmiennym i stałym, o ile spełniają one następujące reguły:

  • Nazwa może zawierać litery od A do Z i od a do z, znak podkreślenia „_” oraz cyfry od 0 do 9.
  • Nazwa musi zaczynać się od litery.
  • Nazwa nie może być słowem kluczowym, dyrektywą ani słowem zastrzeżonym DelphiScript.
  • Podczas interpretacji nazw wielkość liter nie jest rozróżniana. Przy nadawaniu nazw funkcjom, podprogramom, zmiennym lub stałym można używać zarówno wielkich, jak i małych liter, jednak interpreter nie będzie ich rozróżniał. Nazwy różniące się wyłącznie wielkością liter będą w DelphiScript traktowane jako ta sama nazwa.
Szczegółowe informacje o słowach kluczowych można znaleźć w sekcji Słowa kluczowe DelphiScript.

W pliku DelphiScript funkcje i procedury deklaruje się za pomocą bloków Procedure-Begin-End lub Function-Begin-End. Oba te bloki instrukcji wymagają nadania nazwy procedurze lub funkcji. DelphiScript umożliwia tworzenie nazwanych zmiennych i stałych do przechowywania wartości używanych w bieżącym skrypcie.

Dodawanie komentarzy

W skrypcie komentarze to niewykonywalne wiersze kodu zamieszczane z myślą o programiście. Komentarze można umieszczać praktycznie w dowolnym miejscu skryptu.

Każdy tekst występujący po // lub ujęty w (* *) albo {} jest ignorowany przez 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
*)

Komentarze można również umieszczać w tym samym wierszu co wykonywany kod. Na przykład wszystko po średniku w poniższym wierszu kodu jest traktowane jako komentarz.

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

Zmienne lokalne i globalne

Ponieważ wszystkie skrypty mają zmienne lokalne i globalne, bardzo ważne jest stosowanie unikatowych nazw zmiennych w skryptach należących do jednego projektu skryptowego. Jeśli zmienne są zdefiniowane outside procedurami i funkcjami, są globalne i dostępne z dowolnego modułu skryptowego w tym samym projekcie.

Jeśli zmienne są zdefiniowane inside procedury lub funkcji, te zmienne lokalne nie są dostępne poza daną procedurą lub funkcją.

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';

Korzystanie z nazwanych zmiennych

W skrypcie tworzy się nazwane zmienne lub stałe do przechowywania wartości używanych podczas wykonywania programu. Wszystkie zmienne w skrypcie są zawsze typu Variant. Rzutowanie typów nie ma zastosowania, dlatego typy w deklaracjach zmiennych są ignorowane i można je pominąć. Poniższe deklaracje są zatem poprawne:

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

Dzielenie wiersza

Każda instrukcja kodu jest zakończona znakiem średnika ;, który wskazuje jej koniec. DelphiScript umożliwia zapisanie instrukcji w kilku wierszach kodu, dzieląc długą instrukcję na dwa lub więcej wierszy. Jedynym ograniczeniem przy dzieleniu instrukcji na osobne wiersze jest to, że literał ciągu znaków nie może obejmować kilku wierszy.

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 nie nakłada żadnych praktycznych ograniczeń na długość pojedynczego wiersza kodu w skrypcie, jednak ze względu na czytelność i łatwość debugowania dobrą praktyką jest ograniczanie długości wierszy tak, aby można je było wygodnie odczytać na ekranie lub wydruku.

Jeśli wiersz kodu jest bardzo długi, można podzielić go na kilka wierszy, a interpreter DelphiScript potraktuje ten kod tak, jakby był zapisany w jednym wierszu.

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;

Rozróżnianie wielkości liter

Język DelphiScript używany do pisania skryptów nie rozróżnia wielkości liter — oznacza to, że wszystkie słowa kluczowe, instrukcje, nazwy zmiennych, funkcji i procedur można zapisywać bez względu na użycie wielkich lub małych liter. Wielkie i małe litery są traktowane jako równoważne.

Na przykład nazwa zmiennej myVar jest równoważna nazwom myvar i MYVAR. DelphiScript traktuje wszystkie te nazwy jako tę samą zmienną.

Jedynym wyjątkiem są literały ciągów znaków, takie jak ciąg tytułu w definicji okna dialogowego lub wartość zmiennej tekstowej. W tych ciągach zachowywane są różnice w wielkości liter.

Znak spacji

Spacja służy do oddzielania słów kluczowych w instrukcji skryptu. DelphiScript ignoruje jednak wszelkie dodatkowe białe znaki w instrukcji.

Na przykład:

X   = 5
// is equivalent to
X =5

Białych znaków można używać, aby zwiększyć czytelność skryptu.

Funkcje i procedury w skrypcie

Interpreter DelphiScript obsługuje dwa rodzaje metod: procedury i funkcje. Jedyna różnica między funkcją a procedurą polega na tym, że funkcja zwraca wartość.

Skrypt może zawierać co najmniej jedną procedurę definiującą główny kod programu. Można jednak zdefiniować również inne procedury i funkcje, które będą wywoływane przez kod.

Podobnie jak w Embarcadero Delphi, procedury i funkcje są definiowane w bloku instrukcji Begin-End. Aby wywołać funkcję lub procedurę, należy umieścić jej nazwę w instrukcji w taki sam sposób, jak podczas korzystania z wbudowanych funkcji i procedur DelphiScript. Jeśli funkcja lub procedura wymaga parametrów, należy je uwzględnić w instrukcji wywołującej. Zarówno funkcje, jak i procedury można zdefiniować tak, aby przyjmowały parametry, ale tylko funkcje mogą zwracać wartość do instrukcji wywołującej.

Podczas definiowania funkcji i procedur można nadawać im dowolne nazwy, pod warunkiem że są one zgodne ze standardowymi zasadami nazewnictwa 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;

Nazwy funkcji nie można użyć do ustawienia jej wartości zwracanej. Zamiast tego należy użyć słowa kluczowego Result.

Var, Begin-End global block:

Var
  A, B, C;
Begin
  B := 10;
  C := 20;
  A := B + C;
  ShowMessage(IntToStr(A));
End;
  • Szczegółowe informacje na temat operatorów wyrażeń w DelphiScript można znaleźć na stronie Instrukcje i operatory DelphiScript.
  • Szczegółowe informacje na temat funkcji i podprogramów DelphiScript, takich jak operacje wejścia/wyjścia na plikach i podprogramy matematyczne, można znaleźć na stronie Funkcje DelphiScript.
  • Omówienie korzystania z okien dialogowych formularzy i komponentów wizualnych DelphiScript można znaleźć na stronie Formularze i komponenty skryptów DelphiScript.

Wskazówki dotyczące tworzenia skryptów

Odwoływanie się do skryptów w projekcie skryptowym

Kod jednego skryptu może wywoływać procedurę w innym skrypcie należącym do tego samego projektu skryptowego. Każda zmienna globalna w dowolnym skrypcie jest dostępna w obrębie tego samego projektu.

Zmienne lokalne i globalne

Ponieważ skrypty zawierają zmienne lokalne i globalne, ważne jest, aby nazwy zmiennych w skryptach należących do jednego projektu skryptowego były unikatowe. Zmienne zdefiniowane poza procedurami i funkcjami są globalne i dostępne z dowolnego modułu w tym samym projekcie. Zmienne zdefiniowane wewnątrz procedury lub funkcji są natomiast zmiennymi lokalnymi i nie są dostępne poza tymi procedurami lub funkcjami.

Zaleca się umieszczanie w jednym projekcie skryptów o podobnym charakterze oraz utrzymywanie ich liczby na poziomie ułatwiającym zarządzanie — śledzenie zmiennych globalnych w wielu skryptach może stać się problematyczne. Nie ma obowiązku przechowywania skryptów w projekcie skryptowym, ponieważ można je umieszczać również w projektach innych typów.

Unikatowe identyfikatory i zmienne

Podczas korzystania z formularzy skryptowych należy upewnić się, że wszystkie mają unikatowe nazwy. Możliwe jest na przykład nadanie wszystkim formularzom skryptowym w tym samym projekcie skryptowym nazwy form1. W takim przypadku podczas uruchamiania formularza skryptowego w systemie skryptowym występuje konflikt przy próbie wyświetlenia właściwego formularza.

Nazwę formularza skryptowego można zmienić za pomocą Object Inspector. Nazwa zostanie automatycznie zmieniona zarówno w pliku modułu skryptowego, jak i w pliku formularza skryptowego.

Procedury i funkcje bez parametrów

Skrypty należy pisać tak, aby w oknie dialogowym Select Items to Run były widoczne wyłącznie procedury, których wywołanie jest wymagane do uruchomienia skryptu. Aby zapobiec wyświetlaniu innych procedur lub funkcji w oknie dialogowym Select Items to Run, można dodać parametr (Dummy : Integer) obok nazwy metody. Zobacz poniższy przykład.

// 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;

Kody błędów DelphiScript

Error

Description

%s expected but %s found

W skrypcie użyto nieprawidłowego ciągu znaków.

%s or %s expected

W skrypcie użyto nieprawidłowego ciągu znaków.

Function %s is already defined

W kodzie nie są dozwolone wielokrotne wystąpienia funkcji o tej samej nazwie. Zmień nazwy pozostałych funkcji o tej samej nazwie.

Unknown identifier: %s

Nieznany identyfikator. Przed użyciem tego identyfikatora należy go zadeklarować.

Unknown variable type during writing program

Skrypt zawiera nieprawidłowy lub nieznany typ zmiennej.

Unit %s already defined

Wielokrotne wystąpienia tych samych nazw modułów nie są dozwolone. Upewnij się, że nazwy modułów skryptowych są unikatowe.

Unit declaration error

Deklaracja modułu nie jest poprawnie zdefiniowana.

Function %s not found

Brak funkcji w skrypcie.

Link Error

DelphiScript nie może połączyć skryptu z wymaganymi komponentami wewnętrznymi.

Label <%s> already defined

W skrypcie występuje wiele instancji tej samej etykiety. Upewnij się, że etykiety w skrypcie są unikatowe.

Error in declaration block

Blok deklaracji nie jest poprawnie zdefiniowany.

Label <%s> not defined

Etykieta Goto nie jest zdefiniowana.

Variable <%s> already defined

W skrypcie występuje wiele instancji tych samych zmiennych. Upewnij się, że zmienne są unikatowe.

Error in variable declaration block

W bloku deklaracji zmiennych występuje błąd. Deklaracje są nieprawidłowe lub nierozpoznawane przez system skryptowy.

Variable <%s> not defined

Zmienna nie została zdefiniowana, dlatego system skryptowy nie może jej zdefiniować.

Method declaration error

Sygnatura metody jest niedozwolona.

Method parameters declaration error

Użyto nieprawidłowych parametrów metody.

Properties are not supported

Właściwości obiektu nie są rozpoznawane przez system skryptowy.

Only class declarations allowed

Podjęto próbę zadeklarowania elementów innych niż klasy.

%s declaration error

W skrypcie występuje błąd deklaracji.

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

W skrypcie wystąpił błąd składni
— niedozwolona instrukcja, brakujący znak lub nierozpoznane słowo kluczowe.

Bad identifier name <%s>

Nieprawidłowa nazwa identyfikatora, na przykład zduplikowana nazwa. Zmień nazwę identyfikatora.

Bad identifier <%s>

Nieprawidłowy identyfikator. Zdefiniuj nowy identyfikator.

Invalid function usage

Nieprawidłowe użycie funkcji w skrypcie
— na przykład nieprawidłowe parametry.

Invalid procedure usage

Nieprawidłowe użycie procedury w skrypcie
— na przykład nieprawidłowe parametry.

Hex constant declaration error

Nieprawidłowo zadeklarowana wartość stałej szesnastkowej.

Compile before run

Przed wykonaniem skrypt należy skompilować. Błąd wewnętrzny.

Real constant declaration error

Błąd deklaracji stałej typu rzeczywistego.

String constant declaration error

Błąd deklaracji stałej typu łańcuchowego.

Unsupported parameter type

System skryptowy zgłosił nieznany typ parametru.

Variable Result not found for %s

Nie znaleziono wynikowej wartości zmiennej dla określonego ciągu znaków w skrypcie.

Procedure %s not found

Brak procedury w skrypcie.

Parameter %S not found

Brak parametru w skrypcie.

Unknown reader type

Błąd wewnętrzny.

Wrong number of params

Deklaracja i implementacja tej samej procedury lub funkcji różnią się. Sprawdź zgodność parametrów między nimi.

One of the params is not a valid variant type

Jeden z parametrów metody, funkcji lub procedury nie ma prawidłowego typu Variant.

Property does not exist or is readonly

Próba przypisania wartości do właściwości tylko do odczytu lub do nieistniejącej właściwości.

Named arguments are not supported

Argumenty użyte w procedurze lub funkcji są nieprawidłowe dla skryptu.

Parameter not found

Brak wartości parametru.

Parameter type mismatch

Użyto niewłaściwego typu parametru.

Unknown interface

Ten interfejs nie został zadeklarowany ani zdefiniowany.

A required parameter was omitted

Brak parametru wymaganego przez metodę, funkcję lub procedurę.

Unknown error

DelphiScript wykrył nieznany błąd skryptu, który nie jest zdefiniowany w tabeli błędów wewnętrznych.

Invalid operation code

DelphiScript wykrył nieprawidłowy kod operacji.

AI-LocalizedTłumaczenie SI
Jeśli znajdziesz błąd, zaznacz tekst/obraz i naciśnij Ctrl + Enter aby wysłać nam wiadomość.
Nav
Contents
Dostępność funkcji

Dostępne funkcje zależą od tego, z którego rozwiązania Altium korzystasz – Altium Develop, Altium Agile Teams, Altium Agile Enterprise lub Altium Designer (w ramach aktywnej subskrypcji terminowej).

Jeśli opisana funkcja nie jest widoczna w Twoim oprogramowaniu, skontaktuj się z działem sprzedaży Altium, aby dowiedzieć się więcej.

Starsza dokumentacja

Dokumentacja Altium Designer nie jest już wersjonowana. Jeśli potrzebujesz dostępu do dokumentacji dla starszych wersji Altium Designer, odwiedź sekcję Starsza dokumentacja na stronie Inne instalatory.

Contents