Skryptowanie komponentów graficznych

To opracowanie przedstawia obsługiwane graficzne komponenty do skryptowania oraz ich główne właściwości i metody.

Wizualne komponenty formularzy dostępne do użycia w skryptach Altium Designer w większości pochodzą z biblioteki Visual Component Library (VCL) firmy Embarcadero, która jest zbiorem zdefiniowanych komponentów wizualnych do tworzenia aplikacji Windows w językach Delphi i C++.

VCL, opracowana jako wizualna biblioteka klas, ma klasy dziedziczące od obiektu TComponent (który sam jest potomkiem obiektu bazowego TObject) w liniowej hierarchii obiektów. Dlatego typowy komponent skryptu, taki jak obiekt TButton, dziedziczy właściwości, metody i zdarzenia po obiektach nadrzędnych. W tym przypadku hierarchia klas wygląda następująco: TObject → TPersistent → TComponent → TControl → TWinControl → TButtonControl → TButton.

Zwróć uwagę, że komponenty dziedziczące po obiekcie TControl są zazwyczaj komponentami wizualnymi (kontrolkami), natomiast typowe komponenty dziedziczące po TWinControl to najczęściej „opakowania” (wrappers) dla Windows API.

► Zobacz Embarcadero RAD Studio VCL, aby zapoznać się z architekturą VCL i komponentami.

Podczas tworzenia formularza (Form) w Altium Designer Script Editor komponenty są dostępne z panelu Tool Palette. Formularze skryptów mają powiązany plik *.DFM, który zawiera szczegóły konfiguracji formularza, położenia komponentów i inne atrybuty – plik można znaleźć w folderze hosta projektu skryptu. Altium Designer pozwala używać komponentów zarówno w DelphiScript, jak i VBScript podczas projektowania Script Forms.

Panel Tool Palette zawiera skategoryzowane kontrolki wizualne, które można przeciągać na formularz skryptu.

Panel Tool Palette panel zawiera skategoryzowane zestawy komponentów, które można umieszczać na Script Form. Dostępne komponenty są zebrane w rozwijanych sekcjach w panelu Tool Palette, skategoryzowanych jako Standard, Additional, Win32, System, Dialogs, Altium Standard oraz Instrument Controls.

Komponenty (czyli „kontrolki”) dostępne w palecie są komponentami wizualnymi, gdy używa się ich na formularzu skryptu, co oznacza, że użytkownik widzi kontrolkę i może wchodzić z nią w interakcję w czasie działania. Wszystkie kontrolki mają właściwości, metody i zdarzenia opisujące aspekty ich wyglądu, takie jak właściwość położenia kontrolki, metody rysowania lub przesuwania kontrolki oraz zdarzenia reagujące na działania użytkownika.

Właściwości i zdarzenia są dostępne w panelu Object Inspector panel dla aktualnie zaznaczonego komponentu formularza, w tym samego formularza. Metody to procedury i funkcje obsługiwane przez dany komponent.

Przegląd Script Forms

Script Forms

Script Form jest podstawowym interfejsem użytkownika w skryptach, choć istnieją też inne formy, takie jak okna dialogowe, okna pomocnicze itd. Aby utworzyć nowy Script Form, mając otwarty projekt w Altium Designer, wybierz File » New » Script » Script Form lub kliknij prawym przyciskiem nazwę projektu skryptu i wybierz Add New to Project » Script Form. Jeśli włączony jest język VBScript, polecenie jest dostępne zarówno dla VB Script, jak i Delphi Script.

Pojawi się nowy Script Form z domyślną nazwą formularza Form1, którą można zmienić poprzez właściwość Name (w sekcji Misc) w panelu Object Inspector. Nazwy formularzy skryptów powinny być unikalne w projekcie.

Podczas projektowania Script Form otwórz panel Object Inspector przyciskiem Script w dolnym pasku stanu.

Pusty formularz to w zasadzie wizualne okno, do którego można dodawać kontrolki. Okno dialogowe i panel to inne typy formularzy, a domyślnie formularz zawiera standardową funkcjonalność okna, taką jak:

• Kontrolki
• Przyciski Minimalizuj i Maksymalizuj
• Pasek tytułu
• Możliwość zmiany rozmiaru przez przeciąganie krawędzi

