Scripting Graphical Components

Diese Referenz beschreibt die für das Scripting unterstützten grafischen Komponenten sowie deren wichtigste Eigenschaften und Methoden.

Die visuellen Formularkomponenten, die in Altium Designer-Skripten verwendet werden können, stammen größtenteils aus Embarcaderos Visual Component Library (VCL), einer Sammlung definierter visueller Komponenten zur Entwicklung von Windows-Anwendungen mit den Sprachen Delphi und C++.

Als visuelle Klassenbibliothek entwickelt, leiten sich die VCL-Klassen in einer linearen Objekthierarchie vom TComponent Objekt ab (das selbst vom Wurzelobjekt TObject abstammt). Daher erbt eine allgemeine Skriptkomponente, wie etwa das TButton Objekt, die Eigenschaften, Methoden und Ereignisse ihrer übergeordneten Objekte. In diesem Fall lautet die Klassenhierarchie: TObject → TPersistent → TComponent → TControl → TWinControl → TButtonControl → TButton.

Beachten Sie, dass die Komponenten, die vom TControl Objekt abstammen, im Allgemeinen visuelle Komponenten (Steuerelemente) sind, während allgemeine Komponenten, die von TWinControl abstammen, meist Wrapper um die Windows-API sind.

► Siehe Embarcadero RAD Studio VCL für einen Überblick über die VCL-Architektur und -Komponenten.

Beim Erstellen eines Formulars im Altium Designer Script Editor wird auf die Komponenten über das Tool Palette Panel zugegriffen. Script Forms besitzen eine zugehörige *.DFM Datei, die Details zur Konfiguration des Formulars, zu den Positionen seiner Komponenten und zu weiteren Attributen enthält – die Datei befindet sich im Host-Ordner des Skriptprojekts. Altium Designer ermöglicht die Verwendung der Komponenten beim Entwurf von Script Forms sowohl mit DelphiScript als auch mit VBScript.

Das Tool Palette Panel enthält kategorisierte visuelle Steuerelemente, die auf ein Script Form gezogen werden können.

Das Tool Palette panel enthält kategorisierte Komponentenauswahlen, die auf einem Script Form platziert werden können. Die verfügbaren Komponenten sind im Tool Palette Panel in aufklappbaren Abschnitten zusammengestellt und in Standard, Additional, Win32, System, Dialogs, Altium Standard und Instrument Controls kategorisiert.

Die in der Palette verfügbaren Komponenten (oder „Steuerelemente“) sind bei Verwendung auf einem Skriptformular visuelle Komponenten, was bedeutet, dass ein Benutzer ein Steuerelement sehen und möglicherweise zur Laufzeit mit ihm interagieren kann. Alle Steuerelemente besitzen Eigenschaften, Methoden und Ereignisse, die Aspekte ihres Erscheinungsbilds beschreiben, etwa die Positionseigenschaft des Steuerelements, Methoden zum Zeichnen oder Verschieben des Steuerelements sowie Ereignisse, die auf Benutzeraktionen reagieren.

Die Eigenschaften und Ereignisse sind im Object Inspector panel für die aktuell ausgewählte Formularkomponente verfügbar, einschließlich des Formulars selbst. Die Methoden sind Prozeduren und Funktionen, die von dieser Komponente unterstützt werden.

Überblick über Script Forms

Script Forms

Ein Script Form ist die primäre Benutzeroberfläche in Skripten, obwohl es auch andere Formulare wie Dialogfelder, sekundäre Fenster usw. gibt. Um ein neues Script Form zu erstellen, wählen Sie bei geöffnetem Projekt in Altium Designer File » New » Script » Script Form oder klicken Sie mit der rechten Maustaste auf den Namen des Skriptprojekts und wählen Sie Add New to Project » Script Form. Wenn die Sprache VBScript aktiviert ist, steht der Befehl sowohl für VB Script als auch für Delphi Script zur Verfügung.

Ein neues Script Form erscheint standardmäßig mit dem Formularnamen Form1, der über die Eigenschaft Name (unter Misc) im Object Inspector Panel geändert werden kann. Namen von Script Forms sollten innerhalb eines Projekts eindeutig sein.

Beim Entwerfen eines Script Form öffnen Sie das Object Inspector Panel über die Schaltfläche Script in der unteren Statusleiste.

Ein leeres Formular ist im Grunde ein visuelles Fenster, dem Steuerelemente hinzugefügt werden können. Ein Dialog und ein Panel sind unterschiedliche Formulartypen, und standardmäßig umfasst ein Formular Standard-Fensterfunktionen wie:

• Steuerelemente
• Schaltflächen zum Minimieren und Maximieren
• Titelleiste
• Größenänderung durch Ziehen des Rahmens

Diese Funktionen können zusammen mit jeder anderen verfügbaren Formulareigenschaft zur Entwurfszeit über das Object Inspector Panel geändert werden. Da ein Script Form eine VCL-Komponente ist, besitzt es die folgenden drei Elemente:

