PuppetMaster Guide - Writing VBScript Actions



Please note that there will be changes and additions to the VB Script interface as PuppetMaster is developed.

1       Introduction


This is a guide for writing VB Script actions with PuppetMaster. PuppetMaster is available at http://www.lim.com.au/PuppetMaster


One of the ways of customizing PuppetMaster is using VB Script. In fact, some of the programs supported by default in PuppetMaster (eg. PowerPoint, iTunes) are entirely scripted in VB Script.


This is not a tutorial on VB Script – there are plenty of other tutorials on the internet that will teach syntax and features. This is just a guide on how to use VB Script to provide fine control of PuppetMaster



2       Non-Interactive scripts


Let’s start with an example.


Set PowerPointApp = CreateObject("PowerPoint.Application")



The script above will cause a presentation to go to its next slide. To use it, go to Preferences -> Menus -> Add Item

Select Visual Basic Script, give it a name, (eg. “Next Slide”) and paste the script into. Click OK.


The action will be added to your Available items. To show it on your phone, drag it across to the left pane. It’ll appear immediately on your phone if you’re already connected.


Try it out! Load a PowerPoint presentation, start it playing, and then choose “Next Slide” on your phone. You should find that it works as expected.


This demonstrates how simple non-interactive scripts can be created.



3       Hello World Script


Create a new VB Script action called “Hello World”. Paste the following script in


Const etActivate = 1

If ExecuteData.Type = etActivate Then

RemoteController.ShowDialog "Hello World"

End If


When you use this script on your phone, it’ll show “Hello World”. Pressing OK or Back buttons will return you to the parent menu.


When PuppetMaster calls a VBScript, it provides two objects – ExecuteData and RemoteController. ExecuteData provides information on why the script is called.


When a script is first selected from a menu, it is sent an etActivate event. If the script does not tell the RemoteController to display anything, then the script is finished with. However, if the script does display something on the RemoteController, then PuppetMaster assigns the script an ‘active’ state and it will be called in the future.


RemoteController provides methods to interact with the device. Here, we are simply displaying the text “Hello World”



4       Key Handling


PuppetMaster will call the script with ExecuteData.Type set to etKeyPress when the user presses a button. Try the following script


Const etActivate = 1, etKeyPress = 4

Select Case ExecuteData.Type

Case etActivate

RemoteController.ShowDialog "Press a key"

Case etKeyPress

RemoteController.ShowDialog "You pressed " & ExecuteData.KeyID

End Select


If you look at how this script works, you’ll notice that the actual key pressed is provided by part of ExecuteData



5       Persistent Data


Sometimes you’d like the script to know ‘what happened before.’ The RemoteController object has a “Store” property that you can set to any value (or array of values) that will be preserved across calls. Try the following example


Const etActivate = 1, etKeyPress = 4

Select Case ExecuteData.Type

Case etActivate

RemoteController.ShowDialog "Press a key"

 RemoteController.Store = 0

Case etKeyPress

 RemoteController.Store = RemoteController.Store + 1

RemoteController.ShowDialog RemoteController.Store & ": You pressed " & ExecuteData.KeyID

End Select


The Store is initialised to zero in the etActivate section, and is incremented every time a key is pressed. You should see this in the text output on your phone.


Before continuing with example scripts, it’s worth knowing about the different execute types…


6       Execute Types


The actual numeric values for the execute types can be found in the Object Reference

6.1     etActivate


etActivate is sent when the script is first clicked on in a menu. If the script does NOT use one of the RemoteController.Show* methods, then no further messages will be sent to the script, and the menu remains active. To be interactive, the script must handle the etActivate message.


6.2     etBegin, etEnd


etBegin is sent when the script first becomes active. etEnd is when the script becomes inactive. To make the script become active, it must use a RemoteController.Show* method in response to an etActivate


6.3     etKeyPress, etKeyRelease, etIntegerInput, etTextInput


etKeyPress and etKeyRelease are messages sent to the script when keys are pressed and released. The ExecuteData.KeyID property can be used to determine which key was pressed/released.


etIntegerInput and etTextInput are messages sent when a value has been entered by the user. Menus send 0-based integer values representing which index was selected.


6.4     etNext, etBack


etNext and etBack are special cases of user input since they are often dealt with in a very different way on the phones. They generally correspond to “OK” and “Back” keys. etNext and etBack require that you call a RemoteController.Show* if you wish your script to remain active. Not handling etNext/etBack will cause PuppetMaster to display the parent menu.


6.5     etTimer


The etTimer message is sent periodically to your script to allow updating of the phone based on time. Timers are set using RemoteController.StartTimer(Milliseconds) and stopped using RemoteController.StopTimer


7       Timer Example


