MsgBox()

Auto Hotkey

MsgBox

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

MsgBox Text, Title, Options
Result := MsgBox(Text, Title, Options)

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.

Title

The title of the message box window. If omitted, it defaults to the current value of A_ScriptName.

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.

The Options parameter accepts either an integer value, which is passed directly to the operating system's MessageBox function, or a string of zero or more case-insensitive options separated by at least one space or tab. One or more numeric options may also be included in the string.

Function Decimal Value Hex Value String Value
OK (that is, only an OK button is displayed) 0 0x0 OK or O
OK/Cancel 1 0x1 OKCancel, O/C or OC
Abort/Retry/Ignore 2 0x2 AbortRetryIgnore, A/R/I or ARI
Yes/No/Cancel 3 0x3 YesNoCancel, Y/N/C or YNC
Yes/No 4 0x4 YesNo, Y/N or YN
Retry/Cancel 5 0x5 RetryCancel, R/C or RC
Cancel/Try Again/Continue 6 0x6 CancelTryAgainContinue, C/T/C or CTC
Adds a Help button (see remarks below) 16384 0x4000
Icons
Icon Hand (stop/error) 16 0x10 Iconx
Icon Question 32 0x20 Icon?
Icon Exclamation 48 0x30 Icon!
Icon Asterisk (info) 64 0x40 Iconi
Default Button
Makes the 2nd button the default 256 0x100 Default2
Makes the 3rd button the default 512 0x200 Default3
Makes the 4th button the default
(requires the Help button to be present)
768 0x300 Default4
Mode
System Modal (always on top) 4096 0x1000
Task Modal 8192 0x2000
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
Additional string-only options

Owner: To specify an owner window for the MsgBox, use the word Owner followed immediately by a HWND (window ID).

Owner%HWND%

Timeout: To have the MsgBox close automatically if the user has not closed it within a specified time, use the letter T followed by the timeout in seconds, which can contain a decimal point. If this value exceeds 2147483 (24.8 days), it will be set to 2147483.

If the MsgBox times out, the return value is the word Timeout.

Known limitation: If the MsgBox contains only an OK button, the return value will indicate that the OK button was pressed if the MsgBox times out while its own thread is interrupted by another.

Return Value

When called from an expression, MsgBox() returns one of the following strings to represent which button the user pressed:

OK
Cancel
Yes
No
Abort
Retry
Ignore
TryAgain
Continue
Timeout (that is, the word "timeout" is returned if the MsgBox timed out)

Remarks

When using the command syntax, remember to escape any commas in the text or title which are intended to be literal.

To determine which button the user pressed, use the function's return value. For example:

Result := MsgBox("Would you like to continue? (press Yes or No)",, "YesNo")
if Result = "Yes"
    MsgBox You pressed Yes.
else
    MsgBox You pressed No.

if MsgBox("Retry or cancel?",, "R/C") = "Retry"
    MsgBox("You pressed Retry.")

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 the OwnDialogs option. 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 the OwnDialogs option 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.

If the Owner%HWND% option is specified, it takes precedence over any other setting. HWND can be the HWND of any window, even one not owned by the script.

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 the OwnDialogs option.
  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

InputBox, FileSelect, DirSelect, ToolTip, GuiCreate

Example

Function Syntax

MsgBox()  ; "Press OK to continue."

MsgBox("Commas (,) do not need to be escaped in quoted strings.")

MsgBox("This MsgBox has a custom title.", "A Custom Title")

MsgBox("  ; Use a continuation section to span multiple lines:
  (
    The first parameter is displayed as the message.
    The second parameter becomes the window title.
    The third parameter determines the type of message box.
  )", "Window Title", "iconi")

if MsgBox("Do you want to continue? (Press YES or NO)",, "YesNo") = "No"
    return
	
result := MsgBox("This MsgBox will time out in 5 seconds.  Continue?",, "Y/N T5")
if result = "Timeout"
    MsgBox("You didn't press YES or NO within the 5-second period.")
else if result = "No"
    return

; Include a variable or sub-expression in the message.
var := 10
MsgBox("The initial value is: " var)
MsgBox("The result is: " var * 2)  ; Concatenation.
MsgBox("The result is: %var*2%")  ; Include an expression in a string with %%.

Command Syntax

MsgBox  ; "Press OK to continue."

MsgBox Commas (`,) in the text must be escaped when using this syntax.

MsgBox This MsgBox has a custom title., A Custom Title

MsgBox,  ; Use a continuation section to span multiple lines:
  (
    The first parameter is displayed as the message.
    The second parameter becomes the window title.
    The third parameter determines the type of message box.
  ), Window Title, iconi

MsgBox, Do you want to continue? (Press YES or NO),, YesNo, result
if result = "No"
    return
	
MsgBox, This MsgBox will time out in 5 seconds.  Continue?,, Y/N T5, result
if result = "Timeout"
    MsgBox, You didn't press YES or NO within the 5-second period.
else if result = "No"
    return

;Include a variable in the message.
var := 10
MsgBox The initial value is: %var%  ; Enclose variable names in percent signs.
MsgBox % "The result is: " var * 2  ; The "% " prefix makes this whole parameter an expression.
MsgBox The result is: %var*2%  ; Expressions are also allowed within %%.