Writing Scripts

W skrócie

Zacznij pisać skrypty w Altium Designer od prostego przykładu „Hello World” w języku DelphiScript, a następnie dowiedz się, jak utworzyć formularz skryptu z interaktywnymi kontrolkami. Ten artykuł przedstawia podstawowe pojęcia związane ze skryptami, wyjaśnia, jak uruchamiać i zatrzymywać skrypty, oraz pokazuje, jak panele Object Inspector i Tool Palette pomagają w konfigurowaniu formularzy i obsłudze zdarzeń. Czytaj dalej, aby postawić pierwsze kroki w tworzeniu i uruchamianiu własnych skryptów.

- Poznaj podstawowe pojęcia związane ze skryptami, w tym procesy, komponenty, interfejsy obiektów, właściwości, metody i zdarzenia.
- Dowiedz się, jak utworzyć i uruchomić prostą procedurę w języku DelphiScript oraz ustawić procedurę startową projektu.
- Sprawdź, jak tworzyć formularze skryptów, dodawać przyciski oraz konfigurować właściwości komponentów i procedury obsługi zdarzeń.
Zagłęb się w temat dzięki AI:
 

Pisanie skryptów

Z pisaniem skryptów wiąże się szereg podstawowych pojęć i terminów:

  • Procesy to ciągi poleceń, których można używać do wykonywania poleceń w skryptach.
  • Komponenty to wizualne elementy sterujące dostępne w panelu Tool Palette, które można przeciągać i upuszczać na formularzu skryptu, aby operować na projekcie.
  • Komponent umieszczony na formularzu skryptu ma metody, właściwości i zdarzenia.
  • Interfejsy obiektowe to specjalne interfejsy obiektów, które umożliwiają odczytywanie i modyfikowanie danych w dokumentach projektowych z poziomu skryptów.

Języki skryptowe

Domyślnym językiem skryptowym jest DelphiScript (*.pas). Sam silnik skryptowy jest napisany w Embarcadero Delphi, a panel Tool Palette jest oparty na bibliotece VCL (Visual Component Library) środowiska Delphi.

  • Można otwierać i uruchamiać istniejące skrypty napisane w językach VBScript i JavaScript (Jscript). Aby móc tworzyć nowe skrypty w języku VBScript, należy włączyć opcję Legacy.Scripts.SupportOldLanguages w oknie dialogowym Advanced Settings.

  • Dokumentację API skryptowego można znaleźć tutaj: Obiekty API skryptowego. Należy pamiętać, że ta dokumentacja była ostatnio aktualizowana dla starszej wersji Altium Designer. Choć wiele zasad i podejść pozostaje bez zmian, interfejsy, obiekty, metody, właściwości i podobne elementy od tego czasu uległy zmianom, a dokumentacja nie obejmuje wszystkich elementów dostępnych w nowszych wersjach oprogramowania.

Moduł DelphiScript

Proste ćwiczenie z pisania skryptów można wykonać, tworząc najpierw nowy projekt i plik skryptu. Zakładając, że dla projektu i pliku skryptu ustawiono język DelphiScript, można wprowadzić prosty skrypt „Hello World”, jak pokazano poniżej.

Procedure ShowAMessage;
Var
 DefaultMessage;
Begin
 DefaultMessage := 'Hello World!';
 ShowMessage(DefaultMessage);
End;
Po wprowadzeniu zmian w dokumencie obok dokumentu skryptu pojawia się gwiazdka, a ikona w panelu Projects zmienia kolor na czerwony. Po edycji wiersza kodu skryptu na jego lewym marginesie pojawia się czerwony prostokąt wskazujący, że wiersz został zmieniony.

W procedurze znajduje się standardowa funkcja DelphiScript ShowMessage, która otwiera okno dialogowe z komunikatem „Hello World”, zdefiniowanym przez zmienną DefaultMessage.

Ponieważ wszystkie zmienne w skryptach są typu Variant, nie trzeba definiować typu zmiennej DefaultMessage w skrypcie.

Uruchamianie skryptu

Aby uruchomić jeden ze skryptów, wybierz File » Run Script z menu głównego, a następnie wybierz dostępną procedurę skryptu w oknie dialogowym Select Item To Run. Po uruchomieniu danej wersji otworzy się okno dialogowe z komunikatem.

Uruchamianie prostego modułu skryptu HelloWorld z menu File » Run Script.
Uruchamianie prostego modułu skryptu HelloWorld z menu File » Run Script.

