Page tree
Skip to end of metadata
Go to start of metadata

This page is obsolete. For latest VBS User Interface Event Handlers, see UI Event Handlers in the VBS3 Scripting Manual.


Overview

User Interface Event Handlers constantly monitor displays and controls, and execute custom code when a particular UI events has being triggered.

Defining events

Event Handlers can be assigned in two ways: via class property definitions (in description.ext or an addon config.cpp) or via scripting commands.

A control must be ctrlEnable, in order for any event to be able to fire.

Independently of how the event was defined, it can be removed via the following script commands: ctrlRemoveEventHandler & ctrlRemoveAllEventHandlers and displayRemoveEventHandler & displayRemoveAllEventHandlers.

Event properties

Event parameters

Event handlers receive parameters via the _this variable, which is an array containing event-specific information (e.g. the control clicked and the mouse position - see Reference List). The content of this variable can then be used in the command string that is defined for this event.
Example: Event sends a chat message if the right mouse button is clicked over the control:

onMouseButtonDown = "if ((_this select 1)==2) then {player sidechat 'Right mouse button clicked'}";

Command string

The string that is passed to the event handler can contain one or more commands, which are separated by semicolons.
Local variables can be used in the command string.
Example: Mouse double-click event stores the passed text control in variable '_ctrl', saves the original content of it into 'tst_var', and then clears the control:

onMouseButtonDblClick = "_ctrl=_this select 0; tst_var=ctrlText _ctrl; _ctrl ctrlSetText ''";

Return values

Once the commands in the passed string have been executed, the event handler returns a Boolean to the engine (the result of the last command in the string). If the returned value is true (i.e. "event completed"), then no further processing of the event will happen; if it is false then normal event processing continues.
This is really only of interest in two situations: Key-press events ("onKeyDown") and multiple (stacked) handlers for the same type of event.

  • If a key-press event returns true, then this will prevent the engine from interpreting the <Esc> key, and the dialog cannot be closed via that method anymore (and the designer will have to close it by some other way). In order to prevent that the command string should end with a false flag: onKeyDown = "doSomething; false".
  • If multiple handlers are defined for the same event type (via ctrlAddEventHandler or displayAddEventHandler) and the command string returns true, then only the first event will be executed, and any further definitions are ignored. This can be circumvented (just like in the key-press situation) by ending the string with an explicit false:
    _ctrl ctrlAddEventHandler ["MouseButtonDown","systemChat 'EH #1'; false"];
    _ctrl ctrlAddEventHandler ["MouseButtonDown","systemChat 'EH #2'; false"];

The 'onBPS' event is a special situation, where the return value is a String. This string contains the command(s) that are executed when a branch point is loaded. (And as a string is interpreted as a false return value, multiple events can thus be defined.)

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";

Example:

class DlgInput {
  idd = 20000;
  movingEnable = true;

  class controls {
    class EDIT1 : RscEdit {
      idc = 20000; 
      x = .2; y = .2; w = .2; h = .2;
      onMouseButtonDblClick = "(_this select 0) ctrlSetText ''";
    };
  };
};

Script defined events

Events can also be defined via scripting commands: ctrlSetEventHandler & ctrlAddEventHandler, and displaySetEventHandler & displayAddEventHandler.

Important: When using event names with a command, the prefix "on" must be omitted. (e.g. 'ButtonDown' instead of 'onButtonDown')

(findDisplay 46) displaySetEventHandler ["keyDown", "_this execVM 'eventScript.sqf'"];


Reference List

Not all events can be triggered on all types of dialog types. Some will only work with displays, others will only work with specific control types. The possible types are listed below, and the right column ("Scope") shows which controls the event can be used with.
Most user input events (e.g. mouse clicked, keyboard pressed) will not work with HUD-like dialogs (i.e. those defined as RscTitles), since the dialog itself is not interactive.

(Entries in italics have not been verified.)

