PuppetMaster Guide - JavaScript Actions erstellen

 

 

Bitte beachten sie, dass im Zuge der Weiterentwicklung von PuppetMaster Änderungen und Erweiterungen am JavaScriptinterface durchgeführt werden.

1       Einleitung

 

Dies ist eine Anleitung zum Erstellen von JavaScript Actions mit PuppetMaster. PuppetMaster ist erhältlich auf http://www.lim.com.au/PuppetMaster

 

Einer der Möglichkeiten, PuppetMaster an die eigenen Bedürfnisse anzupassen, ist mit JavaScript.

 

Dies ist kein JavaScript Tutorial – es gibt unzählige Anleitungen zu JavaScript's Syntax und Features im Internet. Dies ist lediglich eine kurze Anleitung, wie man JavaScript zur Kontrolle von PuppetMaster einsetzen kann.

 

 

2       Nicht-Interaktive Skripte

 

Ein Beispiel.

 

iTunesApp = new ActiveXObject("iTunes.Application");

iTunesApp.Play();

 

Dieses Skript startet iTunes und beginnt mit der Wiedergabe. Zum starten öffnen Sie in PuppetMaster Preferences -> Menus -> Add Item

JavaScript auswählen, Name aussuchen, (z.B. “Play”) und den Skriptcode einfügen. OK klicken.

 

Das Skript erscheint dann unter Available items. Um es auf dem Handy zu benutzen muss es zuerst mit der Maus auf die linke Seite gezogen werden, wenn Ihr Handy mit PuppetMaster verbunden ist erscheint es dort sofort.

 

Probieren Sie es aus! Wenn Sie iTunes installiert haben und Sie auf “Play” klicken sollte iTunes starten und die Wiedergabe beginnen.

 

Dies zeigt wie einfach nicht-interaktive Skripte realisiert werden können.

 

 

3       Hello World Skript

 

Erstellen Sie eine neue Java Script Action namens “Hello World”. Fügen Sie folgenden Code ein

 

etActivate = 1;

if(ExecuteData.type == 1)

{

  RemoteController.ShowDialog("Hello World");

}

 

Wenn Sie dieses Skript auf Ihrem Handy benutzen, erscheint dort “Hello World”. Die OK oder Zurück Taste bringt Sie ins übergeordnete Menü zurück.

 

Wenn PuppetMaster das JavaScript aufruft, werden zwei Objekte bereitgestellt – ExecuteData und RemoteController. ExecuteData beinhaltet Informationen zum Aufruf des Skripts.

 

Wenn ein Skript aus dem Menü aufgerufen wird, wird ein etActivate Ereignis an das Skript gesendet. Wenn das Skript z.B. via RemoteController keine Anzeige auslö ist das Skript sofort beendet. Wenn allerdings eine Ausgabe mit RemoteController ausgelöst wird, so gilt das Skript als ‘aktiv’ und wird in Zukunft aufgerufen.

 

RemoteController bietet Funktionen zur Interaktion mit dem Handy. In diesem Beispiel zeigen wir einfach den Text “Hello World” auf dem Handy an.

 

 

4       Eingabebehandlung

 

Wenn der Benutzer eine Taste drückt ruft PuppetMaster das Skript mit dem ExecuteData.Type Flag auf etKeyPress gesetzt auf. Probieren Sie folgendes Skript aus

 

etActivate = 1; etKeyPress = 4;

switch(ExecuteData.Type)

{

case etActivate:

RemoteController.ShowDialog("Press a key");

 break;

 

case etKeyPress:

RemoteController.ShowDialog("You pressed " + ExecuteData.KeyID);

 break;

}

 

Wenn Sie sich dieses Skript ansehen werden Sie feststellen, dass die ID der gedrückten Taste ein Unterobjekt von ExecuteData ist.

 

 

5       Daten speichern

 

Manchmal soll ein Skript ‘wissen was vorher passiert ist’. Das RemoteController Objekt hat ein “Store” Element, das Sie auf einen beliebigen Wert (oder Array von Werten) setzen können und dessen Inhalt über mehrere Aufrufe erhalten bleibt. Probieren Sie folgendes Beispiel

 

etActivate = 1; etKeyPress = 4;

switch(ExecuteData.Type)

{

case etActivate:

RemoteController.ShowDialog("Press a key");

 RemoteController.Store = 0;

 break;

 

case etKeyPress:

 RemoteController.Store = RemoteController.Store + 1;

RemoteController.ShowDialog(RemoteController.Store + ": You pressed " + ExecuteData.KeyID);

 break;

}

 

Der Store wird im etActivate Teil mit 0 initialisiert und mit jedem Tastendruck inkrementiert. Dies sollte in der Textausgabe des Handys angezeigt werden.

 

