Korzystanie z komponentów formularza VBScript

Używanie komponentów w formularzach VBScript

Chociaż formularze i komponenty są oparte na bibliotece Visual Component Library (VCL) firmy Embarcadero Delphi™ , to podczas używania VBScript nadal korzysta się z opartego na Delphi edytora formularzy w Altium Designer Tool Palette, aby umieszczać kontrolki na formularzu. Ponadto procedury obsługi zdarzeń są generowane, a kod jest pisany w języku VBScript — niezależnie od delphijskich korzeni formularzy/komponentów w Altium Designer.

Przegląd komponentów

System skryptów obsługuje dwa typy komponentów: wizualne i niewizualne. Komponenty wizualne służą do budowy interfejsu użytkownika, a komponenty niewizualne są używane do różnych zadań, takich jak funkcje udostępniane przez komponenty Timer, OpenDialog i MainMenu. Na przykład niewizualny komponent Timer służy do uruchamiania określonego kodu w zaplanowanych odstępach czasu i nigdy nie jest widoczny dla użytkownika. Komponenty Button, Edit i Memo są komponentami wizualnymi — są widoczne dla użytkownika.

Oba typy komponentów są widoczne na etapie projektowania, ale komponenty niewizualne nie są widoczne w czasie działania (runtime). Komponenty z panelu Tool Palette są obiektowe i mają trzy następujące elementy:

• Właściwości
• Zdarzenia
• Metody

property to cecha obiektu, która wpływa albo na widoczne zachowanie, albo na operacje tego obiektu. Na przykład właściwość Visible określa, czy ten obiekt może być widoczny w formularzu skryptu.

event to działanie lub zdarzenie wykryte przez skrypt. W skrypcie programista pisze kod dla każdej procedury obsługi zdarzeń, która ma przechwycić konkretne zdarzenie, takie jak kliknięcie myszą.

method to procedura, która jest zawsze powiązana z obiektem i definiuje zachowanie tego obiektu.

Wszystkie formularze skryptów mają jeden lub więcej komponentów. Komponenty zwykle wyświetlają informacje lub pozwalają użytkownikowi wykonać działanie. Na przykład Label służy do wyświetlania statycznego tekstu, pole Edit umożliwia użytkownikowi wprowadzenie danych, a Button może służyć do inicjowania działań.

Na formularzu można umieścić dowolną kombinację komponentów, umożliwiając użytkownikowi interakcję z nimi podczas działania skryptu (runtime). Zadaniem programisty skryptu jest zdecydowanie, co ma się stać, gdy użytkownik kliknie przycisk lub zmieni tekst w polu Edit.

System skryptów udostępnia zestaw komponentów do tworzenia prostych lub złożonych interfejsów użytkownika dla skryptów. Wszystkie komponenty, które można umieścić na formularzu, znajdują się w panelu Tool Palette panel.

Aby umieścić komponent na formularzu, znajdź jego ikonę w panelu Tool Palette i kliknij ją dwukrotnie. Ta czynność umieszcza komponent na aktywnym formularzu w domyślnej pozycji, z domyślną szerokością i wysokością. Wizualna reprezentacja większości komponentów jest określana przez zestaw powiązanych z nimi właściwości.

Umieszczony komponent, w domyślnej pozycji i z domyślnymi wymiarami, można zmienić rozmiar lub położenie za pomocą myszy albo poprzez panel Object Inspector. Po upuszczeniu komponentu na formularz system skryptów automatycznie generuje podstawowy kod wymagany do użycia komponentu i aktualizuje formularz skryptu. Aby komponent na formularzu działał, pozostaje jedynie ustawić właściwości, umieścić kod w procedurach obsługi zdarzeń i w razie potrzeby używać metod.

Projektowanie formularzy skryptów

Formularz skryptu jest projektowany tak, aby umożliwiać interakcję z użytkownikiem w środowisku Altium Designer. Projektowanie formularzy skryptów stanowi rdzeń rozwoju wizualnego w Altium Designer.

Każdy komponent umieszczony na formularzu skryptu oraz każda ustawiona właściwość są zapisywane w pliku opisującym formularz (plik *.dfm) i mają związek z powiązanym kodem skryptu (plik *.vbs). Zatem dla każdego formularza skryptu istnieje plik *.vbs oraz odpowiadający mu plik *.dfm.

