.. |Task| image:: S:/uniplot-obj/buttons/Task.png
      :align: top

.. |Sequencer_OpenWS| image:: S:/uniplot-obj/buttons/Sequencer_OpenWS.png
      :align: top

.. |Sequencer_SwitchWS| image:: S:/uniplot-obj/buttons/Sequencer_SwitchWS.png
      :align: top

.. |Sequencer_AddSequence| image:: S:/uniplot-obj/buttons/Sequencer_AddSequence.png
      :align: top

.. |Sequencer_AddAction| image:: S:/uniplot-obj/buttons/Sequencer_AddAction.png
      :align: top

.. |Sequencer_Save| image:: S:/uniplot-obj/buttons/Sequencer_Save.png
      :align: top

.. |Sequencer_FromWS| image:: S:/uniplot-obj/buttons/Sequencer_FromWS.png
      :align: top

.. |Sequencer_Up| image:: S:/uniplot-obj/buttons/Sequencer_Up.png
      :align: top

.. |Sequencer_RV| image:: S:/uniplot-obj/buttons/Sequencer_RV.png
      :align: top

.. |Sequencer_fromRV| image:: S:/uniplot-obj/buttons/Sequencer_fromRV.png
      :align: top

.. |Sequencer_Options| image:: S:/uniplot-obj/buttons/Sequencer_Options.png
      :align: top

.. |Sequencer_GoSubSeq| image:: S:/uniplot-obj/buttons/Sequencer_GoSubSeq.png
      :align: top

.. highlightlang:: us

.. index:: Sequencer Tutorial

.. _sequencertutorial:

Sequencer Tutorial
==================

Innerhalb dieses Tutorials wird ein kleines Demo-Projekt erstellt das 
mehrere einfache Sequenzen enthält. Das Tutorial gibt eine Einführung darüber wie man den 
Sequencer einsetzen kann und erklärt dessen grundlegende Konzepte.

1. Wechsel des Arbeitsbereiches
-------------------------------

Für jedes Projekt legt man mit dem Sequenzer einen eigenen Projektordner an.
Dieser Ordner wird auch Arbeitsbereich genannt und in ihm werden die Sequenzen
abgespeichert die zu diesem Projekt gehören. In ihm sollten auch alle projektbezogenen 
Dokumente und Resourcen gespeichert werden da der Sequencer an vielen Stellen
Schnellzugriffe auf diesen Ordner bereitstellt, z.B hier:

|Task| drücke |Sequencer_OpenWS| um den Arbeitsbereich im Dateibrowser zu öffnen

|Task| gehe mit der Maus über den Namen des Arbeitsbereiches um seinen Pfad im Tooltip zu sehen

Der erste Arbeitsbereich wird automatisch im Benutzerverzeichnis angelegt.
Wir werden dieses Tutorial als kleines eigenes Projekt betrachten, also legen
wir für es einen eigenen Arbeitsbereich an:

|Task| drücke |Sequencer_SwitchWS| um den aktuellen Arbeitsbereich zu wechseln

|Task| gebe den Namen für den neuen Arbeitsbereich ein, z.B. "TutorialWS"

|Task| drücke "create..." und wähle den Ort für den neuen Ordner des Arbeitsbereiches

2. Die erste Sequenz
--------------------

Die erste Sequenz soll "Hallo Welt" in einem Dokument anzeigen und eine Messagebox öffnen.

|Task| drücke |Sequencer_AddSequence| um eine Sequenz zu erzeugen, nenne sie "Hallo Welt"

Nun müssen wir die Aktionen hinzufügen die sich um das Dokument und um die Messagebox kümmern.
Welche Aktionstypen verfügbar sind sieht man wenn man auf |Sequencer_AddAction| drückt
und mit der Maus über die einzelnen Knöpfe geht. Um ein Dokument anzuzeigen gibt es bereits einen
standard Aktionstyp und für die Messagebox werden wir eine Zeile Script schreiben.

Dokument:

|Task| drücke |Sequencer_AddAction| und wähle den Aktionstyp "Lade Dokument"

Noch ist der Aktion keine Dokumentdatei zugewiesen die geladen werden soll, daher ist 
die Aktion Rot und kann nicht ausgeführt werden. Wir werden nun kein bereits vorhandenes
Dokument auswählen sondern ein neues erstellen:

|Task| drücke "Neu" in der Aktion und benenne das Dokument "HalloWeltDoc"

|Task| füge ein Text Object auf der ersten Seite hinzu und beschrifte es mit "Hallo Welt!

|Task| speichere das Dokument (es liegt im Arbeitsbereich) und schließe es

Messagebox:

|Task| drücke |Sequencer_AddAction| und wähle den Aktionstyp "Script Ausführung"

