User Interface Event Handlers

Template:SideTOC User Interface Event handlers allow you to automatically monitor and then execute custom code upon particular UI events being triggered.

Reference List

⚠

When using the event names listed below with the ctrlAddEventHandler, ctrlSetEventHandler, displayAddEventHandler or displaySetEventHandler commands, the prefix "on" in the name must be removed (e.g. 'ButtonDown' instead of 'onButtonDown').

Generic events

onLoad

• Priority: 1
• Use on: Display, Control
• Fired on: Fires when UI container is created, but no action is taken. onLoad event for display fires after onLoad events for all controls it contains are fired.
• Returns: Returns the display or control in format Array.

params ["_uiElement"];

onUnload

• Priority: 1
• Use on: Display
• Fired on: Display is closed, but no controls are destroyed yet.
• Returns: Returns the display and exit code.

params ["_display", "_exitCode"];

onChildDestroyed

• Priority: 1
• Use on: Display
• Fired on: Child display is closed.
• Returns: Returns the display, which child display was closed and exit code.

params ["_display", "_closedChildDisplay", "_exitCode"];

onMouseEnter

• Priority: 1
• Use on: Control
• Fired on: The mouse pointer enters the control area.
• Returns: Returns control.

params ["_control"];

onMouseExit

• Priority: 1
• Use on: Control
• Fired on: The mouse pointer exits the control area.
• Returns: Returns control.

params ["_control"];

onSetFocus

• Priority: 2
• Use on: Control
• Fired on: Input focus is on control. It now begins to accept keyboard input.
• Returns: Returns control.

params ["_control"];

onKillFocus

• Priority: 2
• Use on: Control
• Fired on: Input focus is no longer on control. It no longer accepts keyboard input.
• Returns: Returns control.

params ["_control"];

onTimer

• Priority: 3
• Use on: Control
• Fired on: After amount of time given by setTimer function.
• Returns: Returns control.

params ["_control"];

onKeyDown

• Priority: 2
• Use on: Display, Control
• Fired on: Pressing any keyboard key. Fired before the onKeyUp event.
• Returns: Returns the control, the keyboard code and the state of Shift, Ctrl and Alt.

params ["_control", "_key", "_shift", "_ctrl", "_alt"];

onKeyUp

• Priority: 2
• Use on: Display, Control
• Fired on: Releasing any keyboard key. Fired after the onKeyDown event.
• Returns: Returns the control, the keyboard code and the state of Shift, Ctrl and Alt.

params ["_control", "_key", "_shift", "_ctrl", "_alt"];

onChar

• Priority: 2
• Use on: Control
• Fired on: When some readable characters is recognised.
• Returns: Returns the control and the char code.

params ["_control", "_charCode"];

onIMEChar

• Priority: 2
• 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.

params ["_control", "_charCode"];

onIMEComposition

• Priority: 2
• 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.

params ["_control", "_charCode"];

onJoystickButton

• Priority: 3
• Use on: Control
• Fired on: Pressing and releasing any joystick button.
• Returns: Returns the control and the the pressed button.

private ["_control", "_button"];
_control = _this select 0;
_button = _this select 1;

onMouseButtonDown

• Priority: 2
• Use on: Control
• Fired on: Pressing a mouse button. Followed by the onMouseButtonUp event.
• Returns: Returns the control, the pressed button, the x and y coordinates and the state of Shift, Ctrl and Alt.

params ["_control", "_button", "_xPos", "_yPos", "_shift", "_ctrl", "_alt"];

onMouseButtonUp

• Priority: 2
• Use on: Control
• Fired on: Releasing a mouse button. Follows the onMouseButtonDown event.
• Returns: Returns the control, the pressed button, the x and y coordinates and the state of Shift, Ctrl and Alt.

params ["_control", "_button", "_xPos", "_yPos", "_shift", "_ctrl", "_alt"];

onMouseButtonClick

