Writing Scripts

Pisanie skryptów

Istnieje szereg kluczowych pojęć i terminów związanych z pisaniem skryptów:

• Procesy to ciągi poleceń, których można używać do wykonywania komend w skryptach.
• Komponenty to wizualne elementy sterujące na panelu Tool Palette panel, które można przeciągać i upuszczać na formularz skryptu, aby manipulować projektem.
• Komponent umieszczony na formularzu skryptu ma metody, właściwości i zdarzenia.
• Object Interfaces to specjalne interfejsy obiektów, których można używać do wyodrębniania i modyfikowania danych w dokumentach projektowych z poziomu skryptów.

Języki skryptowe

Domyślny język skryptowy jest ustawiony na DelphiScript (*.pas). Sam silnik skryptowy jest napisany w Embarcadero Delphi, a panel Tool Palette jest oparty na VCL (Visual Component Library) Delphi.

Jednostka DelphiScript

Szybkie i podstawowe ćwiczenie skryptowe można wykonać, tworząc najpierw nowy projekt i plik skryptu. Zakładając, że projekt i plik skryptu są ustawione na język DelphiScript, można wprowadzić prosty skrypt „Hello World”, jak poniżej.

Procedure ShowAMessage;
Var
 DefaultMessage;
Begin
 DefaultMessage := 'Hello World!';
 ShowMessage(DefaultMessage);
End;

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

Uruchamianie skryptu

Aby uruchomić jeden ze skryptów, wybierz File » Run Script z menu głównego, a następnie wskaż dostępną procedurę skryptu w oknie dialogowym Select Item To Run. Po uruchomieniu wersji zostanie otwarte okno dialogowe wyświetlające komunikat.

Uruchamianie prostej jednostki skryptu HelloWorld z menu File » Run Script.

Skrypt można również wykonać za pomocą polecenia Run w edytorze, dostępnego przez przycisk Run (), klawisz skrótu F9 lub przez wybranie Run » Run z menu głównego.

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

Gdy polecenie Run zostanie wybrane po raz pierwszy, otworzy się okno dialogowe Select Item to Run, umożliwiające wskazanie głównej procedury skryptu (ShowAMessage w tym przypadku). Po ustawieniu skrypt można łatwo uruchamiać wielokrotnie z edytora, używając polecenia Run . Użyj Run » Set Project Startup Procedure, aby zmienić ustawienie na inną procedurę, albo zamknij i ponownie otwórz projekt skryptu, aby wyczyścić to ustawienie.

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

Rozwijając projekt HelloWorld utworzony powyżej, można stworzyć podobny skrypt z użyciem jednostki formularza.

Formularz skryptu to okno dialogowe, które może zawierać różne kontrolki, takie jak przyciski, pola memo i listy. Ma procedury obsługi zdarzeń, które reagują, gdy kontrolka wygeneruje zdarzenie, na przykład po kliknięciu przycisku.

Aby utworzyć nowy formularz skryptu, kliknij prawym przyciskiem nazwę projektu w panelu Projects panel, wybierz opcję Add New to Project i wskaż Script Form. Skrypt można zapisać i zmienić jego nazwę, używając File » Save As z menu głównego.

Po utworzeniu nowego projektu skryptu dodaj do niego nowy skrypt.

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

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

Zwróć uwagę, że formularz skryptu oferuje na dole dokumentu dwie zakładki: Code oraz Form .

Zakładka Code zawiera procedury obsługi zdarzeń i procedury, jak pokazano powyżej, natomiast zakładka Form reprezentuje okno dialogowe i zawiera kontrolki oraz powiązane procedury obsługi zdarzeń. Użyj zakładek lub skrótu klawiszowego F12, aby przełączać się między nimi.

Panel Object Inspector umożliwia przeglądanie i edycję 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 jego zaznaczenie i wyświetlenie powiązanych atrybutów w panelu Object Inspector. Alternatywnie użyj listy rozwijanej u góry panelu, aby wybrać z listy wszystkie komponenty aktualnie umieszczone na aktywnym formularzu. Sam formularz również jest uwzględniony.

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

