QSP: Модуль работы с меню

Версия: 1.1


Автор: Olegus t.Gl.
e-mail: olegus.tgl@gmail.com
jabber: olegus@jabber.ru
icq: 145540276

Тема на форуме iFiction.Ru: ссылка
Тема на форуме QSP: ссылка
Актуальная документация к последней версии: ссылка

О модуле

Внутренний язык платформы QSP дает возможность вызывать меню с помощью оператора MENU, однако его использование несколько неудобно тем, что при выборе пункта меню вызывается заданная локация, в которую передается единственный параметр — номер пункта меню, а этого мало. Хотя можно, разумеется, наплодить локаций, для обработки каждого пункта меню, но это громоздко да и вообще некрасиво.

Данный модуль решает данную проблему — с его помощью к каждому пункту меню помимо вызываемой "локации" можно указать произвольное число параметров. Зачем? Например, чтобы одной "локацией" обрабатывать схожие действия, различающиеся каким-нибудь нюансом. Так, пунктам "осмотреть комнату" и "тщательно обыскать комнату" можно назначить одну и ту же локацию-обработчик, но передавать в нее дополнительный параметр, который будет указывать, насколько тщательно игрок хочет произвести осмотр.

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

Кроме этого можно создавать меню с появляющимися/исчезающими в зависимости от тех или иных условий пунктами и указывать программный код, который должен выполняться при выборе данного пункта, не в отдельной локации-обработчике, а прямо в настройках меню.

Варианты модуля

Поскольку для большинства программистов привычнее работать с англоязычными командами, существует соответствующая версия модуля, в которой все операторы и функции даны в англоязычном варианте. Далее по тексту англязычная версия будет обозначаться для краткости как "Версия E".

В документации перечисляются как русскоязычные команды, так и их англоязычные аналоги, однако в описании, параметрах и примерах будут использоваться команды на русском языке.

Входящие в пакет файлы

otg_lib_menu.qspМодуль с командами на русском языке.
otg_lib_menu_eng.qspМодуль с командами на английском языке.
example_menu.qspПример работы с модулем с командами на русском языке.
example_menu_eng.qspПример работы с модулем с командами на английском языке.
otg_lib_menu_help.htmlДокументация по работе с модулем (вы как раз ее читаете)

Подключение модуля

Первым делом необходимо подключить к своему проекту сам модуль. Для этого файл модуля нужно скопировать в тот же каталог, в котором находится основной проект, после чего в начало кода проекта добавить команду "ADDQST" (для QSP версии 5.7.0):

Подключение модуля с командами на русском языке:

ADDQST 'otg_lib_menu.qsp'

Подключение модуля с командами на английском языке:

ADDQST 'otg_lib_menu_eng.qsp'

Все локации модуля начинаются с префикса "Меню." ("Menu." в версии E), а переменные — с префикса "otg_", поэтому пересечения с данными основного проекта быть не должно.

Перечень команд

Меню.СоздатьMenu.CreateСоздает новое меню.
Меню.ДобавитьПунктMenu.AddДобавляет пункт в указанное меню.
Меню.ДобавитьУсловиеMenu.AddConditionДобавляет условие включения последнего добавленного пункта в указанное меню.
Меню.ДобавитьМодульMenu.AddModuleДобавляет выполняемый код для последнего добавленного пункта в указанное меню.
Меню.ОбработкаСобытияMenu.AddEventДобавляет выполняемый код для одного из предопределённых событий работы с меню: "при выборе пункта", "после обработки выбора" и "при отказе от выбора".
Меню.ВызватьMenu.CallВызывает указанное меню и возвращает -1, если был выбран какой-нибудь пункт из меню (или 0 — если не был).
Меню.ВыбралиMenu.ChosenВозвращает -1, если был выбран какой-нибудь пункт из меню (или 0 — если не был).
Меню.ВремяMenu.TimeВозвращает время в миллисекундах, затраченное игроком на выбор того или иного пункта из меню.
Меню.УдалитьMenu.DestroyУдаляет меню со всеми вспомогательными массивами, переменными и т.п.

Описание команд


Меню.Создать · Menu.Create

Создает новое меню.