Ten skrypt zawiera procedurę bez parametrów. W oknie dialogowym Select Item To Run pojawiają się tylko procedury lub funkcje, które don't mają parametrów. Procedury wymagające przekazania parametrów są wywoływane z poziomu skryptu (lub z innego skryptu), ale nie z systemu zewnętrznego, takiego jak okno dialogowe Select Item To Run, w którym parametry nie są przekazywane.

Skrypt można również uruchomić za pomocą polecenia Run edytora, dostępnego pod przyciskiem Run (), za pomocą skrótu klawiaturowego F9 lub przez wybranie Run » Run z menu głównego.

Oprócz samego polecenia Run menu rozwijane Run  oferuje szereg poleceń sterowania skryptem i debugowania.Oprócz samego polecenia Run menu rozwijane Run oferuje szereg poleceń sterowania skryptem i debugowania.

Po pierwszym wybraniu polecenia Run otworzy się okno dialogowe Select Item to Run, w którym można wskazać główną procedurę skryptu (w tym przypadku ShowAMessage). Po jej ustawieniu skrypt można łatwo wielokrotnie uruchamiać z edytora za pomocą polecenia Run . Użyj Run » Set Project Startup Procedure, aby zmienić to ustawienie na inną procedurę, lub zamknij i ponownie otwórz projekt skryptu, aby je wyczyścić.

Aby zatrzymać działający skrypt, użyj przycisku Stop (), wybierz Run » Stop z menu głównego lub użyj skrótu klawiaturowego Ctrl+F3.

Formularz DelphiScript

Rozbudowując utworzony powyżej projekt HelloWorld, można utworzyć podobny skrypt przy użyciu modułu formularza.

Formularz skryptu to okno dialogowe, które może zawierać różne elementy sterujące, takie jak przyciski, wielowierszowe pola tekstowe i pola list. Ma on procedury obsługi zdarzeń, które reagują na zdarzenia generowane przez elementy sterujące, na przykład kliknięcie przycisku.

Aby utworzyć nowy formularz skryptu, kliknij prawym przyciskiem myszy nazwę projektu w panelu Projects, wybierz opcję Add New to Project, a następnie Script Form. Skrypt można zapisać i zmienić jego nazwę za pomocą File » Save As w menu głównym.

Po utworzeniu nowego projektu skryptu dodaj do niego nowy skrypt. Po utworzeniu nowego projektu skryptu dodaj do niego nowy skrypt.

Formularz skryptu tworzy dwa pliki: plik *.dfm, który definiuje elementy okna formularza i uchwyty, oraz plik *.pas, który zawiera procedury obsługi zdarzeń formularza oraz procedury lub funkcje.

Aby wyświetlić i edytować wartości właściwości aktualnie wybranego formularza lub jego komponentów, otwórz panel Object Inspector. Panel Object Inspector służy do zmiany właściwości formularza i wstawiania kodu do procedur obsługi zdarzeń powiązanych z bieżącym formularzem.

Konfiguracja okna formularza skryptu i jego właściwości są widoczne w panelu Object Inspector.
Konfiguracja okna formularza skryptu i jego właściwości są widoczne w panelu Object Inspector.

Zwróć uwagę, że formularz skryptu udostępnia dwie karty u dołu dokumentu: Code i Form .

Karta Code zawiera procedury obsługi zdarzeń i procedury, jak pokazano powyżej, natomiast karta Form przedstawia okno dialogowe i zawiera elementy sterujące oraz powiązane z nimi procedury obsługi zdarzeń. Do przełączania między nimi używaj kart lub skrótu klawiaturowego F12.

W tym przewodniku terminy „okno dialogowe” i „formularz skryptu” są używane zamiennie. Termin „formularz” odnosi się do okna projektowanego w czasie rzeczywistym w systemie skryptowym, natomiast „okno dialogowe” to aktywny formularz w oprogramowaniu, który oczekuje na działanie użytkownika i wykonuje określoną czynność po kliknięciu przycisku lub elementu sterującego.

Panel Object Inspector umożliwia przeglądanie i edytowanie właściwości oraz zdarzeń komponentów w aktywnym formularzu skryptu. Kliknięcie pojedynczego komponentu na aktywnym formularzu skryptu w oknie edytora projektu spowoduje zaznaczenie go i wyświetlenie powiązanych z nim atrybutów w panelu Object Inspector. Można też użyć pola rozwijanego u góry panelu, aby wybrać komponent z listy wszystkich komponentów aktualnie umieszczonych na aktywnym formularzu. Lista obejmuje również sam formularz.

Użyj panelu Object Inspector, aby skonfigurować okno dialogowe formularza i jego działanie. 
Użyj panelu Object Inspector, aby skonfigurować okno dialogowe formularza i jego działanie.

