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.
For details about the parameters, return value, naming, and more, see the following sections.
Type: Integer
If omitted, it defaults to 1. Otherwise, specify one of the following numbers:
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, e.g. MyCallback(Param1, *). 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.
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.
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).
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:
| Event | Raised when... |
|---|---|
| Close | The window is closed. |
| ContextMenu | The user right-clicks within the window or presses Menu or Shift+F10. |
| DropFiles | Files/folders are dragged and dropped onto the window. |
| Escape | The user presses Esc while the GUI window is active. |
| Size | The window is resized, minimized, maximized or restored. |
The following events are supported by GuiControl objects, depending on the control type:
| Event | Raised when... |
|---|---|
| Change | The control's value changes. |
| Click | The control is clicked. |
| DoubleClick | The control is double-clicked. |
| ColClick | One of the ListView's column headers is clicked. |
| ContextMenu | The user right-clicks the control or presses Menu or Shift+F10 while the control has the keyboard focus. |
| Focus | The control gains the keyboard focus. |
| LoseFocus | The control loses the keyboard focus. |
| ItemCheck | A ListView or TreeView item is checked or unchecked. |
| ItemEdit | A ListView or TreeView item's label is edited by the user. |
| ItemExpand | A TreeView item is expanded or collapsed. |
| ItemFocus | The focused item changes in a ListView. |
| ItemSelect | A ListView or TreeView item is selected, or a ListView item is deselected. |
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 GuiObj.Hide, or destroy the window by calling GuiObj.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
}
MyGui.Show()
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)
Type: Object or String (empty)
The GuiControl object of the control that received the event (blank if none).
Type: Integer
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 position number of the currently focused item. 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 row number or ID (or 0 if the user clicked somewhere other than an item). For Menu and Shift+F10, Item contains the selected item's row number or ID.
Type: Integer (boolean)
One of the following values:
Type: Integer
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)
Type: Object or String (empty)
The GuiControl object of the control upon which the files were dropped (blank if none).
Type: Array
An array 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
}Type: Integer
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.
Gui_Escape(GuiObj)
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)
Type: Integer
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.
Type: Integer
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.
Raised when the control's value changes.
Ctrl_Change(GuiCtrlObj, Info)
Type: Integer
Slider: A numeric value indicating how the slider moved. For details, see Detecting Changes.
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)
Type: Integer
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.
Type: String
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)
Type: Integer
ListView, TreeView and StatusBar: Same as for the Click event.
ListBox: The position number of the currently 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)
Type: Integer
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.
Raised when the control gains or loses the keyboard focus.
Ctrl_Focus(GuiCtrlObj, Info) Ctrl_LoseFocus(GuiCtrlObj, 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.
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 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.