Podczas pracy z formularzem skryptu i jego komponentami ich właściwości można przeglądać i modyfikować w panelu Object Inspector. Można zaznaczyć więcej niż jeden komponent, klikając je z wciśniętym klawiszem Shift, albo przeciągając prostokąt zaznaczenia wokół komponentów na formularzu skryptu. Formularz skryptu ma tytuł mapowany na właściwość Caption w panelu Object Inspector.

Tworzenie nowego formularza skryptu

Mając otwarty projekt skryptu, kliknij prawym przyciskiem myszy projekt w panelu Projects i wybierz z menu kontekstowego pozycje Add New to Project, a następnie VB Script Form. Zostanie utworzony nowy formularz skryptu z domyślną nazwą EditScript1.vbs . Alternatywnie, w projekcie *.PrjPCB wybierz polecenie File » New » Script Files » VB Script Form.

Wyświetlanie formularza skryptu

Skrypt musi zawierać procedurę, która wyświetla formularz podczas wykonywania formularza skryptu w Altium Designer. W ramach tej procedury wywoływana jest dla formularza metoda ShowModal. Właściwość formularza Visible musi być ustawiona na false (odznaczona), aby metoda ShowModal formularza skryptu działała poprawnie.

Przykład ShowModal

Sub RunDialog
  DialogForm.ShowModal
End Sub

Powyższy przykład ShowModal to prosty sposób wyświetlenia formularza skryptu, gdy z poziomu skryptu wywoływane jest okno dialogowe RunDialog. Zwróć uwagę, że wartości można przypisać komponentom obiektu DialogForm przed wywołaniem metody DialogForm.ShowModal.

Przykład ModalResult pokazany poniżej jest bardziej złożony. Jego późniejsze metody są używane dla przycisków w formularzu skryptu. Metody skryptu powodują zakończenie działania okna dialogowego, gdy użytkownik kliknie przycisk OK lub Cancel, co spowoduje zwrócenie odpowiednio mrOk lub mrCancel przez metodę ShowModal.

ModalResult Example

sub bOKButtonClick(Sender)
  ModalResult := mrOK
end sub
 
sub bCancelButtonClick(Sender)
  ModalResult := mrCancel
end sub
 
sub RunShowModalExample
  'Form Visible property must be false for ShowModal to work properly.
  If Form.ShowModal = mrOk     Then ShowMessage("mrOk")
  If Form.ShowModal = mrCancel Then ShowMessage("mrCancel")
end sub

To samo, co powyżej, można osiągnąć, ustawiając wartość ModalResult na mrOk dla przycisku OK oraz na mrCancel dla przycisku Cancel w ich procedurach obsługi zdarzeń. Gdy użytkownik kliknie którykolwiek z przycisków, okno dialogowe zostanie zamknięte. Nie ma potrzeby wywoływania metody Close, ponieważ gdy metoda ModalResult zostanie ustawiona, silnik skryptów automatycznie zamyka formularz skryptu.

Zwróć uwagę, że aby ustawić ModalResult formularza na anulowanie, gdy użytkownik naciśnie klawisz Esc, ustaw właściwość Cancel przycisku Cancel na true (zaznaczoną) w panelu Object Inspector albo wstaw Sender.Cancel := True w procedurze obsługi zdarzenia CancelButtonClick przycisku formularza.

Akceptowanie danych wejściowych użytkownika

Jednym z często używanych komponentów, które mogą przyjmować dane od użytkownika, jest komponent EditBox. Ten komponent EditBox ma pole tekstowe, w którym użytkownik może wpisać ciąg znaków. Istnieją także inne komponenty, które mogą przyjmować tekst, takie jak komponent edycji z maską (masked edit), czyli komponent edycji z maską wprowadzania w polu tekstowym. Maska kontroluje (filtruje) dane wejściowe i jest przechowywana w ciągu parametrów.

Poniższy przykład ilustruje, co dzieje się, gdy użytkownik kliknie przycisk po wpisaniu tekstu w polu edycji. Zwróć uwagę, że jeśli użytkownik nie wpisał żadnego tekstu do komponentu edycji, procedura obsługi zdarzenia odpowie komunikatem ostrzegawczym

