OnExit() / OnExit

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

OnExit() [v1.1.20+]

OnExit(Func , AddRemove)

Parameters

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 (with some rare exceptions) and no more functions are called. Otherwise, the script exits after all registered functions are called.

ExitFunc(ExitReason, ExitCode)

AddRemove

If blank or omitted, it defaults to 1 (call the function after any previously registered functions). Otherwise, specify one of the following numbers:

• 1 = 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

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.

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.

OnExit

Deprecated: This command is not recommended for use in new scripts. Use the OnExit function instead.

OnExit , Label

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.

Remarks

IMPORTANT: Since the specified subroutine is called instead of terminating the script, that subroutine must use the ExitApp command if termination is desired.

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 words from the table below.

Remarks

The OnExit callback function or 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(0x0011, "WM_QUERYENDSESSION") (see OnMessage example #2 for a working script).

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 callback function or 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 callback function or 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 callback function or subroutine starts off fresh with the default values for settings such as SendMode. These defaults can be changed in the auto-execute section.

Exit Reasons

Related

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

Examples

#Persistent  ; Prevent the script from exiting automatically.
OnExit("ExitFunc")

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

#Persistent  ; Prevent the script from exiting automatically.
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  ; Prevent the script from exiting automatically.
OnExit(ObjBindMethod(MyObject, "Exiting"))

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