Formularze i komponenty

Przegląd komponentów graficznych

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 komponenty Timer, OpenDialog i MainMenu.

• Komponent niewizualny Timer może 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.

Oba typy komponentów są widoczne na etapie projektowania, ale komponenty niewizualne nie są widoczne w czasie działania. 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 na formularzu skryptu.

Event to działanie lub zdarzenie wykryte przez skrypt. W skrypcie programista pisze kod dla każdego programu obsługi zdarzeń, zaprojektowanego do przechwycenia konkretnego zdarzenia, takiego jak kliknięcie myszą.

Method to procedura, która jest zawsze powiązana z obiektem i definiuje zachowanie 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 służy do umożliwienia użytkownikowi wprowadzenia danych, a Button może służyć do inicjowania działań.

Na formularzu można umieścić dowolną kombinację komponentów, a podczas działania skryptu użytkownik może wchodzić w interakcję z dowolnym komponentem na formularzu. Zadaniem programisty jest zdecydować, co się stanie, gdy użytkownik kliknie przycisk lub zmieni tekst w polu Edit.

System skryptów udostępnia szereg komponentów, które można wykorzystać do tworzenia złożonych interfejsów użytkownika dla skryptów. Aby umieścić komponent na formularzu, znajdź jego ikonę w panelu Tool Palette panel i kliknij ją dwukrotnie. Ta czynność umieszcza komponent na aktywnym formularzu. Reprezentacja wizualna większości komponentów jest ustawiana za pomocą ich właściwości. Komponent jest początkowo umieszczany w domyślnej pozycji na formularzu, ale w razie potrzeby można go przestawiać (przeciągać) i zmieniać jego rozmiar (rozciągać). Możesz też później zmienić rozmiar i położenie, używając panelu Object Inspector .

Gdy komponent zostanie upuszczony na formularz, system skryptów automatycznie generuje kod niezbędny do użycia komponentu i aktualizuje formularz skryptu. Aby komponent na formularzu działał, wystarczy ustawić właściwości oraz zaimplementować kod obsługi zdarzeń, wykorzystując odpowiednie metody.

Projektowanie formularzy skryptów

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

W praktyce wszystkie komponenty są umieszczane na formularzu skryptu, a każda ustawiona właściwość jest zapisywana w pliku opisującym formularz (plik *.DFM), który jest powiązany z odpowiadającym mu kodem skryptu (plik *.PAS). Dla każdego formularza skryptu istnieje plik .PAS oraz odpowiadający mu plik .DFM.

