RU/addEventHandler

	This article needs checking.
	Reason(s): sourceResource is not as described

This template is no longer in use as it results in poor readability. Эта функция прикрепляет к событию ( event ) обработчик. Обработчик - это функция, которая будет вызываться каждый раз, когда происходит событие, к которому она была прикреплена. Подробнее о работе системы событий смотрите в статье event system.

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

• source: это тот элемент, который вызывал срабатывание события.
• this: это элемент, к которому был прикреплен обработчик с помощью addEventHandler
• sourceResource: ресурс, который вызвал событие
• sourceResourceRoot: элемент-корень (root element) ресурса, вызвавшего событие
• client: клиент, который вызвал событие с помошью triggerServerEvent. Если событие вызвано не клиентской стороной, то не используется.

• eventName: название того события, которое вызвало функцию-обработчик.

Важно помнить, что события распространяются вверх и вниз по дереву элементов. Событие, сработавшее на корне (root), срабатывает для всех элементов дерева. Событие, вызванное на любом другом элементе, распространится на всех предков (элемент-родитель, родитель родителя и т.д.) и всех потомков. Для того, чтобы уточнить, будет ли обработчик срабатывать, если событие было вызвано не для указанного элемента, а распространилось по дереву от других элементов, вы можете использовать параметр getPropagated.

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

Синтаксис

bool addEventHandler ( string eventName, element attachedTo, function handlerFunction, [bool getPropagated = true] )    

Обязательные аргументы

• eventName: Название события event к которому вы хотите прикрепить функцию-обработчик.
• attachedTo: Элемент (element) , к которому вы хотите прикрепить обработчик. Обработчик будет вызван только если указанное событие сработает для этого элемента или одного из его потомков.
• handlerFunction: Функция-обработчик, которую вы будете вызывать, когда срабатывает событие. Функции будет передан весь набор параметров для этого события, хотя совсем не обязательно, чтобы функция принимала их все.

Замечание 1: Обратите внимание, что функция с таким названием должна быть определена до того, как она будет использоваться в addEventHandler (в противном случае возникнет ошибка "string-defined function").

Замечание 2: Следует различать саму функцию и ее вызов. Вызов функции обозначается с помощью скобок (), внутри которых также записываются необходимые аргументы. В обработчике же нужно указывать именно саму функцию, т.е. название без скобок () и каких-либо аргументов.

Дополнительные аргументы

• getPropagated: Логическая переменная (boolean) , которая определяет, будет ли вызываться обработчик, в том случае если событие распространилось по дереву элементов (начиная от source), а не было вызвано напрямую для attachedTo. Таким образом, если установлено значение false, то событие сработает тогда и только тогда, когда оно было вызвано для элемента attachedTo (т.е. если source == this).

Вывод

Возвращает true , если обработчик был успешно добавлен. Возвращает false, если не существует указанного события, или переданы некорректные параметры.

Пример

Click to collapse [-]

Server

В этом примере сервер отправляет всем игрокам сообщение, когда спавнится какой-либо игрок.

-- получаем указатель на элемент-корень
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 )

Смотрите также

Серверные функции

• getCancelReason - получает причину отмены события
• triggerClientEvent - позволяет вызвать срабатывание события, предварительно созданного на клиенте
• triggerLatentClientEvent - аналог triggerClientEvent, но скорость передачи может быть ограничена

Клиентские функции

• triggerLatentServerEvent - аналог triggerServerEvent, но скорость передачи может быть ограничена
• triggerServerEvent - позволяет вызвать срабатывание события, предварительно созданного на сервере

Общие функции

• addEvent - позволяет зарегистрировать своё собственное событие
• addEventHandler - прикрепляет к событию обработчик
• cancelEvent - останавливает автоматическую внутреннюю обработку события
• cancelLatentEvent - останавливает автоматическую внутреннюю обработку скрытого события
• getEventHandlers - получает прикреплённые функции из события и присоединённый элемент из текущего lua-скрипта
• getLatentEventHandles - получает текущие скрытые события в очереди
• getLatentEventStatus - получает состояние одного скрытого события в очереди
• removeEventHandler - открепляет от события обработчик
• triggerEvent - вызывает срабатывание указанного события для указанного элемента в дереве элементов
• wasEventCancelled - проверяет, было ли отменено последнее завершённое событие