SetHandler

From ESOUI Wiki

Jump to: navigation, search

Controls got the possibility to register handlers on them. With these handlers you are able to react with your custom code (callback function)
if a defined event at this control fires (e.g. initialization, mouse click, mouse double click, mouse button down, mouse button up, resize, drag, drop, move, ...).
The syntax of the event handler register function is:
control:SetHandler

* SetHandler(*string* _eventName_, *function* _functionRef_, *string* _name_, *[ControlHandlerOrder|#ControlHandlerOrder]* _controlHandlerOrder_, *string* _targetName_)
 
CONTROL_HANDLER_ORDER_NONE = 0
CONTROL_HANDLER_ORDER_BEFORE = 1
CONTROL_HANDLER_ORDER_AFTER = 2

So by the help of the SetHandler function of a control you are able to register callback functions _functionRef_ which are executed as the specified handler event _eventName_ raises.
The eventname must be one of the possible On* events (which inherit from OnSetControlEventHandler). Here is a link to the UI XML information wiki page containing the event handlers (starting with "On").
Please notice that not all control types support all handlers! e.g. a label control got no OnClick but only an OnMouseDown event handler, and a button control got no OnDurationChanged handler of an animation timeline!

On* - Event handlers


The parameter _name_ is used to define e.g. an AddOn name used for the register of this handler. Other AddOns can use e.g. the same string value in their _targetName_ parameter to specify at what time
their callback function _functionRef_ should be called, in relation to the other AddOns's _name_ callback function: Before or after -> Defined via the parameter _controlHandlerOrder_

Example:
AddOn1 with the name "MyAddon1" sets an OnMouseUp handler on a label control:

labelCtrl:SetHandler("OnMouseUp", function(self, mouseButton, upInside, shift, ctrl, alt, command) 
    --code here 
end, "MyAddon1")


AddOn2 with the name "MyAddon2" sets an OnMouseUp handler on the same label control, but wants to run it's code before MyAddon1's OnMouseUp handler on the same label:

labelCtrl:SetHandler("OnMouseUp", function(self, mouseButton, upInside, shift, ctrl, alt, command) 
    --code run before MyAddon1's callback function here 
end, "MyAddon2", CONTROL_HANDLER_ORDER_BEFORE , "MyAddon1")


The SetHandler function of controls can also be applied directly at the XML of controls, by using the appropriate XML tags, e.g.

   <OnInitialized>
   </OnInitialized>
   <OnMouseUp> 
     --Your lua code can be executed here, e.g.
     --Variable self points to the current XML control
     --Other variables of the event parameters can be used like button and upinside of OnMouseUp
     if button == MOUSE_BUTTON_INDEX_LEFT and upinside then
       d("Left mouse button pressed at " .. tostring(self:GetName())
     end
 
   </OnMouseUp>


XML handler elements such as <OnUpdate> now also have attributes for name, target, and order.

This basically replaces the functions ZO_PreHookHandler and ZO_PostHookHandler with more detailed possibilities.

ESO API patch notes announcing the Control Handler Order

Personal tools
Namespaces
Variants
Actions
Menu
Wiki
Toolbox