Руководство по PuppetMaster - Написание действий на JavaScript

 

 

Пожалуйста, обратите внимание, что интерфейс JavaScript будет изменяться и дополняться по мере разработки PuppetMaster.

1        Введение

 

Это руководство по написанию действий на JavaScript для PuppetMaster. PuppetMaster доступен по адресу: http://www.lim.com.au/PuppetMaster

 

Один из путей настройки PuppetMaster - использование JavaScript.

 

Это не учебник по JavaScript - есть много других учебников в интернете, которые обучают синтаксису и возможностям языка. Это просто руководство о том, как использовать JavaScript, чтобы обеспечить точное управление от PuppetMaster.

 

 

2         Неинтерактивные скрипты

 

Начнём с примера.

 

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

iTunesApp.Play();

 

Этот скрипт приводит к запуску iTunes и началу воспроизведения. Чтобы использовать это, перейдите в Preferences -> Menus -> Add Item

Выберите Visual Basic Script, задайте имя (напр. “Play”) и вставьте скрипт. Нажмите OK.

 

Действие будет добавлено в Available items. Чтобы отобразить его в телефоне, перенесите действие в левую панель. Оно отобразится в телефоне немедленно, если он подключен.

 

Попробуйте, как это действует! Убедитесь, что iTunes установлен, и тогда выберите “Play” на вашем телефоне. Вы должны обнаружить, что iTunes запустился и играет, как задумано.

 

Этот пример демонстрирует, как можно создавать простые неинтерактивные скрипты.

 

 

3         Hello World Script

 

Создадим новое действие JavaScript, называющееся ‘Hello World’. Вставьте следующий скрипт.

 

etActivate = 1;

if(ExecuteData.type == 1)

{

  RemoteController.ShowDialog("Hello World");

}

 

Когда вы используете этот скрипт на вашем телефоне, он покажет ‘Hello World’. Нажатие кнопок OK или Back вернёт вас в предыдущее меню.

 

Когда PuppetMaster вызывает JavaScript, он предоставляет два объекта - ExecuteData и RemoteController. ExecuteData передаёт информацию, почему был вызван скрипт.

 

Когда скрипт впервые выбран из меню, он посылает событие типа etActivate. Если скрипт не сообщает RemoteController что-нибудь отобразить, то скрипт завершается. Однако, если скрипт показывает что-то на дисплее RemoteController, то PuppetMaster присваивает скрипту активное состояние ('active'), и он будет вызван позже.

 

RemoteController предоставляет методы для взаимодействия с устройством. Здесь мы просто показали текст ‘Hello World’

 

 

4         Перехват клавиш

 

PuppetMaster вызывает скрипт с ExecuteData.Type, установленным на etKeyPress, когда пользователь нажимает кнопку. Попробуйте  запустить следующий скрипт.

 

etActivate = 1; etKeyPress = 4;

switch(ExecuteData.Type)

{

case etActivate:

RemoteController.ShowDialog("Нажмите клавишу");

 break;

 

case etKeyPress:

RemoteController.ShowDialog("Вы нажали " + ExecuteData.KeyID);

 break;

}

 

Если вы посмотрите, как работает этот скрипт, то обратите внимание, что нажатие клавиши передаётся как часть ExecuteData.

 

 

5         Устойчивые данные

 

Время от времени, вам может понадобиться дать скрипту знать, «что произошло раньше». Объект RemoteController обладает свойством ‘Store’, которому вы можете установить любое значение (или массив значений), которое будет сохраняться между вызовами. Попробуйте следующий пример

 

etActivate = 1; etKeyPress = 4;

switch(ExecuteData.Type)

{

case etActivate:

RemoteController.ShowDialog("Нажмите клавишу");

 RemoteController.Store = 0;

 break;

 

case etKeyPress:

 RemoteController.Store = RemoteController.Store + 1;

RemoteController.ShowDialog(RemoteController.Store + ": Вы нажали " + ExecuteData.KeyID);

 break;

}

 

Store инициализируется нулём в секции etActivate и увеличивается каждый раз при нажатии клавиши. Вы должны увидеть это в текстовом выводе на вашем телефоне.

 

Перед продолжением примеров скриптов, важно изучить разные типы событий…

 

 

6         Типы событий

 

Реальные цифровые значения для типов событий можно найти в Справочнике по Объектам.

6.1           etActivate

 

etActivate посылается, когда пользователь впервые щёлкает по скрипту в меню. Если скрипт НЕ использует ни одного из методов RemoteController.Show*, то нет событий, посылаемых скрипту, и меню остаётся активным. Например, такой скрипт может просто запустить какое-то приложение на компьютере, не требующее взаимодействия с пользователем. Чтобы обеспечить интерактивность, скрипт должен обрабатывать событие etActivate.

 

6.2           etBegin, etEnd

 

etBegin посылается, когда скрипт впервые активизируется. EtEnd - когда скрипт деактивизируется. Чтобы сделаться активным, скрипт должен использовать метод RemoteController.Show* в ответ на etActivate

 

6.3           etKeyPress, etKeyRelease, etIntegerInput, etTextInput

 

etKeyPress и etKeyRelease - это события, посылаемые скрипту, когда клавиши нажимаются и отпускаются. Свойство ExecuteData.KeyID  может быть использовано, чтобы определить, какая клавиша нажата/отпущена.

 

etIntegerInput и etTextInput - события, посылаемые, когда пользователем введено значение. Меню посылают 0-базовое целое значение, представляющее индекс элемента, который был выбран.

 

6.4           etNext, etBack

 