Informacje są wyświetlane na dwóch zakładkach – Properties oraz Events:

• Zakładka Properties panelu zawiera listę wszystkich atrybutów właściwości dla wybranego komponentu. Dokładna lista dostępnych atrybutów zależy od konkretnego typu komponentu aktualnie analizowanego. 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 podkategorii Behavior ) określa, czy obiekt jest wyświetlany na formularzu skryptu, na którym został umieszczony. Właściwości komponentu można modyfikować według potrzeb. Kliknij w 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 przypadku.
• Zakładka Events panelu udostępnia listę wszystkich zdarzeń, na które może reagować aktualnie wybrany komponent. Ponownie, dokładna lista dostępnych zdarzeń zależy od konkretnego typu komponentu aktualnie analizowanego. Gdy wystąpi zdarzenie, na przykład kliknięcie przycisku na formularzu, skrypt wykona odpowiednie działanie — pod warunkiem, że w kodzie zdefiniowano procedurę obsługi tego zdarzenia. Taka procedura nazywana jest procedurą obsługi zdarzeń (event handler).

Szkielet procedury obsługi zdarzenia można dodać do kodu dokumentu skryptu z poziomu panelu Object Inspector. Wystarczy wybrać komponent, dla którego chcesz zdefiniować zdarzenie, wybrać konkretny typ zdarzenia, a następnie dwukrotnie kliknąć w polu po prawej stronie zdarzenia. Tworzona jest nazwa zdarzenia i używana w definicji nazwy procedury obsługi zdarzenia — FormName.EventName. Następnie kod szkieletowy procedury obsługi zdarzenia jest dodawany do głównego kodu skryptu, który staje się aktywną zakładką w obszarze projektowania. „Wypełnienie” procedury obsługi zdarzenia można potem zakodować tak, aby zapewnić pożądaną reakcję, gdy zdarzenie wystąpi i zostanie wykryte przez uruchomiony skrypt.

Dolna część panelu zawiera opis podsumowujący aktualnie wybraną właściwość lub zdarzenie, jeśli jest dostępny.

Dla tego skryptu formularza zmień właściwości Caption formularza w panelu Object Inspector z HelloWorldForm na Hello World!. Te ciągi odpowiadają tym użytym w przykładowym kodzie procedury obsługi zdarzenia i procedury pokazanym dalej poniżej.

Dodawanie i konfigurowanie kontrolek

Po skonfigurowaniu podstawowego formularza można w razie potrzeby dodać do okna dialogowego kontrolki, korzystając z panelu Tool Palette. Panel Tool Palette, oparty na bibliotece Visual Component Library (VCL) środowiska Delphi, jest paletą komponentów oferującą szeroki wybór kontrolek okienkowych, uporządkowanych w kategorie komponentów (więcej informacji na stronach  Scripting Graphical Components oraz Component Categories).

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

Użyj kontrolek u góry panelu, nazw kategorii oraz menu kontekstowego (prawy przycisk myszy), aby skonfigurować sposób prezentacji kontrolek w panelu: rozwijanie/zwijanie kategorii, zmiana sposobu wyświetlania elementów palety itp.

Dla wersji dialogowej projektu „Hello World” na formularzu znajdują się dwa przyciski – Display oraz Close. Kliknij TButton w obszarze Standard panelu Tool Palette.

Wykonaj to dwukrotnie, aby umieścić na formularzu dwa przyciski. Jeden przycisk posłuży do wyświetlenia komunikatu „Hello World!” w osobnym oknie dialogowym, a drugi do zamknięcia głównego okna dialogowego.

Wszystkie komponenty w panelu mają powiązane właściwości (Properties), metody (Methods) i zdarzenia (Events), gdzie:

