# MsgBox

Displays the specified text in a small window containing one or more buttons (such as Yes and No).

MsgBox, Text
MsgBox [, Options, Title, Text, Timeout]

#### Parameters

Text | If all the parameters are omitted, the MsgBox will display the text "Press OK to continue." Otherwise, this parameter is the text displayed inside the message box to instruct the user what to do, or to present information. Escape sequences can be used to denote special characters. For example, `n indicates a linefeed character, which ends the current line and begins a new one. Thus, using text1`n`ntext2 would create a blank line between text1 and text2. If Text is long, it can be broken up into several shorter lines by means of a continuation section, which might improve readability and maintainability.
Options | Indicates the type of message box and the possible button combinations. If blank or omitted, it defaults to 0. See the table below for allowed values. This parameter will not be recognized if it contains an expression or a variable reference such as %option%. Instead, use a literal numeric value.
Title | The title of the message box window. If omitted or blank, it defaults to the name of the script (without path).
Timeout | (optional) Timeout in seconds (can contain a decimal point but cannot be an expression). If this value exceeds 2147483 (24.8 days), it will be set to 2147483. After the timeout has elapsed the message box will be automatically closed and the IfMsgBox command will see the value TIMEOUT. Known limitation: If the MsgBox contains only an OK button, IfMsgBox will think that the OK button was pressed if the MsgBox times out while its own thread is interrupted by another.

The Options parameter can be a combination (sum) of one or more of the following values.

Function | Decimal Value | Hex Value
OK (that is, only an OK button is displayed) | 0 | 0x0
OK/Cancel | 1 | 0x1
Abort/Retry/Ignore | 2 | 0x2
Yes/No/Cancel | 3 | 0x3
Yes/No | 4 | 0x4
Retry/Cancel | 5 | 0x5
Cancel/Try Again/Continue (2000/XP+) | 6 | 0x6
Adds a Help button (see remarks below) | 16384 | 0x4000
Icon Hand (stop/error) | 16 | 0x10
Icon Question | 32 | 0x20
Icon Exclamation | 48 | 0x30
Icon Asterisk (info) | 64 | 0x40
Makes the 2nd button the default | 256 | 0x100
Makes the 3rd button the default | 512 | 0x200
System Modal (always on top) | 4096 | 0x1000
Task Modal | 8192 | 0x2000
Shows the MsgBox on default desktop (Windows NT/2000/XP or later) | 131072 | 0x20000
Always-on-top (style WS_EX_TOPMOST) (like System Modal but omits title bar icon) | 262144 | 0x40000
Make the text right-justified | 524288 | 0x80000
Right-to-left reading order for Hebrew/Arabic | 1048576 | 0x100000

#### Remarks

The table above is used by adding up the values you wish to be present in the MsgBox. For example, to specify a Yes/No box with the default button being No instead of Yes, the Options value would be 256+4 (260). In hex, it would be 0x100+0x4 (0x104).

MsgBox has smart comma handling, so it is usually not necessary to escape commas in the Text parameter.

To determine which button the user pressed in the most recent MsgBox, use the IfMsgBox command. For example:

    MsgBox, 4,, Would you like to continue? (press Yes or No)
    IfMsgBox Yes
        MsgBox You pressed Yes.
    else
        MsgBox You pressed No.

The names of the buttons can be customized by following this example.

Tip: Pressing Control-C while a MsgBox window is active will copy its text to the clipboard. This applies to all MsgBoxes, not just those produced by AutoHotkey.

Using MsgBox with GUI windows: A GUI window may display a modal MsgBox by means of Gui +OwnDialogs. A modal MsgBox prevents the user from interacting with the GUI window until the MsgBox is dismissed. In such a case, it is not necessary to specify the System Modal or Task Modal options from the table above.

When Gui +OwnDialogs is not in effect, the Task Modal option (8192) can be used to disable all the script's windows until the user dismisses the MsgBox.

The Help button: When the Help button option (83) is present in Options, pressing the Help button will have no effect unless both of the following are true:

1. The MsgBox is owned by a GUI window by means of Gui +OwnDialogs.
2. The script is monitoring the WM_HELP message (0x53). For example: OnMessage(0x53, "WM_HELP"). When the WM_HELP() function is called, it may guide the user by means such as showing another window or MsgBox.

The Close button (in MsgBox's title bar): Since the MsgBox window is a built-in feature of the operating system, its X button is enabled only when certain buttons are present. If there is only an OK button, clicking the X button is the same as pressing OK. Otherwise, the X button is disabled unless there is a Cancel button, in which case clicking the X is the same as pressing Cancel.

#### Related

IfMsgBox, InputBox, FileSelectFile, FileSelectFolder, ToolTip, GUI

#### Example

    MsgBox This is the 1-parameter method. Commas (,) do not need to be escaped.
    MsgBox, 4, , This is the 3-parameter method. Commas (,) do not need to be escaped.
    MsgBox, 4, , Do you want to continue? (Press YES or NO)
    IfMsgBox No
        return
    MsgBox, 4, , 4-parameter method: this MsgBox will time out in 5 seconds.  Continue?, 5
    IfMsgBox Timeout
        MsgBox You didn't press YES or NO within the 5-second period.
    else IfMsgBox No
        return

    ; By preceding any parameter with "% ", it becomes an expression. In the following example,
    ; math is performed, an array element is accessed, and a function is called.  All of these
    ; items are concatenated via the "." operator to form a single string displayed by MsgBox:
    MsgBox % "New width for object #" . A_Index . " is: " . RestrictWidth(ObjectWidth%A_Index% * ScalingFactor)

    ; The following example alerts the user that a MsgBox is going to steal focus (in case the user is typing).
    SplashTextOn,,, A MsgBox is about to appear.
    Sleep 3000
    SplashTextOff
    MsgBox The backup process has completed.