EventFiredNotes and ParametersScope
onLoadDisplay and all controls are created.
Note that findDisplay will not be able to find the newly created display until after the onLoad event has finished processing. If you require access to the display in your onLoad event handler, use the handle passed in the _this parameter.
Returns the display.D
onUnloadDisplay is closed, but no controls are destroyed yet.Returns the display and exit code. The exit code is 2 if the dialog was closed by pressing the <Esc> key, otherwise it's the number that was passed via the closeDialog command.D
onChildDestroyedChild display is closed.Returns the display, which child display was closed and exit code.D
onBPSA multiplayer session is either saved or loaded (BPS==Branch Point Save), while the current user has a dialog opened.Returns the display for save events, and nothing for load events.
Any command(s) defined in the passed string will be executed when a branchpoint (BP) is saved; the command(s) that should be executed when a BP is loaded have to be enclosed in quotation marks (i.e. passed as a string within the command string), and be the last (preceded by a semicolon), or only, element: "saveAction; 'loadAction'". The saveAction is executed when a branchpoint is saved, the (optional) loadAction is passed as a string, and executed when a branchpoint is loaded. (e.g. onBPS = "TST_COUNT=TST_COUNT+1; 'TST_COUNT=TST_COUNT-1'")
D (V3.4+)
onRearrangeThe aspect ratio has been changed (e.g. via the video options).Returns the display.D (V3.4+)
onTimerAfter the time defined in a control's "timer" property has passed, since the control has been opened.Returns control.Any dialog control (V3.4+)
onMouseEnterThe mouse pointer enters the control area.Returns control.A, B, T, Sb, To
onMouseExitThe mouse pointer exits the control area.Returns control.A, B, T, Sb, To
onSetFocusInput focus is on control. It now begins to accept keyboard input.Returns control.A, AT, B, C, G, H, L, M, Sb, Sl, SV, T, To
onKillFocusInput focus is no longer on control. It no longer accepts keyboard input. A control only loses focus if another one receives it - just leaving the control bounding box does not kill focus.Returns control.A, AT, B, C, G, H, L, M, Sb, Sl, SV, T, To
onKeyDownPressing any keyboard key. Fired before the VBS User Interface Event Handlers#onKeyUp event.Returns the control, the DIK KeyCodes and the state of Shift, Ctrl and Alt.
Be aware that if this EH is attached to a display, and its function doesn't return false, the <Esc> key will become non-functional, and you will not be able to close the dialog. This can be used to make the dialog closure dependent on certain condition, e.g. onKeyDown = "if (somecondition || (_this select 1)!=1) then {false} else {true}"
A, AT, B, C, D, G, H, L, Ln, M, Sb, Sl, SV, T, To
onKeyUpReleasing any keyboard key. Fired after the VBS User Interface Event Handlers#onKeyDown event.Returns the control, the DIK KeyCodes and the state of Shift, Ctrl and Alt.A, AT, B, C, D, G, H, L, M, Sb, Sl, SV, T, To
onCharWhen some readable characters is recognized.Returns the control and the char code.A, AT, B, C, D, G, H, L, M, Sb, Sl, SV, T, To
onIMECharWhen IME character is recognized (used in Korean and other eastern languages).Returns the control and the char code.Control
onIMECompositionWhen partial IME character is recognized (used in Korean and other eastern languages).Returns the control and the char code.Control
onJoystickButtonPressing and releasing any joystick button.Returns the control and the the pressed button.Control
onMouseButtonDownPressing a mouse button. Followed by the VBS User Interface Event Handlers#onMouseButtonUp event.Returns the control, the pressed button (0:left, 1:right, etc.), the x and y coordinates and the state of Shift, Ctrl and Alt.
For some displays (e.g. 46: editor) the value for x & y is always [.5,.5].
If a display is overlaid by a dialog, the display EH will still fire, even when the dialog is clicked!
A, AT, B, C, D2, G, H, L, M, Sb, Sl, SV, T, To
onMouseButtonUpReleasing a mouse button. Follows the VBS User Interface Event Handlers#onMouseButtonDown event.Returns the control, the pressed button (0:left, 1:right, etc.), the x and y coordinates and the state of Shift, Ctrl and Alt.
For some displays (e.g. 46: editor) the value for x & y is always [.5,.5].
If a display is overlaid by a dialog, the display EH will still fire, even when the dialog is clicked!
A, AT, B, C, D2, G, H, L, M, Sb, Sl, SV, T, To
onMouseButtonClickPressing and releasing a mouse button.Returns the control, the pressed button (0:left, 1:right, etc.), the x and y coordinates, and the state of Shift, Ctrl and Alt.A, AT, B, C, G, H, L, M, Sl, SV, T, To
onMouseButtonDblClickPressing and releasing a mouse button twice within very short time.Returns the control, the pressed button (0:left, 1:right, etc.), the x and y coordinates and the state of Shift, Ctrl and Alt.A, AT, B, C, G, H, L, M, Sl, SV, T, To
onMouseMovingFires continuously while moving the mouse with a certain interval.Returns the control, the x and y coordinates, and a Boolean indicating whether currently over a compatible control.
(V2.00+: For displays or non-compatible controls the display and mouse speed x,y is returned.)
A, AT, B, C, D2, G, H, L, M, Sb, Sl, SV, T, To
onMouseHoldingFires continuously while mouse is not moving with a certain interval.Returns the control, the x and y coordinates, and a Boolean indicating whether currently over a compatible control.
(V2.00+: For displays or non-compatible controls the display and relative mouse speed x,y is returned.)
A, AT, B, C, D2, G, H, L, M, Sb, Sl, SV, T, To
onMouseZChangedFires when mouse wheel position is changed.Returns the control and the number of lines scrolled (depends on scroll-speed and system settings). Values are positive for forward scrolls or negative for backward scrolls.A, AT, B, C, D2, G, H, L, M, Sb, Sl, SV, T, To
onCanDestroyAsk this control if dialog can be closed (used for validation of contained data).Returns the control and exit code (0=closed via closeDialog, 2=closed via <Esc>).?
onDestroyDestroying controlReturns the control and exit code.?
onButtonClickThe attached button action is performed.Returns control.A, B
onButtonDownThe left mouse button is pressed over the button area or a key on the keyboard is pressed.Returns control.A, B
onDrawFires when the map is drawn (can occur more than once per second).Returns the map control.M
onLBSelChangedThe selection in a listbox or combobox has changed. The left mouse button has been released and the new selection is fully made.Returns the control and the selected element index (always only one -the latest one- even if multiple selections are enabled).C, L
onLBDblClickDouble click on some row in listbox.Returns the control and the selected element index.L
onLBDragDrag & drop operation started.Returns the control and a nested array containing [text,data,value] for all the selected elements.L
onLBDraggingDrag & drop operation is in progress.Returns the control currently hovered over, the current x and y coordinates, the IDC of the source control, and a nested array containing [text,data,value,index] for all the selected elements, and a -1 as the last value (unknown meaning).
In 2D listboxes the element index is calculated by counting every cell in every line (e.g. the 1st cell in line 3 -each containing 2 cells- would return 4).
L
onLBDropDrag & drop operation finished.Returns the control item was dropped onto, the current x and y coordinates, the IDC of the source control, and a nested array containing [text,data,value,index] for all the selected elements, and the index it was dropped into (or -1 if dropped onto a non-listbox or into an empty space of a listbox).
In 2D listboxes the element index is calculated by counting every cell in every line (e.g. the 1st cell in line 3 -each containing 2 cells- would return 4).
A, B, C, H, L, M, Sb, Sl, SV, T, To
onSetVisibleA control's visibility is changed via ctrlShow.Returns the control and the visibility status (1=visible, 0=hidden).A, AT, B, C, G, H, L, M, S, Sb, Sl, Str, SV, T, To
onAdvTreeToggleA row was collapsed or expanded (either via a user action or a script command).Returns the control, row number (1-based), and whether the branch is currently expanded.AT
onAdvTreeClickAny item in a row was clicked (down & up). If button is still held down after about 1 second, event will fire nevertheless.Returns the control, row number (1-based), column number (0-based).AT
onAdvTreeDblClickAny item in a row was double-clicked.Returns the control, row number (1-based), column number (0-based).AT
onAdvTreeMouseDownThe mouse button is currently pressed over any item in a row.Returns the control, row number (1-based), column number (0-based).AT
onAdvTreeMouseUpThe mouse button is released over any item in a row.Returns the control, row number (1-based), column number (0-based).AT
onTreeLButtonDownPressing and releasing left mouse button on a tree.Returns the control.Tr
onTreeMouseHoldFires continuously while mouse is not moving with a certain interval.Returns the control.Tr
onTreeMouseMoveFires continuously while moving the mouse with a certain interval.Returns the control.Tr
onTreeMouseExitThe mouse pointer exits the tree control areaReturns the control.Tr
onTreeSelChangedChanging the selection in a tree.Returns the control.Tr
onTreeDblClickPressing and releasing twice on a tree.Returns the control.Tr
onTreeExpandedThe tree folder structure has been expanded.Returns the control.Tr
onTreeCollapsedThe tree folder structure has been collapsed.Returns the control.Tr
onToolBoxSelChangedChanged the selection in a toolbox.Returns the control and the selected element index.To
onCheckBoxesSelChangedChanged the selection in a checkbox.Returns the control, the selected element index and the current state.Ch
onStateBoxToggleA statebox control was clicked.Returns the control, current state, and previous state.
If the Command string returns true, then the state will not be changed!
Sb
onHTMLLinkPressing and releasing a HTML link.Returns the control and href.H
onSliderPosChangedChanging the position of a slider.Returns the control and the change.Sl
onObjectMovedMoving an object.Returns the control and the offset on the x,y and z axes.O
onMenuSelectedSome item in context menu (used now only in new mission editor) was selected.Returns the control and the command id.CM
onPlanDrawFires each frame the control is displayed.Returns the control. Does not work if assigned via ctrlSetEventHandler!PV
onplanUnitEnteredA unit entered a section covered by the plan.Returns [vehicle, control, unit, section]. Be aware that unlike all other events, this one doesn't return the control as the first element!PV
onPlanOnUnitLeftA unit left a section covered by the plan.Returns [vehicle, control, unit, section]. See note in 'onPlanUnitEntered'.PV
onPlanClickThe mouse button has been pressed.Returns the [control, x, y], with the coordinated being relative to the plan.PV
onPlanUnitSelectA unit, visible on the plan, was clicked.Returns [control, unit, selected]. 'Selected' will toggle between true and false.PV

Demo missions