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

PowerPointApp.SlideShowWindows(1).View.Next

 

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

 RemoteController.StartTimer(1000)

Case etEnd

 RemoteController.StopTimer

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

  ShowMenu

 Case etIntegerInput

  RemoteController.Store(1) = ExecuteData.Input

 End Select

End Sub

 

Sub HandleDialog

 Select Case ExecuteData.Type

 Case etBack, etNext

   ShowMenu

 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

 ShowMenu

End If

 

Select Case RemoteController.Store(0)

Case stMenu

 HandleMenu

Case stDialog

 HandleDialog

Case stPercentInput

 HandlePercentInput

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

Name

Notes

Type

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

KeyID

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)

Input

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

Name

Notes

CanShowImage

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

Store

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

ImageWidth

This is the image display width of the device

ImageHeight

This is the image display height of the device

 

9.2.2    Methods

Name

Notes

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.

Store

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

 

 

10  Modes

 

Mode Type

Events related to the mode

Dialog

etKeyPress, etKeyRelease

Text

etKeyPress, etKeyRelease

Percent Input

EtIntegerInput

Progress

etKeyPress, etKeyRelease

Menu

EtIntegerInput

Text Input

EtTextInput

Image

etKeyPress, etKeyRelease

 

 

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