Podczas pracy z formularzem skryptu i jego komponentami wszystkie właściwości elementów można przeglądać i modyfikować w panelu Object Inspector. Możesz 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. Formularz skryptu ma tytuł (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, kliknij pozycję Add New to Project w menu kontekstowym i wybierz pozycję Delphi Script Form. Otworzy się nowy formularz skryptu z domyślną nazwą EditScript1.pas.

Wyświetlanie formularza skryptu

Skrypt musi mieć procedurę, która wyświetla formularz podczas wykonywania formularza skryptu. W ramach tej procedury można wywołać dla formularza metodę ShowModal. Właściwość Visible formularza musi mieć wartość false, aby metoda ShowModal formularza skryptu działała poprawnie.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

Przykład ShowModal to bardzo proste podejście do wyświetlania formularza skryptu, gdy wywoływana jest procedura RunDialog. Zwróć uwagę, że wartości można przypisać komponentom obiektu DialogForm przed wywołaniem metody DialogForm.ShowModal.

Przykład właściwości ModalResult pokazany poniżej jest nieco bardziej złożony. Następujące metody w skrypcie są używane dla przycisków na formularzu skryptu. Metody powodują zakończenie okna dialogowego, gdy użytkownik kliknie przycisk OK lub Cancel, co zwraca odpowiednio mrOk lub mrCancel z metody ShowModal.

ModalResult Example:

Procedure TForm.OKButtonClick(Sender: TObject);
Begin
  ModalResult := mrOK;
End;

Procedure TForm.CancelButtonClick(Sender: TObject);
Begin
  ModalResult := mrCancel;
End;

Procedure RunShowModalExample;
Begin
  // Form's Visible property must be false for ShowModal to work correctly.
  If Form.ShowModal = mrOk Then ShowMessage('mrOk');
  If Form.ShowModal = mrCancel Then ShowMessage('mrCancel');
End;

Gdy użytkownik kliknie którykolwiek przycisk na tym formularzu skryptu, okno dialogowe zostaje zamknięte. Nie ma potrzeby wywoływania metody Close, ponieważ po ustawieniu metody ModalResult silnik skryptów zamyka formularz skryptu automatycznie.

Zwróć uwagę, że jeśli chcesz ustawić ModalResult formularza na Cancel, gdy użytkownik naciśnie klawisz Esc , użyj panelu Object Inspector , aby ustawić właściwość Cancel przycisku Cancel na True, albo wstaw Sender.Cancel := True w procedurze obsługi zdarzenia CancelButtonClick przycisku formularza.

Przyjmowanie danych wejściowych od użytkownika

Jednym z popularnych komponentów, które mogą przyjmować dane wejściowe od użytkownika, jest komponent TEdit. Ten komponent ma pole, w którym użytkownik może wpisać ciąg znaków. Zwróć uwagę, że istnieją też inne komponenty Delphi, takie jak TMaskEdit, czyli komponent edycji z maską wejściową zapisaną w ciągu znaków — kontroluje ona lub filtruje dane wejściowe.

Poniższy przykład ilustruje proces, gdy użytkownik kliknie przycisk po wpisaniu czegoś w polu edycji. Jeśli użytkownik nie wpisał nic w komponencie edycji (puste), procedura obsługi zdarzenia odpowiada komunikatem ostrzegawczym.

Procedure TScriptForm.ButtonClick(Sender : TObject);
Begin
  If Edit1.Text = '' Then
  Begin
    ShowMessage('Warning - empty input!');
    Exit;
  End;
  // do something else for the input
End;

Zwróć uwagę, że użytkownik może zmienić fokus wejściowy okna dialogowego za pomocą klawisza Tab lub klikając inną kontrolkę w formularzu.

Reagowanie na zdarzenia

Gdy przycisk na formularzu lub komponent zostanie kliknięty, system skryptów reaguje, odbierając powiadomienie o zdarzeniu z Altium Designer i wywołując odpowiednią metodę obsługi zdarzenia.

See also
Projekt HelloWorld z folderu Scripts\DelphiScript Scripts\General\ kolekcji scripts collection.
Przykładowy skrypt ShowModal z folderu Scripts\DelphiScript Scripts\General\ kolekcji scripts collection.

Pisanie procedur obsługi zdarzeń

Każdy komponent w skrypcie formularza ma zestaw nazw zdarzeń, które są używane przez procedury obsługi zdarzeń skryptu, określające, jak skrypt zareaguje 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.

Kod reagujący na zdarzenia jest zwykle zawarty w procedurach obsługi zdarzeń DelphiScript, a wszystkie komponenty mają zestaw zdarzeń, na które mogą reagować. Na przykład wszystkie klikalne komponenty mają zdarzenie OnClick, które jest wyzwalane, gdy użytkownik kliknie komponent. Wszystkie takie komponenty mają też zdarzenie związane z uzyskaniem i utratą fokusu. Jednak jeśli kod dla OnEnter i OnExit nie został określony (OnEnter - kontrolka uzyskała fokus; OnExit - kontrolka utraciła fokus), zdarzenie zostanie zignorowane przez skrypt.

Podsumowując, zdarzenie jest łącznikiem mię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. Ten kod modyfikuje wartości właściwości i wywołuje metody.

Właściwości komponentu

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

Zdarzenia komponentu

Aby zobaczyć listę zdarzeń, na które komponent może reagować, zaznacz komponent i otwórz kartę Events w panelu Object Inspector. Aby utworzyć procedurę obsługi zdarzenia, wybierz zdarzenie, na które komponent ma reagować, i kliknij dwukrotnie nazwę zdarzenia — system skryptów automatycznie wstawi szkielet kodu procedury obsługi zdarzenia.

Na przykład wybierz komponent TButton z panelu Tool Palette i upuść go na formularz skryptu, a następnie kliknij dwukrotnie obok nazwy zdarzenia OnClick w panelu Object Inspector . System skryptów przeniesie fokus do edytora kodu i zostanie utworzony szkielet kodu dla zdarzenia OnClick.

Jeśli na przykład przycisk ma metodę Close w procedurze obsługi zdarzenia CloseClick, to po kliknięciu przycisku procedura obsługi zdarzenia przycisku przechwyci zdarzenie OnClick, powodując wykonanie kodu wewnątrz procedury obsługi zdarzenia. W konsekwencji metoda Close zamyka formularz skryptu.

Podsumowując: wybierz komponent przycisku na formularzu albo za pomocą panelu Object Inspector, wybierz stronę Events i kliknij dwukrotnie po prawej stronie zdarzenia OnClick, a w skrypcie pojawi się nowa procedura obsługi zdarzenia. Alternatywnie kliknij dwukrotnie sam przycisk, a system skryptów doda procedurę obsługi dla tego zdarzenia OnClick. Zwróć uwagę, że inne typy komponentów będą miały inne działania domyślne.

Metody komponentu

Aby zobaczyć listę metod komponentu, zapoznaj się z dokumentem Component Reference.

Upuszczanie komponentów na formularz skryptu

Aby używać komponentów z panelu Tool Palette panel w skrypcie, przed upuszczeniem komponentów na formularz musi istnieć formularz skryptu. Zwykle, gdy komponenty są upuszczane na formularz skryptu, tych obiektów nie trzeba tworzyć ani niszczyć — formularz skryptu robi to automatycznie.

System skryptowy automatycznie generuje też kod niezbędny do użycia komponentu i aktualizuje formularz skryptu. Potem pozostaje już tylko ustawienie właściwości, umieszczenie kodu w procedurach obsługi zdarzeń oraz użycie wymaganych metod, aby zaimplementować działający formularz skryptu.

Tworzenie komponentów w skrypcie

Komponenty można bezpośrednio tworzyć lub niszczyć w skrypcie, przekazując parametr Nil do Constructor komponentu. Zwykle nie trzeba przekazywać uchwytu formularza, ponieważ formularz skryptu automatycznie się tym zajmuje. Na przykład można tworzyć i niszczyć okna dialogowe Open i Save (klasy TOpenDialog i TSaveDialog z Embarcadero Delphi RTL).

Dostosowywanie formularzy skryptu

Najważniejsze kwestie dotyczące dostosowywania formularzy skryptu to:

• Aby wymusić, by formularz pozostawał na wierzchu innych otwartych paneli, ustaw właściwość FormStyle na fsStayOnTop.
• Aby zdefiniować domyślne zachowanie formularza, ustaw FormKind na jedną z następujących wartości: fkNone, fkNormal, fkServerPanel lub fkModal.
• Jeśli fkModal jest zamknięty, formularz będzie modalny — tzn. będzie czekał na dane wejściowe użytkownika przed kontynuowaniem, np. na zamknięcie formularza. Jeśli fkServerPanel, formularz zostanie pokazany jako panel serwera. Jeśli fkNormal, formularz działa jak zwykły formularz niemodalny.
• Aby usunąć domyślne paski przewijania formularza, zmień wartości właściwości HorzScrollBar i VertScrollBar.
• Aby uczynić formularz ramką MDI lub elementem podrzędnym MDI, użyj właściwości FormStyle.
• Aby zmienić styl obramowania formularza, użyj właściwości BorderIcons i BorderStyle (wyniki są widoczne w czasie działania).
• Aby zmienić ikonę zminimalizowanego formularza, użyj właściwości Icon.
• Aby określić początkową pozycję formularza w oknie aplikacji, użyj właściwości Position.
• Aby określić początkowy stan formularza (np. zminimalizowany, zmaksymalizowany lub normalny), użyj właściwości WindowState.
• Aby zdefiniować obszar roboczy formularza w czasie działania, użyj właściwości ClientHeight i ClientWidth (zwróć uwagę, że ClientHeight i ClientWidth reprezentują obszar wewnątrz obramowania formularza; Height i Width reprezentują cały obszar formularza).
• Aby określić, która kontrolka ma początkowy fokus w formularzu w czasie działania, użyj właściwości ActiveControl.
• Aby przekazywać wszystkie zdarzenia klawiatury do formularza, niezależnie od wybranej kontrolki, użyj właściwości KeyPreview.
• Aby wskazać konkretne menu, jeśli formularz zawiera więcej niż jedno menu, użyj właściwości Menu.

Odświeżanie formularzy skryptu i komponentów

Gdy powierzchnia formularza skryptu staje się nieaktualna, np. kontrolki nie są aktualizowane ani odmalowywane, mogą wyglądać na „zamrożone” lub uszkodzone — może to wynikać z intensywnego przetwarzania w tle wykonywanego przez ten skrypt.

Metoda Update formularza skryptu oraz wiele komponentów skryptowych z panelu Tool Palette udostępniają sposób na odświeżenie zawartości graficznej formularza lub konkretnych kontrolek. Wiersze zawierające metodę Update są w poniższym przykładzie podświetlone na szaro.

StatusBar component and its Update method Example:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
Begin
 If OpenPictureDialog1.Execute then
 Begin
 XPProgressBar1.Position := 0;
 XStatusBar1.SimpleText  := '  Loading...';
 XStatusBar1.Update;
 
 // loading a monochrome bitmap only
 Image1.Picture.LoadFromFile(OpenPictureDialog1.FileName);
 
 // Check if image is monochrome, otherwise prompt a warning
 If Image1.Picture.Bitmap.PixelFormat <> pf1bit Then
 Begin
 ShowWarning('The image is not a monochrome!');
 Close;
 End;
 
 lImageSize.Caption := IntToStr(Image1.Picture.Width) + ' x ' +
 IntToStr(Image1.Picture.Height) + ' mils';
 
 convertbutton.Enabled  := True;
 LoadButton.Enabled     := False;
 XStatusBar1.SimpleText := '  Ready...';
 XStatusBar1.Update;
 End;
End;

Powyższy fragment kodu pochodzi z projektu skryptu PCB Logo Creator, który można znaleźć w folderze Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator w downloadable kolekcji skryptów.