Forms & Components

Überblick über grafische Komponenten

Das Skriptsystem verarbeitet zwei Arten von Komponenten: visuelle und nicht visuelle Komponenten.

Visuelle Komponenten werden zum Aufbau der Benutzeroberfläche verwendet, und die nicht visuellen Komponenten werden für verschiedene Aufgaben eingesetzt, wie z. B. die Komponenten Timer, OpenDialog und MainMenu.

• Die nicht visuelle Komponente Timer kann verwendet werden, um bestimmten Code in geplanten Intervallen zu aktivieren, und sie ist für den Benutzer niemals sichtbar.
• Die Komponenten Button, Edit und Memo sind visuelle Komponenten.

Beide Komponententypen erscheinen zur Entwurfszeit, aber nicht visuelle Komponenten sind zur Laufzeit nicht sichtbar. Komponenten aus dem Bereich Tool Palette sind objektorientiert und besitzen die folgenden drei Elemente:

• Eigenschaften
• Ereignisse
• Methoden

Eine Property ist ein Merkmal eines Objekts, das entweder das sichtbare Verhalten oder die Operationen dieses Objekts beeinflusst. Beispielsweise bestimmt die Eigenschaft Visible, ob dieses Objekt in einem Skriptformular sichtbar ist oder nicht.

Ein Event ist eine vom Skript erkannte Aktion oder ein erkanntes Ereignis. In einem Skript schreibt der Programmierer Code für jeden Ereignishandler, der dafür ausgelegt ist, ein bestimmtes Ereignis wie einen Mausklick zu erfassen.

Eine Method ist eine Prozedur, die immer einem Objekt zugeordnet ist und das Verhalten eines Objekts definiert.

Alle Skriptformulare haben eine oder mehrere Komponenten. Komponenten zeigen normalerweise Informationen an oder ermöglichen dem Benutzer, eine Aktion auszuführen. Beispielsweise wird ein Label verwendet, um statischen Text anzuzeigen, ein Edit-Feld wird verwendet, damit ein Benutzer Daten eingeben kann, und ein Button kann verwendet werden, um Aktionen auszulösen.

Beliebige Kombinationen von Komponenten können auf einem Formular platziert werden, und während das Skript ausgeführt wird, kann ein Benutzer mit jeder Komponente auf einem Formular interagieren. Es ist die Aufgabe des Programmierers zu entscheiden, was geschieht, wenn ein Benutzer auf eine Schaltfläche klickt oder den Text in einem Edit-Feld ändert.

Das Skriptsystem stellt eine Reihe von Komponenten bereit, mit denen komplexe Benutzeroberflächen für Skripte erstellt werden können. Um eine Komponente auf einem Formular zu platzieren, suchen Sie ihr Symbol im Tool Palette panel und doppelklicken Sie darauf. Dadurch wird eine Komponente auf dem aktiven Formular platziert. Die visuelle Darstellung der meisten Komponenten wird über ihre Eigenschaften festgelegt. Eine Komponente wird zunächst an einer Standardposition auf dem Formular platziert, kann aber nach Bedarf neu positioniert (gezogen) und in der Größe geändert (gestreckt) werden. Sie können Größe und Position später auch über das Object Inspector panel ändern.

Wenn eine Komponente auf ein Formular abgelegt wird, erzeugt das Skriptsystem automatisch den erforderlichen Code zur Verwendung der Komponente und aktualisiert das Skriptformular. Es müssen nur die Eigenschaften festgelegt und der Code des Ereignishandlers implementiert werden, um die gewünschten Methoden zu verwenden und die Komponente auf dem Formular funktionsfähig zu machen.

Entwerfen von Skriptformularen

Ein Skriptformular ist dafür ausgelegt, innerhalb der Umgebung mit dem Benutzer zu interagieren. Das Entwerfen von Skriptformularen ist der Kern der visuellen Entwicklung.

In der Praxis werden alle Komponenten auf einem Skriptformular platziert, und jede festgelegte Eigenschaft wird in einer Datei gespeichert, die das Formular beschreibt (eine *.DFM-Datei), welche in Beziehung zum zugehörigen Skriptcode steht (die *.PAS-Datei). Für jedes Skriptformular gibt es die Datei .PAS und die entsprechende Datei .DFM.

