GUI-API

Es ist manchmal notwendig, dass für Vorlagen und Effekte Einstellungen und Eingaben vom Benutzer gebraucht werden. Daher bietet die Scripting-API die Möglichkeit, einfache Grafische Benutzeroberflächen (GUI) zu gestalten.

Einfügen der GUI

Die Gestaltung geschieht innerhalb der vordefinierten Funktion (dem "Hook") GetGUI, die irgendwo im betreffenden Skript eingefügt sein muss:

 function GetGUI(SlideShowObject: ISlideShowObject): string;
 begin
   Result := '';
 end;

Diese Funktion hält einen Parameter SlideShowObject. Dieses ist eine Referenz auf das Objekt, welches das Skript ausführt. Das ist in der Regel das Effekt- bzw. das BlackBox-Objekt selbst.

Die Definition der GUI erfolgt mittels JSON-Syntax. Die Funktion liefert also einen JSON-String zurück.

Struktur des JSON-Strings

Allgemeiner Aufbau

Das JSON-Objekt ist ein Array aus Komponenten-Objekten:

 [
   {
     # Komponente 1
   },
   {
     # Komponente 2
   }
 ]

Jede Komponente benötigt das Key-Element, das Caption-Element und das Type-Element. Alle diese Elemente sind vom Datentyp String.

• Key: Eindeutige Kennung der Komponente, seine ID
• Type: Art der Komponente. Kann folgende Werte annehmen:
  • Title: Title der Vorlage oder des Effekts
  • Edit: Eingabefeld
  • ListBox: Listenelement, enthält Strings
  • ComboBox: Aufklappbarer Auswahldialog, enthält Strings
  • CheckBox: Kästchen zur binären Auswahl
  • ImageComboBox: Aufklappbarer Auswahldialog, enthält Bilder
  • SpinEdit: Eingabefeld für Ganzzahlen, liefert Integer-Werte
  • Slider: auch unter TrackBar bekannt, Schieberegler, liefert Integer-Werte
• Caption: Beschriftung der Komponente, kann leer sein.

Optionen

Zusätzlich gibt es das optionale Options-Objekt, welches bei Bedarf bestimmte Zusatzinformationen enthalten kann - je nach Type.

 # Beispiel für ein Edit-Feld und ein beschränktes Spin-Edit mit Optionen
 [
   {
     "Key" : "Edit1",
     "Type" : "Edit",
     "Caption" : "Dies ist eine Edit-Feld"
   },
   {
     "Key" : "Spin1",
     "Type" : "SpinEdit",
     "Caption" : "Dies ist ein SpinEdit-Feld",
     "Options" :
       {
         "Min" : 1,
         "Max" : 10
       }
   }
 ]

Layout

Standardmäßig werden die im Array aufgezählten Komponenten untereinander angeordnet und über die gesamte Breite des Eigenschaften-Fensters gezogen. Ist eine Caption angegegeben, erscheint diese vor der eigentlichen Komponente als Beschriftung.

Schachtelung

Es ist möglich, Komponenten auch nebeneinander anzuordnen. Dafür müssen sich diese innerhalb eines Unterarrays befinden:

 # JSON-Array für die GUI
 [
   {<Ein Objekt in Zeile 1>},
   [{<Ein Objekt in Zeile 2>}, {<Noch ein Objekt in Zeile 2>}],
   {<Ein Objekt in Zeile 3>}
 ]

Generell ist eine beliebige Schachtelung von Komponenten erlaubt. Jedes Unterarray wechselt das Layout von Horizontal zu Vertikal. Das erlaubt das Erstellen auch von komplizierteren Tabellenlayouts.

Beispiel

 [
   {
     "Key" : "Edit1",
     "Type" : "Edit",
     "Caption" : "Name:"
   },
   [
     [
       {
         "Key" : "Edit2",
         "Type" : "Edit",
         "Caption" : "Anschrift Teil 1:"
       },
       {
         "Key" : "Edit3",
         "Type" : "Edit", 
         "Caption" : "Anschrift Teil 2:"
       } 
     ], 
     [
       {
         "Key" : "Combo1",
         "Type" : "ComboBox",
         "Caption": "Kontaktmöglichkeit:",
         "Options": 
           {
             "Items" : ["eMail", "Telefon", "Rauchzeichen"]
           }
       },
       {
         "Key" : "Edit4",
         "Type" : "Edit",
         "Caption" : "Eingabe Kontakt:"
       }
     ]
 ]

Dieses Beispiel könnte zur Eingabe von Adressschemata geeignet sein - der Anwendungsfall für die konkrete DiaShow sei hierbei einmal vernachlässigt. Dieses Layout ergibt ein breites Edit-Feld (der Name), und darunter eine kleine 2x2-Tabelle (links untereinander die Anschrift mit Edit-Feldern und rechts untereinander die Combobox und das Edit-Feld für die Kontaktdaten).