|Task| drücke "Neu" und benenne das Script file "ShowMessageBox"

|Task| schreibe die Zeile ::

	MessageBox("Hallo Welt!")

|Task| speichere das Script

Das war's, die Sequenz kann nun durch Drücken auf den Play Knopf (Sequenzbereich) ausgeführt werden.

.. image:: S:/uniplot-obj/images/sequencer-Tutorial1.*

Die Aktionen können auch einzeln ausgeführt werden. Drücke hierfür den Play Knopf im Aktionsbereich
oder doppelklicke die Aktion in der Sequenzliste.

|Task| speichere die Sequenzkonfiguration im Arbeitsbereich |Sequencer_Save|

3. Grundlegendes Daten-Handling
-------------------------------

Um die Aktionstypen "Datenaustausch" und "Dateibrowser" vorzustellen werden wir nun erst einmal zwei kleine
Datenfiles erstellen:

|Task| erstelle eine neue Datei "Data1.csv" im Ordner des Arbeitsbereiches und schreibe in diese: ::

    Time, Torque
    s, Nm
    1, 50
    2, 150
    3, 120
	
Denke daran den Arbeitsbereich hier öffnen zu können: |Sequencer_OpenWS|

|Task| erstelle eine zweite Datei "Data2.csv" im Arbeitsbereich und schreibe in diese: ::

    Time, Torque
    s, Nm
    1, 110
    2, 40
    3, 60
	
|Task| lade "Data1.csv" in den Datenbrowser

Nun wollen wir die Daten in einem 2D x/y Chart in unserem Dokument anzeigen.
Nach der Ausführung der "Lade Dokument" Aktion wird das Dokument als Kopie geladen.
Dies verhindert das versehentliche Überschreiben des Originaldokuments in Workflows
bei denen das finale Dokument aus einem Basisdokument heraus generiert wird.
Den Unterschied zwischen "Ausführen" und "Bearbeiten" sieht man z.B. in der Menüzeile von Uniplot.
Wir wollen unser Dokument also bearbeiten:

|Task| selektiere die "Lade Dokument" Aktion und drücke "Bearbeiten"

|Task| selektiere "Time" als X-Kanal and "Torque" als Y-Kanal im Datenbrowser und drücke "Laden"

|Task| speichere das Dokument

Es sollte nun folgendermaßen aussehen:

.. image:: S:/uniplot-obj/images/sequencer-Tutorial2.*

Nun werden wir unser zweites Datenfile während der Sequenzausführung in unser Dokument laden:

|Task| füge zur Sequenz eine Aktion "Datenaustausch" hinzu

|Task| selektiere in dieser "Data2.csv" aus dem Arbeitsbereich über |Sequencer_FromWS|

|Task| die Script Aktion kann nun mit der Checkbox in der Sequenzliste abgeschaltet werden

Wird die Sequenz jetzt gestartet wird sie das Dokument nun laden und die Daten mit unserem
zeiten Datenfile ersetzen.

4. Der erste Runtime Value
--------------------------

Im nächsten Schritt werden wir etwas Benutzerinteraktion in unsere Sequenz einbauen,
der Benutzer soll das Datenfile nun innerhalb der Sequenzausführung auswählen können.
Hierfür werden wir zum ersten Mal "Runtime Values" verwenden, da man mit deren Hilfe Aktionen
aus anderen Aktionen heraus steuern kann. In userem Fall wird eine Aktion ("Dateibrowser") den Dateipfad
zu den Daten bestimmen und dieser wird von einer weiteren (unserer "Datenaustausch" Aktion) verwendet.

|Task| füge zur Sequenz eine Aktion "Dateibrowser" hinzu und schiebe sie mit |Sequencer_Up| an den Anfang der Sequenz

Bei einem Blick auf die Einstellungen der neuen Aktion sieht man, daß der Pfad zur ausgewählten Datei
in den Runtime Value "DATAFILEPATH" geschrieben wird:

|Task| führe die Aktion "Dateibrowser" einzeln aus und wähle "Data2.csv"

Der Runtime Value ist nun gesetzt, man sieht ihn nach Drücken auf |Sequencer_RV| im Arbeitsbereich.
Nun werden wir den Pfad in unserer "Datenaustausch" Aktion verwenden. Dafür schalten wir den Eingang von
"Aus Arbeitsbereich" zu "Aus Runtime Value" |Sequencer_fromRV|. Der Name "DATAFILEPATH" ist in beiden Aktionen
vordefiniert um bereits überein zu stimmen, aber es können natürlich auch andere Namen verwendet werden.

Wird die Sequenz jetzt gestartet sieht man wie beide Aktionen nun zusammen spielen.

