View source for ES/addEventHandler

__NOTOC__ 
{{Server client function}} {{Note|Se recomienda encarecidamente que no usen el mismo nombre para la función de controlador y para el nombre del evento, ya que puede producir confusión si se usan múltiples funciones de controlador.}}
Esta función añadirá un controlador de eventos. Un controlador de eventos es una función que se llamará cuando el evento que está unido sea provocado. Mira el [[Sistema de eventos]] para mas informacion sobre como funciona el sistema de eventos.

Los controladores de eventos son funciones que son llamadas cuando un evento en particular sucede. Cada evento especifica una seria específica de variables que son pasadas hacia el controlador de eventos y pueden ser leídas por la función. Las siguientes variables globales están disponibles para usarlas en funciones de controlador:
*'''source''': el elemento que provoca el evento
*'''this''': el elemento al cual está unido el controlador de eventos
<!-- mom, it's broken
*'''sourceResource''': el resource que provocó el evento
*'''sourceResourceRoot''': el elemento raíz del resource que provocó el evento
-->
*'''client''': el cliente que provocó el evento usando [[ES/triggerServerEvent|triggerServerEvent]]. No establecer si el evento no fue provocado por un cliente.
{{New_feature|3|1.0|
*'''eventName''': el nombre del evento que provocó la funcion de controlador.
}}

Es importante recordar que se mueven hacia arriba o hacia abajo en el árbol de elementos. Un evento provocado sobre el elemento raíz es provocado sobre cada elemento del árbol. Un evento provocado sobre cualquier otro elemento es provocado sobre sus antecesores (su elemento padre, los padres de sus padres, etc) y sus hijos, nietos y bisnietos. Puedes usar el argumento ''getPropagated'' para especificar si deseas que el controlador reciba eventos que se han propagado hacia arriba o hacia abajo del árbol.

El orden en el cual los controladores de eventos son provocados no está definido, no debes confiarte de un controlador de evento que está siendo ejecutado antes de otro.

==Sintaxis== 
<syntaxhighlight lang="lua">
bool addEventHandler ( string nombreEvento, element unidoA, function funcionControlador, [ bool getPropagated = true, string pioridad= "normal" ] )    
</syntaxhighlight> 

===Argumentos Requeridos=== 
*'''nombreEvento:''' El nombre del evento al que quieres unir la funcion de controlador.
*'''unidoA:''' El [[elemento]] al que deseas unir el controlador. El controlador solo será llamado cuando el evento al que está unido sea provocado para este elemento, o uno de sus hijos. Generalmente, puede ser el elemento raíz (queriendo decir que el controlador será llamado cuando el evento sea provocado para ''cualquier'' elemento).
*'''funcionControlador:''' La función de controlador que deseas llamar cuando el evento sea provocado. Esta función pasará todos los parámetros del evento como argumentos, pero no es requerido ya que los toma todos.

===Argumentos Opcionales===
*'''getPropagated:''' Un boolean que representa si el controlador será provocado si el evento fue propagado hacia arriba o hacia abajo del árbol de elementos (comenzando del origen), y no provocado directamente sobre unidoA (esto es, si los controladores que estan están unidos tienen este argumento establecido en ''false'' solo serán profocados si ''source == this'').
{{New_feature|3.0139|1.3.1|
*'''prioridad :''' Un string que representa la prioridad del orden de provocaión relativo a otros controladores de eventos con el mismo nombre. Los valores posibles son:
**'''high :''' alto
**'''normal : ''' normal
**'''low :''' bajo
''Tambien es posible agregar un mejor control de prioridad by añadiendo un número positivo o negativo al string de prioridad. Por ejemplo (en orden de prioridad de preferencia): "high+4" "high" "high-1" "normal-6" "normal-7" "low+1" "low" "low-1"''
}}

===Devuelve===
Devuelve ''true'' si el controlador de eventos fue unido con éxito. Devuelve ''false'' si el evento especificado se pudo encontrar o ningún parámetro es válido.

==Ejemplo==
<section name="Servidor" class="server" show="true">
En este ejemplo de servidor se envía un mensaje a todos dentro del servidor cuando un jugador aparece.
<syntaxhighlight lang="lua">
-- obtiene el elemento raíz
rootElement = getRootElement()
-- define nuestra función de controlador
function onPlayerSpawnHandler ( elJugador )
	-- obtiene el nombre del jugador
	local nombreJugador = getPlayerName( elJugador )
	-- muestra en la ventana de chat que han aparecido
	outputChatBox ( "¡Ha aparecido " .. nombreJugador .. "!" )
end

addEventHandler( "onPlayerSpawn", rootElement, onPlayerSpawnHandler )
</syntaxhighlight>
</section>

==Cambios==
{{ChangelogHeader}}
{{ChangelogItem|1.3.0-9.03795|Añadido argumento de prioridad}}

==Vea tambien==
{{Funciones de eventos}}
[[en:addEventHandler]]
[[ru:addEventHandler]]