Informacje są wyświetlane na dwóch kartach – Properties i Events:

  • Karta Properties panelu zawiera wszystkie atrybuty właściwości wybranego komponentu. Dokładna lista dostępnych atrybutów zależy od typu aktualnie przeglądanego komponentu. Właściwość to cecha obiektu, która wpływa na jego widoczne zachowanie lub działanie. Na przykład właściwość Visible (w Behavior podkategoria) określa, czy obiekt jest wyświetlany na formularzu skryptu, na którym został umieszczony. Właściwości komponentu można modyfikować zgodnie z potrzebami. Kliknij pole po prawej stronie właściwości i wpisz wartość bezpośrednio, przełącz pole wyboru lub wybierz pozycję z listy rozwijanej, zależnie od rodzaju właściwości.
  • Karta Events panelu zawiera listę wszystkich zdarzeń, na które może reagować aktualnie wybrany komponent. Również w tym przypadku dokładna lista dostępnych zdarzeń zależy od typu aktualnie przeglądanego komponentu. Gdy wystąpi zdarzenie, takie jak kliknięcie przycisku na formularzu, skrypt wykona odpowiednie działanie, pod warunkiem że w kodzie zdefiniowano procedurę obsługi tego zdarzenia. Taka procedura jest nazywana procedurą obsługi zdarzenia.

Szkielet procedury obsługi zdarzenia można dodać do kodu dokumentu skryptu z poziomu panelu Object Inspector. Wystarczy wybrać komponent, dla którego ma zostać zdefiniowane zdarzenie, wybrać typ zdarzenia, a następnie dwukrotnie kliknąć pole po jego prawej stronie. Dla zdarzenia tworzona jest nazwa, która służy do utworzenia nazwy procedury obsługi zdarzenia — FormName.EventName. Szkielet kodu procedury obsługi zdarzenia jest następnie dodawany do głównego kodu skryptu, którego karta staje się aktywna w obszarze projektowania. Następnie można uzupełnić procedurę obsługi zdarzenia kodem zapewniającym pożądaną reakcję, gdy zdarzenie wystąpi i zostanie wykryte przez działający skrypt.

Dolna sekcja panelu zawiera krótki opis aktualnie wybranej właściwości lub zdarzenia, o ile jest dostępny.

Można jednocześnie zaznaczyć i edytować wiele komponentów. W panelu zostaną wyświetlone właściwości i zdarzenia wspólne dla wszystkich zaznaczonych komponentów. Pola właściwości i zdarzeń, których wartości różnią się między komponentami, pozostaną puste. Wystarczy odpowiednio edytować właściwości lub zdarzenia — zmiany zostaną natychmiast zastosowane do każdego zaznaczonego komponentu. Można na przykład zmienić czcionkę tekstu na wielu przyciskach. Zaznacz wszystkie przyciski i odpowiednio zmień właściwości w kategorii Font — wszystkie przyciski zostaną zaktualizowane tak, aby ich tekst był wyświetlany tą samą czcionką.

W przypadku tego skryptu formularza zmień właściwości Caption formularza w panelu Object Inspector z HelloWorldForm na Hello World!. Te ciągi znaków odpowiadają ciągom użytym w przykładowym kodzie procedury obsługi zdarzenia i procedury przedstawionym poniżej.

Szczegółowe informacje na temat komponentów oraz ich właściwości, metod i zdarzeń można znaleźć na stronie Kategorie komponentów.

Dodawanie i konfigurowanie kontrolek

Po skonfigurowaniu podstawowego formularza można dodać do okna dialogowego potrzebne kontrolki, korzystając z panelu Tool Palette. Tool Palette, oparty na bibliotece Visual Component Library środowiska Delphi, to paleta komponentów oferująca szeroki wybór kontrolek okien uporządkowanych według kategorii komponentów (więcej informacji można znaleźć na stronach Komponenty graficzne skryptów i  Kategorie komponentów).

Sekcje panelu Tool Palette można rozwijać i zwijać za pomocą zakładek nagłówków obszarów.
Sekcje panelu Tool Palette można rozwijać i zwijać za pomocą zakładek nagłówków obszarów.

Użyj elementów sterujących w górnej części panelu, nazw kategorii oraz menu kontekstowego, aby skonfigurować sposób wyświetlania kontrolek w panelu: rozwijać i zwijać kategorie, zmieniać sposób prezentacji elementów palety itp.

Wszystkie komponenty używane w panelu dziedziczą po TComponent z biblioteki Borland Delphi Visual Component Library.

W wersji projektu „Hello World” z oknem dialogowym na formularzu znajdują się dwa przyciski — Display i Close. Kliknij TButton w obszarze Standard panelu Tool Palette.

