{"name":"displayAddEventHandler","operator":null,"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","replaced_by":[],"games":[{"game":"arma2","name":"Arma 2","version":"1.00"},{"game":"arma2oa","name":"Arma 2: Operation Arrowhead","version":"1.50"},{"game":"tkoh","name":"Take On Helicopters","version":"1.00"},{"game":"arma3","name":"Arma 3","version":"0.50"}],"since":{"game":"arma2","name":"Arma 2","version":"1.00"},"arma3_since":"0.50","branch":null,"locality":{"argument":null,"effect":null,"server_exec":false},"exec":null,"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]","since":null,"effect":null,"exec":null,"params":[{"name":"display","type":"Display","optional":false,"default":null,"description":null,"types":["Display"],"since":null,"text":"display: Display"},{"name":"eventName","type":"String","optional":false,"default":null,"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**').","types":["String"],"since":null,"text":"eventName: String - 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**')."},{"name":"code","type":"String or Arma 3 v1.06 Code","optional":false,"default":null,"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- 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`","types":["String","Code"],"since":null,"text":"code: String or Arma 3 v1.06 Code - 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- 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`"}],"returns":{"type":"Number","types":["Number"],"description":"index of the newly added event handler or `-1` if creation failed","text":"Number - index of the newly added event handler or `-1` if creation failed"},"form":"binary","operator":null,"left":{"text":"display","types":["Display"]},"right":{"text":"[eventName, code]","types":["Array"]}}],"examples":[{"text":"```sqf\nmoduleName_keyDownEHId = findDisplay 46 displayAddEventHandler [\"KeyDown\", \"hint str _this;\"];\n```","code":["moduleName_keyDownEHId = findDisplay 46 displayAddEventHandler [\"KeyDown\", \"hint str _this;\"];"]},{"text":"```sqf\nmoduleName_keyDownEHId = findDisplay 46 displayAddEventHandler [\"KeyDown\", { hint str _this }];\n```","code":["moduleName_keyDownEHId = findDisplay 46 displayAddEventHandler [\"KeyDown\", { hint str _this }];"]}],"multiplayer":null,"problems":null,"aliases":[],"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 (#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```"}],"categories":["Arma 2: New Scripting Commands","Arma 2: Operation Arrowhead: Scripting Commands","Arma 2: Scripting Commands","Arma 3: Scripting Commands","Command Group: Event Handlers","Command Group: GUI Control - Event Handlers","Introduced with Arma 2 version 1.00","Scripting Commands","Take On Helicopters: Scripting Commands"]}