• Priority: 2
• 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.

params ["_control", "_button", "_xPos", "_yPos", "_shift", "_ctrl", "_alt"];

onMouseButtonDblClick

• Priority: 2
• 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.

params ["_control", "_button", "_xPos", "_yPos", "_shift", "_ctrl", "_alt"];

onMouseMoving

• Priority: 2
• Fired on: Fires continuously while moving the mouse with a certain interval.

---

• Use on: Control
• 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 else it will be relative to its parent control for instance if inside a controlsGroup

params ["_control", "_xPos", "_yPos", "_mouseOver"];

---

• Use on: Display
• Returns: Returns the display, and some kind of x and y delta position.

params ["_control", "_xPos", "_yPos"];

onMouseHolding

• Priority: 2
• Use on: Display, Control
• Fired on: Fires continuously while mouse is not moving with a certain interval.
• Returns: Returns the control, the x and y coordinates and mouseOver. If used with a display, the mouseOver parameter is excluded.

params ["_control", "_xPos", "_yPos", "_mouseOver"];  // control

params ["_control", "_xPos", "_yPos"]; // display

onMouseZChanged

• Priority: 2
• Use on: Display, Control
• Fired on: Fires when mouse wheel position is changed. Does not fire on disabled control.
• Returns: Returns the display or control and the change of the scrollwheel.

params ["_uiElement", "_scroll"];

onCanDestroy

• Priority: 3
• 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.

params ["_control", "_exitCode"];

onDestroy

• Priority: 3
• Use on: Control
• Fired on: Destroying control
• Returns: Returns the control and exit code.

params ["_control", "_exitCode"];

Button events

onButtonClick

• Priority: 1
• Use on: Button
• Fired on: The attached button action is performed. When returned value is true, button's display remains opened.
• Returns: Returns control.

params ["_control"];

1.00

onButtonDblClick

• Priority: ?
• Use on: Button
• Fired on: button double click?
• Returns: ?

onButtonDown

• Priority: 1
• 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.

params ["_control"];

onButtonUp

• Priority: 1
• Use on: Button
• Fired on: The left mouse button is released outside the button area and the attached button action is not performed.
• Returns: Returns control.

params ["_control"];

Listbox events

onLBSelChanged

• Priority: 2
• Use on: Listbox, Combobox
• Fired on: The selection in a listbox is changed. The left mouse button has been released and the new selection is fully made.
• Returns: Returns the control and the selected element index.

params ["_control", "_selectedIndex"];

onLBListSelChanged

• Priority: 2
• Use on: Listbox
• Fired on: Selection in XCombo box changed (but value is not stored yet).
• Returns: Returns the control and the selected element index.

params ["_control", "_selectedIndex"];

onLBDblClick

• Priority: 2
• Use on: Listbox
• Fired on: Double click on some row in listbox.
• Returns: Returns the control and the selected element index.

params ["_control", "_selectedIndex"];

onLBDrag

• Priority: 2
• Use on: Listbox
• Fired on: Drag & drop operation started.
• Returns: Returns the control and the selected element index.

params ["_control", "_selectedIndex"];

onLBDragging

• Priority: 2
• Use on: Listbox
• Fired on: Drag & drop operation is in progress.
• Returns: Returns the control and the x and y coordinates.

params ["_control", "_xPos", "_yPos"];

onLBDrop

• Priority: 2
• Use on: Listbox, Combobox, Textbox, ActiveText, Button
• Fired on: Drag & drop operation finished.
• Returns: Returns the control and the x and y coordinates.
  When the Listbox is inside a ctrlGroup the eventhandler need to be added to the ctrlGroup.

params ["_control", "_xPos", "_yPos"];

Tree events

onTreeSelChanged

• Priority: 2
• Use on: Tree
• Fired on: Changing the selection in a tree.
• Returns: Returns the control and the new selection path.

params ["_control", "_selectionPath"];

onTreeLButtonDown

