Версия: 1.1
Внутренний язык платформы 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 | Удаляет меню со всеми вспомогательными массивами, переменными и т.п. |
Создает новое меню.
Синтаксис:
GS 'Меню.Создать', <Имя меню>
Параметры:
Имя меню | Обязательный параметр. Строка с уникальным идентификатором меню. Идентификатор должен соответствовать требованиям QSP к именам переменных. |
Пример:
GS 'Меню.Создать', 'Меню'
Добавляет пункт к указанному меню.
Синтаксис:
GS 'Меню.ДобавитьПункт', <Имя меню>, <Название пункта>, <Путь к файлу иконки>, <Название локации-обработчика>, <Параметр 1>, <Параметр 2> …
Параметры:
Имя меню | Обязательный параметр. Строка с уникальным идентификатором ранее созданного меню. |
Название пункта | Обязательный параметр. Строка с уникальным названием пункта меню. Может состоять из любых символов. Если указать "---", то в меню будет вставлен разделитель. |
Путь к файлу иконки | Необязательный параметр. Путь к файлу иконки для пункта меню. |
Название локации-обработчика | Обязательный параметр (если этот пункт не является разделителем). Название локации, вызываемой для обработки выбора данного пункта меню. |
Параметр 1 Параметр 2 … Параметр N | Необязательные параметры. Значения параметров, передаваемых в локацию-обработчик. |
Пример:
GS 'Меню.ДобавитьПункт', 'Меню', 'Осмотреть комнату', '', 'ДействияВКомнате', 'осмотреть', 'бегло' GS 'Меню.ДобавитьПункт', 'Меню', 'Обыскать комнату', '', 'ДействияВКомнате', 'осмотреть', 'тщательно' GS 'Меню.ДобавитьПункт', 'Меню', '---'
Добавляет условие включения последнего добавленного пункта в указанное меню.
Синтаксис:
GS 'Меню.ДобавитьУсловие', <Имя меню>, <Условие>
Параметры:
Имя меню | Обязательный параметр. Строка с уникальным идентификатором ранее созданного меню. |
Условие | Обязательный параметр. Строка с программным кодом на языке QSP, возвращающим результат в переменной Result . Если возвращается 0, то данный пункт в момент вызова меню в меню не включается. При записи кода допускаются переносы строк, а также запись кода в виде {…код…} |
Пример:
GS 'Меню.ДобавитьПункт', 'Меню', 'Открыть сундук' GS 'Меню.ДобавитьУсловие', 'Меню', { if СундукОткрыт: !Если сундук открыт, то этот пункт в меню нам не нужен Result=0 else !Если сундук закрыт, то включаем этот пункт в меню Result=-1 end } GS 'Меню.ДобавитьПункт', 'Меню', 'Закрыть сундук' GS 'Меню.ДобавитьУсловие', 'Меню', "Result=IIF(СундукОткрыт,-1,0)"
Добавляет выполняемый код для последнего добавленного пункта в указанное меню.
Синтаксис:
GS 'Меню.ДобавитьМодуль', <Имя меню>, <Код модуля>
Параметры:
Имя меню | Обязательный параметр. Строка с уникальным идентификатором ранее созданного меню. |
Код модуля | Обязательный параметр. Строка с программным кодом на языке QSP, который будет выполнен при выборе данного пункта меню. При записи кода допускаются переносы строк, а также запись кода в виде {…код…} |
Пример:
GS 'Меню.ДобавитьПункт', 'Меню', 'Закрыть сундук' GS 'Меню.ДобавитьМодуль', 'Меню', { *NL *NL 'Крышка сундука захлопнулась с глухим щелчком.' СундукОткрыт=0 } GS 'Меню.ДобавитьПункт', 'Меню', 'Открыть сундук' GS 'Меню.ДобавитьМодуль', 'Меню', " *NL *NL 'Поколодовав немного над замком, вы открыли сундук.' СундукОткрыт=-1 "
Добавляет выполняемый код для одного из предопределённых событий работы с меню: "при выборе пункта", "после обработки выбора" и "при отказе от выбора".
Синтаксис:
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]+') в пещере!' }
Вызывает указанное меню и возвращает -1, если был выбран какой-нибудь пункт из меню (или 0 — если не был).
Синтаксис:
GS 'Меню.Вызвать', <Имя меню> func('Меню.Вызвать', <Имя меню>)
Параметры:
Имя меню | Обязательный параметр. Строка с уникальным идентификатором ранее созданного меню. |
Пример:
GS 'Меню.Вызвать', 'Меню' if func('Меню.Вызвать', 'Меню')=0: *NL 'Ничего не выбрали!'
Возвращает -1, если был выбран какой-нибудь пункт из меню (или 0 — если не был).
Синтаксис:
func('Меню.Выбрали', <Имя меню>)
Параметры:
Имя меню | Обязательный параметр. Строка с уникальным идентификатором ранее созданного меню. |
Пример:
if func('Меню.Выбрали', 'Меню')=0: *NL 'Ничего не выбрали!'
Возвращает время в миллисекундах (1/1000 секунды), затраченное игроком на выбор того или иного пункта из меню.
Синтаксис:
func('Меню.Время', <Имя меню>)
Параметры:
Имя меню | Необязательный параметр. Строка с уникальным идентификатором ранее созданного меню. Если данный параметр не указан, то возвращается время выбора пункта из последнего вызванного меню. |
Пример:
func('Меню.Время', 'Меню') func('Меню.Время')
Удаляет указанное меню со всеми вспомогательными массивами и переменными.
Синтаксис:
GS 'Меню.Удалить', <Имя меню>
Параметры:
Имя меню | Обязательный параметр. Строка с уникальным идентификатором ранее созданного меню. |
Пример:
GS 'Меню.Удалить', 'Меню'
Версия 1.1: