DelphiScript
W skrócie
- 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.
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ż:
- Różnice między DelphiScript a Delphi
- Słowa kluczowe DelphiScript
- Instrukcje i operatory DelphiScript
- Funkcje DelphiScript
- Formularze i komponenty DelphiScript
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.
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.
Altium Designer i biblioteka RTL Delphi
System skryptowy obsługuje podzbiór biblioteki wykonawczej Embarcadero Delphi Run Time Library (RTL) oraz 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.
Poniżej podano lokalizacje i przeznaczenie wybranych przykładowych skryptów:
-
Scripts\DelphiScript Scripts\DXPfolder — demonstruje API klienta i systemu -
Scripts\DelphiScript Scripts\PCB folder — demonstruje API PCB -
Scripts\DelphiScript Scripts\Processesfolder — demonstruje procesy serwera -
Scripts\DelphiScript Scripts\Generalfolder — demonstruje słowa kluczowe DelphiScript -
Scripts\DelphiScript Scripts\Schfolder — demonstruje API edytora schematów -
Scripts\DelphiScript Scripts\WSMfolder — demonstruje API menedżera przestrzeni roboczej
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.
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;
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 |
|---|---|
|
W skrypcie użyto nieprawidłowego ciągu znaków. |
|
W skrypcie użyto nieprawidłowego ciągu znaków. |
|
W kodzie nie są dozwolone wielokrotne wystąpienia funkcji o tej samej nazwie. Zmień nazwy pozostałych funkcji o tej samej nazwie. |
|
Nieznany identyfikator. Przed użyciem tego identyfikatora należy go zadeklarować. |
|
Skrypt zawiera nieprawidłowy lub nieznany typ zmiennej. |
|
Wielokrotne wystąpienia tych samych nazw modułów nie są dozwolone. Upewnij się, że nazwy modułów skryptowych są unikatowe. |
|
Deklaracja modułu nie jest poprawnie zdefiniowana. |
|
Brak funkcji w skrypcie. |
|
DelphiScript nie może połączyć skryptu z wymaganymi komponentami wewnętrznymi. |
|
W skrypcie występuje wiele instancji tej samej etykiety. Upewnij się, że etykiety w skrypcie są unikatowe. |
|
Blok deklaracji nie jest poprawnie zdefiniowany. |
|
Etykieta Goto nie jest zdefiniowana. |
|
W skrypcie występuje wiele instancji tych samych zmiennych. Upewnij się, że zmienne są unikatowe. |
|
W bloku deklaracji zmiennych występuje błąd. Deklaracje są nieprawidłowe lub nierozpoznawane przez system skryptowy. |
|
Zmienna nie została zdefiniowana, dlatego system skryptowy nie może jej zdefiniować. |
|
Sygnatura metody jest niedozwolona. |
|
Użyto nieprawidłowych parametrów metody. |
|
Właściwości obiektu nie są rozpoznawane przez system skryptowy. |
|
Podjęto próbę zadeklarowania elementów innych niż klasy. |
|
W skrypcie występuje błąd deklaracji. |
|
W skrypcie wystąpił błąd składni |
|
Nieprawidłowa nazwa identyfikatora, na przykład zduplikowana nazwa. Zmień nazwę identyfikatora. |
|
Nieprawidłowy identyfikator. Zdefiniuj nowy identyfikator. |
|
Nieprawidłowe użycie funkcji w skrypcie |
|
Nieprawidłowe użycie procedury w skrypcie |
|
Nieprawidłowo zadeklarowana wartość stałej szesnastkowej. |
|
Przed wykonaniem skrypt należy skompilować. Błąd wewnętrzny. |
|
Błąd deklaracji stałej typu rzeczywistego. |
|
Błąd deklaracji stałej typu łańcuchowego. |
|
System skryptowy zgłosił nieznany typ parametru. |
|
Nie znaleziono wynikowej wartości zmiennej dla określonego ciągu znaków w skrypcie. |
|
Brak procedury w skrypcie. |
|
Brak parametru w skrypcie. |
|
Błąd wewnętrzny. |
|
Deklaracja i implementacja tej samej procedury lub funkcji różnią się. Sprawdź zgodność parametrów między nimi. |
|
Jeden z parametrów metody, funkcji lub procedury nie ma prawidłowego typu Variant. |
|
Próba przypisania wartości do właściwości tylko do odczytu lub do nieistniejącej właściwości. |
|
Argumenty użyte w procedurze lub funkcji są nieprawidłowe dla skryptu. |
|
Brak wartości parametru. |
|
Użyto niewłaściwego typu parametru. |
|
Ten interfejs nie został zadeklarowany ani zdefiniowany. |
|
Brak parametru wymaganego przez metodę, funkcję lub procedurę. |
|
DelphiScript wykrył nieznany błąd skryptu, który nie jest zdefiniowany w tabeli błędów wewnętrznych. |
|
DelphiScript wykrył nieprawidłowy kod operacji. |