Wykonaj tę czynność dwukrotnie, aby umieścić na formularzu dwa przyciski. Jeden przycisk będzie służył do wyświetlania komunikatu „Hello World!” w osobnym oknie dialogowym, a drugi — do zamykania głównego okna dialogowego.

Komponenty można umieszczać na formularzu skryptu, klikając dwukrotnie komponent w panelu Tool Palette lub klikając komponent raz, a następnie klikając na formularzu w miejscu, w którym ma się pojawić.

Ze wszystkimi komponentami w panelu są powiązane właściwości, metody i zdarzenia, przy czym:

  •  Property to cecha obiektu, która wpływa na jego widoczne zachowanie lub działanie. Na przykład właściwość Visible określa, czy obiekt jest widoczny na formularzu skryptu.
  •  Method to procedura, która jest zawsze powiązana z obiektem i definiuje jego zachowanie.
  •  Event to działanie lub wystąpienie określonej sytuacji wykrywane przez skrypt. W skrypcie programista pisze kod dla każdej procedury obsługi zdarzenia, której zadaniem jest przechwycenie określonego zdarzenia, takiego jak kliknięcie myszą.

Właściwości i zdarzenia komponentu można przeglądać i modyfikować po jego umieszczeniu za pomocą panelu Object Inspector.

Za pomocą panelu Object Inspector można zmienić domyślne nazwy i podpisy obu przycisków.

Ustaw nazwę pierwszego przycisku na bDisplay, a jego podpis na Display. Ustaw nazwę drugiego przycisku na bClose, a jego podpis na Close. Dzięki temu będą one zgodne z przedstawionym poniżej przykładowym kodem obsługi zdarzeń.

Wybierz komponent i edytuj jego właściwości w panelu Object Inspector.
Wybierz komponent i edytuj jego właściwości w panelu Object Inspector.

Pole komentarza w dolnej części panelu Object Inspector zawiera opis podświetlonej właściwości.

Kod obsługi zdarzeń można tworzyć, odwołując się bezpośrednio do kontrolek na formularzu. W tym przykładzie przycisk Display otworzy okno dialogowe ShowMessage nad istniejącym formularzem, a działanie przycisku Close spowoduje zamknięcie tego formularza.

Kod obsługi zdarzeń

Dwukrotne kliknięcie przycisku Display spowoduje otwarcie formularza w widoku kodu i utworzenie szkieletu kodu jego procedury obsługi zdarzenia. Można też wybrać przycisk, a następnie kartę Events w panelu Object Inspector. Dwukrotne kliknięcie zdarzenia OnClick w panelu otworzy widok kodu, tak jak opisano powyżej. W widoku kodu można dodać instrukcję ShowMessage do procedury obsługi zdarzenia, jak pokazano w poniższym listingu.

Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
 ShowMessage('Hello World!');
End;
Aby wyświetlić wcześniej zdefiniowane procedury obsługi zdarzeń dla dowolnego komponentu na formularzu skryptu, wybierz komponent, a następnie kliknij kartę Events w panelu Object Inspector.
Podobnie można zdefiniować procedurę obsługi zdarzenia przycisku Close, generując zdarzenie OnClick, które wykonuje instrukcję Close (form):
Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
 Close;
End;

Po zdefiniowaniu procedur obsługi zdarzeń należy dodać do skryptu procedurę, która będzie punktem wejścia podczas wywoływania okna dialogowego z poziomu oprogramowania. Dodaje się ją na końcu kodu skryptu.

Zwróć uwagę, że nazwa formularza to HelloWorldForm, a nazwa procedury to RunHelloWorld — nazwy formularzy w tym samym skrypcie muszą być unikatowe, aby uniknąć konfliktów nazw.

Procedure RunHelloWorld;
Begin
 HelloWorldForm.ShowModal;
End;

Skrypt można zapisać, a następnie uruchomić z menu głównego (File» Run Script), wybierając procedurę RunHelloWorld w pozycji HelloWorldDialog.

Alternatywnie procedurę można przypisać do polecenia/przycisku Run () za pośrednictwem menu Run » Set Startup Project Procedure.

Uruchamianie skryptu formularza HelloWorld, w którym przycisk Display wywołuje okno dialogowe ShowMessage.
Uruchamianie skryptu formularza HelloWorld, w którym przycisk Display wywołuje okno dialogowe ShowMessage.

Panel Object Inspector ułatwia zmianę właściwości i zdarzeń modułu formularza. Na przykład, aby zmienić położenie formularza w obszarze roboczym, użyj panelu do zmiany wartości poScreenCenter właściwości określającej położenie formularza. Po uruchomieniu skryptu okno dialogowe zostanie umieszczone na środku ekranu.