Darüber hinaus kann man den Mechanismus zur Dateiauswahl sogar noch erweitern indem man eine "Setze Runtime Values"
Aktion vorschaltet. So kann man den Wert von "DATAFILEPATH" vordefinieren, also quasi einen default Pfad setzen.
Die "Dateibrowser" Aktion kann man nun bei Bedarf einfach dazuschalten.

5. PDF Export, weiterer Einsatz von Runtime Values
--------------------------------------------------

Nun wollen wir unser Dokument am Ende der Sequenz als PDF exportieren. Das ist einfach:

|Task| füge zur Sequenz eine Aktion "PDF Export" hinzu

Drücke Play und die PDF Datei wird erzeugt.

(falls für UniPlot noch kein Ghostscript konfiguriert wurde, bitte hier schauen :ref:`pdf-export`)

Die Voreinstellung für den Dateinamen des PDF files ist "FIX" ("MyFileName"), also konstant.
Nun wollen wir den Namen allerdings dynamisch erzeugen. Als Beispiel wollen wir den Namen der Datendatei nehmen und
dazu das aktuelle Datum anhängen. Also werden wir den Namen in einem kleinen Script zusammenbasteln und
diesen dann an die "Export PDF" Aktion weitergeben. Auch hierfür werden wir wieder "Runtime Values" verwenden,
auf diese kann man mit :ref:`Seq_GetRuntimeValue` und :ref:`Seq_SetRuntimeValue` innerhalb eines Scriptes
zugreifen:

|Task| füge zur Sequenz eine Aktion "Script Ausführung" hinzu, drücke "Neu" und nenne das Script "GeneratePdfFilename"

|Task| schiebe die Aktion vor die "PDF Export" Aktion

|Task| drücke "Bearbeiten", schreibe folgende Zeilen und speichere das Script: ::

    sDataFilePath = Seq_GetRuntimeValue("DATAFILEPATH")

    sDataFileName = SplitPath(sDataFilePath)[3]
    sDate = DT_Format(DT_GetCurrentTime(), "%x")
    sPdfFileName = sDataFileName + "_" + sDate

    Seq_SetRuntimeValue("PDF_FILENAME", sPdfFileName)

|Task| schalte die Dateinamensdefinition in der "PDF Export" Aktion auf |Sequencer_fromRV|

Das wars, jetzt kann man die Sequenz laufen lassen, das exportierte PDF Dokument erhält nun dynamisch seinen Namen.

.. image:: S:/uniplot-obj/images/sequencer-Tutorial3.*

6. Starten und steuern des Sequenzers aus externer Software heraus
------------------------------------------------------------------

Es ist ein üblicher Anwendungsfall eine Auswertung aus einer externen Software (z.B. Automatisierungssysteme,
Datenbank Tools) heraus zu starten. Meistens müssen hierbei auch noch einzelne Parameter übergeben werden,
wie z.B. der Pfad eines Datenfiles oder einige Flags zur Beeinflussung des Generierungsvorganges.

Dies ist durch die Verwendung des Sequenzers in UniPlot sehr einfach. 

Hierzu muss einfach ein Batch file geschrieben werden, in dem der Ort des Arbeitsbereiches (/ws), der Name der Sequenz (/seq)
und die Liste der Parameter (/rv) übergenben werden.

|Task| schalte die "Dateibrowser" Aktion nun aus, wir wollen den Pfad zu unseren Daten nun im Batch file definieren

|Task| speichere den Arbeitsbereich mit |Sequencer_Save| und schließe UniPlot

|Task| erstelle ein Text file, kopiere die folgende Zeile hinein und speichere es als "MyCmd.bat" ::

    C:\Uniplot\uniplot.exe /ws "D:\Projects\TutorialWS" /seq "Hello World" /rv "DATAFILEPATH = D:\Projects\TutorialWS\Data2.csv"

|Task| ändere den Pfad zur uniplot.exe wenn nötig

|Task| ändere den Pfad zum Arbeitsbereich wenn nötig

|Task| ändere den Pfad zum Daten file wenn nötig

|Task| speichere und schließe das batch file

Ein Doppelklick auf das file öffnet nun UniPlot und startet die Auswertung unter Verwendung von "Data2.csv".

Um die automatische Auswertung nun zu vervollständigen wollen wir, daß sich UniPlot nach dem Export des PDF files
automatisch schließt. Für solch kleine Aufgaben die nicht speziell konfiguriert werden müssen gibt es einen weiteren 
Aktionstyp, er heißt "Snippets":

|Task| füge zur Sequenz eine Aktion "Snippet" hinzu und wähle die Funktionalität "Shutdown"

|Task| schalte die Option "Öffne PDF" in the "PDF Export" Aktion aus

Speichere den Arbeitsbereich und schließe Uniplot. Starte das batch file, Uniplot ist nun bereit für eine komplett
automatisierte Auswertung.