• Priority: 2
• Use on: Tree
• Fired on: Pressing and releasing left mouse button on a tree.
• Returns: Returns the control.

params ["_control"];

onTreeDblClick

• Priority: 2
• Use on: Tree
• Fired on: Pressing and releasing twice on a tree entry.
• Returns: Returns the control and the current selection path.

params ["_control", "_selectionPath"];

onTreeExpanded

• Priority: 3
• Use on: Tree
• Fired on: The tree folder structure has been expanded.
• Returns: Returns the control.

params ["_control"];

onTreeCollapsed

• Priority: 3
• Use on: Tree
• Fired on: The tree folder structure has been collapsed.
• Returns: Returns the control.

params ["_control"];

onTreeMouseMove

• Priority: 2
• Use on: Tree
• Fired on: Fires continuously while moving the mouse with a certain interval.
• Returns: Returns the control.

params ["_control"];

onTreeMouseHold

• Priority: 2
• Use on: Tree
• Fired on: Fires continuously while mouse is not moving with a certain interval.
• Returns: Returns the control.

params ["_control"];

onTreeMouseExit

• Priority: 2
• Use on: Tree
• Fired on: The mouse pointer exits the tree control area
• Returns: Returns the control.

params ["_control"];

Checkbox events

1.00

onChecked

• Use on: Checkbox
• Priority: ?
• Fired on: CheckBox checked
• Returns: ?

1.00

onCheckedChanged

• Priority: ?
• Use on: Checkbox
• Fired on: Checked state of CheckBox changed.
• Returns: Returns control and the checked state (0 or 1, not boolean).

params ["_control", "_checked"];

onCheckBoxesSelChanged

• Priority: 2
• Use on: Checkbox
• Fired on: Changed the selection in a checkbox.
• Returns: Returns the control, the selected element index and the current state.

params ["_control", "_selectedIndex", "_currentState"];

Misc. events

onToolBoxSelChanged

• Priority: 2
• Use on: Toolbox
• Fired on: Changed the selection in a toolbox.
• Returns: Returns the control and the selected element index.

params ["_control", "_selectedIndex"];

onHTMLLink

• Priority: 2
• Use on: HTML
• Fired on: Pressing and releasing a HTML link.
• Returns: Returns the control and href.

params ["_control", "_url"];

onSliderPosChanged

• Priority: 2
• Use on: Slider
• Fired on: Changing the position of a slider.
• Returns: Returns the control and the change.

params ["_control", "_newValue"];

onObjectMoved

• Priority: 2
• Use on: Object
• Fired on: Moving an object.
• Returns: Returns the control and the offset on the x, y and z axes.

params ["_control", "_offset"];

onMenuSelected

• Priority: 2
• 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.

params ["_control", "_commandId"];

onDraw

• Priority: ?
• Use on: Map
• Fired on: Fires when the map is drawn (can occur more than once per second).
• Returns: Returns the map control.

params ["_control"];

1.56

onVideoStopped

• Priority: 2
• Use on: Control
• Fired on: Activated every time the video ends (when looped, handler is executed after every finished loop).
• Returns: Returns the control.

params ["_control"];

Event parameters

The events handlers receive parameters in the _this variable. Each event passes a different set of parameters (listed in the table above) in an array. The control or display that the event was assigned to is always found in _this select 0.

Scope

1.00 In ArmA, most control-specific events work for controls and do not work for displays. The two exceptions being: onKeyDown and onKeyUp.
1.00 Since Arma 2, most control-specific events now 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). The event property value (string) is executed as a line of code.

An example line (this would be put within a control or dialog class):

onMouseDown = "hint str _this";

Full Example:

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/controls using the ctrlSetEventHandler scripting command. For the event handler to be called enable the control using the ctrlEnable scripting command.

// adding 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 {
			[] execVM "path\script.sqf";
			_handled = true;
		};
	};
	_handled;
};