Referencyjną wersję skryptów projektu Hello World można znaleźć w folderze Scripts\Delphiscript Scripts\General w kolekcji skryptów do pobrania. Należy pamiętać, że są to starsze projekty referencyjne, które nie są aktualizowane.

Wywoływanie procedury

Jak wspomniano powyżej, każdy skrypt w projekcie (napisany w tym samym języku) ma dostęp do zmiennych globalnych i procedur, więc procedura w jednym skrypcie może wywołać inną procedurę w innym skrypcie tego samego projektu.

Można to zademonstrować za pomocą dodatkowego fragmentu kodu ShowAParametricMessage w przykładowym projekcie HelloWorld:

Procedure ShowAParametricMessage(S : String);
Var
    DefaultMessage;
Begin
    DefaultMessage := 'Hello World!';

    If S = '' Then ShowMessage(DefaultMessage)
              Else ShowMessage(S);
End;

Definiuje on zmienną tekstową „S”, którą można przekazać do procedury ShowAParametricMessage.

Przekazany ciąg znaków zostanie wyświetlony za pomocą funkcji okna dialogowego ShowMessage, natomiast prosta instrukcja If-Then-Else powoduje wyświetlenie domyślnego komunikatu „Hello World!”, jeśli ciąg jest pusty.

Aby zobaczyć, jak to działa, otwórz przykładowy projekt (HelloWorld.PrjScr) i dodaj wiersz wyróżniony na szaro do skryptu HelloWorldDialog (nie do skryptu HelloWorld), jak pokazano poniżej.

...
Procedure THelloWorldForm.bDisplayClick(Sender: TObject);
Begin
    Showmessage('Hello World!');
End;

Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
    ShowAParametricMessage('Goodbye World');
    close;
End;

Procedure RunHelloWorld;
Begin
    HelloWorldForm.ShowModal;
End;
...

Po uruchomieniu skryptu HelloWorldDialog i kliknięciu przycisku Close zostaje wywołana globalna procedura ShowAParametricMessage ze skryptu HelloWorld.

Procedura z parametrem w skrypcie HelloWorld jest wywoływana ze skryptu HelloWorldDialog.
Procedura z parametrem w skrypcie HelloWorld jest wywoływana ze skryptu HelloWorldDialog.

Wywołanie przekazuje do procedury ShowAParametricMessage ciąg znaków z komunikatem „Goodbye World”, dzięki czemu komunikat ten jest wyświetlany po kliknięciu przycisku Close, przed zamknięciem formularza.

Pokazane powyżej wywołanie skryptu wstawia określony komunikat do procedury zamykania formularza HelloWoldDialog.
Pokazane powyżej wywołanie skryptu wstawia określony komunikat do procedury zamykania formularza HelloWoldDialog.

Jeśli przekazany parametr tekstowy jest pusty, ShowAParametricMessage(''), wyświetlany jest domyślny komunikat „Hello World!”, zdefiniowany w procedurze ShowAParametricMessage.

Listę skrótów klawiaturowych usprawniających pisanie i debugowanie skryptów można znaleźć na stronie Narzędzia edytora skryptów.

Przeglądanie identyfikatorów skryptu za pomocą panelu Code Explorer

Panel Code Explorer przedstawia wizualne zestawienie wszystkich identyfikatorów (zmiennych, funkcji i procedur) używanych w aktywnym dokumencie skryptu.

Panel Code Explorer
Panel Code Explorer

Informacje o identyfikatorach wyświetlane w panelu są pogrupowane w następujących folderach najwyższego poziomu:

  • Procedures & Functions – zawiera wszystkie procedury i funkcje zadeklarowane w aktywnym dokumencie skryptu. Dla każdej procedury lub funkcji wyświetlane są również wszystkie przekazywane do niej parametry oraz jej zmienne lokalne.

  • Variables – zawiera wszystkie zmienne globalne zadeklarowane w aktywnym dokumencie skryptu.

Jeśli dla procedury lub funkcji zadeklarowano zmienne lokalne, zostaną one wyświetlone w podfolderze zmiennych danej procedury lub funkcji. Poszczególne typy identyfikatorów są oznaczone różnymi ikonami:

Procedura

Funkcja

Parametr procedury/funkcji

Zmienna (lokalna lub globalna)

Dwukrotne kliknięcie pozycji w panelu (lub jej zaznaczenie i naciśnięcie klawisza Enter) powoduje przejście do odpowiedniego fragmentu kodu w obszarze projektowym.

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