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.
Table of contents
1. Inserting the 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.
2. Structure of the JSON string
2.1 General structure
Das JSON-Objekt ist ein Array aus Komponenten-Objekten:
[
{
# Component 1
},
{
# Component 2
}
]
Jede Komponente benötigt das Key-Element, das Caption-Element und das Type-Element. Alle diese Elemente sind vom Datentyp String.
- Key: Unique identifier of the component, its ID
- Type: Type of component. Can take the following values:
- 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.
2.2 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
}
}
]
2.2.1 Default values
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
2.3 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.
2.3.1 Nesting
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.
2.3.2 Example
[
{
"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 ein konkretes Projekt 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).