OnEvent

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

Object.OnEvent(EventName, Callback , AddRemove := 1)

Parameters

Object

A Gui or GuiControl object.

EventName

The name of the event.

Callback

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

If this parameter is a string, its meaning depends on whether the GUI has an event sink (that is, whether GuiCreate's EventObj parameter was specified). If the GUI has an event sink, the string must be the name of a method belonging to the event sink; otherwise, it must be the name of a function.

To register a function regardless of whether the GUI has an event sink, pass a function reference.

AddRemove

One of the following values:
1 (the default): Call the callback after any previously registered callbacks.
-1: Call the callback before any previously registered callbacks.
0: Do not call the callback.

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 always Object; i.e. the Gui or GuiControl object which raised the event.

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. 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.

Threads

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 in the auto-execute section.

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.

Events

The following events are supported by Gui objects:

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

Window Events

Close

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.

Gui_Close(GuiObj)

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 := GuiCreate()
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
}
myGui.Show()

ContextMenu

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 the Apps key or Shift-F10.

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

GuiCtrlObj

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

Item

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.

IsRightClick

True if the user clicked the right mouse button.
False if the user pressed the Apps key or Shift-F10.

X, Y

The X and Y coordinates of where the script should display the menu (e.g. Menu, MyContext, 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.

DropFiles

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)

GuiCtrlObj

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

FileArray

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, file in FileArray
        MsgBox File %i% is:`n%file%
}

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.

Escape

Launched when the user presses the Escape key while the GUI window is active.

Gui_Escape(GuiObj)

By default, pressing the Escape key 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.

Size

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

Gui_Size(GuiObj, MinMax, Width, Height)

MinMax

One of the following values:

0: The window is neither minimized nor maximized.
1: The window is maximized.
-1: The window is minimized.

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

Change

Raised when the control's value changes.

Ctrl_Change(GuiCtrlObj, Info)

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.

Click

Raised when the control is clicked.

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

Info

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.

Href

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.

DoubleClick

Raised when the control is double-clicked.

Ctrl_DoubleClick(GuiCtrlObj, Info)

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.

ColClick

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

Ctrl_ColClick(GuiCtrlObj, Info)

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.

ContextMenu

Raised when the user right-clicks the control or presses the Apps key 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)

Info

Reserved.

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.

ItemCheck

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

Ctrl_ItemCheck(GuiCtrlObj, Item, Checked)

Applies to: ListView, TreeView.

ItemEdit

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.

ItemExpand

Raised when a TreeView item is expanded or collapsed.

Ctrl_ItemExpand(GuiCtrlObj, Item, Expanded)

Applies to: TreeView.

ItemFocus

Raised when the focused item changes in a ListView.

Ctrl_ItemFocus(GuiCtrlObj, Item)

Applies to: ListView.

ItemSelect

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.