sub TScriptForm.ButtonClick(Sender)
  If Edit1.Text = "" Then
  ShowMessage("Warning - empty input!")
  Exit
  End
  ' do something else for the input
End sub

Zwróć uwagę, że użytkownik może przenosić fokus wprowadzania na formularzu za pomocą klawisza Tab lub klikając inną kontrolkę formularza.

Reagowanie na zdarzenia

Gdy formularz lub komponent zostanie wybrany przez użytkownika, Altium Designer wysyła komunikat do systemu skryptów, który reaguje na powiadomienie o zdarzeniu, wywołując odpowiednią metodę obsługi zdarzenia.

Pisanie procedur obsługi zdarzeń

Skrypt może wymagać reagowania na zdarzenia, które mogą wystąpić dla komponentu w czasie działania. Zdarzenie jest łącznikiem pomiędzy wystąpieniem w Altium Designer, takim jak kliknięcie przycisku, a fragmentem kodu, który na to wystąpienie reaguje. Kod reagujący to procedura obsługi zdarzenia (event handler), która modyfikuje wartości właściwości i wywołuje metody.

Oprócz właściwości każdy komponent ma zestaw nazw zdarzeń. Programista skryptu decyduje, jak skrypt będzie reagował na działania użytkownika w Altium Designer. Na przykład, gdy użytkownik kliknie przycisk na formularzu, Altium Designer wysyła komunikat do skryptu, a skrypt reaguje na to nowe zdarzenie — jeśli dla przycisku określono zdarzenie OnClick, zostanie ono wykonane.

Wszystkie takie komponenty mają również zdarzenie związane z uzyskaniem i utratą fokusu. Jednak jeśli kod dla OnEnter i OnExit nie jest określony (OnEnter — kontrolka ma fokus; OnExit — kontrolka traci fokus), zdarzenie zostanie zignorowane przez skrypt.

Właściwości komponentu

Aby zobaczyć listę właściwości komponentu, zaznacz komponent i aktywuj kartę Properties w panelu Object Inspector.

Zdarzenia komponentu

Aby zobaczyć listę zdarzeń, na które komponent może reagować, zaznacz komponent i aktywuj kartę Events w panelu Object Inspector. Aby utworzyć procedurę obsługi zdarzenia, na które komponent ma reagować, wybierz odpowiednie zdarzenie i kliknij dwukrotnie jego nazwę.

Na przykład wybierz komponent Button1 z panelu Tool Palette, upuść go na formularz skryptu i kliknij dwukrotnie obok nazwy zdarzenia OnClick. System skryptów przeniesie fokus do edytora kodu, gdzie zostanie utworzony szkielet kodu dla zdarzenia OnClick. Jeśli przycisk ma metodę Close w swojej procedurze obsługi zdarzenia CloseClick, to po kliknięciu przycisku jego procedura obsługi przechwytuje zdarzenie kliknięcia, a kod wewnątrz procedury obsługi jest wykonywany. Oznacza to, że metoda Close zamyka formularz skryptu.

Podsumowując, procedurę obsługi zdarzenia tworzy się w skrypcie, zaznaczając komponent na formularzu lub w panelu Object Inspector, a następnie klikając dwukrotnie po prawej stronie wybranego zdarzenia (np. OnClick) na karcie Events Inspektora — w skrypcie pojawi się odpowiedni szkielet kodu.

Alternatywnie, po dwukrotnym kliknięciu przycisku system skryptów doda procedurę obsługi dla zdarzenia OnClick. Inne typy komponentów będą miały zupełnie inne domyślne działania.

Metody komponentu

Zobacz Component Reference, aby uzyskać listę metod dla komponentu, oraz odwołaj się do dokumentacji Embarcadero Delphi, aby uzyskać bardziej szczegółowe informacje.

Tworzenie komponentów w czasie wykonywania

Komponenty można bezpośrednio tworzyć i usuwać w skrypcie. Zwykle nie ma potrzeby przekazywania uchwytu formularza, ponieważ formularz skryptu zajmuje się tym automatycznie — zamiast tego przekaż parametr Nil do konstruktora komponentu.

Na przykład okna dialogowe Open i Save można tworzyć i usuwać (klasy TOpenDialog i TSaveDialog, jako część Delphi RTL).