Синтаксис:

GS 'Меню.Создать', <Имя меню>

Параметры:

Имя менюОбязательный параметр. Строка с уникальным идентификатором меню. Идентификатор должен соответствовать требованиям QSP к именам переменных.

Пример:

GS 'Меню.Создать', 'Меню'

Меню.ДобавитьПункт · Menu.Add

Добавляет пункт к указанному меню.

Синтаксис:

GS 'Меню.ДобавитьПункт', <Имя меню>, <Название пункта>, <Путь к файлу иконки>, <Название локации-обработчика>, <Параметр 1>, <Параметр 2> …

Параметры:

Имя менюОбязательный параметр. Строка с уникальным идентификатором ранее созданного меню.
Название пунктаОбязательный параметр. Строка с уникальным названием пункта меню. Может состоять из любых символов. Если указать "---", то в меню будет вставлен разделитель.
Путь к файлу иконкиНеобязательный параметр. Путь к файлу иконки для пункта меню.
Название локации-обработчикаОбязательный параметр (если этот пункт не является разделителем). Название локации, вызываемой для обработки выбора данного пункта меню.
Параметр 1
Параметр 2

Параметр N
Необязательные параметры. Значения параметров, передаваемых в локацию-обработчик.

Пример:

GS 'Меню.ДобавитьПункт', 'Меню', 'Осмотреть комнату', '', 'ДействияВКомнате', 'осмотреть', 'бегло'
GS 'Меню.ДобавитьПункт', 'Меню', 'Обыскать комнату', '', 'ДействияВКомнате', 'осмотреть', 'тщательно'
GS 'Меню.ДобавитьПункт', 'Меню', '---'

Меню.ДобавитьУсловие · Menu.AddCondition

Добавляет условие включения последнего добавленного пункта в указанное меню.

Синтаксис:

GS 'Меню.ДобавитьУсловие', <Имя меню>, <Условие>

Параметры:

Имя менюОбязательный параметр. Строка с уникальным идентификатором ранее созданного меню.
УсловиеОбязательный параметр. Строка с программным кодом на языке QSP, возвращающим результат в переменной Result. Если возвращается 0, то данный пункт в момент вызова меню в меню не включается. При записи кода допускаются переносы строк, а также запись кода в виде {…код…}

Пример:

GS 'Меню.ДобавитьПункт', 'Меню', 'Открыть сундук'
GS 'Меню.ДобавитьУсловие', 'Меню', {
  if СундукОткрыт:
    !Если сундук открыт, то этот пункт в меню нам не нужен
    Result=0
  else
    !Если сундук закрыт, то включаем этот пункт в меню
    Result=-1
  end
}

GS 'Меню.ДобавитьПункт', 'Меню', 'Закрыть сундук'
GS 'Меню.ДобавитьУсловие', 'Меню', "Result=IIF(СундукОткрыт,-1,0)"

Меню.ДобавитьМодуль · Menu.AddModule

Добавляет выполняемый код для последнего добавленного пункта в указанное меню.

Синтаксис:

GS 'Меню.ДобавитьМодуль', <Имя меню>, <Код модуля>

Параметры:

Имя менюОбязательный параметр. Строка с уникальным идентификатором ранее созданного меню.
Код модуляОбязательный параметр. Строка с программным кодом на языке QSP, который будет выполнен при выборе данного пункта меню. При записи кода допускаются переносы строк, а также запись кода в виде {…код…}

Пример:

GS 'Меню.ДобавитьПункт', 'Меню', 'Закрыть сундук'
GS 'Меню.ДобавитьМодуль', 'Меню', {
  *NL
  *NL 'Крышка сундука захлопнулась с глухим щелчком.'
  СундукОткрыт=0
}


GS 'Меню.ДобавитьПункт', 'Меню', 'Открыть сундук'
GS 'Меню.ДобавитьМодуль', 'Меню', "
  *NL
  *NL 'Поколодовав немного над замком, вы открыли сундук.'
  СундукОткрыт=-1
"

Меню.ОбработкаСобытия · Menu.AddEvent

Добавляет выполняемый код для одного из предопределённых событий работы с меню: "при выборе пункта", "после обработки выбора" и "при отказе от выбора".

