RU/addEventHandler: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
mNo edit summary
m (prefer normal note)
 
(8 intermediate revisions by 5 users not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__  
{{RU/Server client function}}
{{RU/Server client function}}
{{Needs_Checking|sourceResource is not as described}}
{{Note|Настоятельно не рекомендуется использовать одинаковые названия для события и функции-обработчика, поскольку это может привести к путанице в том случае, если на это событие будут добавлены несколько разных обработчиков.}}
{{Note_box|Настоятельно не рекомендуется использовать одинаковые названия для события и функции-обработчика, поскольку это может привести к путанице в том случае, если на это событие будут добавлены несколько разных обработчиков.}}
Эта функция прикрепляет к событию ( [[event]] ) обработчик. Обработчик - это функция, которая будет вызываться каждый раз, когда происходит событие, к которому она была прикреплена. Подробнее о работе системы событий смотрите в статье [[event system]].
Эта функция прикрепляет к событию ( [[event]] ) обработчик. Обработчик - это функция, которая будет вызываться каждый раз, когда происходит событие, к которому она была прикреплена. Подробнее о работе системы событий смотрите в статье [[event system]].


Line 8: Line 7:
*'''source''': это тот элемент, который вызывал срабатывание события.
*'''source''': это тот элемент, который вызывал срабатывание события.
*'''this''': это элемент, к которому был прикреплен обработчик с помощью addEventHandler
*'''this''': это элемент, к которому был прикреплен обработчик с помощью addEventHandler
<!-- mom, it's broken
*'''sourceResource''': ресурс, который вызвал событие
*'''sourceResource''': ресурс, который вызвал событие
*'''sourceResourceRoot''': элемент-корень (root element) ресурса, вызвавшего событие
*'''sourceResourceRoot''': элемент-корень (root element) ресурса, вызвавшего событие
-->
*'''client''': клиент, который вызвал событие с помошью [[triggerServerEvent]]. Если событие вызвано не клиентской стороной, то не используется.
*'''client''': клиент, который вызвал событие с помошью [[triggerServerEvent]]. Если событие вызвано не клиентской стороной, то не используется.
{{New_feature|3|1.0|
{{New_feature|3|1.0|
Line 21: Line 22:
==Синтаксис==  
==Синтаксис==  
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
bool addEventHandler ( string eventName, element attachedTo, function handlerFunction, [bool getPropagated = true] )     
bool addEventHandler ( string eventName, element attachedTo, function handlerFunction, [bool getPropagated = true, string priority = "normal" ] )     
</syntaxhighlight>  
</syntaxhighlight>  


===Обязательные аргументы===  
===Обязательные аргументы===  
*'''eventName:''' Название события [[event]] к которому вы хотите прикрепить функцию-обработчик.
*'''eventName:''' Название события [[event]] к которому вы хотите прикрепить функцию-обработчик.
*'''attachedTo:''' Элемент ([[element]]) , к которому вы хотите прикрепить обработчик. Обработчик будет вызван только если указанное событие сработает для этого элемента или одного из его потомков. Для того, чтобы обработчик вызывался при срабатывании события для ''любого'' элемента, используется корень (root), однако рекомендуется прикреплять обработчик к как можно более "конкретному" классу элементов.  
*'''attachedTo:''' Элемент ([[element]]), к которому вы хотите прикрепить обработчик. Обработчик будет вызван только если указанное событие сработает для этого элемента или одного из его потомков.
*'''handlerFunction:''' Функция-обработчик, которую вы будете вызывать, когда срабатывает событие. Функции будет передан весь набор параметров для этого события, хотя совсем не обязательно, чтобы функция принимала их все. Обратите внимание, что функция с таким названием должна быть определена до того, как она будет использоваться в addEventHandler (в противном случае возникнет ошибка "string-defined function").
*'''handlerFunction:''' Функция-обработчик, которую вы будете вызывать, когда срабатывает событие. Функции будет передан весь набор параметров для этого события, хотя совсем не обязательно, чтобы функция принимала их все.  
''Замечание 1'': Обратите внимание, что функция с таким названием должна быть определена до того, как она будет использоваться в addEventHandler (в противном случае возникнет ошибка "string-defined function").
 
''Замечание 2'': Следует различать саму функцию и ее вызов. Вызов функции обозначается с помощью скобок (), внутри которых также записываются необходимые аргументы. В обработчике же нужно указывать именно саму функцию, т.е. название без скобок () и каких-либо аргументов.  


===Дополнительные аргументы===
===Дополнительные аргументы===
*'''getPropagated:''' Логическая переменная (boolean) , которая определяет, будет ли вызываться обработчик, в том случае если событие распространилось по дереву элементов (начиная от source), а не было вызвано напрямую для ''attachedTo''. Таким образом, если установлено значение ''false'', то событие сработает тогда и только тогда, когда оно было вызвано для элемента ''attachedTo'' (т.е. если ''source == this'').
*'''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".


===Вывод===
===Вывод===
Line 66: Line 75:
addEventHandler( "someEvent", someElement,someFunction )
addEventHandler( "someEvent", someElement,someFunction )
</syntaxhighlight>
</syntaxhighlight>
==Журнал изменений==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.03795|Добавлен аргумент priority}}


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

Latest revision as of 08:38, 7 September 2019

[[{{{image}}}|link=|]] 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, если не существует указанного события, или переданы некорректные параметры.

Пример

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 )

Журнал изменений

Version Description
1.3.0-9.03795 Добавлен аргумент priority

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

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

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

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

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

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

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