Te funkcje, wraz z innymi dostępnymi właściwościami formularza, można zmieniać na etapie projektowania za pomocą panelu Object Inspector. Ponieważ Script Form jest komponentem VCL, ma następujące trzy elementy:

• Properties – Cechy obiektu wpływające 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.
• Events – Akcje lub zdarzenia wykrywane przez skrypt. Skrypt musi zawierać kod dla każdego programu obsługi zdarzeń (Event handler), który jest zaprojektowany do przechwytywania konkretnego zdarzenia, takiego jak kliknięcie myszą.
• Methods – Procedury skryptu powiązane z obiektami (w tym przypadku obiektami komponentów) i definiujące ich zachowanie.

► Zobacz Writing Scripts, aby uzyskać podstawowy przewodnik po tworzeniu skryptu opartego na formularzu.

Właściwości, metody i zdarzenia formularza

Kontrolki panelu Tool Palette są oparte na bibliotece Embarcadero Visual Component Library (VCL). Aby uzyskać pełne informacje o metodach, właściwościach i zdarzeniach komponentu Form (TForm), zapoznaj się z dokumentacją Embarcadero VCL.

► Zobacz Embarcadero TForm reference

Właściwości TForm

Dostępne właściwości dla obiektu komponentu TForm (bazowego formularza skryptu) można przeglądać na następujące sposoby:

• Przez panel Object Inspector – w widoku formularza edytora (z zaznaczoną kartą Form ) kliknij w obszar samego formularza i wybierz kartę Object Inspector's Properties .

Zwróć uwagę, że w panelu będą widoczne tylko obiekty komponentów wizualnych. Obiekty niewizualne, które działają „w tle” jako kontrolki, nie są wyświetlane na formularzu.

• Korzystając z funkcji Code Completion – w widoku kodu edytora (z zaznaczoną kartą Code ) okno kontekstowe Code Completion wyświetli wszystkie opcje kodu dla nazwy obiektu.

Dla obiektu Form wpisz TForm. (zwróć uwagę na kropkę), aby aktywować okno. Zawęź wyszukiwanie, wpisując pierwsze litery żądanej właściwości – pamiętaj, że wyświetlane są zarówno właściwości, jak i metody.

• Z dokumentacji referencyjnej Embarcadero na stronie TForm Properties reference page.

Metody TForm

Dostępne metody dla obiektu komponentu TForm można przeglądać na następujące sposoby:

• Użyj funkcji Code Completion – w widoku kodu edytora wpisz nazwę komponentu, a następnie kropkę. Otworzy się okno Code Completion, które wyświetli metody (i właściwości) dla nazwy obiektu. Zwróć uwagę, że okno podpowiedzi można też ręcznie aktywować skrótami klawiszowymi Crtl+Space.

• Skorzystaj z dokumentacji referencyjnej Embarcadero na stronie TForm Methods reference page. Uwaga: pokazuje ona wszystkie metody dziedziczone, jednak tę opcję można odznaczyć.

Zdarzenia TForm

Dostępne zdarzenia dla obiektu komponentu TForm można przeglądać na następujące sposoby:

• Panel Object Inspector – w widoku formularza edytora kliknij w obszar samego formularza i wybierz kartę Events w Object Inspector.

• Dokumentacja referencyjna Embarcadero na stronie TFrom Events reference page.

Właściwości, zdarzenia i metody komponentów

Kontrolki panelu Tool Palette są oparte na bibliotece Embarcadero Visual Component Library (VCL). Aby uzyskać pełne informacje o metodach, właściwościach i zdarzeniach dla większości komponentów, odwołaj się do kategorii komponentów w dokumentacji Embarcadero VCL. Niektóre typy komponentów w Tool Palette, w szczególności Altium Instrument Controls, są dostępne wyłącznie w Altium Designer i nie są ujęte w dokumentacji referencyjnej Embarcadero.

► Zobacz Embarcadero VCL Components Categories Index

Właściwości komponentów

Aby zobaczyć listę właściwości komponentu:

• Wybierz komponent na formularzu i aktywuj kartę Properties w panelu Object Inspector – jak pokazano powyżej dla obiektu komponentu TForm.
• Wybierz odnośnik Properties (na górze) na odpowiedniej stronie referencyjnej komponentu w Embarcadero reference documentation. Na przykład w przypadku kontrolki TButton wybierz kategorię Standard Component, stronę TButton, a następnie widok Properties.

Zdarzenia komponentów

Aby zobaczyć listę zdarzeń, na które komponent może reagować:

• Wybierz komponent na formularzu i aktywuj kartę Events w panelu Object Inspector – jak pokazano powyżej dla obiektu komponentu TForm.
• Wybierz odpowiednią stronę referencyjną komponentu, a następnie jej odnośnik Events w Embarcadero reference documentation. Uwaga: jest to przydatne jako przewodnik po dostępnych zdarzeniach dla komponentu i może nie w pełni odpowiadać zdarzeniom dostępnym dla komponentów skryptowych Altium Designer.

Aby utworzyć procedurę obsługi zdarzenia, wybierz zdarzenie, na które komponent ma reagować, na karcie Object Inspector Events i kliknij dwukrotnie w polu wpisu zdarzenia. Procedura obsługi zdarzenia, nazwana na podstawie komponentu i akcji zdarzenia, zostanie następnie automatycznie wygenerowana w skrypcie. Jeśli zdarzenie zostanie zmienione w panelu Object Inspector, odpowiadająca mu procedura w kodzie zostanie odpowiednio przemianowana.

Metody komponentów

Obejmuje to odwołania dla następujących kategorii obiektów kontrolek.

• Standard
• Additional
• Win32
• System
• Dialog
• Altium Standard
• Instrument Controls

W większości kategorie te grupują typy wizualnych kontrolek formularzy oparte na standardowych komponentach VCL w stylu Delphi. Wyjątkiem są kategorie Altium Standard i Instrument Controls, ponieważ oferują komponenty dostępne wyłącznie w systemie skryptowym Altium Designer.

► Zobacz Tool Palette Component Categories.

Praca z formularzami i komponentami

Dostosowywanie Script Forms

• Aby 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 wybrano fkModal, formularz będzie formularzem modalnym. Oznacza to formularz oczekujący na dane wejściowe użytkownika przed kontynuowaniem działań, takich jak zamknięcie formularza.
  • Jeśli wybrano fkServerPanel, formularz zostanie wyświetlony jako panel serwera.
  • Jeśli wybrano fkNormal, formularz działa jak zwykły formularz niemodalny.
• Aby dodać/usunąć paski przewijania formularza, zmień wartości właściwości HorzScrollBar i VertScrollBar.
• Aby uczynić formularz ramką lub elementem podrzędnym MDI (Multiple Document Interface), 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ę dla 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 (na przykład: 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, natomiast 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 wybrać spośród dostępnych komponentów.
• 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 i komponentów

W niektórych przypadkach wygląd formularza skryptu może stać się nieaktualny, na przykład gdy intensywne przetwarzanie w tle wykonywane przez skrypt powoduje, że kontrolki nie są aktualizowane ani odrysowywane i wyglądają na zawieszone lub uszkodzone.

Metoda Update formularza skryptu zapewnia programowy sposób odświeżenia zawartości graficznej formularza lub określonych kontrolek. W poniższym przykładzie kodu wiersze kodu metody Update są wyróżnione na szaro.

Using the Update method to refresh the Status Bar:

Procedure TConverterForm.loadbuttonClick(Sender: TObject);
Var
   I, J : Integer;
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
            For J := 0 to Image1.Picture.Height – 1 Do
                For I := 0 to Image1.Picture.Height – 1 Do
            Begin
                If Image1.Canvas.Pixels[I,J] <> clWhite Then
                    Image1.Canvas.Pixels[I,J] := clBlack;
            End;
        End;

        ScalingFactorChange(Nil);

        convertbutton.Enabled  := True;
        LoadButton.Enabled     := False;
        XStatusBar1.SimpleText := '  Ready...';
        XStatusBar1.Update;
    End;
End;

Zapoznaj się z projektem skryptu PCB Logo Creator znajdującym się w folderze Scripts\Delphiscript Scripts\PCB\PCB Logo Creator w do pobrania kolekcji skryptów.