Bei der Arbeit mit einem Skriptformular und seinen Komponenten können alle Eigenschaften der Elemente über das Object Inspector panel geprüft und geändert werden. Sie können mehr als eine Komponente auswählen, indem Sie bei gedrückter Umschalttaste auf die Komponenten klicken oder ein Auswahlrechteck um die Komponenten auf dem Formular ziehen. Ein Skriptformular hat einen Titel (die Eigenschaft Caption im Object Inspector panel).

Erstellen eines neuen Skriptformulars

Wenn ein Skriptprojekt geöffnet ist, klicken Sie im Bereich Projects mit der rechten Maustaste auf ein Projekt, klicken Sie im eingeblendeten Kontextmenü auf den Eintrag Add New to Project und wählen Sie einen Eintrag Delphi Script Form. Ein neues Skriptformular wird mit dem Standardnamen EditScript1.pas geöffnet.

Anzeigen eines Skriptformulars

Ein Skript muss über eine Prozedur verfügen, die das Formular anzeigt, wenn das Skriptformular ausgeführt wird. Innerhalb dieser Prozedur kann die Methode ShowModal für das Formular aufgerufen werden. Die Eigenschaft Visible des Formulars muss false sein, damit die Methode ShowModal des Skriptformulars korrekt funktioniert.

ShowModal example:

Procedure RunDialog;
Begin
  DialogForm.ShowModal;
End;

Das Beispiel ShowModal ist ein sehr einfacher Ansatz, um das Skriptformular anzuzeigen, wenn die Prozedur RunDialog aufgerufen wird. Beachten Sie, dass den Komponenten des Objekts DialogForm Werte zugewiesen werden können, bevor die Methode DialogForm.ShowModal aufgerufen wird.

Das unten gezeigte Beispiel für die Eigenschaft ModalResult ist etwas komplexer. Die folgenden Methoden im Skript werden für Schaltflächen auf einem Skriptformular verwendet. Die Methoden bewirken, dass der Dialog beendet wird, wenn der Benutzer entweder auf die Schaltfläche OK oder Cancel klickt, wodurch jeweils mrOk oder mrCancel von der Methode ShowModal zurückgegeben wird.

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;

Wenn der Benutzer auf diesem Skriptformular auf eine der beiden Schaltflächen klickt, wird das Dialogfeld geschlossen. Es ist nicht erforderlich, die Methode Close aufzurufen, denn wenn die Methode ModalResult gesetzt ist, schließt die Skript-Engine das Skriptformular automatisch.

Beachten Sie, dass Sie, wenn Sie das ModalResult des Formulars auf Cancel setzen möchten, wenn ein Benutzer die Taste Esc drückt, das Object Inspector panel verwenden, um die Eigenschaft Cancel der Schaltfläche Cancel auf True zu setzen, oder Sender.Cancel := True in den Ereignishandler CancelButtonClick der Formularschaltfläche einfügen können.

Benutzereingaben annehmen

Eine der gängigen Komponenten, die Eingaben vom Benutzer annehmen können, ist die Komponente TEdit. Diese Komponente besitzt ein Feld, in das der Benutzer eine Zeichenfolge eingeben kann. Beachten Sie, dass es weitere Delphi-Komponenten wie TMaskEdit gibt, also eine Edit-Komponente mit einer in einer Zeichenfolge gespeicherten Eingabemaske — diese steuert oder filtert die Eingabe.

Das folgende Beispiel veranschaulicht den Ablauf, wenn der Benutzer auf die Schaltfläche klickt, nachdem er etwas in das Edit-Feld eingegeben hat. Wenn der Benutzer nichts in die Edit-Komponente eingegeben hat (leer), reagiert der Ereignishandler mit einer Warnmeldung.

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

Beachten Sie, dass ein Benutzer den Eingabefokus des Dialogfelds mit der Taste Tab oder durch Klicken auf ein anderes Steuerelement im Formular ändern kann.

