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 OnGetGUI(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
  • Gallery: Auswahldialog in Form einer Galerie, enthält Bilder
  • SpinEdit: Eingabefeld für Ganzzahlen, liefert Integer-Werte
  • Slider: auch unter TrackBar bekannt, Schieberegler, liefert Integer-Werte
  • Label: Beschriftungsfeld
• 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
       }
   }
 ]

Standard-Werte

Es gibt keine Möglichkeit, Default-Werte in der GUI anzugeben. Da es aber wahrscheinlich ist, dass bestimmte Komponenten einen Standardwert besitzen sollen, gibt es eine einfache Lösung. Dadurch, dass Vorlagen mit angehängten Skripts und deren GUIs in ihrem Momentan-Zustand gespeichert werden, kann man vor dem Ablegen der Vorlagen in der GUI einfach die gewünschten Werte voreinstellen. Diese werden dann zusammen mit dieser abgespeichert und sind fortan ihre Standardwerte

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).