Синтаксис:

GS 'Меню.ОбработкаСобытия', <Имя меню>, <Имя события>, <Код модуля>

Параметры:

Имя менюОбязательный параметр. Строка с уникальным идентификатором ранее созданного меню.
Имя события Обязательный параметр. Строка с именем предопределенного события. Событие "возникает" (и соответственно выполняется привязанный к событию код) в следующие моменты времени:

При выборе пункта Событие возникает при выборе любого пункта из меню, но перед его обработкой (т.е. до вызова обрабатывающей локации или выполнения прописанного кода).
После обработки выбора Событие возникает после вызова обрабатывающей выбор пункта меню локации (либо обработки прописанного в этом пункте кода).
При отказе от выбора Событие возникает при закрытии меню без выбора какого-либо пункта.

В код событий "При выборе пункта" и "После обработки выбора" передаются аргументы с индексами: 0 — название выбранного пункта меню, 1…N — прописанные в пункте параметры, передаваемые в обрабатывающую пункт локацию или привязанный код.
Код модуляНеобязательный параметр. Строка с программным кодом на языке QSP, который будет выполнен при возникновении указанного события. При записи кода допускаются переносы строк, а также запись кода в виде {…код…}

Пример:

GS 'Меню.ОбработкаСобытия', 'Меню', 'При отказе от выбора', {
  *NL 'Ничего не хотим ('+func('Меню.Время','МенюПещера')+') делать в пещере!'
}

GS 'Меню.ОбработкаСобытия', 'Меню', 'При выборе пункта',{
  *NL 'Сейчас будем что-то делать (пункт: "'+$ARGS[0]+'", параметр 0: '+$ARGS[1]+', параметр 1: '+$ARGS[2]+') в пещере!'
}

GS 'Меню.ОбработкаСобытия', 'Меню', 'После обработки выбора',{
  *NL 'Ну вот и обработали действие (пункт: "'+$ARGS[0]+'", параметр 0: '+$ARGS[1]+', параметр 1: '+$ARGS[2]+') в пещере!'
}

Меню.Вызвать · Menu.Call

Вызывает указанное меню и возвращает -1, если был выбран какой-нибудь пункт из меню (или 0 — если не был).

Синтаксис:

GS 'Меню.Вызвать', <Имя меню>
func('Меню.Вызвать', <Имя меню>)

Параметры:

Имя менюОбязательный параметр. Строка с уникальным идентификатором ранее созданного меню.

Пример:

GS 'Меню.Вызвать', 'Меню'
if func('Меню.Вызвать', 'Меню')=0: *NL 'Ничего не выбрали!'

Меню.Выбрали · Menu.Chosen

Возвращает -1, если был выбран какой-нибудь пункт из меню (или 0 — если не был).

Синтаксис:

func('Меню.Выбрали', <Имя меню>)

Параметры:

Имя менюОбязательный параметр. Строка с уникальным идентификатором ранее созданного меню.

Пример:

if func('Меню.Выбрали', 'Меню')=0: *NL 'Ничего не выбрали!'

Меню.Время · Menu.Time

Возвращает время в миллисекундах (1/1000 секунды), затраченное игроком на выбор того или иного пункта из меню.

Синтаксис:

func('Меню.Время', <Имя меню>)

Параметры:

Имя менюНеобязательный параметр. Строка с уникальным идентификатором ранее созданного меню. Если данный параметр не указан, то возвращается время выбора пункта из последнего вызванного меню.

Пример:

func('Меню.Время', 'Меню')
func('Меню.Время')

Меню.Удалить · Menu.Destroy

Удаляет указанное меню со всеми вспомогательными массивами и переменными.

Синтаксис:

GS 'Меню.Удалить', <Имя меню>

Параметры:

Имя менюОбязательный параметр. Строка с уникальным идентификатором ранее созданного меню.

Пример:

GS 'Меню.Удалить', 'Меню'

Перечень изменений

Версия 1.1:





Copyright © 2011 iFiction.Ru / Olegus t.Gl. · Пользуйтесь с умом и по закону. Гарантии не прилагаются.