Registers a function or method to be called when the given event is raised by a GUI window or control.

Gui.OnEvent(EventName, Callback , AddRemove)
GuiCtrl.OnEvent(EventName, Callback , AddRemove)



Type: String

The name of the event. See Events further below.


Type: String or Function Object

The function, method or object to call when the event is raised.

If the GUI has an event sink (that is, if Gui()'s EventObj parameter was specified), this parameter may be the name of a method belonging to the event sink.

Otherwise, this parameter must be a function object.


Type: Integer

If omitted, it defaults to 1 (call the callback after any previously registered callbacks). Otherwise, specify one of the following numbers:

Callback Parameters

If the callback is a method registered by name, its hidden this parameter seamlessly receives the event sink object (that is, the object to which the method belongs). This parameter is not shown in the parameter lists in this documentation.

Since Callback can be an object, it can be a BoundFunc object which inserts additional parameters at the beginning of the parameter list and then calls another function. This is a general technique not specific to OnEvent, so is generally ignored by the rest of this documentation.

The callback's first explicit parameter is the Gui or GuiControl object which raised the event. The only exception is that this parameter is omitted when a Gui handles its own events, since this already contains a reference to the Gui.

Many events pass additional parameters about the event, as described for each event.

As with all methods or functions called dynamically, the callback is not required to declare parameters which the callback itself does not need, but in this case an asterisk must be specified as the final parameter. If an event has more parameters than are declared by the callback, they will simply be ignored (unless the callback is variadic).

The callback can declare more parameters than the event provides if (and only if) the additional parameters are declared optional. However, the use of optional parameters is not recommended as future versions of the program may extend an event with additional parameters, in which case the optional parameters would stop receiving their default values.

Callback Return Value

If multiple callbacks have been registered for an event, a callback may return a non-empty value to prevent any remaining callbacks from being called.

The return value may have additional meaning for specific events. For example, a Close callback may return a non-zero number (such as true) to prevent the GUI window from closing.

Callback Name

By convention, the syntax of each event below is shown with a function name of the form ObjectType_EventName, for clarity. Scripts are not required to follow this convention, and can use any valid function name.


Each event callback is called in a new thread, and therefore starts off fresh with the default values for settings such as SendMode. These defaults can be changed during script startup.

Whenever a GUI thread is launched, that thread's last found window starts off as the GUI window itself. This allows functions for windows and controls -- such as WinGetStyle, WinSetTransparent, and ControlGetFocus -- to omit WinTitle and WinText when operating upon the GUI window itself (even if it is hidden).

Except where noted, each event is limited to one thread at a time, per object. If an event is raised before a previous thread started by that event finishes, it is usually discarded. To prevent this, use Critical as the callback's first line (however, this will also buffer/defer other threads such as the press of a hotkey).

Destroying the GUI

When a GUI is destroyed, all event callbacks are released. Therefore, if the GUI is destroyed while an event is being dispatched, subsequent event callbacks are not called. For clarity, callbacks should return a non-empty value after destroying the GUI.


The following events are supported by Gui objects:

EventRaised when...
CloseThe window is closed.
ContextMenuThe user right-clicks within the window or presses Menu or Shift+F10.
DropFilesFiles/folders are dragged and dropped onto the window.
EscapeThe user presses Esc while the GUI window is active.
SizeThe window is resized, minimized, maximized or restored.

The following events are supported by GuiControl objects, depending on the control type:

EventRaised when...
ChangeThe control's value changes.
ClickThe control is clicked.
DoubleClickThe control is double-clicked.
ColClickOne of the ListView's column headers is clicked.
ContextMenuThe user right-clicks the control or presses Menu or Shift+F10 while the control has the keyboard focus.
FocusThe control gains the keyboard focus.
LoseFocusThe control loses the keyboard focus.
ItemCheckA ListView or TreeView item is checked or unchecked.
ItemEditA ListView or TreeView item's label is edited by the user.
ItemExpandA TreeView item is expanded or collapsed.
ItemFocusThe focused item changes in a ListView.
ItemSelectA ListView or TreeView item is selected, or a ListView item is deselected.

Window Events


Launched when the user or another program attempts to close the window, such as by pressing the X button in its title bar, selecting "Close" from its system menu, or calling WinClose.


By default, the window is automatically hidden after the callback returns, or if no callbacks were registered. A callback can prevent this by returning 1 (or true), which will also prevent any remaining callbacks from being called. The callback can hide the window immediately by calling Gui.Hide, or destroy the window by calling Gui.Destroy.

For example, this GUI shows a confirmation prompt before closing:

myGui := Gui()
myGui.AddText("", "Press Alt+F4 or the X button in the title bar.")
myGui.OnEvent("Close", myGui_Close)
myGui_Close(thisGui) {  ; Declaring this parameter is optional.
    if MsgBox("Are you sure you want to close the GUI?",, "y/n") = "No"
        return true  ; true = 1


Launched whenever the user right-clicks anywhere in the window except the title bar and menu bar. It is also launched in response to pressing Menu or Shift+F10.

Gui_ContextMenu(GuiObj, GuiCtrlObj, Item, IsRightClick, X, Y)

The GuiControl object of the control that received the event (blank if none).


When a ListBox, ListView, or TreeView is the target of the context menu (as determined by GuiCtrlObj), Item specifies which of the control's items is the target.

ListBox: The number of the currently focused row. Note that a standard ListBox does not focus an item when it is right-clicked, so this might not be the clicked item.

ListView and TreeView: For right-clicks, Item contains the clicked item's ID or row number (or 0 if the user clicked somewhere other than an item). For the AppsKey and Shift-F10, Item contains the selected item's ID or row number.


True if the user clicked the right mouse button.
False if the user pressed Menu or Shift+F10.

X, Y

The X and Y coordinates of where the script should display the menu (e.g. MyContextMenu.Show X, Y). Coordinates are relative to the upper-left corner of the window's client area.

Unlike most other GUI events, the ContextMenu event can have more than one concurrent thread.

Each control can have its own ContextMenu event callback which is called before any callback registered for the Gui object. Control-specific callbacks omit the GuiObj parameter, but all other parameters are the same.

Note: Since Edit and MonthCal controls have their own context menu, a right-click in one of them will not launch the ContextMenu event.


Launched whenever files/folders are dropped onto the window as part of a drag-and-drop operation (but if this callback is already running, drop events are ignored).

Gui_DropFiles(GuiObj, GuiCtrlObj, FileArray, X, Y)

The GuiControl object of the control upon which the files were dropped (blank if none).


An array (object) of filenames, where FileArray[1] is the first file and FileArray.Length returns the number of files. A for-loop can be used to iterate through the files:

Gui_DropFiles(GuiObj, GuiCtrlObj, FileArray, X, Y) {
    for i, DroppedFile in FileArray
        MsgBox "File " i " is:`n" DroppedFile
X, Y

The X and Y coordinates of where the files were dropped, relative to the upper-left corner of the window's client area.


Launched when the user presses Esc while the GUI window is active.


By default, pressing Esc has no effect. Known limitation: If the first control in the window is disabled (possibly depending on control type), the Escape event will not be launched. There may be other circumstances that produce this effect.


Launched when the window is resized, minimized, maximized, or restored.

Gui_Size(GuiObj, MinMax, Width, Height)

One of the following values:

Note that a maximized window can be resized without restoring/un-maximizing it, so a value of 1 does not necessarily mean that this event was raised in response to the user maximizing the window.

Width, Height
The new width and height of the window's client area, which is the area excluding title bar, menu bar, and borders.

A script may use the Size event to reposition and resize controls in response to the user's resizing of the window.

When the window is resized (even by the script), the Size event might not be raised immediately. As with other window events, if the current thread is uninterruptible, the Size event won't be raised until the thread becomes interruptible. If the script has just resized the window, follow this example to ensure the Size event is raised immediately:

Critical "Off"  ; Even if Critical "On" was never used.
Sleep -1

Gui.Show automatically does a Sleep -1, so it is generally not necessary to call Sleep in that case.

Control Events


Raised when the control's value changes.

Ctrl_Change(GuiCtrlObj, Info)

For Slider controls, Info is a numeric value indicating how the slider moved. For details, see Detecting Changes (Slider).

For all other controls, Info currently has no meaning.

To retrieve the control's new value, use GuiCtrlObj.Value.

Applies to: DDL, ComboBox, ListBox, Edit, DateTime, MonthCal, Hotkey, UpDown, Slider, Tab.


Raised when the control is clicked.

Ctrl_Click(GuiCtrlObj, Info)
Link_Click(GuiCtrlObj, Info, Href)

ListView: The row number of the clicked item, or 0 if the mouse was not over an item.

TreeView: The ID of the clicked item, or 0 if the mouse was not over an item.

Link: The link's ID attribute (a string) if it has one, otherwise the link's index (an integer).

StatusBar: The part number of the clicked section (however, the part number might be a very large integer if the user clicks near the sizing grip at the right side of the bar).

For all other controls, Info currently has no meaning.


Link: The link's HREF attribute. Note that if a Click event callback is registered, the HREF attribute is not automatically executed.

Applies to: Text, Pic, Button, CheckBox, Radio, ListView, TreeView, Link, StatusBar.


Raised when the control is double-clicked.

Ctrl_DoubleClick(GuiCtrlObj, Info)

ListView, TreeView and StatusBar: Same as for the Click event.

ListBox: The position of the focused item. Double-clicking empty space below the last item usually focuses the last item and leaves the selection as it was.

Applies to: Text, Pic, Button, CheckBox, Radio, ComboBox, ListBox, ListView, TreeView, StatusBar.


Raised when one of the ListView's column headers is clicked.

Ctrl_ColClick(GuiCtrlObj, Info)

The one-based column number that was clicked. This is the original number assigned when the column was created; that is, it does not reflect any dragging and dropping of columns done by the user.

Applies to: ListView.


Raised when the user right-clicks the control or presses Menu or Shift+F10 while the control has the keyboard focus.

Ctrl_ContextMenu(GuiCtrlObj, Item, IsRightClick, X, Y)

For details, see ContextMenu.

Applies to: All controls except Edit and MonthCal (and the Edit control within a ComboBox), which have their own standard context menu.

Focus / LoseFocus

Raised when the control gains or loses the keyboard focus.

Ctrl_Focus(GuiCtrlObj, Info)
Ctrl_LoseFocus(GuiCtrlObj, Info)


Applies to: Button, CheckBox, Radio, DDL, ComboBox, ListBox, ListView, TreeView, Edit, DateTime.

Not supported: Hotkey, Slider, Tab and Link. Note that Text, Pic, MonthCal, UpDown and StatusBar controls do not accept the keyboard focus.


Raised when a ListView or TreeView item is checked or unchecked.

Ctrl_ItemCheck(GuiCtrlObj, Item, Checked)

Applies to: ListView, TreeView.


Raised when a ListView or TreeView item's label is edited by the user.

Ctrl_ItemEdit(GuiCtrlObj, Item)

An item's label can only be edited if -ReadOnly has been used in the control's options.

Applies to: ListView, TreeView.


Raised when a TreeView item is expanded or collapsed.

Ctrl_ItemExpand(GuiCtrlObj, Item, Expanded)

Applies to: TreeView.


Raised when the focused item changes in a ListView.

Ctrl_ItemFocus(GuiCtrlObj, Item)

Applies to: ListView.


Raised when a ListView or TreeView item is selected, or a ListView item is deselected.

ListView_ItemSelect(GuiCtrlObj, Item, Selected)
TreeView_ItemSelect(GuiCtrlObj, Item)

Applies to: ListView, TreeView.

ListView: This event is raised once for each item being deselected or selected, so can be raised multiple times in response to a single action by the user.

Other Events

Other types of GUI events can be detected and acted upon via OnNotify, OnCommand or OnMessage. For example, a script can display context-sensitive help via ToolTip whenever the user moves the mouse over particular controls in the window. This is demonstrated in the GUI ToolTip example.