---
name: "User Interface Event Handlers"
type: topic
aliases: ["Arma 3: Event Handlers/User Interface", "Arma 3: User Interface Event Handlers", "UIEH"]
source: https://community.bistudio.com/wiki/User_Interface_Event_Handlers
revid: 378424
updated: 2026-04-06T13:41:34Z
---
# User Interface Event Handlers
__NOEDITSECTION__
User Interface Event Handlers are used to execute code when events related to GUI components (i.e. [Display](../topics/Display.md)s and [Control](../topics/Control.md)s) occur.
> [!WARNING]
> About [ctrlDelete](../commands/ctrlDelete.md) in an Event Handler's script: [ctrlDelete](../commands/ctrlDelete.md) needs to be the last executed statement or Arma will crash.
>
> Alternatively, the code can also be [spawned](../topics/Scheduler.md) to circumvent this issue.
>
> ```cpp
> onButtonClick = "ctrlDelete (_this select 0); systemChat 'You will never see this';"; // Crashes the game
> onButtonClick = "systemChat 'Bye bye button!'; ctrlDelete (_this select 0);"; // Works fine
> onButtonClick = "_this spawn { ctrlDelete (_this select 0); systemChat 'Bye bye button!'; };"; // Works fine
> ```
### Reference List
#### Generic Events
##### onLoad
- **Use on:** Display, Control
- **Fired on:** Fires when UI container is created, but no action is taken. The `onLoad` event for display fires **after** the `onLoad` events for all controls it contains are fired.
- **Returns:** Display or control, for controls it also returns the control's config (since Arma 3 v1.56).
```sqf
params ["_displayOrControl", ["_config", configNull]];
```
> [!NOTE]
> The order of initialisation is as follows:
> 1. all controls, top to bottom.
> 1. Display
> This means that during the `onLoad` event of the upper controls the lower controls have yet to be created.
##### onUnload
- **Use on:** Display
- **Fired on:** Display is closed, but no controls are destroyed yet.
- **Returns:** Returns the display and exit code.
```sqf
params ["_display", "_exitCode"];
```
> [!NOTE]
> The `onUnload` event never fires for RscTitles displays created with [cutRsc](../commands/cutRsc.md).
> [!WARNING]
> Code or function should be [call](../commands/call.md)ed, otherwise controls might be destroyed before [spawn](../commands/spawn.md)ed code is executed!
##### onChildDestroyed
- **Use on:** Display
- **Fired on:** Child display is closed.
- **Returns:** Returns the display, which child display was closed and exit code.
```sqf
params ["_display", "_closedChildDisplay", "_exitCode"];
```
##### onCommitted (Arma 3 v2.14)
- **Use on:** Control
- **Fired on:** [ctrlSetFade](../commands/ctrlSetFade.md), [ctrlSetScale](../commands/ctrlSetScale.md), [ctrlSetAngle](../commands/ctrlSetAngle.md) and [ctrlSetPosition](../commands/ctrlSetPosition.md) in combination with [ctrlCommit](../commands/ctrlCommit.md).
- **Returns:** Returns the control, type of animation (`"alpha"`, `"scale"`, `"rotation"` or `"position"`) and the committed time.
```sqf
params ["_control", "_animType", "_animTime"];
```
##### onEditChanged (Arma 3 v2.14)
- **Use on:** Control
- **Fired on:** Any changes to the CT_EDIT text field content.
- **Returns:** Returns the control and the changed text.
```sqf
params ["_control", "_newText"];
```
##### onMouseEnter
- **Use on:** Control
- **Fired on:** The mouse pointer enters the control area.
- **Returns:** Returns control.
```sqf
params ["_control"];
```
> [!NOTE]
> The `onMouseEnter` event only fires on enabled buttons (see [ctrlEnable](../commands/ctrlEnable.md)).
>
> Arma 3 v2.18 This event handler type seems to only work on controls that can be interacted with. For example buttons, listboxes and so on.
##### onMouseExit
- **Use on:** Control
- **Fired on:** The mouse pointer exits the control area.
- **Returns:** Returns control.
```sqf
params ["_control"];
```
> [!NOTE]
> Arma 3 v2.18 This event handler type seems to only work on controls that can be interacted with. For example buttons, listboxes and so on.
##### onSetFocus
- **Use on:** Control
- **Fired on:** Input focus is on control. It now begins to accept keyboard input.
- **Returns:** Returns control.
```sqf
params ["_control"];
```
##### onKillFocus
- **Use on:** Control
- **Fired on:** Input focus is no longer on control. It no longer accepts keyboard input.
- **Returns:** Returns control.
```sqf
params ["_control"];
```
##### onTimer
- **Use on:** Control
- **Fired on:** N/A.
- **Returns:** N/A.
> [!NOTE]
> This feature has yet to be implemented.
##### onKeyDown
- **Use on:** Display, Control
- **Fired on:** Pressing any keyboard key. Fired before the [`onKeyUp`](../topics/User_Interface_Event_Handlers.md#onkeyup) event.
- **Returns:** Returns the display or control, the keyboard code and the state of Shift, Ctrl and Alt.
```sqf
params ["_displayOrControl", "_key", "_shift", "_ctrl", "_alt"];
true // Intercepts the default action, e.g. pressing Escape won't close the dialog.
```
In Arma 3, in order to be able to intercept key events during gameplay, the Event Handler should be added to Display 46:
```sqf
findDisplay 46 displayAddEventHandler ["KeyDown", {}];
```
In general, one should never return [true](../commands/true.md) in the `onKeyDown` EH, especially if it's added to Display 46 - otherwise all input is overridden and there is no way to do anything in the game anymore.
> [!WARNING]
> Pressing and holding key triggers 'autorepeat' action on Windows, which in turn will make this EH fire repeatedly as well.
##### onKeyUp
- **Use on:** Display, Control
- **Fired on:** Releasing any keyboard key. Fired after the [onKeyDown](../topics/User_Interface_Event_Handlers.md#onkeydown) event.
- **Returns:** Returns the display or control, the keyboard code and the state of Shift, Ctrl and Alt.
```sqf
params ["_displayOrControl", "_key", "_shift", "_ctrl", "_alt"];
```
##### onChar
- **Use on:** Display, Control
- **Fired on:** When some readable characters is recognised.
- **Returns:** Returns the display or control and the [char code](https://www.ascii-code.com/).
```sqf
params ["_displayOrControl", "_charCode"];
```
##### onIMEChar
- **Use on:** Control
- **Fired on:** When IME character is recognized (used in Korean and other eastern languages).
- **Returns:** Returns the control and the char code.
```sqf
params ["_control", "_charCode"];
```
##### onIMEComposition
- **Use on:** Control
- **Fired on:** When partial IME character is recognized (used in Korean and other eastern languages).
- **Returns:** Returns the control and the char code.
```sqf
params ["_control", "_charCode"];
```
##### onMouseButtonDown
- **Use on:** Display, Control
- **Fired on:** Pressing a mouse button. Followed by the [`onMouseButtonUp`](../topics/User_Interface_Event_Handlers.md#onmousebuttonup) event.
- **Returns:** Returns the display or control, the pressed button, the x and y coordinates and the state of Shift, Ctrl and Alt.
```sqf
params ["_displayOrControl", "_button", "_xPos", "_yPos", "_shift", "_ctrl", "_alt"];
```
##### onMouseButtonUp
- **Use on:** Display, Control
- **Fired on:** Releasing a mouse button. Follows the [`onMouseButtonDown`](../topics/User_Interface_Event_Handlers.md#onmousebuttondown) event.
- **Returns:** Returns the display or control, the pressed button, the x and y coordinates and the state of Shift, Ctrl and Alt.
```sqf
params ["_displayOrControl", "_button", "_xPos", "_yPos", "_shift", "_ctrl", "_alt"];
```
##### onMouseButtonClick
- **Use on:** ListBox, ComboBox, TextBox, Button, ActiveText
- **Fired on:** Pressing and releasing a mouse button.
- **Returns:** Returns the control, the pressed button, the x and y coordinates and the state of Shift, Ctrl and Alt.
```sqf
params ["_control", "_button", "_xPos", "_yPos", "_shift", "_ctrl", "_alt"];
```
##### onMouseButtonDblClick
- **Use on:** Control
- **Fired on:** Pressing and releasing a mouse button twice within very short time.
- **Returns:** Returns the control, the pressed button, the x and y coordinates and the state of Shift, Ctrl and Alt.
```sqf
params ["_control", "_button", "_xPos", "_yPos", "_shift", "_ctrl", "_alt"];
```
##### onMouseMoving
- **Fired on:** Fires continuously while moving the mouse with a certain interval.
---
- **Use on:** Control, Display
- **Returns:** Returns the control, the x and y coordinates relative to the controls parent and mouseOver.
If the controls parent is its display then x and y will be the same as [getMousePosition](../commands/getMousePosition.md) else it will be relative to its parent control (for instance if inside a CT_CONTROLS_GROUP).
```sqf
params ["_control", "_xPos", "_yPos", "_mouseOver"];
```
---
- **Use on:** Display
- **Returns:** Returns the display, and how much the mouse was moved since the last time the event fired in UI coordinates.
```sqf
params ["_display", "_xDeltaPos", "_yDeltaPos"];
```
##### onMouseHolding
- **Fired on:** Fires continuously with a specific interval while mouse is stationary.
---
- **Use on:** Control, Display
- **Returns:** Returns the control, the x and y coordinates relative to the controls parent and mouseOver.
If the controls parent is its display then x and y will be the same as [getMousePosition](../commands/getMousePosition.md) else it will be relative to its parent control (for instance if inside a CT_CONTROLS_GROUP).
```sqf
params ["_control", "_xPos", "_yPos", "_mouseOver"];
```
---
- **Use on:** Display
- **Returns:** Returns the display, and *some kind of* x and y delta position.
```sqf
params ["_display", "_xPos", "_yPos"];
```
##### onMouseZChanged
- **Use on:** Display, Control
- **Fired on:** Fires when mouse wheel position is changed. Only fires on enabled controls.
- **Returns:** Returns the display or control and the change of the scrollwheel.
```sqf
params ["_displayOrControl", "_scroll"];
```
##### onCanDestroy
- **Use on:** Control
- **Fired on:** Ask this control if dialog can be closed (used for validation of contained data).
- **Returns:** Returns the control and exit code.
```sqf
params ["_control", "_exitCode"];
```
##### onDestroy
- **Use on:** Control
- **Fired on:** Destroying control
- **Returns:** Returns the control and exit code.
```sqf
params ["_control", "_exitCode"];
```
#### Button Events
##### onButtonClick
- **Use on:** Button
- **Fired on:** The attached button action is performed. When returned value is [true](../commands/true.md), the engine behaviour is overridden.
- **Returns:** Returns control.
```sqf
params ["_control"];
```
##### onButtonDblClick (Arma 3 v1.00)
- **Use on:** Button
- **Fired on:** Button double clicked.
- **Returns:** Returns control.
```sqf
params ["_control"];
```
##### onButtonDown
- **Use on:** Button
- **Fired on:** The left mouse button is pressed over the button area or a key on the keyboard is pressed.
- **Returns:** Returns control.
```sqf
params ["_control"];
```
##### onButtonUp
- **Use on:** Button
- **Fired on:** When left mouse button is released outside the button area and the attached button action **went unexecuted**.
- **Returns:** Returns control.
```sqf
params ["_control"];
```
#### Listbox Events
##### onLBSelChanged
- **Use on:** Listbox, Combobox, Table
- **Fired on:** The selection in a listbox is changed. The left mouse button has been released and the new selection is fully made.
> [!WARNING]
> This EH will fire even if no new selection was made and the user clicked on existing selection
> [!NOTE]
> Since Arma 3 v2.11 controls with the LB_MULTI style pass an additional `_lbSelection` parameter to the EH script (see [lbCurSel](../commands/lbCurSel.md), [lbSelection](../commands/lbSelection.md)).
- **Returns:** Returns the control and the selected element index.
```sqf
params ["_control", "_lbCurSel", "_lbSelection"];
```
##### onLBListSelChanged
- **Use on:** Combobox
- **Fired on:** When selection in XCombo box changed (but value has yet to be stored).
- **Returns:** Returns the control and the selected element index.
```sqf
params ["_control", "_selectedIndex"];
```
##### onLBDblClick
- **Use on:** Listbox
- **Fired on:** Double click on some row in listbox.
- **Returns:** Returns the control and the selected element index.
```sqf
params ["_control", "_selectedIndex"];
```
##### onLBDrag
- **Use on:** Listbox
- **Fired on:** Drag & drop operation started.
- **Returns:** Returns the control and an array of arrays of information on the dragged item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).
Control must have unique IDC and `canDrag` parameter enabled in its class in order to work.
```sqf
params ["_control", "_listboxInfo"];
// Get info of first item being dragged:
(_listboxInfo select 0) params ["_lbText", "_lbValue", "_lbData"];
```
##### onLBDragging
- **Use on:** Listbox
- **Fired on:** Drag & drop operation is in progress.
- **Returns:** Returns the control, the x and y coordinates in screen space, listbox IDC where item(s) were dragged from and an array of arrays of information on the dragged item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).
```sqf
params ["_control", "_xPos", "_yPos", "_listboxIDC", "_listboxInfo"];
// Get info of first item being dragged:
(_listboxInfo select 0) params ["_lbText", "_lbValue", "_lbData"];
```
##### onLBDrop
- **Use on:** Listbox, Combobox, Textbox, ActiveText, Button, ControlsGroup
- **Fired on:** When a Drag & drop operation is finished.
- **Returns:** Returns the control, the x and y coordinates in screen space, listbox IDC where item(s) were dragged from and an array of arrays of information on the dropped item(s) (if listbox is of style LB_MULTI then multiple items can be dragged and dropped at the same time).
When the Listbox is inside a CT_CONTROLS_GROUP the Event Handler needs to be added to the CT_CONTROLS_GROUP.
Will only work for a CT_CONTROLS_GROUP that is outside of any other group.
```sqf
params ["_control", "_xPos", "_yPos", "_listboxIDC", "_listboxInfo"];
//Get info of first item being dropped:
(_listboxInfo select 0) params ["_lbText", "_lbValue", "_lbData"];
```
#### Tree Events
##### onTreeSelChanged
- **Use on:** Tree
- **Fired on:** Changing the selection in a tree.
- **Returns:** Returns the control and the new selection path.
```sqf
params ["_control", "_selectionPath"];
```
##### onTreeLButtonDown
- **Use on:** Tree
- **Fired on:** Pressing and releasing left mouse button on a tree.
- **Returns:** Returns the control.
```sqf
params ["_control"];
```
##### onTreeDblClick
- **Use on:** Tree
- **Fired on:** Pressing and releasing twice on a tree entry.
- **Returns:** Returns the control and the current selection path.
```sqf
params ["_control", "_selectionPath"];
```
##### onTreeExpanded
- **Use on:** Tree
- **Fired on:** The tree folder structure has been expanded.
- **Returns:** Returns the control and path.
```sqf
params ["_control", "_selectionPath"];
```
##### onTreeCollapsed
- **Use on:** Tree
- **Fired on:** The tree folder structure has been collapsed.
- **Returns:** Returns the control and path.
```sqf
params ["_control", "_selectionPath"];
```
##### onTreeMouseMove
- **Use on:** Tree
- **Fired on:** Fires continuously while moving the mouse with a certain interval.
- **Returns:** Returns the control. Also returns the path, probably since Eden Editor update.
```sqf
params ["_control", "_path"];
```
##### onTreeMouseHold
- **Use on:** Tree
- **Fired on:** Fires continuously at a specific interval while mouse is still.
- **Returns:** Returns the control. Also returns the path, probably since Eden Editor update.
```sqf
params ["_control", "_path"];
```
##### onTreeMouseExit
- **Use on:** Tree
- **Fired on:** The mouse pointer exits the tree control area
- **Returns:** Returns the control.
```sqf
params ["_control"];
```
##### onTreeFilterUpdated (Arma 3 v2.12)
- **Use on:** Tree
- **Fired on:** A search/filter done on the tree
- **Returns:** Returns the control.
```sqf
params ["_treeControl", "_searchControl", "_searchString"];
```
#### Checkbox Events
##### onChecked (Arma 3 v1.00)
- **Use on:** Checkbox (CT_CHECKBOX).
- **Fired on:** N/A
- **Returns:** N/A
> [!NOTE]
> This feature has yet to be implemented.
##### onCheckedChanged (Arma 3 v1.00)
- **Use on:** Checkbox (CT_CHECKBOX).
- **Fired on:** Checked state of ctrlCheckBox / RscCheckBox changed.
- **Returns:** Returns control and the checked state ( 0 for unchecked, 1 for checked ).
```sqf
params ["_control", "_checked"];
```
##### onCheckBoxesSelChanged
- **Use on:** Checkboxes (CT_CHECKBOXES).
- **Fired on:** Changed the selection of checkboxes.
- **Returns:** Returns the control, the selected element index and the current state.
```sqf
params ["_control", "_selectedIndex", "_currentState"];
```
#### Misc. Events
##### onToolBoxSelChanged
- **Use on:** Toolbox
- **Fired on:** Changed the selection in a toolbox.
- **Returns:** Returns the control and the selected element index.
```sqf
params ["_control", "_selectedIndex"];
```
##### onHTMLLink
- **Use on:** HTML
- **Fired on:** Pressing and releasing a HTML link.
- **Returns:** Returns the control and href.
```sqf
params ["_control", "_url"];
```
##### onSliderPosChanged
- **Use on:** Slider
- **Fired on:** Changing the position of a slider.
- **Returns:** Returns the control and the change.
```sqf
params ["_control", "_newValue"];
```
##### onObjectMoved
- **Use on:** Object
- **Fired on:** Moving an object.
- **Returns:** Returns the control and the offset on the x, y and z axes.
```sqf
params ["_control", "_offset"];
```
##### onMenuSelected
- **Use on:** Context menu
- **Fired on:** Some item in context menu (used now only in new mission editor) was selected.
- **Returns:** Returns the control and the command id.
```sqf
params ["_control", "_commandId"];
```
##### onDraw
- **Use on:** Map, Display (only on UIOnTexture Display Arma 3 v2.12)
- **Fired on:** Fires when the map is drawn or the UI On Texture Display received a [draw request](../commands/displayUpdate.md) (can occur more than once per second).
- **Returns:** Returns the map control.
> [!IMPORTANT]
> This event handler gets destroyed when the mission it was executed in ends.
```sqf
params ["_controlOrDisplay"];
```
##### onVideoStopped (Arma 2: Operation Arrowhead v1.56)
- **Use on:** Control
- **Fired on:** Activated every time the video ends (when looped, handler is executed after every finished loop).
- **Returns:** Returns the control.
```sqf
params ["_control"];
```
> [!WARNING]
> When using the event names via GUI scripting commands (e.g [ctrlAddEventHandler](../commands/ctrlAddEventHandler.md), [displayAddEventHandler](../commands/displayAddEventHandler.md)), the prefix "on" in the name **must be removed** (e.g. `ButtonDown` instead of `onButtonDown`)!
### Event Parameters
The Event Handlers receive parameters through the [magic variable](../topics/Magic_Variables.md) `_this`. Each event passes a different set of parameters (listed above) in an array. The control or display that the event was assigned to is always found in `_this select 0`.
### Scope
Armed Assault v1.00 In Armed Assault, most control-specific events ONLY work for controls and never for displays. The two exceptions being: `onKeyDown` and `onKeyUp`.
Arma 2 v1.00 Since Arma 2, most control-specific events work for both displays and controls.
### Defining Events
User Interface Event Handlers can be assigned in two ways: Via class property definitions or via scripting commands.
#### Class-Defined Events
Events can be defined in the Dialog (display) or Control classes (in Config.cpp or [Description.ext](../topics/Description.ext.md)). The event property value (string) is executed as a line of code.
An example line (this would be found within a control or dialog class):
```cpp
onMouseButtonDown = "hint str _this";
```
Full Example:
```cpp
class RscControlsGroup
{
type = 15;
idc = -1;
style = 0;
x = 0;
y = 0;
w = 1;
h = 1;
class VScrollbar
{
color[] = { 1, 1, 1, 1 };
width = 0.021;
autoScrollSpeed = -1;
autoScrollDelay = 5;
autoScrollRewind = 0;
};
class HScrollbar
{
color[] = { 1, 1, 1, 1 };
height = 0.028;
};
class ScrollBar // >= Arma 2
{
color[] = { 1, 1, 1, 0.6 };
colorActive[] = { 1, 1, 1, 1 };
colorDisabled[] = { 1, 1, 1, 0.3 };
thumb = "#(argb,8,8,3)color(1,1,1,1)";
arrowEmpty = "#(argb,8,8,3)color(1,1,1,1)";
arrowFull = "#(argb,8,8,3)color(1,1,1,1)";
border = "#(argb,8,8,3)color(1,1,1,1)";
};
class Controls {};
};
class MouseHandler : RscControlsGroup
{
onMouseHolding = "[0, _this] call myEventFunction";
onMouseButtonDown = "[1, _this] call myEventFunction";
onMouseButtonUp = "[2, _this] call myEventFunction";
onMouseZChanged = "[3, _this] call myEventFunction";
onMouseEnter = "[4, _this] call myEventFunction";
idc = 123;
x = 0.0;
y = 0.0;
w = 1.0;
h = 1.0;
colorBackground[] = { 0.2, 0.0, 0.0, 0.0 };
};
```
#### Script-Defined Events
These events can also be given to dialogs and controls using the [displayAddEventHandler](../commands/displayAddEventHandler.md) and [ctrlAddEventHandler](../commands/ctrlAddEventHandler.md) commands. The control has to be enabled for the Event Handler in order for Event Handlers to fire (see [ctrlEnable](../commands/ctrlEnable.md)).
```sqf
// Add Event Handler:
(findDisplay 46) displayAddEventHandler ["KeyDown", {
_this call functionName_keyDown;
}];
// Function definition:
functionName_keyDown = {
params ["_ctrl", "_dikCode", "_shift", "_ctrlKey", "_alt"];
private _handled = false;
if (!_shift && !_ctrlKey && !_alt) then {
if (_dikCode in (actionKeys "NetworkStats")) then {
systemChat format ["EH fired for %1", _ctrl];
_handled = true;
};
};
_handled;
};
```
Source: [BI Community Wiki — User Interface Event Handlers](https://community.bistudio.com/wiki/User_Interface_Event_Handlers) (revision 378424).