Bevor wir mit weiteren Beispielen fortfahren lohnt sich ein kurzer Überblick über die verschiedenen Ausführungsobjekte…

 

6       Ausführungsobjekte

 

Die numerischen Werte für die Ausführungsobjekte sind in der Objektreferenz aufgeführt.

6.1     etActivate

 

etActivate wird ausgelöst wenn das Skript erstmalig aus dem Menü aufgerufen wird. Wenn das Skript KEINE RemoteController.Show* Methode benutzt werden keine weiteren Nachrichten gesendet und das Menü bleibt aktiv. Interaktive Skripte müssen die etActivate Nachricht behandeln.

 

6.2     etBegin, etEnd

 

etBegin wird bei erstmaliger Aktivierung des Skripts gesendet. etEnd wird gesendet wenn das Skript inaktiv wird. Aktive Skripte müssen eine RemoteController.Show* Funktion als Antwort auf etActivate benutzen

 

6.3     etKeyPress, etKeyRelease, etIntegerInput, etTextInput

 

etKeyPress und etKeyRelease werden gesendet wenn eine Taste gedrückt und losgelassen wird. Um rauszufinden, welche Taste gedrückt/losgelassen wurde, kann die ExecuteData.KeyID Eigenschaft verwendet werden.

 

Wenn der Benutzer eine Eingabe gemacht hat werden etIntegerInput bzw. etTextInput versendet. Menüs versenden 0-basierte Zahlenwerte, die dem Index der Menüauswahl entsprechen.

 

6.4     etNext, etBack

 

etNext und etBack sind Sonderfälle der Benutzereingabe, da diese Tasten auf unterschiedlichen Handys unterschiedlich behandelt werden. Im Allgemeinen entsprechen sie der “OK” und “Zurück” Taste. etNext und etBack erwarten einen RemoteController.Show* Aufruf wenn da Skript aktiv gehalten werden soll, ansonsten wird PuppetMaster das übergeordnete Menü anzeigen.

 

6.5     etTimer

 

Die etTimer Nachricht wird periodisch an das Skript gesendet und kann für zeitbasierte Updates des Handys verwendet werden. Timer werden mit RemoteController.StartTimer(Millisekunden) gestartet und mit RemoteController.StopTimer() beendet.

 

7       Timer Beispiel

 

Um PuppetMaster zu veranlassen, Ihr Skript in periodischen Zeitabständen aufzurufen, muss die RemoteController.StartTimer Routine verwendet werden. Beim Beenden des Skripts sollte der Timer ausserdem entsprechend beenden werden. Das folgende Beispiel benutzt die in JavaScript eingebaute Date Funktion.

 

etActivate = 1, etBegin = 2, etEnd = 3, etTimer = 8;

switch(ExecuteData.Type)

{

case etActivate:

case etTimer:

 RemoteController.ShowDialog(new Date());

 break;

case etBegin:

 RemoteController.StartTimer(1000);

 break;

 

case etEnd:

 RemoteController.StopTimer();

 break;

}

 

RemoteController.StartTimer erwartet einen Parameter in Millisekunden, die der Zeitspanne zwischen den etTimer Nachrichten entspricht. Der Aufruf des obigen Beispiels sollte die Systemzeit auf dem Handy anzeigen.

 

8       Multi-Zustand Skripte

 

Das folgende Beispiel soll veranschaulichen, wie Skripte mit mehreren Zuständen geschrieben werden können. Sie sollten nun selbst in der Lage sein rauzufinden, wie dies funktioniert.

 

etActivate = 1; etIntegerInput = 6; etNext = 7; etBack = 9;

stMenu = 0; stDialog = 1; stPercentInput = 2;

 

function ShowMenu()

{

 RemoteController.Store[0] = stMenu;

 RemoteController.ShowMenu("MultiState Example", new Array("Show Dialog", "Show Percent Input"));

}

 

function HandlePercentInput()

{

 switch(ExecuteData.Type)

 {

 case etBack:

 case etNext:

  ShowMenu();

  break;

 

 case etIntegerInput:

  RemoteController.Store[1] = ExecuteData.Input;

  break;

 }

}

 

function HandleDialog()

{

 switch(ExecuteData.Type)

 {

 case etBack:

 case etNext:

   ShowMenu();

   break;

 }

}

 

function HandleMenu()

{

 if(ExecuteData.Type == etIntegerInput)

 {

  switch(ExecuteData.Input)

  {

  case 0:

    RemoteController.ShowDialog("Current Percent " + RemoteController.Store[1]);

    RemoteController.Store[0] = stDialog;

    break;

 

  case 1:

    RemoteController.ShowPercentInput("Enter Percent", RemoteController.Store[1]);

    RemoteController.Store[0] = stPercentInput;

    break;

  }

 }

}

 

