RU/addEventHandler
| Note: Настоятельно не рекомендуется использовать одинаковые названия для события и функции-обработчика, поскольку это может привести к путанице в том случае, если на это событие будут добавлены несколько разных обработчиков. |
Эта функция прикрепляет к событию ( event ) обработчик. Обработчик - это функция, которая будет вызываться каждый раз, когда происходит событие, к которому она была прикреплена. Подробнее о работе системы событий смотрите в статье event system.
Обработчики - это функции, вызываемые каждый раз, когда происходит событие. Каждое событие имеет определенный набор параметров, которые передаются обработчику и могут считываться вашей функцией обработки. Кроме этого внутри любой функции-обработчика доступны следующие глобальные переменные:
- source: это тот элемент, который вызывал срабатывание события.
- this: это элемент, к которому был прикреплен обработчик с помощью addEventHandler
- client: клиент, который вызвал событие с помошью triggerServerEvent. Если событие вызвано не клиентской стороной, то не используется.
- eventName: название того события, которое вызвало функцию-обработчик.
Важно помнить, что события распространяются вверх и вниз по дереву элементов. Событие, сработавшее на корне (root), срабатывает для всех элементов дерева. Событие, вызванное на любом другом элементе, распространится на всех предков (элемент-родитель, родитель родителя и т.д.) и всех потомков. Для того, чтобы уточнить, будет ли обработчик срабатывать, если событие было вызвано не для указанного элемента, а распространилось по дереву от других элементов, вы можете использовать параметр getPropagated.
Порядок вызова обработчиков в том случае, если их несколько, неопределен. Не следует полагаться на то, что один обработчик сработает раньше другого.
Синтаксис
bool addEventHandler ( string eventName, element attachedTo, function handlerFunction, [bool getPropagated = true, string priority = "normal" ] )
Обязательные аргументы
- eventName: Название события event к которому вы хотите прикрепить функцию-обработчик.
- attachedTo: Элемент (element), к которому вы хотите прикрепить обработчик. Обработчик будет вызван только если указанное событие сработает для этого элемента или одного из его потомков.
- handlerFunction: Функция-обработчик, которую вы будете вызывать, когда срабатывает событие. Функции будет передан весь набор параметров для этого события, хотя совсем не обязательно, чтобы функция принимала их все.
Замечание 1: Обратите внимание, что функция с таким названием должна быть определена до того, как она будет использоваться в addEventHandler (в противном случае возникнет ошибка "string-defined function").
Замечание 2: Следует различать саму функцию и ее вызов. Вызов функции обозначается с помощью скобок (), внутри которых также записываются необходимые аргументы. В обработчике же нужно указывать именно саму функцию, т.е. название без скобок () и каких-либо аргументов.
Дополнительные аргументы
- getPropagated: Логическая переменная (boolean), которая определяет, будет ли вызываться обработчик, в том случае если событие распространилось по дереву элементов (начиная от source), а не было вызвано напрямую для attachedTo. Таким образом, если установлено значение false, то событие сработает тогда и только тогда, когда оно было вызвано для элемента attachedTo (т.е. если source == this).
- priority: Строковая переменная (string), представляющая приоритет порядка запуска по отношению к другим обработчикам событий такого же имени. Возможные значения:
- "high"
- "normal"
- "low"
Замечание: Кроме того, можно добавить более точные приоритетные установки, добавив положительное или отрицательное число к строке приоритета. Например (в порядке убывания приоритета): "high+4" "high" "high-1" "normal-6" "normal-7" "low+1" "low" "low-1".
Вывод
Возвращает true , если обработчик был успешно добавлен. Возвращает false, если не существует указанного события, или переданы некорректные параметры.
Пример
В этом примере сервер отправляет всем игрокам сообщение, когда спавнится какой-либо игрок.
-- получаем указатель на элемент-корень rootElement = getRootElement() -- описываем функцию для обработки function onPlayerSpawnHandler ( thePlayer ) -- получаем имя игрока local playerName = getPlayerName( thePlayer ) -- отправляем всем сообщение о спавне игрока с указанным именем outputChatBox ( playerName .. " has spawned!" ) end addEventHandler( "onPlayerSpawn", rootElement, onPlayerSpawnHandler )
Также в качестве параметра handlerFunction: можно использовать "безымянные" функции, описывая их в вызове addEventHandler. Для этого используется конструкция:
addEventHandler( "someEvent", someElement, function (argument1, argument2) --здесь можно описывать функцию-обработчик end)
что будет эквивалентно
function someFunction (argument1, argument2) --здесь можно описывать функцию-обработчик end addEventHandler( "someEvent", someElement,someFunction )
Журнал изменений
| Version | Description |
|---|
| 1.3.0-9.03795 | Добавлен аргумент priority |