Auf Ereignisse reagieren

Wenn auf eine Schaltfläche in einem Formular oder auf eine Komponente geklickt wird, reagiert das Skriptsystem, indem es eine Ereignisbenachrichtigung von Altium Designer empfängt und die entsprechende Ereignishandler-Methode aufruft.

See also
Das HelloWorld-Projekt aus dem Ordner Scripts\DelphiScript Scripts\General\ der scripts collection.
Das Beispielskript ShowModal aus dem Ordner Scripts\DelphiScript Scripts\General\ der scripts collection.

Schreiben von Ereignishandlern

Jede Komponente in einem Formularskript hat eine Reihe von Ereignisnamen, und diese werden von Skript-Ereignishandlern verwendet, die festlegen, wie das Skript auf Benutzeraktionen in Altium Designer reagiert. Wenn beispielsweise ein Benutzer auf eine Schaltfläche in einem Formular klickt, sendet Altium Designer eine Nachricht an das Skript, und das Skript reagiert auf dieses neue Ereignis. Wenn das Ereignis OnClick für eine Schaltfläche angegeben ist, wird es ausgeführt.

Der Code zur Reaktion auf Ereignisse befindet sich normalerweise in DelphiScript-Ereignishandlern, und alle Komponenten haben eine Reihe von Ereignissen, auf die sie reagieren können. Beispielsweise haben alle anklickbaren Komponenten ein Ereignis OnClick, das ausgelöst wird, wenn ein Benutzer auf eine Komponente klickt. Alle diese Komponenten haben außerdem ein Ereignis zum Empfangen und Verlieren des Fokus. Wenn jedoch der Code für OnEnter und OnExit nicht angegeben wurde (OnEnter - das Steuerelement hat den Fokus erhalten; OnExit - das Steuerelement hat den Fokus verloren), wird das Ereignis von einem Skript ignoriert.

Zusammengefasst ist ein Ereignis eine Verknüpfung zwischen einem Vorkommnis in Altium Designer, etwa dem Klicken auf eine Schaltfläche, und einem Codeabschnitt, der auf dieses Vorkommnis reagiert. Der reagierende Code ist ein Ereignishandler. Dieser Code ändert Eigenschaftswerte und ruft Methoden auf.

Eigenschaften der Komponente

Um eine Liste der Eigenschaften einer Komponente anzuzeigen, wählen Sie eine Komponente aus und öffnen Sie die Registerkarte Properties im Object Inspector panel.

Komponentenereignisse

Um eine Liste der Ereignisse anzuzeigen, auf die eine Komponente reagieren kann, wählen Sie eine Komponente aus und öffnen Sie die Registerkarte Events im Object Inspector panel. Um eine Ereignisbehandlungsprozedur zu erstellen, wählen Sie das Ereignis aus, auf das die Komponente reagieren soll, und doppelklicken Sie auf den Ereignisnamen — das Skriptsystem fügt automatisch den Framework-Code für den Ereignishandler ein.

Wählen Sie beispielsweise die Komponente TButton aus dem Tool Palette panel aus und legen Sie sie auf dem Skriptformular ab. Doppelklicken Sie dann im Object Inspector panel neben den Ereignisnamen OnClick. Das Skriptsystem setzt den Fokus auf den Code Editor, und der Gerüstcode für das Ereignis OnClick wird erstellt.

Wenn eine Schaltfläche beispielsweise eine Methode Close im Ereignishandler CloseClick hat, dann erfasst der Ereignishandler der Schaltfläche beim Klicken auf die Schaltfläche das Ereignis OnClick, wodurch der Code innerhalb des Ereignishandlers ausgeführt wird. Folglich schließt die Methode Close das Skriptformular.

Zusammengefasst: Wählen Sie eine Schaltflächenkomponente entweder auf dem Formular oder über das Object Inspector panel aus, wählen Sie die Seite Events und doppelklicken Sie auf die rechte Seite des Ereignisses OnClick; daraufhin erscheint ein neuer Ereignishandler im Skript. Alternativ können Sie auch auf die Schaltfläche selbst doppelklicken, und das Skriptsystem fügt einen Handler für dieses Ereignis OnClick hinzu. Beachten Sie, dass andere Komponententypen andere Standardaktionen haben.