To get PuppetMaster to call your script periodically, you need to use the RemoteController.StartTimer method. You will also need to tell it to stop triggering periodic events when you exit. The following example uses VBScript’s inbuilt Time function.


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

Select Case ExecuteData.Type

Case etActivate, etTimer

 RemoteController.ShowDialog Time

Case etBegin


Case etEnd


End Select


RemoteController.StartTimer takes a parameter in milliseconds that represents the time between each etTimer message. Running the above example should cause the system time to be displayed on your mobile phone.


8       MultiState scripts


The following example gives an idea of how scripts with multiple states can be created. Understanding how it works is left as an exercise to the reader.


Const etActivate = 1, etIntegerInput = 6, etNext = 7, etBack = 9

Const stMenu = 0, stDialog = 1, stPercentInput = 2


Sub ShowMenu

 RemoteController.Store(0) = stMenu

 RemoteController.ShowMenu "MultiState Example", array("Show Dialog", "Show Percent Input")

End Sub


Sub HandlePercentInput

 Select Case ExecuteData.Type

 Case etBack, etNext


 Case etIntegerInput

  RemoteController.Store(1) = ExecuteData.Input

 End Select

End Sub


Sub HandleDialog

 Select Case ExecuteData.Type

 Case etBack, etNext


 End Select

End Sub


Sub HandleMenu

 If ExecuteData.Type = etIntegerInput Then

  Select Case ExecuteData.Input

  Case 0

    RemoteController.ShowDialog "Current Percent " & RemoteController.Store(1)

    RemoteController.Store(0) = stDialog

  Case 1

    RemoteController.ShowPercentInput "Enter Percent", RemoteController.Store(1)

    RemoteController.Store(0) = stPercentInput

  End Select

 End If

End Sub


If ExecuteData.Type = etActivate Then

Dim StoreData(2)

 RemoteController.Store = StoreData

 RemoteController.Store(0) = stMenu

 RemoteController.Store(1) = 50 ' Just give percent some starting value


End If


Select Case RemoteController.Store(0)

Case stMenu


Case stDialog


Case stPercentInput


End Select


9       Object Reference


9.1     ExecuteData object


The ExecuteData object provides information on why the script is being run.


9.1.1      Properties




This provides the type. The following are currently defined:

 etActivate = 1

 etBegin = 2

 etEnd = 3

 etKeyPress = 4

 etKeyRelease = 5

 etIntegerInput = 6

 etBack = 7

 etTimer = 8

 etNext = 9

 etTextInput = 10

These are discussed in the Execute Types section


String value that represents the key pressed.

 “<” – Left Arrow

 “>” – Right Arrow

 “^” – Up Arrow

 “v” – Down Arrow

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

 “u”, “d” - + and – buttons on Sony Ericsson phones

 “f” – Menu Button

 “c” – Clear button (Not available on Nokia 6230)


Integer value for menus, percent input

String value for text input


9.2     RemoteController object


The RemoteController object provides access to remote control device.


9.2.1    Properties




This returns true or false depending on if the device is capable of displaying images.


This value is used to store data across multiple script executions. See Persistent Data section.


This is the image display width of the device


This is the image display height of the device


9.2.2    Methods



ShowDialog Text

Displays Text on the device

ShowImage ImageFileName, ImageFileType, TimeBeforeHighQuality

ImageFileName must be a full path to a supported image file type.

TimeBeforeHighQuality controls active degradation of the image. If another image has been displayed within the last TimeBeforeHighQuality (in milliseconds), then the image will be converted to a lower quality to improve interactivity if required. To always display a high quality image, specify 0.

Showing an image that is of different dimensions to ImageWidth and ImageHeight will cause it to be resized to fit before display.

Supported file types are currently: BMP, JPG, PCX, TGA

ShowMenu Title, MenuArray

MenuArray is an array of strings. Sends input via etIntegerInput which is zero-based

ShowPercentInput Title, StartingPercent

Shows a percent input on the phone. etIntegerInput messages will be generated for every change in value.

ShowProgress Text

Shows a progress dialog.

ShowSortedMenu Title, MenuArray

Same as ShowMenu, but will sort the names before display.

ShowText Title, Text

Shows Text on the device. If the text is too long to fit in one screen, the user can scroll it using Up/Down arrows

ShowTextInput Title, InitialText

Allows the user to input text. Most phones support T9 input for this.


This value is used to store data across multiple script executions. See Persistent Data section.



10  Modes


Mode Type

Events related to the mode


etKeyPress, etKeyRelease


etKeyPress, etKeyRelease

Percent Input



etKeyPress, etKeyRelease



Text Input



etKeyPress, etKeyRelease



Comments, corrections, questions? Email me: jeff@lim.com.au