OnExit

Specifies a subroutine or function to run automatically when the script exits.

OnExit [, Label]
OnExit(Func [, AddRemove])  ; Requires [v1.1.20+]

Parameters

Label

If omitted, any previously registered label is unregistered. Otherwise, specify the name of the label whose contents will be executed (as a new thread) when the script exits by any means.

Func

A function name or function object to call when the script is exiting. The function can optionally define parameters as shown below. If an OnExit function returns a non-zero integer, the script does not exit. Otherwise, the script exits after all registered functions are called.

ExitFunc(ExitReason, ExitCode)

AddRemove

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

If a label (subroutine) has been registered, it is always called first.

Remarks

IMPORTANT: Since the specified subroutine is called instead of terminating the script, that subroutine must use the ExitApp command if termination is desired. [v1.1.20+]: New scripts should use a function instead of a subroutine -- this reduces the risk of accidentally creating a script which can't be exited, and ensures that the exit code passed to Exit or ExitApp is preserved.

[v1.1.20+]: Any number of OnExit functions can be registered. If a label (subroutine) is also registered, the functions are called after the subroutine calls ExitApp. An OnExit function usually should not call ExitApp; if it does, the script terminates immediately.

The OnExit subroutine is called when the script exits by any means (except when it is killed by something like "End Task"). It is also called whenever the #SingleInstance and Reload commands ask a previous instance to terminate.

A script can detect and optionally abort a system shutdown or logoff via OnMessage(0x11, "WM_QUERYENDSESSION").

The OnExit thread does not obey #MaxThreads (it will always launch when needed). In addition, while it is running, it cannot be interrupted by any thread, including hotkeys, custom menu items, and timed subroutines. However, it will be interrupted (and the script will terminate) if the user chooses Exit from the tray menu or main menu, or the script is asked to terminate as a result of Reload or #SingleInstance. Because of this, the OnExit subroutine should be designed to finish quickly unless the user is aware of what it is doing.

If the OnExit thread encounters a failure condition such as a runtime error, the script will terminate. This prevents a flawed OnExit subroutine from making a script impossible to terminate.

If the OnExit thread was launched due to an Exit or ExitApp command that specified an exit code, in [v1.1.19] and earlier that code is ignored and no longer available. In [v1.1.20+] the initial exit code is used unless overridden by calling ExitApp with a new exit code.

Whenever an exit attempt is made, each OnExit subroutine or function starts off fresh with the default values for settings such as SendMode. These defaults can be changed in the auto-execute section.

The built-in variable A_ExitReason is blank unless the OnExit subroutine is currently running or has been called at least once by a prior exit attempt. If not blank, it is one of the following words:

Related

OnMessage(), RegisterCallback(), OnClipboardChange, ExitApp, Shutdown, #Persistent, Threads, Gosub, Return, Menu

Examples

The following examples use #Persistent to prevent the script from exiting automatically. After running the script, right click the tray icon and click Exit to test the OnExit subroutine or function. Then click "Yes" to terminate the script or "No" to keep it running.

#Persistent
OnExit, ExitSub
return

ExitSub:
if A_ExitReason not in Logoff,Shutdown  ; Avoid spaces around the comma in this line.
{
    MsgBox, 4, , Are you sure you want to exit?
    IfMsgBox, No
        return
}
ExitApp  ; A script with an OnExit subroutine will not terminate unless the subroutine uses ExitApp.

#Persistent

; Register a function to be called on exit:
OnExit("ExitFunc")

; Register an object to be called on exit:
OnExit(ObjBindMethod(MyObject, "Exiting"))

ExitFunc(ExitReason, ExitCode)
{
    if ExitReason not in Logoff,Shutdown
    {
        MsgBox, 4, , Are you sure you want to exit?
        IfMsgBox, No
            return 1  ; OnExit functions must return non-zero to prevent exit.
    }
    ; Do not call ExitApp -- that would prevent other OnExit functions from being called.
}

class MyObject
{
    Exiting()
    {
        MsgBox, MyObject is cleaning up prior to exiting...
        /*
        this.SayGoodbye()
        this.CloseNetworkConnections()
        */
    }
}