etNext и etBack - специальные случаи пользовательского ввода, так как они могут применяться очень разными путями в телефонах. Обычно они связаны с кнопками «OK» и «Назад». etNext и etBack требуют, чтобы вы вызвали метод RemoteController.Show*, если хотите, чтобы скрипт остался активен. Неперехваченные etNext/etBack приведут к тому, что PuppetMaster отобразит предыдущее меню.

 

6.5           etTimer

 

Событие etTimer посылается скрипту периодически, чтобы обеспечить обновление на телефоне с течением времени. Таймеры устанавливаются использованием RemoteController.StartTimer(миллисекунды) и останавливаются использованием RemoteController.StopTimer().

 

7        Timer Example

 

Чтобы позволить PuppetMaster периодически вызывать ваш скрипт, вам нужно использовать метод RemoteController.StartTimer. Вы также должны оповестить об остановке срабатывания периодических событий при выходе. Следующий пример использует встроенную в JavaScript функцию Date

 

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 использует параметр в миллисекундах, который определяет время между  каждым событием etTimer. Запуск скрипта, приведённого выше, должен привести к отображению системного времени в вашем мобильном телефоне.

 

8        Скрипты с множеством состояний

 

Следующий пример даёт идею, как создавать скрипты с множеством состояний. Понимание, как это работает, останется упражнением для читателя.

 

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

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

 

function ShowMenu()

{

 RemoteController.Store[0] = stMenu;

 RemoteController.ShowMenu("Пример Мультисостояний", new Array("Показ. диалог", " Показ. % ввода"));

}

 

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("Текущий % " + RemoteController.Store[1]);

    RemoteController.Store[0] = stDialog;

    break;

 

  case 1:

    RemoteController.ShowPercentInput("Введите процент", 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 // Просто даёт проценту некоторое стартовое значение

 ShowMenu();

}

 

switch(RemoteController.Store[0])

{

case stMenu:

 HandleMenu();

 break;

case stDialog:

 HandleDialog();

 break;

case stPercentInput:

 HandlePercentInput();

 break;

}

 

 

9        Справочник по Объектам

 

9.1           Объект ExecuteData

 

Объект ExecuteData предоставляет информацию, почему был запущен скрипт.

 

9.1.1        Свойства

Имя

Замечания

Type

Предоставляет значение типа. Сейчас определены следующие:

 etActivate = 1

 etBegin = 2

 etEnd = 3

 etKeyPress = 4

 etKeyRelease = 5

 etIntegerInput = 6

 etBack = 7

 etTimer = 8

 etNext = 9

 etTextInput = 10

Они обсуждаются в разделе Типы событий.

KeyID

Строковое значение, представляющее нажатую клавишу.

 “<” - Стрелка влево

 “>” - Стрелка вправо

 “^” - Стрелка вверх

 “v” - Стрелка вниз

 “0” – “9”, “#, *” - Клавиатура

 “u”, “d” - клавиши + и - на телефонах Sony Ericsson

 “f” - Кнопка меню (!abc)

 “c” - Кнопка C (доступна не на всех телефонах)

Input

Целое значение для меню, процент ввода

Строковое значение для текстового ввода.

 

9.2           Объект RemoteController

 

Объект RemoteController предоставляет доступ к устройству дистанционного управления.

 

9.2.1      Свойства

Имя

Замечания

CanShowImage

Возвращает true или false в зависимости от возможности устройства к показу изображений.

Store

Это значение используется для хранения данных между многими исполнениями скрипта. См. раздел Устойчивые данные.

ImageWidth

Это ширина дисплея для вывода рисунка в устройстве

ImageHeight

Это высота дисплея для вывода рисунка в устройстве

 

9.2.2      Методы

Имя

Замечания

ShowDialog(Текст);

Показывает Текст на устройстве.

ShowImage ImageFileName, ImageFileType, TimeBeforeHighQuality

ImageFileName должно быть полным путём к файлу рисунка поддерживаемого типа.

TimeBeforeHighQuality управляет временем активной деградации рисунка. Если другой рисунок был показан в течение последнего TimeBeforeHighQuality (в миллисекундах), то рисунок  будет преобразован с понижением качества для улучшения интерактивности, если требуется. Чтобы всегда показывать рисунки высокого качества, задайте этому параметру 0.

Показ изображения с размерами, иными чем ImageWidth и ImageHeight приводит к его ресэмплированию для умещения на дисплее.

ImageFileType - поддерживаемые типы изображений, на данный момент: BMP, JPG, PCX, TGA.

ShowMenu(Заголовок, МассивМеню);

МассивМеню - это массив строк. Посылает ввод посредством 0-базового etIntegerInput

ShowPercentInput(Заголовок, НачПроцент);

Показывает процентный ввод на телефоне. События etIntegerInput генерируются для каждого изменения значения.

ShowProgress(Текст);

Показывает прогрессивный диалог.

ShowSortedMenu(Заголовок, МассивМеню);

То же, что и ShowMenu, но сортирует имена перед показом.

ShowText(Заголовок, Текст);

Показывает Текст на устройстве. Если текст очень длинный и не помещается на экране, пользователь может прокручивать его стрелками Вверх/Вниз

ShowTextInput(Заголовок, НачТекст);

Позволяет пользователю вводить текст. Многие телефоны поддерживают T9 - метод ускоренного ввода текста для этого.

Store

Это значение используется для хранения данных между многими выполнениями скрипта. См. раздел Устойчивые данные.

 

 

10       Режимы

 

Тип режима

События, относящиеся к режиму

Dialog

etKeyPress, etKeyRelease

Text

etKeyPress, etKeyRelease

Percent Input

etIntegerInput

Progress

etKeyPress, etKeyRelease

Menu

etIntegerInput

Text Input

etTextInput

Image

etKeyPress, etKeyRelease

 

 

Комментарии, исправления, вопросы? Пишите: jeff@lim.com.au