|
|
| Line 1: |
Line 1: |
| __NOTOC__
| |
| {{RU/Server client function}}
| |
| {{Needs_Checking|sourceResource is not as described}}
| |
| {{Note_box|Настоятельно не рекомендуется использовать одинаковые названия для события и функции-обработчика, поскольку это может привести к путанице в том случае, если на это событие будут добавлены несколько разных обработчиков.}}
| |
| Эта функция прикрепляет к событию ( [[event]] ) обработчик. Обработчик - это функция, которая будет вызываться каждый раз, когда происходит событие, к которому она была прикреплена. Подробнее о работе системы событий смотрите в статье [[event system]].
| |
|
| |
|
| Обработчики - это функции, вызываемые каждый раз, когда происходит событие. Каждое событие имеет определенный набор параметров, которые передаются обработчику и могут считываться вашей функцией обработки. Кроме этого внутри любой функции-обработчика доступны следующие глобальные переменные:
| |
| *'''source''': это тот элемент, который вызывал срабатывание события.
| |
| *'''this''': это элемент, к которому был прикреплен обработчик с помощью addEventHandler
| |
| <!-- mom, it's broken
| |
| *'''sourceResource''': ресурс, который вызвал событие
| |
| *'''sourceResourceRoot''': элемент-корень (root element) ресурса, вызвавшего событие
| |
| -->
| |
| *'''client''': клиент, который вызвал событие с помошью [[triggerServerEvent]]. Если событие вызвано не клиентской стороной, то не используется.
| |
| {{New_feature|3|1.0|
| |
| *'''eventName''': название того события, которое вызвало функцию-обработчик.
| |
| }}
| |
|
| |
| Важно помнить, что события распространяются вверх и вниз по дереву элементов. Событие, сработавшее на корне (root), срабатывает для всех элементов дерева. Событие, вызванное на любом другом элементе, распространится на всех предков (элемент-родитель, родитель родителя и т.д.) и всех потомков. Для того, чтобы уточнить, будет ли обработчик срабатывать, если событие было вызвано не для указанного элемента, а распространилось по дереву от других элементов, вы можете использовать параметр ''getPropagated''.
| |
|
| |
| Порядок вызова обработчиков в том случае, если их несколько, неопределен. Не следует полагаться на то, что один обработчик сработает раньше другого.
| |
|
| |
| ==Синтаксис==
| |
| <syntaxhighlight lang="lua">
| |
| bool addEventHandler ( string eventName, element attachedTo, function handlerFunction, [bool getPropagated = true, string priority = "normal" ] )
| |
| </syntaxhighlight>
| |
|
| |
| ===Обязательные аргументы===
| |
| *'''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'', если не существует указанного события, или переданы некорректные параметры.
| |
|
| |
| ==Пример==
| |
| <section name="Server" class="server" show="true">
| |
| В этом примере сервер отправляет всем игрокам сообщение, когда спавнится какой-либо игрок.
| |
| <syntaxhighlight lang="lua">
| |
| -- получаем указатель на элемент-корень
| |
| rootElement = getRootElement()
| |
| -- описываем функцию для обработки
| |
| function onPlayerSpawnHandler ( thePlayer )
| |
| -- получаем имя игрока
| |
| local playerName = getPlayerName( thePlayer )
| |
| -- отправляем всем сообщение о спавне игрока с указанным именем
| |
| outputChatBox ( playerName .. " has spawned!" )
| |
| end
| |
|
| |
| addEventHandler( "onPlayerSpawn", rootElement, onPlayerSpawnHandler )
| |
| </syntaxhighlight>
| |
| </section>
| |
|
| |
| Также в качестве параметра ''handlerFunction:'' можно использовать "безымянные" функции, описывая их в вызове addEventHandler. Для этого используется конструкция:
| |
| <syntaxhighlight lang="lua">
| |
| addEventHandler( "someEvent", someElement, function (argument1, argument2)
| |
| --здесь можно описывать функцию-обработчик
| |
| end)
| |
| </syntaxhighlight>
| |
| что будет эквивалентно
| |
| <syntaxhighlight lang="lua">
| |
| function someFunction (argument1, argument2)
| |
| --здесь можно описывать функцию-обработчик
| |
| end
| |
| addEventHandler( "someEvent", someElement,someFunction )
| |
| </syntaxhighlight>
| |
|
| |
| ==Журнал изменений==
| |
| {{ChangelogHeader}}
| |
| {{ChangelogItem|1.3.0-9.03795|Добавлен аргумент priority}}
| |
|
| |
| ==Смотрите также==
| |
| {{RU/Event_functions}}
| |
|
| |
| [[en:addEventHandler]]
| |