7. Bedingte Ausführung von Aktionen
-----------------------------------

Neben der Möglichkeit einzelne Aktionen mit der Checkbox in der Sequenzliste An und Aus zu schalten
kann man über einen Runtime Value auch dynamisch steuern ob eine Aktion ausgeführt werden soll oder nicht.

Als Beispiel wollen wir nun einen zweiten Parameter zu unserem batch file hinzufügen welcher steuern soll
ob der PDF Export ausgeführt werden soll oder nicht:

|Task| erweitere den /rv parameter im batch file mit dem Runtime Value "DO_PDF_EXPORT"

    /rv "DATAFILEPATH = D:\Projects\TutorialWS\Data2.csv, DO_PDF_EXPORT = 1"

|Task| drücke |Sequencer_Options| in der "Export PDF" Aktion

|Task| schalte "Bedingte Ausführung" an und gib ein:

.. image:: S:/uniplot-obj/images/sequencer-Tutorial4.*

|Task| drücke "OK"

Beachte das der Hintergrund der Checkbox in der Sequenzliste lila eingefärbt ist um anzuzeigen das
die Aktion nun nur unter einer bestimmten Bedingung ausgeführt wird. Steuern lässt sich diese Bedingung nun
über den Parameter "DO_PDF_EXPORT" im batch file.

8. Mehrfache Ausführung von Aktionen
------------------------------------

Neben der bedingten Ausführung gibt es auch noch ein weiteres allgemeines Feature in jeder Aktion, 
und dies ist die mehrfache Ausführung bzw. das Loopen von Aktionen. Hierbei wird die Aktion abhänging von der
Größe einer Liste in einem Runtime Value mehrfach ausgeführt. Um diese Feature zu zeigen werden wir zwei
neue Sequenzen erstellen:

|Task| drücke |Sequencer_AddSequence| und nenne die neue Sequenz "Start Sequenz"

|Task| drücke |Sequencer_AddSequence| und nenne die neue Sequenz "Looped Sequenz"

|Task| füge zur Sequenz "Start Sequenz" eine Aktion "Setze Runtime values" hinzu

|Task| füge hier einen Runtime Value "PATH_LIST" hinzu und setze seinen Wert auf ::

    C:\MyFile1.txt, C:\MyFile2.txt, C:\MyFile3.txt

|Task| füge zur Sequenz "Start Sequenz" eine Aktion "Starte Sequenz" hinzu und wähle hier "Looped Sequenz" aus

|Task| drücke |Sequencer_Options| in der "Starte Sequenz" Aktion

|Task| aktiviere hier "Mehrfache Ausführung" und gib ein:

.. image:: S:/uniplot-obj/images/sequencer-Tutorial5.*

|Task| drücke "OK"

|Task| drücke |Sequencer_GoSubSeq| um in die Subsequenz zu springen

|Task| füge zur Subsequenz "Looped Sequenz" eine Aktion "Script Ausführung" hinzu, bearbeite und schreibe: ::

    sPath = Seq_GetRuntimeValue("SINGLE_PATH")
    
    sMessage = "In diesem Durchlauf der Subsequenz kannst du SINGLE_PATH\n" 
    sMessage = sMessage + "mit seinem Wert \"" + sPath + "\" verwenden!"
	
    MessageBox(sMessage)

|Task| speichere das Script

.. image:: S:/uniplot-obj/images/sequencer-Tutorial6.*

Starte nun die Sequenz "Start Sequence". Die Subsequenz "Looped Sequenz" wird nun für jeden Eintrag aus dem
Runtime Value "PATH_LIST" aufgerufen wobei sich der Wert von "SINGLE_PATH" jeweils ändert.

Ein geläufiger Anwendungsfall für diese Feature ist z.B. die Definition einer Dateiliste in einem batch file
um mehrere Auswertungen mit verschiedenen Datenfiles über eine Aufruf anzusteuern.

9. Fazit
--------

Glückwunsch, wir haben nun unseren ersten eigenen Abeitsbereich mit einer kleinen Liste von Sequenzen erstellt!

Versuche doch mal den Sequenzer in einem deiner nächsten Projekte einzusetzen, wir sind sicher das dieses
neue Feautre das Strukturieren der Auswertungen erleichtern wird. Auch das schnelle Wechseln zwischen Projekten
und die Möglichkeit separat einzelne Teile der Auswertung mit nur einem Mausklick auszuführen werden helfen.

Wir sind offen für ein allgemeines Feedback oder Vorschläge für neue Aktionstypen und Snippets!

Dies wird auch Basis dafür sein in welche Richtung wir dieses Feature weiterentwickeln.

:sub:`id-1074338`