• Properties – Die Merkmale eines Objekts, die sein sichtbares Verhalten oder seine Operationen beeinflussen. Beispielsweise bestimmt die Eigenschaft Visible , ob ein Objekt auf einem Skriptformular sichtbar ist.
• Events – Aktionen oder Ereignisse, die vom Skript erkannt werden. Ein Skript muss Code für jeden Ereignishandler enthalten, der dafür ausgelegt ist, ein bestimmtes Ereignis wie einen Mausklick zu erfassen.
• Methods – Skriptprozeduren, die Objekten zugeordnet sind (in diesem Fall Komponentenobjekten) und deren Verhalten definieren.

► Siehe Writing Scripts für eine grundlegende Anleitung zur Entwicklung eines formularbasierten Skripts.

Formulareigenschaften, Methoden und Ereignisse

Die Steuerelemente des Tool Palette Panels basieren auf Embarcaderos Visual Component Library (VCL). Vollständige Details zu den Methoden, Eigenschaften und Ereignissen der Form-Komponente (TForm) finden Sie in der Embarcadero-VCL-Dokumentation.

► Siehe die Embarcadero TForm reference

TForm-Eigenschaften

Die verfügbaren Eigenschaften für das Komponentenobjekt TForm, das Basis-Skriptformular, können auf folgende Weise angezeigt werden:

• Über das Object Inspector Panel – Klicken Sie in der Formularansicht des Editors (Registerkarte Form ausgewählt) in den Hauptbereich des Formulars selbst und wählen Sie die Registerkarte Object Inspector's Properties .

Beachten Sie, dass im Panel nur visuelle Komponentenobjekte angezeigt werden. Nicht visuelle Objekte, die als im Hintergrund arbeitende Steuerelemente fungieren, werden auf dem Formular nicht angezeigt.

• Über die Code-Completion-Funktion – In der Codeansicht des Editors (Registerkarte Code ausgewählt) zeigt das kontextsensitive Code-Completion-Fenster alle Codeoptionen für einen Objektnamen an.

Geben Sie für das Form-Objekt TForm. ein (beachten Sie den Punkt), um das Fenster zu aktivieren. Grenzen Sie die Suche ein, indem Sie die ersten Buchstaben einer gewünschten Eigenschaft eingeben – beachten Sie, dass sowohl Eigenschaften als auch Methoden angezeigt werden.

• Aus der Embarcadero-Referenzdokumentation auf der Seite TForm Properties reference page.

TForm-Methoden

Die verfügbaren Methoden für das Komponentenobjekt TForm können auf folgende Weise angezeigt werden:

• Verwenden Sie die Code-Completion-Funktion – Geben Sie in der Codeansicht des Editors einen Komponentennamen gefolgt von einem Punkt ein. Das Code-Completion-Fenster wird geöffnet und zeigt die Codemethoden (und Eigenschaften) für einen Objektnamen an. Beachten Sie, dass das Codefenster auch manuell mit den Tastenkombinationen Crtl+Space aktiviert werden kann.

• Siehe die Embarcadero-Referenzdokumentation auf der Seite TForm Methods reference page. Beachten Sie, dass dort alle geerbten Methoden angezeigt werden, diese Option jedoch deaktiviert werden kann.

TForm-Ereignisse

Die verfügbaren Ereignisse für das Komponentenobjekt TForm können auf folgende Weise angezeigt werden:

• Das Object Inspector Panel – Klicken Sie in der Formularansicht des Editors in den Hauptbereich des Formulars selbst und wählen Sie die Registerkarte Events des Object Inspector.

• Die Embarcadero-Referenzdokumentation auf der Seite TFrom Events reference page.

Komponenteneigenschaften, Ereignisse und Methoden

Die Steuerelemente des Tool Palette Panels basieren auf Embarcaderos Visual Component Library (VCL). Vollständige Details zu den Methoden, Eigenschaften und Ereignissen für die meisten Komponenten finden Sie in den Komponentenkategorien der Embarcadero-VCL-Dokumentation. Einige Komponententypen im Tool Palette, insbesondere die Altium Instrument Controls, sind exklusiv für Altium Designer und in der Embarcadero-Referenzdokumentation nicht enthalten.

► Siehe den Embarcadero VCL Components Categories Index

Komponenteneigenschaften

So zeigen Sie eine Liste der Eigenschaften einer Komponente an:

• Wählen Sie eine Komponente auf dem Formular aus und aktivieren Sie die Registerkarte Properties im Object Inspector Panel – wie oben für das Komponentenobjekt TForm gezeigt.
• Wählen Sie den Link Properties (oben) auf der entsprechenden Komponentenreferenzseite in der Embarcadero reference documentation. Im Fall des Steuerelements TButton wählen Sie beispielsweise die Kategorie Standard Component, die Seite TButton und anschließend die Ansicht Properties.

Komponentenereignisse

So zeigen Sie eine Liste der Ereignisse an, auf die eine Komponente reagieren kann:

• Wählen Sie eine Komponente auf dem Formular aus und aktivieren Sie die Registerkarte Events im Object Inspector Panel – wie oben für das Komponentenobjekt TForm gezeigt.
• Wählen Sie eine geeignete Komponentenreferenzseite und dann deren Link Events in der Embarcadero reference documentation. Beachten Sie, dass dies als Leitfaden für die verfügbaren Ereignisse einer Komponente nützlich ist und möglicherweise nicht vollständig mit den für die Scripting-Komponenten von Altium Designer verfügbaren Ereignissen übereinstimmt.

Um eine Ereignisbehandlungsprozedur zu erstellen, wählen Sie auf der Registerkarte Object Inspector Events das Ereignis aus, auf das die Komponente reagieren soll, und doppelklicken Sie in das Eingabefeld des Ereignisses. Die Ereignishandler-Prozedur, benannt nach der Komponente und der Ereignisaktion, wird dann automatisch im Skript erzeugt. Wenn das Ereignis im Object Inspector Panel umbenannt wird, wird die entsprechende Codeprozedur entsprechend umbenannt.

Komponentenmethoden

Dies umfasst Referenzen für die folgenden Kategorien von Steuerelementobjekten.

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

Diese Kategorien fassen größtenteils Typen visueller Formularsteuerelemente zusammen, die auf standardmäßigen VCL-Komponenten vom Delphi-Typ basieren. Die Kategorien Altium Standard und Instrument Controls bilden die Ausnahme, da sie Komponenten anbieten, die exklusiv für das Scripting-System von Altium Designer sind.

► Siehe die Tool Palette Component Categories.

Arbeiten mit Formularen und Komponenten

Anpassen von Script Forms

• Um dafür zu sorgen, dass ein Formular beispielsweise über anderen geöffneten Panels bleibt, setzen Sie die Eigenschaft FormStyle auf fsStayOnTop.
• Um das Standardverhalten eines Formulars festzulegen, setzen Sie FormKind auf einen der folgenden Werte: fkNone, fkNormal, fkServerPanel oder fkModal.
  • Wenn fkModal ausgewählt ist, ist das Formular modal. Das bedeutet, dass das Formular auf Benutzereingaben wartet, bevor Aktionen wie das Schließen des Formulars fortgesetzt werden.
  • Wenn fkServerPanel ausgewählt ist, wird das Formular als Server-Panel angezeigt.
  • Wenn fkNormal ausgewählt ist, verhält sich das Formular wie ein normales nicht-modales Formular.
• Um die Bildlaufleisten eines Formulars hinzuzufügen bzw. zu entfernen, ändern Sie den Wert der Eigenschaften HorzScrollBar und VertScrollBar.
• Um das Formular als MDI-Frame (Multiple Document Interface) oder untergeordnetes Fenster festzulegen, verwenden Sie die Eigenschaft FormStyle.
• Um den Rahmenstil eines Formulars zu ändern, verwenden Sie die Eigenschaften BorderIcons und BorderStyle. (Die Ergebnisse sind zur Laufzeit sichtbar.)
• Um das Symbol für das minimierte Formular zu ändern, verwenden Sie die Eigenschaft Icon.
• Um die Anfangsposition eines Formulars im Anwendungsfenster festzulegen, verwenden Sie die Eigenschaft Position.
• Um den Anfangszustand eines Formulars festzulegen (zum Beispiel minimiert, maximiert oder normal), verwenden Sie die Eigenschaft WindowState.
• Um den Arbeitsbereich eines Formulars zur Laufzeit festzulegen, verwenden Sie die Eigenschaften ClientHeight und ClientWidth. Beachten Sie, dass ClientHeight und ClientWidth den Bereich innerhalb des Formularrahmens darstellen, während Height und Width den gesamten Bereich des Formulars darstellen.
• Um festzulegen, welches Steuerelement zur Laufzeit den anfänglichen Fokus in einem Formular erhält, verwenden Sie die Eigenschaft ActiveControl, um aus den verfügbaren Komponenten auszuwählen.
• Um alle Tastaturereignisse an ein Formular weiterzuleiten, unabhängig vom ausgewählten Steuerelement, verwenden Sie die Eigenschaft KeyPreview.
• Um ein bestimmtes Menü festzulegen, wenn ein Formular mehr als ein Menü enthält, verwenden Sie die Eigenschaft Menu.

Formulare und Komponenten aktualisieren

In einigen Fällen kann die visuelle Darstellung eines Skriptformulars veraltet sein, zum Beispiel wenn eine intensive Hintergrundverarbeitung durch ein Skript dazu führt, dass die Steuerelemente nicht aktualisiert oder neu gezeichnet werden und eingefroren oder beschädigt erscheinen.

Die Methode Update des Skriptformulars bietet eine programmgesteuerte Möglichkeit, den grafischen Inhalt eines Formulars oder bestimmter Steuerelemente zu aktualisieren. Im folgenden Codebeispiel sind die Codezeilen der Methode Update grau hervorgehoben.

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;

Siehe das Skriptprojekt PCB Logo Creator im Ordner Scripts\Delphiscript Scripts\PCB\PCB Logo Creator der herunterladbaren Skriptsammlung .