Function Reference

GUIGetMsg

Polls the GUI to see if any events have occurred.

GUIGetMsg ( [advanced = 0] )

Parameters

advanced [optional] return extended information in an array.
    $GUI_EVENT_SINGLE (0) = (default) Returns a single event.
    $GUI_EVENT_ARRAY (1) = returns an array containing the event and extended information.

Constants are defined in GUIConstantsEx.au3.

Return Value

Returns an event, or an array depending on the "advanced" parameter.

The "event" returned is the control ID of the control sending the message, or it is a special event (like the window is closing, minimizing). Or if there is no message, the event is 0.

Event ID: the ID of the control sending the message
$GUI_EVENT_NONE (0): No event
$GUI_EVENT_CLOSE: dialog box being closed (either by defined button or system menu).
$GUI_EVENT_MINIMIZE: dialog box minimized with Windows title bar button.
$GUI_EVENT_RESTORE: dialog box restored by click on task bar icon.
$GUI_EVENT_MAXIMIZE: dialog box maximized with Windows title bar button.
$GUI_EVENT_MOUSEMOVE: the mouse cursor has moved.
$GUI_EVENT_PRIMARYDOWN: the primary mouse button was pressed.
$GUI_EVENT_PRIMARYUP: the primary mouse button was released.
$GUI_EVENT_SECONDARYDOWN: the secondary mouse button was pressed.
$GUI_EVENT_SECONDARYUP: the secondary mouse button was released.
$GUI_EVENT_RESIZED: dialog box has been resized.
$GUI_EVENT_DROPPED: End of a Drag&Drop action @GUI_DragId, @GUI_DragFile and @GUI_DropId will be used to retrieve the ID's/file corresponding to the involve control.

Constants are defined in GUIConstantsEx.au3.

When using the "advanced" parameter the information is returned in an array with extended information:

$aArray[0] = 0 or Event ID or Control ID
$aArray[1] = The window handle the event is from
$aArray[2] = The control handle the event is from (if applicable)
$aArray[3] = The current X position of the mouse cursor (relative to the GUI window)
$aArray[4] = The current Y position of the mouse cursor (relative to the GUI window)

If the GUIOnEventMode option is set to 1 then the return from GUIGetMsg is always 0 and the @error is set to 1.

If the option GUIEventOptions is set to 1 the minimize, restore and maximize button will not do any action on the window just a simple notification.

Remarks

This function automatically idles the CPU when required so that it can be safely used in tight loops without hogging all the CPU.

Information about the mouse position and the hovering control can be retrieved with GUIGetCursorInfo(). No event is fired when the mouse is over a control so GUIGetCursorInfo() must be called to retrieve the controlID.

Related

GUICreate, GUICtrlCreate..., GUICtrlRead, GUICtrlSendMsg, GUICtrlSetOnEvent, GUIEventOptions (Option), GUIGetCursorInfo, GUIOnEventMode (Option)

Example

Example 1

#include <GUIConstantsEx.au3>
#include <MsgBoxConstants.au3>

Example()

; -------------------------------------------------------------------------------------
; Example - Press the button to see the value of the radio boxes
; The script also detects state changes (closed/minimized/timeouts, etc).
Func Example()
        Opt("GUICoordMode", 1)

        GUICreate("Radio Box Demo", 400, 280)

        ; Create the controls
        Local $idButton_1 = GUICtrlCreateButton("B&utton 1", 30, 20, 120, 40)
        GUICtrlCreateGroup("Group 1", 30, 90, 165, 160)
        GUIStartGroup()
        Local $idRadio_1 = GUICtrlCreateRadio("Radio &0", 50, 120, 70, 20)
        GUICtrlCreateRadio("Radio &1", 50, 150, 60, 20)
        Local $idRadio_3 = GUICtrlCreateRadio("Radio &2", 50, 180, 60, 20)

        ; Init our vars that we will use to keep track of GUI events
        Local $iRadioVal1 = 0 ; We will assume 0 = first radio button selected, 2 = last button

        ; Show the GUI
        GUISetState(@SW_SHOW)

        Local $idMsg = 0
        ; In this message loop we use variables to keep track of changes to the radios, another
        ; way would be to use GUICtrlRead() at the end to read in the state of each control
        While 1
                $idMsg = GUIGetMsg()
                Select
                        Case $idMsg = $GUI_EVENT_CLOSE
                                MsgBox($MB_SYSTEMMODAL, "", "Dialog was closed")
                                ExitLoop
                        Case $idMsg = $GUI_EVENT_MINIMIZE
                                MsgBox($MB_SYSTEMMODAL, "", "Dialog minimized", 2)
                        Case $idMsg = $GUI_EVENT_RESTORE
                                MsgBox($MB_SYSTEMMODAL, "", "Dialog restored", 2)
                        Case $idMsg = $idButton_1
                                MsgBox($MB_SYSTEMMODAL, "", "Default button clicked:" & @CRLF & "Radio " & $iRadioVal1)
                        Case $idMsg >= $idRadio_1 And $idMsg <= $idRadio_3
                                $iRadioVal1 = $idMsg - $idRadio_1
                EndSelect
        WEnd

        GUIDelete()
EndFunc   ;==>Example

Example 2

#include <GUIConstantsEx.au3>
#include <MsgBoxConstants.au3>

Example()

Func Example()
        ; Create a GUI.
        Local $hGUI1 = GUICreate("Example GUI1")
        ; Create a button.
        Local $idButton1 = GUICtrlCreateButton("Button1", 10, 10, 80, 22)
        ; Display the GUI
        GUISetState(@SW_SHOW, $hGUI1)

        ; Create a GUI.
        Local $hGUI2 = GUICreate("Example GUI2", 300, 300)
        ; Create a button.
        Local $idButton2 = GUICtrlCreateButton("Button2", 10, 10, 80, 22)
        ; Display the GUI
        GUISetState(@SW_SHOW, $hGUI2)

        ; Initialize a Local variable.
        Local $aMsg = 0

        While 1
                ; Assign to $aMsg the advanced GUI messages.
                $aMsg = GUIGetMsg($GUI_EVENT_ARRAY)

                ; Switch from GUIs
                Switch $aMsg[1]
                        Case $hGUI1
                                ; The event comes from the GUI1

                                ; Switch from event ID
                                Switch $aMsg[0]
                                        Case $GUI_EVENT_CLOSE
                                                ExitLoop
                                        Case $idButton1
                                                MsgBox($MB_SYSTEMMODAL, "", "Button1 clicked.")
                                EndSwitch
                        Case $hGUI2
                                ; The event comes from the GUI2

                                ; Switch from event ID
                                Switch $aMsg[0]
                                        Case $GUI_EVENT_CLOSE
                                                GUIDelete($hGUI2)
                                        Case $idButton2
                                                MsgBox($MB_SYSTEMMODAL, "", "Button2 clicked.")
                                EndSwitch
                EndSwitch
        WEnd

        ; Delete the previous GUIs and all controls.
        GUIDelete($hGUI1)
EndFunc   ;==>Example