Komponentenmethoden

Eine Liste der Methoden einer Komponente finden Sie im Dokument Component Reference.

Ablegen von Komponenten auf einem Skriptformular

Um Komponenten aus dem Tool Palette panel in einem Skript zu verwenden, muss zunächst ein Skriptformular vorhanden sein, bevor Komponenten auf dem Formular abgelegt werden können. Wenn Komponenten auf einem Skriptformular abgelegt werden, müssen diese Objekte normalerweise nicht erstellt oder zerstört werden — das Skriptformular übernimmt dies automatisch.

Das Skriptsystem erzeugt außerdem automatisch den Code, der für die Verwendung einer Komponente erforderlich ist, und aktualisiert das Skriptformular. Danach müssen nur noch die Eigenschaften festgelegt, Code in Ereignishandler eingefügt und die erforderlichen Methoden verwendet werden, um ein funktionsfähiges Skriptformular zu implementieren.

Komponenten in einem Skript erstellen

Komponenten können in einem Skript direkt erstellt oder zerstört werden, indem ein Nil-Parameter an das Constructor einer Komponente übergeben wird. Normalerweise müssen Sie das Handle des Formulars nicht übergeben, da das Skriptformular dies automatisch übernimmt. Sie können zum Beispiel Open und Save-Dialoge erstellen und zerstören (TOpenDialog- und TSaveDialog-Klassen aus der Embarcadero Delphi RTL).

Skriptformulare anpassen

Die wesentlichen Punkte zum Anpassen von Skriptformularen sind:

• Um ein Formular zu zwingen, über anderen geöffneten Panels zu bleiben, 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 geschlossen ist, ist das Formular modal — das heißt, es wartet auf eine Benutzereingabe, bevor fortgefahren wird, etwa durch Schließen des Formulars. Wenn fkServerPanel, wird das Formular als Server-Panel angezeigt. Wenn fkNormal, verhält sich das Formular wie ein normales nicht modales Formular.
• Um die standardmäßigen Bildlaufleisten des Formulars zu entfernen, ändern Sie den Wert der Eigenschaften HorzScrollBar und VertScrollBar.
• Um das Formular zu einem MDI-Rahmen oder MDI-Kind zu machen, verwenden Sie die Eigenschaft FormStyle.
• Um den Rahmenstil des 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 des Formulars festzulegen (z. B. minimiert, maximiert oder normal), verwenden Sie die Eigenschaft WindowState.
• Um den Arbeitsbereich des Formulars zur Laufzeit festzulegen, verwenden Sie die Eigenschaften ClientHeight und ClientWidth (beachten Sie, dass ClientHeight und ClientWidth den Bereich innerhalb des Formularrahmens darstellen; Height und Width stellen den gesamten Bereich des Formulars dar).
• Um festzulegen, welches Steuerelement zur Laufzeit im Formular den anfänglichen Fokus hat, verwenden Sie die Eigenschaft ActiveControl.
• Um alle Tastaturereignisse an das 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.

Skriptformulare und Komponenten aktualisieren

Wenn die Oberfläche eines Skriptformulars nicht mehr aktuell ist, etwa wenn die Steuerelemente nicht aktualisiert oder neu gezeichnet werden, können die Steuerelemente eingefroren oder beschädigt aussehen — dies kann durch intensive Hintergrundverarbeitung dieses Skripts verursacht werden.

Die Methode Update des Skriptformulars sowie viele Skriptkomponenten aus dem Tool Palette panel bieten eine Möglichkeit, den grafischen Inhalt des Formulars oder der jeweiligen Steuerelemente zu aktualisieren. Die Zeilen mit der Methode Update sind im folgenden Beispiel grau hervorgehoben.

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;

Der obige Codeausschnitt stammt aus dem Skriptprojekt PCB Logo Creator, das im Ordner Scripts\Delphiscript Scripts\Pcb\PCB Logo Creator der herunterladbaren Skriptsammlung zu finden ist.