Ξ
Δ
◄
►
¬
Ѕ
Filter
Directives
Built-in Variables
Built-in Functions
Control Flow Statements
Operators
Declarations
Commands
Sub-commands
Built-in Methods/Properties
Ahk2Exe Compiler
Highlight keywords
</head> <body> <h1>MsgBox</h1> <p>Displays the specified text in a small window containing one or more buttons (such as Yes and No).</p> <pre class="Syntax"> <span class="func">MsgBox</span>, Text <span class="func">MsgBox</span> <span class="optional">, Options, Title, Text, Timeout</span> </pre> <h2 id="Parameters">Parameters</h2> <dl> <dt>Text</dt> <dd><p>If all the parameters are omitted, the message box 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.</p> <p><a href="../misc/EscapeChar.htm">Escape sequences</a> 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.</p> <p>If <em>Text</em> is long, it can be broken up into several shorter lines by means of a <a href="../Scripts.htm#continuation">continuation section</a>, which might improve readability and maintainability.</p></dd> <dt>Options</dt> <dd><p>Indicates the type of message box and the possible button combinations. If blank or omitted, it defaults to 0. See the tables below for allowed values.</p> <p>This parameter must be either a literal number or <span class="ver">[in v1.1.06+]</span> a forced expression such as <code>% Options</code>. Any other non-blank value will not be recognized as this parameter, but instead as part of <em>Text</em> in the single-parameter mode.</p></dd> <dt>Title</dt> <dd><p>The title of the message box window. If omitted or blank, it defaults to the name of the script (without path).</p></dd> <dt id="Timeout">Timeout</dt> <dd><p>(optional) Timeout in seconds, which can contain a decimal point but is not an expression by default. <span class="ver">[v1.1.06+]</span>: This can be a forced expression such as <code>% mins*60</code>.</p> <p>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 <a href="IfMsgBox.htm">IfMsgBox</a> command will see the value TIMEOUT.</p> <p>The following limitation was fixed in <span class="ver">[v1.1.30.01]</span>: If the message box contains only an OK button, <a href="IfMsgBox.htm">IfMsgBox</a> will think that the OK button was pressed if the message box times out while its own <a href="../misc/Threads.htm">thread</a> is inactive due to being interrupted by another.</p></dd> </dl> <h2 id="Options">Values for the <em>Options</em> parameter</h2> <p>The <em>Options</em> parameter can be a combination (sum) of values from the following groups.</p> <h3 id="Group_1_Buttons">Group #1: Buttons</h3> <p>To indicate the buttons displayed in the message box, add <strong>one</strong> of the following values:</p> <table class="info"> <tr> <th style="width:287px">Function</th> <th abbr="Dec">Decimal Value</th> <th abbr="Hex">Hex Value</th> </tr> <tr> <td>OK (that is, only an OK button is displayed)</td> <td>0</td> <td>0x0</td> </tr> <tr> <td>OK/Cancel</td> <td>1</td> <td>0x1</td> </tr> <tr> <td>Abort/Retry/Ignore</td> <td>2</td> <td>0x2</td> </tr> <tr> <td>Yes/No/Cancel</td> <td>3</td> <td>0x3</td> </tr> <tr> <td>Yes/No</td> <td>4</td> <td>0x4</td> </tr> <tr> <td>Retry/Cancel</td> <td>5</td> <td>0x5</td> </tr> <tr> <td>Cancel/Try Again/Continue</td> <td>6</td> <td>0x6</td> </tr> </table> <h3 id="Group_2_Icon">Group #2: Icon</h3> <p>To display an icon in the message box, add <strong>one</strong> of the following values:</p> <table class="info"> <tr> <th style="width:287px">Function</th> <th abbr="Dec">Decimal Value</th> <th abbr="Hex">Hex Value</th> </tr> <tr> <td>Icon Hand (stop/error)</td> <td>16</td> <td>0x10</td> </tr> <tr> <td>Icon Question</td> <td>32</td> <td>0x20</td> </tr> <tr> <td>Icon Exclamation</td> <td>48</td> <td>0x30</td> </tr> <tr> <td>Icon Asterisk (info)</td> <td>64</td> <td>0x40</td> </tr> </table> <h3 id="Group_3_Default_Button">Group #3: Default Button</h3> <p>To indicate the default button, add <strong>one</strong> of the following values:</p> <table class="info"> <tr> <th style="width:287px">Function</th> <th abbr="Dec">Decimal Value</th> <th abbr="Hex">Hex Value</th> </tr> <tr> <td>Makes the 2nd button the default</td> <td>256</td> <td>0x100</td> </tr> <tr> <td>Makes the 3rd button the default</td> <td>512</td> <td>0x200</td> </tr> <tr> <td>Makes the 4th button the default<br>(requires the Help button to be present)</td> <td>768</td> <td>0x300</td> </tr> </table> <h3 id="Group_4_Modality">Group #4: Modality</h3> <p>To indicate the modality of the dialog box, add <strong>one</strong> of the following values:</p> <table class="info"> <tr> <th style="width:287px">Function</th> <th abbr="Dec">Decimal Value</th> <th abbr="Hex">Hex Value</th> </tr> <tr> <td>System Modal (always on top)</td> <td>4096</td> <td>0x1000</td> </tr> <tr> <td>Task Modal</td> <td>8192</td> <td>0x2000</td> </tr> <tr> <td>Always-on-top (style WS_EX_TOPMOST)<br> (like System Modal but omits title bar icon)</td> <td>262144</td> <td>0x40000</td> </tr> </table> <h3 id="Group_5_Other_Options">Group #5: Other Options</h3> <p>To specify other options, add <strong>one or more</strong> of the following values:</p> <table class="info"> <tr> <th style="width:287px">Function</th> <th abbr="Dec">Decimal Value</th> <th abbr="Hex">Hex Value</th> </tr> <tr> <td>Adds a Help button (see remarks below)</td> <td>16384</td> <td>0x4000</td> </tr> <tr> <td>Make the text right-justified</td> <td>524288</td> <td>0x80000</td> </tr> <tr> <td>Right-to-left reading order for Hebrew/Arabic</td> <td>1048576</td> <td>0x100000</td> </tr> </table> <h2 id="Remarks">Remarks</h2> <p>A message box usually looks like this:</p> <img src="../static/dlg_message.png" alt="MsgBox" /> <p>The tables above are used by adding up the values you wish to be present in the message box. For example, to specify a Yes/No box with the default button being No instead of Yes, the <em>Options</em> value would be 256+4 (260). In hex, it would be 0x100+0x4 (0x104).</p> <p>MsgBox has smart comma handling, so it is usually not necessary to <a href="../misc/EscapeChar.htm">escape</a> commas in the <em>Text</em> parameter.</p> <p>To determine which button the user pressed in the most recent message box, use the <a href="IfMsgBox.htm">IfMsgBox</a> command. For example:</p> <pre>MsgBox, 4,, Would you like to continue? (press Yes or No) IfMsgBox Yes MsgBox You pressed Yes. else MsgBox You pressed No.</pre> <p>The names of the buttons can be customized by following <a href="../scripts/index.htm#MsgBoxButtonNames">this example</a>.</p> <p><strong>Tip</strong>: Pressing <kbd>Ctrl</kbd>+<kbd>C</kbd> while a message box is active will copy its text to the clipboard. This applies to all message boxes, not just those produced by AutoHotkey.</p> <p><strong>Using MsgBox with GUI windows</strong>: A GUI window may display a <em>modal</em> message box by means of <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a>. A <em>modal</em> message box prevents the user from interacting with the GUI window until the message box is dismissed. In such a case, it is not necessary to specify the System Modal or Task Modal options from the table above.</p> <p>When <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a> is <em>not</em> in effect, the Task Modal option (8192) can be used to disable all the script's windows until the user dismisses the message box.</p> <p><strong>The Help button</strong>: When the Help button option (16384) is present in <em>Options</em>, pressing the Help button will have no effect unless both of the following are true:</p> <ol> <li>The message box is owned by a GUI window by means of <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a>.</li> <li>The script is monitoring the WM_HELP message (0x0053). For example: <code><a href="OnMessage.htm">OnMessage</a>(0x0053, "WM_HELP")</code>. When the WM_HELP() function is called, it may guide the user by means such as showing another window or MsgBox.</li> </ol> <p><strong>The Close button (in the message box's title bar)</strong>: Since the message box is a built-in feature of the operating system, its <strong>X</strong> button is enabled only when certain buttons are present. If there is only an OK button, clicking the <strong>X</strong> button is the same as pressing OK. Otherwise, the X button is disabled unless there is a Cancel button, in which case clicking the <strong>X</strong> is the same as pressing Cancel.</p> <h2 id="Related">Related</h2> <p><a href="IfMsgBox.htm">IfMsgBox</a>, <a href="InputBox.htm">InputBox</a>, <a href="FileSelectFile.htm">FileSelectFile</a>, <a href="FileSelectFolder.htm">FileSelectFolder</a>, <a href="ToolTip.htm">ToolTip</a>, <a href="Gui.htm">GUI</a></p> <h2 id="Examples">Examples</h2> <div class="ex" id="ExOneParam"> <p><a class="ex_number" href="#ExOneParam"></a> The 1-parameter method. A quick and easy way to show information. The user can press an OK button to close the message box and continue execution.</p> <pre>MsgBox This is the 1-parameter method. Commas (,) do not need to be escaped.</pre> </div> <div class="ex" id="ExThreeParam"> <p><a class="ex_number" href="#ExThreeParam"></a> The 3-parameter method. Use the first and second parameter to specify the options and the title.</p> <pre>MsgBox, 4, , This is the 3-parameter method. Commas (,) do not need to be escaped.</pre> </div> <div class="ex" id="ExIfMsgBox"> <p><a class="ex_number" href="#ExIfMsgBox"></a> Use <a href="IfMsgBox.htm">IfMsgBox</a> to determine which button the user pressed in the most recent message box.</p> <pre>MsgBox, 4, , Do you want to continue? (Press YES or NO) IfMsgBox No return</pre> </div> <div class="ex" id="ExTimeout"> <p><a class="ex_number" href="#ExTimeout"></a> The 4-parameter method. Use the fourth parameter (Timeout) to automatically close the message box after a certain number of seconds.</p> <pre>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</pre> </div> <div class="ex" id="ExExpression"> <p><a class="ex_number" href="#ExExpression"></a> By preceding any parameter with <code>% </code>, it becomes an <a href="../Variables.htm#Expressions">expression</a>. In the following example, math is performed, a <a href="../misc/Arrays.htm#pseudo">pseudo-array</a> element is accessed, and a function is called. All these items are concatenated via the "." operator to form a single string displayed by MsgBox.</p> <pre>MsgBox % "New width for object #" . A_Index . " is: " . RestrictWidth(ObjectWidth%A_Index% * ScalingFactor)</pre> </div> <div class="ex" id="ExFocus"> <p><a class="ex_number" href="#ExFocus"></a> Alerts the user that a message box is going to steal focus (in case the user is typing).</p> <pre>SplashTextOn,,, A message box is about to appear. Sleep 3000 SplashTextOff MsgBox The backup process has completed.</pre> </div> </body> </html>