• Właściwość 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 może być widoczny na formularzu skryptu.
• Metoda Method to procedura zawsze powiązana z obiektem, definiująca zachowanie tego obiektu.
• Zdarzenie Event to akcja lub wystąpienie wykryte przez skrypt. W skrypcie programista pisze kod dla każdego programu obsługi zdarzeń (Event Handler), który ma przechwycić konkretne zdarzenie, takie jak kliknięcie myszą.

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

Korzystając z panelu Object Inspector, można zmienić domyślne nazwy i podpisy (captions) 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. Ma to na celu dopasowanie do przykładowego kodu obsługi zdarzeń przedstawionego poniżej.

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

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

Kod obsługi zdarzeń

Dwukrotne kliknięcie przycisku Display otworzy formularz w widoku Code i utworzy szkielet kodu dla jego procedury obsługi zdarzenia. Alternatywnie zaznacz przycisk, a następnie kartę Events w panelu Object Inspector. Dwukrotne kliknięcie zdarzenia OnClick w panelu otworzy widok kodu jak wyżej. W widoku Code do procedury obsługi zdarzenia można dodać instrukcję ShowMessage, jak pokazano w zestawieniu poniżej.

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

Procedure THelloWorldForm.bCloseClick(Sender: TObject);
Begin
 Close;
End;

Po zdefiniowaniu procedur obsługi zdarzeń potrzebna jest w skrypcie procedura, która będzie używana jako punkt startowy 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 — ważne jest, aby w tym samym skrypcie nazwy formularzy były 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)), uruchamiając pozycję procedury RunHelloWorld w ramach wpisu HelloWorldDialog.

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

Uruchomienie skryptu formularza HelloWorld, w którym przycisk Display aktywuje okno dialogowe ShowMessage.

Panel Object Inspector ułatwia zmianę właściwości i zdarzeń jednostki formularza. Na przykład, aby zmienić położenie formularza w obszarze roboczym, użyj panelu, aby zmodyfikować wartość poScreenCenter dla właściwości położenia formularza. Okno dialogowe zostanie teraz umieszczone na środku ekranu pulpitu podczas uruchamiania skryptu.

Wywoływanie procedury

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

Można to zademonstrować dodatkową sekcją 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;

Ustanawia to zmienną typu string „S”, którą można przekazać do procedury ShowAParametricMessage.

Przekazany ciąg zostanie wyświetlony przy użyciu funkcji okna dialogowego ShowMessage, natomiast prosta metoda If-Then-Else spowoduje wyświetlenie domyślnego komunikatu „Hello World!”, jeśli ciąg jest pusty.

Aby zobaczyć to w działaniu, otwórz przykładowy projekt (HelloWorld.PrjScr) i dodaj szarą, podświetloną linię 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;
...

Gdy skrypt HelloWorldDialog zostanie uruchomiony i kliknięty zostanie przycisk Close , globalna procedura ShowAParametricMessage zostanie wywołana ze skryptu HelloWorld.

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

Wywołanie przekazuje ciąg komunikatu „Goodbye World” do procedury ShowAParametricMessage, więc komunikat ten jest wyświetlany po kliknięciu przycisku Close, przed zamknięciem formularza.

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

Jeśli przekazany parametr typu string jest pusty, ShowAParametricMessage(''), zostanie wyświetlony domyślny komunikat „Hello World!”, zgodnie z definicją w procedurze ShowAParametricMessage.

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

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

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/funkcji wyszczególnione są także parametry przekazywane do procedury/funkcji oraz zmienne lokalne.

  

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

  

Jeśli dla procedury/funkcji zadeklarowano zmienne lokalne, pojawią się one w podfolderze zmiennych (variables) pod daną procedurą/funkcją. Do rozróżnienia poszczególnych identyfikatorów używane są unikatowe ikony:

Dwukrotne kliknięcie wpisu w panelu (lub zaznaczenie go i naciśnięcie klawisza Enter) spowoduje przejście do odpowiadającego mu fragmentu kodu w przestrzeni projektowej.