GUI-API: Unterschied zwischen den Versionen

Aus AquaSoft Wiki
Zur Navigation springenZur Suche springen
 
(8 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt)
Zeile 1: Zeile 1:
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 [Benutzeroberflächen] (GUI) zu gestalten.  
+
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 [https://de.wikipedia.org/wiki/Grafische_Benutzeroberfl%C3%A4che Grafische Benutzeroberflächen] (GUI) zu gestalten.  
  
 
= Einfügen der GUI =
 
= Einfügen der GUI =
Die Gestaltung geschieht innerhalb der vordefinierten Funktion '''GetGUI''', die irgendwo im betreffenden Skript eingefügt sein muss:
+
Die Gestaltung geschieht innerhalb der vordefinierten Funktion (dem "Hook") '''GetGUI''', die irgendwo im betreffenden Skript eingefügt sein muss:
 
<code>
 
<code>
   function GetGUI(SlideShowObject: ISlideShowObject): string;
+
   function OnGetGUI(SlideShowObject: ISlideShowObject): string;
 
   begin
 
   begin
 
     Result := ''''''';
 
     Result := ''''''';
Zeile 30: Zeile 30:
 
* ''Key'': Eindeutige Kennung der Komponente, seine ID
 
* ''Key'': Eindeutige Kennung der Komponente, seine ID
 
* ''Type'': Art der Komponente. Kann folgende Werte annehmen:
 
* ''Type'': Art der Komponente. Kann folgende Werte annehmen:
** ''[[Dokumentation der Komponente Title|Title]]'': Title der Vorlage oder des Effekts
+
** ''[[Title]]'': Title der Vorlage oder des Effekts
** ''[[Dokumentation der Komponente Edit|Edit]]'': Eingabefeld
+
** ''[[Edit]]'': Eingabefeld
** ''[[Dokumentation der Komponente ListBox|ListBox]]'': Listenelement, enthält Strings
+
** ''[[ListBox]]'': Listenelement, enthält Strings
** ''[[Dokumentation der Komponente ComboBox|ComboBox]]'': Aufklappbarer Auswahldialog, enthält Strings
+
** ''[[ComboBox]]'': Aufklappbarer Auswahldialog, enthält Strings
** ''[[Dokumentation der Komponente CheckBox|CheckBox]]'': Kästchen zur binären Auswahl
+
** ''[[CheckBox]]'': Kästchen zur binären Auswahl
** ''[[Dokumentation der Komponente ImageComboBox|ImageComboBox]]'': Aufklappbarer Auswahldialog, enthält Bilder
+
** ''[[Gallery]]'': Auswahldialog in Form einer Galerie, enthält Bilder
** ''[[Dokumentation der Komponente SpinEdit|SpinEdit]]'': Eingabefeld für Ganzzahlen, liefert Integer-Werte
+
** ''[[SpinEdit]]'': Eingabefeld für Ganzzahlen, liefert Integer-Werte
** ''[[Dokumentation der Komponente Slider|Slider]]'': auch unter '''TrackBar''' bekannt, Schieberegler, liefert Integer-Werte
+
** ''[[Slider]]'': auch unter '''TrackBar''' bekannt, Schieberegler, liefert Integer-Werte
 +
** ''[[Label]]'': Beschriftungsfeld
 
* ''Caption'': Beschriftung der Komponente, kann leer sein.
 
* ''Caption'': Beschriftung der Komponente, kann leer sein.
  
Zeile 62: Zeile 63:
 
   ]
 
   ]
 
</code>
 
</code>
 +
 +
=== 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 ==
 
== 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:
 +
<code>
 +
  # 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>}
 +
  ]
 +
</code>
 +
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 ===
 +
<code>
 +
  [
 +
    {
 +
      "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:"
 +
        }
 +
      ]
 +
  ]
 +
</code>
 +
 +
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).
 +
  
 
[[Kategorie:Scripting-API]]
 
[[Kategorie:Scripting-API]]

Aktuelle Version vom 20. Dezember 2012, 14:45 Uhr

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