---
name: "displayAddEventHandler"
type: command
status: ok
groups: ["GUI Control - Event Handlers", "Event Handlers"]
arma3_since: "0.50"
locality: {"argument": null, "effect": null, "server_exec": false}
source: https://community.bistudio.com/wiki/displayAddEventHandler
revid: 369069
updated: 2024-09-02T20:24:59Z
---

# displayAddEventHandler

*Command · GUI Control - Event Handlers, Event Handlers · Arma 3 v0.50 · introduced in Arma 2 v1.00*

## Description

Adds an event handler to the given display. See [User Interface Event Handlers](../topics/User_Interface_Event_Handlers.md) for the full list of event names.
If applicable, see DIK_KeyCodes for a list of key code constants, which are relevant to key related user interface events like: [KeyDown](../topics/User_Interface_Event_Handlers.md#onkeydown) & [KeyUp](../topics/User_Interface_Event_Handlers.md#onkeyup).

> [!IMPORTANT]
> Display EHs are processed from last to first added; an input override should be set up in the first added EH.

> [!NOTE]
> The event handler ID can be accessed inside the event handler code using the `_thisEventHandler` [magic variable](../topics/Magic_Variables.md#thiseventhandler).

## Syntax

```sqf
display displayAddEventHandler [eventName, code]
```

**Parameters:**

- `display`: [Display](../topics/Display.md)
- `eventName`: [String](../topics/String.md) - event name

  > [!IMPORTANT]
  > When using the event names listed [here](../topics/User_Interface_Event_Handlers.md) with the [ctrlAddEventHandler](../commands/ctrlAddEventHandler.md), [ctrlSetEventHandler](../commands/ctrlSetEventHandler.md), [displayAddEventHandler](../commands/displayAddEventHandler.md) or [displaySetEventHandler](../commands/displaySetEventHandler.md) commands, the prefix "on" in the event name must be removed (e.g. **'ButtonDown**' instead of **'onButtonDown**').
- `code`: [String](../topics/String.md) or Arma 3 v1.06 [Code](../topics/Code.md) - the code which gets executed when event is triggered. Returning [true](../commands/true.md) in event handler code will override default engine handling for keyboard events.
  Several [Magic Variables](../topics/Magic_Variables.md) are available:
  - Event Handler parameters are accessible via `_this`
  - The Event Handler type is available as `_thisEvent`
  - The Event Handler index is available as `_thisEventHandler`

**Returns:** [Number](../topics/Number.md) - index of the newly added event handler or `-1` if creation failed

## Examples

### Example 1

```sqf
moduleName_keyDownEHId = findDisplay 46 displayAddEventHandler ["KeyDown", "hint str _this;"];
```

### Example 2

```sqf
moduleName_keyDownEHId = findDisplay 46 displayAddEventHandler ["KeyDown", { hint str _this }];
```

## See also

[disableSerialization](../commands/disableSerialization.md) · [displayRemoveAllEventHandlers](../commands/displayRemoveAllEventHandlers.md) · [displayRemoveEventHandler](../commands/displayRemoveEventHandler.md) · [displaySetEventHandler](../commands/displaySetEventHandler.md) · [ctrlAddEventHandler](../commands/ctrlAddEventHandler.md) · [User Interface Event Handlers](../topics/User_Interface_Event_Handlers.md) · [findDisplay](../commands/findDisplay.md) · DIK KeyCodes · [keyName](../commands/keyName.md)

## Community notes

**Axyl** — 2014-03-10

From within an Addon, you must assign the events from a spawned script.  e.g. 

```sqf
0 spawn { findDisplay 46 displayAddEventHandler ["KeyDown", "_this call my_KeyDownFunctionhandler"]; };
```

---

**Pigneedle** — 2016-01-22

Be sure to wait until the main display is initialized before using this command by using:

```sqf
waitUntil { !isNull (findDisplay 46) };
```

---

**Nelis75733126** — 2017-05-28

use ([#define](../topics/PreProcessor_Commands.md#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](../commands/format.md) to the second parameter.

---

**DrSova** — 2017-08-07

Using **KeyUp** you can't override default engine action by returning **true**

---

**R3vo** — 2021-06-26

To prevent a display from getting closed by pressing ESC, add the following event handler.

```sqf
#include "\a3\ui_f\hpp\definedikcodes.inc"
_display displayAddEventHandler ["KeyDown",
{
    params ["", "_key"];
    _key == DIK_ESC; // ESC pressed while dialog is open, overwrite default behaviour
}];
```

<sub>Source: [BI Community Wiki — displayAddEventHandler](https://community.bistudio.com/wiki/displayAddEventHandler) (revision 369069).</sub>