{"name":"displayAddEventHandler","title":"displayAddEventHandler","type":"command","url":"https://community.bistudio.com/wiki/displayAddEventHandler","revid":369069,"updated":"2024-09-02T20:24:59Z","groups":["GUI Control - Event Handlers","Event Handlers"],"status":"ok","games":{"arma2":"1.00","arma2oa":"1.50","tkoh":"1.00","arma3":"0.50"},"since":"arma2 1.00","arma3_since":"0.50","description":"Adds an event handler to the given display. See User Interface Event Handlers for the full list of event names.\nIf applicable, see DIK_KeyCodes for a list of key code constants, which are relevant to key related user interface events like: KeyDown & KeyUp.\n\n> [!IMPORTANT]\n> Display EHs are processed from last to first added; an input override should be set up in the first added EH.\n\n> [!NOTE]\n> The event handler ID can be accessed inside the event handler code using the `_thisEventHandler` magic variable.","syntaxes":[{"syntax":"display displayAddEventHandler [eventName, code]","params":[{"name":"display","type":"Display","type_expr":"Display"},{"name":"eventName","type":"String","description":"event name\n\n> [!IMPORTANT]\n> When using the event names listed here with the ctrlAddEventHandler, ctrlSetEventHandler, displayAddEventHandler or displaySetEventHandler commands, the prefix \"on\" in the event name must be removed (e.g. '**ButtonDown'** instead of '**onButtonDown'**).","type_expr":"String"},{"name":"code","type":"String or Arma 3 v1.06 Code","description":"the code which gets executed when event is triggered. Returning true in event handler code will override default engine handling for keyboard events.\nSeveral Magic Variables are available:\n\n- Event Handler parameters are accessible via `_this`\n- The Event Handler type is available as `_thisEvent`\n- The Event Handler index is available as `_thisEventHandler`","type_expr":"String | Code"}],"returns":{"type":"Number","type_expr":"Number","description":"index of the newly added event handler or `-1` if creation failed"},"form":"binary","left":{"text":"display"},"right":{"text":"[eventName, code]"}}],"examples":[{"code":["moduleName_keyDownEHId = findDisplay 46 displayAddEventHandler [\"KeyDown\", \"hint str _this;\"];"]},{"code":["moduleName_keyDownEHId = findDisplay 46 displayAddEventHandler [\"KeyDown\", { hint str _this }];"]}],"see_also":["disableSerialization","displayRemoveAllEventHandlers","displayRemoveEventHandler","displaySetEventHandler","ctrlAddEventHandler","User Interface Event Handlers","findDisplay","DIK KeyCodes","keyName"],"notes":[{"user":"Axyl","date":"2014-03-10T14:52:00Z","text":"From within an Addon, you must assign the events from a spawned script. e.g.\n\n```sqf\n0 spawn { findDisplay 46 displayAddEventHandler [\"KeyDown\", \"_this call my_KeyDownFunctionhandler\"]; };\n```"},{"user":"Pigneedle","date":"2016-01-22T08:15:00Z","text":"Be sure to wait until the main display is initialized before using this command by using:\n\n```sqf\nwaitUntil { !isNull (findDisplay 46) };\n```"},{"user":"Nelis75733126","date":"2017-05-28T11:32:00Z","text":"use (\n#define) if you want `displayAddEventHandler` to use data defined in the same script. You can then integrate that data either directly, or by applying format to the second parameter."},{"user":"DrSova","date":"2017-08-07T15:08:00Z","text":"Using **KeyUp** you can't override default engine action by returning **true**"},{"user":"R3vo","date":"2021-06-26T16:17:00Z","text":"To prevent a display from getting closed by pressing ESC, add the following event handler.\n\n```sqf\n#include \"\\a3\\ui_f\\hpp\\definedikcodes.inc\"\n_display displayAddEventHandler [\"KeyDown\",\n{\n    params [\"\", \"_key\"];\n    _key == DIK_ESC; // ESC pressed while dialog is open, overwrite default behaviour\n}];\n```"}]}