if(ExecuteData.Type == etActivate)

{

 RemoteController.Store = new Array(2);

 RemoteController.Store[0] = stMenu;

 RemoteController.Store[1] = 50 // Just give percent some starting value

 ShowMenu();

}

 

switch(RemoteController.Store[0])

{

case stMenu:

 HandleMenu();

 break;

case stDialog:

 HandleDialog();

 break;

case stPercentInput:

 HandlePercentInput();

 break;

}

 

 

9       Objektreferenz

 

9.1     ExecuteData Objekt

 

Das ExecuteData Objekt hält Informationen zum Skriptaufruf bereit.

 

9.1.1      Eigenschaften

Name

Hinweise

Type

Beinhaltet den Typ, folgende Typen sind derzeit definiert:

 etActivate = 1

 etBegin = 2

 etEnd = 3

 etKeyPress = 4

 etKeyRelease = 5

 etIntegerInput = 6

 etBack = 7

 etTimer = 8

 etNext = 9

 etTextInput = 10

Weitere Informationen hierzu im Ausführungsobjekte Kapitel

KeyID

String entsprechend der gedrückten Taste.

 “<” – Pfeil links

 “>” – Pfeil rechts

 “^” – Pfeil hoch

 “v” – Pfeil runter

 “0” – “9”, “#, “*” – Keypad

 “u”, “d” - + und – Tasten auf Sony Ericsson Handys

 “f” – Menü Taste

 “c” – Löschen Taste (nicht auf allen Handys verfügbar)

Input

Integerwert für Menüs, Prozenteingabe

String für Texteingabe

 

9.2     RemoteController Objekt

 

Das RemoteController Objekt bietet Zugriff auf das Handy.

 

9.2.1    Eigenschaften

Name

Hinweise

CanShowImage

Testet die Fähigkeit des Handys, Bilder anzeigen zu können und liefert dementsprechend true oder false zurück.

Store

Dieser Wert kann dazu benutzt werden, Daten über Skriptaufrufe hinweg zu speichern. Siehe Kapitel Daten speichern.

ImageWidth

Die Bildbreite des Handys

ImageHeight

Die Bildhöhe des Handys

 

9.2.2    Methoden

Name

Hinweise

ShowDialog(Text);

Zeigt Text auf dem Handy an

ShowImage ImageFileName, ImageFileType, TimeBeforeHighQuality

ImageFileName muss der komplette Pfad zu einem unterstützten Bildtyp sein.

TimeBeforeHighQuality steuert das aktive Runterrechnen des Bildes. Wenn in den letzten TimeBeforeHighQuality Millisekunden ein anderes Bild angezeigt wurde, dann wird das Bild auf eine niedrigere Qualitätsstufe heruntergerechnet, um Interaktivität zu gewährleisten. Um Bilder immer mit höchster Qualität anzuzeigen, geben sie 0 an.

Bilder mit anderen Ausmassen als ImageWidth und ImageHeight werden vor dem Anzeigen dem Handy entsprechend skaliert.

Unterstützte Bildtypen sind derzeit: BMP, JPG, PCX, TGA

ShowMenu(Title, MenuArray);

MenuArray ist ein Array von Strings. Sendet 0-basierte etIntegerInput Eingaben

ShowPercentInput(Title, StartingPercent);

Zeigt eine Prozenteingabe auf dem Handy an. etIntegerInput Nachrichten werden bei jeder Veränderung des Wertes generiert.

ShowProgress(Text);

Zeigt einen Fortschrittsdialog an.

ShowSortedMenu(Title, MenuArray);

Wie ShowMenu, sortiert vor der Anzeige allerdings nach Namen.

ShowText(Title, Text);

Zeigt Text auf dem Handy an. Wenn der Text zu gross für den Handybildschirm ist kann der Benutzer mit den Hoch/Runter Pfeiltasten scrollen

ShowTextInput(Title, InitialText);

Erlaubt dem Benutzer, Text mit T9 Unterstützung einzugeben (wenn vom Handy unterstützt).

Store

Dieser Wert kann dazu benutzt werden, Daten über Skriptaufrufe hinweg zu speichern. Siehe Kapitel Daten speichern.

 

 

10  Modi

 

Modus Typ

dem Modus zugeordnete Ereignisse

Dialog

etKeyPress, etKeyRelease

Text

etKeyPress, etKeyRelease

Percent Input

etIntegerInput

Progress

etKeyPress, etKeyRelease

Menu

etIntegerInput

Text Input

etTextInput

Image

etKeyPress, etKeyRelease

 

 

Kommentare, Verbesserungen, Fragen? Mailen Sie an: jeff@lim.com.au