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) , к которому вы хотите прикрепить обработчик. Обработчик будет вызван только если указанное событие сработает для этого элемента или одного из его потомков. Для того, чтобы обработчик вызывался при срабатывании события для любого элемента, используется корень (root), однако рекомендуется прикреплять обработчик к как можно более "конкретному" классу элементов.
• handlerFunction: Функция-обработчик, которую вы будете вызывать, когда срабатывает событие. Функции будет передан весь набор параметров для этого события, хотя совсем не обязательно, чтобы функция принимала их все. Обратите внимание, что функция с таким названием должна быть определена до того, как она будет использоваться в addEventHandler (в противном случае возникнет ошибка "string-defined function").

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

• 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 - проверяет, было ли отменено последнее завершённое событие