</head> <body> <h1>GUI</h1> <p>Creates and manages windows and controls. Such windows can be used as data entry forms or custom user interfaces.</p> <pre class="Syntax"><span class="func">Gui</span>, <a href="#SubCommands">SubCommand</a> <span class="optional">, Value1, Value2, Value3</span></pre> <p>The <em>SubCommand</em>, <em>Value1</em>, <em>Value2</em> and <em>Value3</em> parameters are dependent upon each other and their usage is described below.</p> <h2 id="toc">Sumário</h2> <ul> <li><a href="#SubCommands">Sub-commands</a></li> <li><a href="#ControlOptions">Options for a Control (Gui Add)</a><ul> <li><a href="#PosSize">Positioning and Sizing of Controls</a></li> <li><a href="#Events">Storing and Responding to User Input</a></li> <li><a href="#OtherOptions">Controls: Common Styles and Other Options</a></li> </ul></li> <li><a href="#Labels">Window Events</a>: <a href="#GuiClose">GuiClose</a> | <a href="#GuiEscape">GuiEscape</a> | <a href="#GuiSize">GuiSize</a> | <a href="#GuiContextMenu">GuiContextMenu</a> | <a href="#GuiDropFiles">GuiDropFiles</a></li> <li><a href="#MultiWin">Creating Multiple GUI windows</a></li> <li><a href="#DefaultWin">GUI Events, Threads, and Subroutines</a></li> <li><a href="#Navigate">Keyboard Navigation</a></li> <li><a href="#Appear">Window Appearance</a></li> <li><a href="#GenRemarks">Observações Gerais</a></li> <li><a href="#Examples">Exemplos</a></li> </ul> <h2 id="SubCommands">Sub-commands</h2> <p>For <em>SubCommand</em>, specify one of the following:</p> <ul> <li><a href="#New">New</a> <span class="ver">[v1.1.04+]</span>: Creates a new window.</li> <li><a href="#Add">Add</a>: Creates a control such as text, button, or checkbox.</li> <li><a href="#Show">Show</a>: Displays the window. It can also minimize, maximize, or move the window.</li> <li><a href="#Submit">Submit</a>: Saves the user's input and optionally hides the window.</li> <li><a href="#Cancel">Cancel</a> / <a href="#Hide">Hide</a>: Hides the window.</li> <li><a href="#Destroy">Destroy</a>: Deletes the window.</li> <li><a href="#Font">Font</a>: Sets the typeface, size, style, and text color for subsequently created controls.</li> <li><a href="#Color">Color</a>: Sets the background color for the window and/or its controls.</li> <li><a href="#Margin">Margin</a>: Sets the margin/spacing used whenever no explicit position has been specified for a control.</li> <li><a href="#Options">Options and styles for a window</a>: Sets various options for the appearance and behavior of the window.</li> <li><a href="#Menu">Menu</a>: Adds or removes a menu bar.</li> <li><a href="#Minimize">Minimize</a> / <a href="#Maximize">Maximize</a> / <a href="#Restore">Restore</a>: Performs the indicated operation on the window.</li> <li><a href="#Flash">Flash</a>: Blinks the window and its taskbar button.</li> <li><a href="#Default">Default</a>: Changes the current thread's default GUI window name.</li> </ul> <h3 id="New">New <span class="ver">[v1.1.04+]</span></h3> <p>Creates a new window and sets it as the <a href="#Default">default</a> for the current thread.</p> <pre class="Syntax"><span class="func">Gui</span>, New <span class="optional">, Options, Title</span> <span class="func">Gui</span>, GuiName:New <span class="optional">, Options, Title</span></pre> <p>If <em>GuiName</em> is specified, a new GUI will be created, destroying any existing GUI with that name. Otherwise, a new unnamed and unnumbered GUI will be created.</p> <p><em>Options</em> can contain any of the <a href="#Options">options</a> supported by the main GUI command.</p> <p>If <em>Title</em> is omitted, the script's file name is used.</p> <p>This sub-command comes with the following caveats:</p> <ul> <li>In most cases the window is created automatically on demand, so it is usually unnecessary to call <code>Gui New</code>.</li> <li>Although the new window is set as the <a href="#Default">default</a> for the <em>current</em> thread, non-GUI threads still <a href="#DefaultWin">default to GUI number 1</a>.</li> <li>If the GUI has no name and is not the <a href="#Default">default GUI</a>, it must be identified by its HWND. Use the <a href="#GuiHwndOutputVar">+Hwnd<i>GuiHwnd</i></a> option to store the HWND of the new window in <em>GuiHwnd</em>. <code>Gui, %<i>GuiHwnd</i>%:Default</code> can be used to make the other Gui commands operate on it by default.</li> </ul> <p>On the positive side:</p> <ul> <li>Calling <code>Gui New</code> ensures that the script is creating a new GUI, not modifying an existing one. It might also make the script's purpose clearer to other people who read your code (or future you).</li> <li><code>Gui New</code> eliminates the need to pick a unique name or number for each GUI. This can be especially useful if the script needs to create more than one GUI, or is intended to be included in other scripts.</li> <li>Sometimes it is more intuitive to set the window's title when the GUI is created instead of when it is <a href="#Show">shown</a>.</li> </ul> <p>If no name is given, the following applies:</p> <ul> <li>Special <a href="#Labels">labels</a> such as <a href="#GuiClose">GuiClose</a> have the default "Gui" prefix unless overridden by <a href="#PlusLabel">+Label<em>Prefix</em></a> in the options.</li> <li>Whenever the GUI launches a new thread, <a href="../Variables.htm#Gui">A_Gui</a> contains a HWND instead of a name.</li> </ul> <p class="note"><strong>Note:</strong> Prior to <span class="ver">[v1.1.08]</span>, this sub-command did not set the default Gui if a name was specified.</p> <h3 id="Add">Add</h3> <p>Adds a control to a GUI window (first creating the GUI window itself, if necessary).</p> <pre class="Syntax"><span class="func">Gui</span>, Add, ControlType <span class="optional">, Options, Text</span></pre> <p><em>ControlType</em> is one of the following:</p> <ul> <li><a href="GuiControls.htm#Text">Text</a>, <a href="GuiControls.htm#Edit">Edit</a>, <a href="GuiControls.htm#UpDown">UpDown</a>, <a href="GuiControls.htm#Picture">Picture</a></li> <li><a href="GuiControls.htm#Button">Button</a>, <a href="GuiControls.htm#Checkbox">Checkbox</a>, <a href="GuiControls.htm#Radio">Radio</a></li> <li><a href="GuiControls.htm#DropDownList">DropDownList</a>, <a href="GuiControls.htm#ComboBox">ComboBox</a></li> <li><a href="GuiControls.htm#ListBox">ListBox</a>, <a href="ListView.htm">ListView</a>, <a href="TreeView.htm">TreeView</a></li> <li><a href="GuiControls.htm#Link">Link</a>, <a href="GuiControls.htm#Hotkey">Hotkey</a>, <a href="GuiControls.htm#DateTime">DateTime</a>, <a href="GuiControls.htm#MonthCal">MonthCal</a></li> <li><a href="GuiControls.htm#Slider">Slider</a>, <a href="GuiControls.htm#Progress">Progress</a></li> <li><a href="GuiControls.htm#GroupBox">GroupBox</a>, <a href="GuiControls.htm#Tab">Tab</a>, <a href="GuiControls.htm#StatusBar">StatusBar</a></li> <li><a href="GuiControls.htm#ActiveX">ActiveX</a> (e.g. Internet Explorer Control)</li> <li><a href="GuiControls.htm#Custom">Custom</a></li> </ul> <p><em>Options</em> is a string of zero or more options, as described in the following sections:</p> <ul> <li><a href="#PosSize">Positioning and Sizing of Controls</a></li> <li><a href="#Events">Storing and Responding to User Input</a></li> <li><a href="#OtherOptions">Controls: Common Styles and Other Options</a></li> </ul> <p>Por exemplo:</p> <pre>Gui, Add, Text,, Please enter your name: Gui, Add, Edit, vName Gui, Show</pre> <h3 id="Show">Show</h3> <p>Unless otherwise specified in <em>Options</em>, this sub-command makes the window visible, unminimizes it (if necessary), <a href="WinActivate.htm">activates</a> it, and sets its title.</p> <pre class="Syntax"><span class="func">Gui</span>, Show <span class="optional">, Options, Title</span></pre> <p>If <em>Title</em> is omitted, the previous title is retained (or if none, the script's file name is used).</p> <p>Omit the X, Y, W, and H options below to have the window retain its previous size and position. If there is no previous position, the window will be auto-centered in one or both dimensions if the X and/or Y options mentioned below are absent. If there is no previous size, the window will be auto-sized according to the size and positions of the controls it contains.</p> <p>Zero or more of the following strings may be present in <em>Options</em> (specify each number as decimal, not hexadecimal):</p> <p><strong>Wn</strong>: Specify for <strong>n</strong> the width (in pixels) of the window's client area (the client area excludes the window's borders, title bar, and <a href="#Menu">menu bar</a>).</p> <p><strong>Hn</strong>: Specify for <strong>n</strong> the height of the window's client area, in pixels.</p> <p><strong>Xn</strong>: Specify for <strong>n</strong> the window's X-position on the screen, in pixels. Position 0 is the leftmost column of pixels visible on the screen.</p> <p><strong>Yn</strong>: Specify for <strong>n</strong> the window's Y-position on the screen, in pixels. Position 0 is the topmost row of pixels visible on the screen.</p> <p><strong>Center</strong>: Centers the window horizontally and vertically on the screen.</p> <p><strong>xCenter</strong>: Centers the window horizontally on the screen. Por exemplo: <code>Gui, Show, xCenter y0</code>.</p> <p><strong>yCenter</strong>: Centers the window vertically on the screen.</p> <p id="AutoSize"><strong>AutoSize</strong>: Resizes the window to accommodate only its currently visible controls. This is useful to resize the window after new controls are added, or existing controls are resized, hidden, or unhidden. Por exemplo: <code>Gui, Show, AutoSize Center</code>.</p> <p><strong>Minimize</strong>: Minimizes the window and activates the one beneath it.</p> <p><strong>Maximize</strong>: Maximizes and activates the window.</p> <p><strong>Restore</strong>: Unminimizes or unmaximizes the window, if necessary. The window is also shown and activated, if necessary.</p> <p><strong>NoActivate</strong>: Unminimizes or unmaximizes the window, if necessary. The window is also shown without activating it.</p> <p><strong>NA</strong>: Shows the window without activating it. If the window is minimized, it will stay that way but will probably rise higher in the z-order (which is the order seen in the alt-tab selector). If the window was previously hidden, this will probably cause it to appear on top of the active window even though the active window is not deactivated.</p> <p><strong>Hide</strong>: Hides the window and activates the one beneath it. This is identical in function to <a href="#Cancel">Gui Cancel</a> except that it allows a hidden window to be moved, resized, or given a new title without showing it. Por exemplo: <code>Gui, Show, Hide x55 y66 w300 h200, New Title</code>.</p> <h3 id="Submit">Submit</h3> <p>Saves the contents of each control to its <a href="#var">associated variable</a> (if any) and hides the window unless the NoHide option is present.</p> <pre class="Syntax"><span class="func">Gui</span>, Submit <span class="optional">, NoHide</span></pre> <p>For controls that produce multiple fields of output, such as a <a href="GuiControls.htm#ListBoxMulti">multi-select ListBox</a>, the output uses the window's <a href="#Delimiter">current delimiter</a>. If the window does not exist -- perhaps due to having been destroyed via <a href="#Destroy">Gui Destroy</a> -- this sub-command has no effect.</p> <div id="Cancel"><h3 id="Hide">Cancel / Hide</h3></div> <p>Hides the window without saving the controls' contents to their <a href="#var">associated variables</a>.</p> <pre class="Syntax"><span class="func">Gui</span>, Cancel <span class="func">Gui</span>, Hide</pre> <p>If the window does not exist -- perhaps due to having been destroyed via <a href="#Destroy">Gui Destroy</a> -- this sub-command has no effect.</p> <h3 id="Destroy">Destroy</h3> <p>Removes the window (if it exists) and all its controls, freeing the corresponding memory and system resources.</p> <pre class="Syntax"><span class="func">Gui</span>, Destroy</pre> <p>If the script later recreates the window, all of the window's properties such as color and font will start off at their defaults (as though the window never existed). If this sub-command is not used, all GUI windows are automatically destroyed when the script exits.</p> <h3 id="Font">Font</h3> <p>Sets the font typeface, size, style, and/or color for controls added to the window from this point onward.</p> <pre class="Syntax"><span class="func">Gui</span>, Font <span class="optional">, Options, FontName</span></pre> <p>Por exemplo:</p> <pre>Gui, Font, s10, Verdana <em>; Set 10-point Verdana.</em></pre> <p>Omit the last two parameters to restore the font to the system's default GUI typeface, size, and color.</p> <p><em>FontName</em> may be the name of any font, such as one from the <a href="../misc/FontsStandard.htm">font table</a>. If <em>FontName</em> is omitted or does not exist on the system, the previous font's typeface will be used (or if none, the system's default GUI typeface). This behavior is useful to make a GUI window have a similar font on multiple systems, even if some of those systems lack the preferred font. For example, by using the following commands in order, Verdana will be given preference over Arial, which in turn is given preference over MS Sans Serif:</p> <pre>Gui, Font,, MS Sans Serif Gui, Font,, Arial Gui, Font,, Verdana <em>; Preferred font.</em></pre> <p>If the <em>Options</em> parameter is blank, the previous font's attributes will be used. Otherwise, specify one or more of the following option letters as substitutes:</p> <p><strong>C</strong>: Color name (see <a href="Progress.htm#colors">color chart</a>) or RGB value -- or specify the word Default to return to the system's default color (black on most systems). Example values: <code>cRed</code>, <code>cFFFFAA</code>, <code>cDefault</code>. Observação: <a href="GuiControls.htm#Button">Buttons</a> do not obey custom colors. Also, an individual control can be created with a font color other than the current one by including the C option. Por exemplo: <code>Gui, Add, Text, cRed, My Text</code>.</p> <p><strong>S</strong>: Size (in points). Por exemplo: <code>s12</code> (specify decimal, not hexadecimal)</p> <p><strong>W</strong>: Weight (boldness), which is a number between 1 and 1000 (400 is normal and 700 is bold). Por exemplo: <code>w600</code> (specify decimal, not hexadecimal)</p> <p>The following words are also supported: <strong>bold</strong>, <em>italic</em>, <s>strike</s>, <u>underline</u>, and norm. <em>Norm</em> returns the font to normal weight/boldness and turns off italic, strike, and underline (but it retains the existing color and size). It is possible to use norm to turn off all attributes and then selectively turn on others. For example, specifying <code>norm italic</code> would set the font to normal then to italic.</p> <p>To specify more than one option, include a space between each. Por exemplo: <code>cBlue s12 bold</code>.</p> <p>If a script creates <a href="#MultiWin">multiple GUI windows</a>, each window remembers its own "current font" for the purpose of creating more controls.</p> <p>On a related note, the operating system offers standard dialog boxes that prompt the user to pick a font, color, or icon. These dialogs can be displayed via <a href="DllCall.htm">DllCall()</a> as demonstrated at <a href="https://github.com/majkinetor/mm-autohotkey/tree/master/Dlg">GitHub</a>.</p> <p id="fontq"><strong>Q</strong>: <span class="ver">[AHK_L 19+]:</span> Text rendering quality. Por exemplo: <code>q3</code>. Q should be followed by a number from the following table:</p> <table class="info"> <tr> <th>Number</th> <th abbr="Constant">Windows Constant</th> <th abbr="Descr">Descrição</th> </tr> <tr> <td>0</td> <td>DEFAULT_QUALITY</td> <td>Appearance of the font does not matter.</td> </tr> <tr> <td>1</td> <td>DRAFT_QUALITY</td> <td>Appearance of the font is less important than when the PROOF_QUALITY value is used.</td> </tr> <tr> <td>2</td> <td>PROOF_QUALITY</td> <td>Character quality of the font is more important than exact matching of the logical-font attributes.</td> </tr> <tr> <td>3</td> <td>NONANTIALIASED_QUALITY</td> <td>Font is never antialiased, that is, font smoothing is not done.</td> </tr> <tr> <td>4</td> <td>ANTIALIASED_QUALITY</td> <td>Font is antialiased, or smoothed, if the font supports it and the size of the font is not too small or too large.</td> </tr> <tr> <td>5</td> <td>CLEARTYPE_QUALITY</td> <td>Windows XP and later: If set, text is rendered (when possible) using ClearType antialiasing method.</td> </tr> </table> <p>For more details of what these values mean, see <a href="http://msdn.microsoft.com/en-us/library/dd183499.aspx">MSDN: CreateFont</a>.</p> <p>Since the highest quality setting is usually the default, this feature is more typically used to disable anti-aliasing in specific cases where doing so makes the text clearer.</p> <h3 id="Color">Color</h3> <p>Sets the background color of the window and/or its controls.</p> <pre class="Syntax"><span class="func">Gui</span>, Color <span class="optional">, WindowColor, ControlColor</span></pre> <p><em>WindowColor</em> is used as the background for the GUI window itself. <em>ControlColor</em> is applied to all present and future controls in the window (though some types of controls do not support a custom color). Although <em>ControlColor</em> is initially obeyed by <a href="ListView.htm">ListViews</a> and <a href="TreeView.htm">TreeViews</a>, subsequent changes to <em>ControlColor</em> do not affect them. In such cases, use <code>GuiControl +BackgroundFF9977, MyListView</code> to explicitly change the color.</p> <p>Leave either parameter blank to retain the current color. Otherwise, specify one of the 16 primary <a href="Progress.htm#colors">HTML color names</a> or a 6-digit RGB color value (the 0x prefix is optional), or specify the word Default to return either to its default color. Example values: <code>Silver</code>, <code>FFFFAA</code>, <code>0xFFFFAA</code>, <code>Default</code>.</p> <p>By default, the window's background color is the system's color for the face of buttons, and the controls' background color is the system's default window color (usually white).</p> <p>The color of the <a href="#Menu">menu bar</a> and its submenus can be changed as in this example: <code><a href="Menu.htm">Menu</a>, MyMenuBar, Color, White</code>.</p> <p>To make the background transparent, use <a href="WinSet.htm#TransColor">WinSet TransColor</a>. However, if you do this without first having assigned a custom window color via <a href="#Color">Gui Color</a>, buttons will also become transparent. To prevent this, first assign a custom color and then make that color transparent. Por exemplo:</p> <pre>Gui, Color, EEAA99 Gui +LastFound <em>; Make the GUI window the <a href="../misc/WinTitle.htm#LastFoundWindow">last found window</a> for use by the line below.</em> WinSet, TransColor, EEAA99</pre> <p>To additionally remove the border and title bar from a window with a transparent background, use the following <strong>after</strong> the window has been made transparent:</p> <pre>Gui -Caption <em>; Or use <i>Gui, GuiName:-Caption</i> if it isn't the <a href="#DefaultWin">default window</a>.</em></pre> <p>To illustrate the above, there is an example of an on-screen display (OSD) near the bottom of this page.</p> <h3 id="Margin">Margin</h3> <p>Sets the number of pixels of space to leave at the left/right and top/bottom sides of the window when auto-positioning any control that lacks an explicit <a href="#XY">X or Y coordinate</a>.</p> <pre class="Syntax"><span class="func">Gui</span>, Margin <span class="optional">, X, Y</span></pre> <p>Also, the margins are used to determine the vertical and horizontal distance that separates auto-positioned controls from each other. Finally, the margins are taken into account by the first use of <a href="#Show">Gui Show</a> to calculate the window's size (when no explicit size is specified).</p> <p><code>Gui, Margin</code> affects only the <a href="#Default">default window</a>, while <code>Gui, Name:Margin</code> affects only the <a href="#MultiWin">named window</a>. If this command is not used, when the first control is added to a window, the window acquires a default margin on all sides proportional to the size of the currently selected <a href="#Font">font</a> (0.75 times font-height for top &amp; bottom, and 1.25 times font-height for left &amp; right).</p> <p>Although the margin may be changed during the course of adding controls, the change will affect only controls added in the future, not ones that already exist. Finally, either X or Y may be blank to leave the corresponding margin unchanged.</p> <h3 id="Options">Options and styles for a window</h3> <p>One or more options may be specified immediately after the GUI command.</p> <pre class="Syntax"><span class="func">Gui</span>, +/-Option1 +/-Option2 ...</pre> <p>For performance reasons, it is better to set all options in a single line, and to do so before creating the window (that is, before any use of other sub-commands such as <a href="#Add">Gui Add</a>).</p> <p>The effect of this command is cumulative; that is, it alters only those settings that are explicitly specified, leaving all the others unchanged.</p> <p>Specify a plus sign to add the option and a minus sign to remove it. Por exemplo:</p> <pre>Gui +Resize -MaximizeBox <em>; Change the settings of the <a href="#DefaultWin">default</a> GUI window.</em> Gui <strong>MyGui:</strong>+Resize -MaximizeBox <em>; Change the settings of the GUI named <i>MyGui</i>.</em></pre> <p><strong>AlwaysOnTop</strong>: Makes the window stay on top of all other windows, which is the same effect as <a href="WinSet.htm#AlwaysOnTop">WinSet AlwaysOnTop</a>.</p> <p><strong>Border</strong>: Provides a thin-line border around the window. This is not common.</p> <p><strong>Caption</strong> (present by default): Provides a title bar and a thick window border/edge. When removing the caption from a window that will use <a href="WinSet.htm#TransColor">WinSet TransColor</a>, remove it only after setting the TransColor.</p> <p id="Delimiter"><strong>Delimiter</strong>: Specifies that the window should use a field separator other than pipe (|) whenever controls' contents are added via <a href="#Add">Gui Add</a>, modified via <a href="GuiControl.htm">GuiControl</a>, or retrieved via <a href="#Submit">Gui Submit</a> or <a href="GuiControlGet.htm">GuiControlGet</a>. Specify a single character immediately after the word Delimiter. For example, <code>Gui +Delimiter`n</code> would use a linefeed character, which might be especially appropriate with <a href="../Scripts.htm#continuation">continuation sections</a>. Similarly, <code>Gui +Delimiter|</code> would revert to the default delimiter. To use space or tab, specify <code>Gui +DelimiterSpace</code> or <code>Gui +DelimiterTab</code>. Once the delimiter is changed, it affects all existing and subsequent <a href="../misc/Threads.htm">threads</a> that operate on this particular window.</p> <p><strong>Disabled</strong>: Disables the window, which prevents the user from interacting with its controls. This is often used on a window that owns other windows (see <a href="#Owner">Owner</a>).</p> <p id="DPIScale"><strong>DPIScale</strong> <span class="ver">[v1.1.11+]</span>: Use <code>Gui -DPIScale</code> to disable <a href="../misc/DPIScaling.htm">DPI scaling</a>, which is enabled by default. If DPI scaling is enabled, coordinates and sizes passed to or retrieved from the Gui sub-commands and related variables are automatically scaled based on <a href="../Variables.htm#ScreenDPI">screen DPI</a>. For example, with a DPI of 144 (150%), <code>Gui Show, w100</code> would make the Gui 150 (100 * 1.5) pixels wide, and resizing the window to 200 pixels wide via the mouse or <a href="WinMove.htm">WinMove</a> would cause <a href="../Variables.htm#GuiWidth">A_GuiWidth</a> to return 133 (200 // 1.5). <a href="../Variables.htm#ScreenDPI">A_ScreenDPI</a> contains the system's current DPI.</p> <p>DPI scaling only applies to Gui sub-commands and related variables, so coordinates coming directly from other sources such as ControlGetPos or WinGetPos will not work. There are a number of ways to deal with this:</p> <ul> <li>Avoid using hard-coded coordinates wherever possible. For example, use the <a href="#xp">xp</a>, <a href="#xs">xs</a>, <a href="#xm">xm</a> and <a href="#PosPlusMargin">x+m</a> options for positioning controls and specify height in <a href="#R">rows of text</a> instead of pixels.</li> <li>Enable (<code>Gui +DPIScale</code>) and disable (<code>Gui -DPIScale</code>) scaling on the fly, as needed. Changing the setting does not affect positions or sizes which have already been set.</li> <li>Manually scale the coordinates. For example, <code>x*(A_ScreenDPI/96)</code> converts x from logical/Gui coordinates to physical/non-Gui coordinates.</li> </ul> <p id="GuiHwndOutputVar"><strong>Hwnd</strong><em>OutputVar</em> <span class="ver">[v1.1.04+]:</span> This option stores the window handle (HWND) of the GUI in <em>OutputVar</em>. Por exemplo: <code>Gui +HwndMyGuiHwnd</code>. When within a function, <em>MyGuiHwnd</em> is treated as a <a href="../Functions.htm#DynVar">function dynamic variable</a>. A GUI's HWND is often used with <a href="PostMessage.htm">PostMessage</a>, <a href="PostMessage.htm">SendMessage</a>, and <a href="DllCall.htm">DllCall()</a>. It can also be used directly as an <a href="../misc/WinTitle.htm#ahk_id">ahk_id WinTitle</a> or in place of a GUI name; for example, <code>Gui %MyGuiHwnd%:Destroy</code>.</p> <p id="PlusLabel"><strong>Label</strong> <span class="ver">[v1.0.44.09+]:</span> Sets custom names for this window's <a href="#Labels">special labels</a>. For example, <code>Gui MyGui:+LabelMyGui_On</code> would use the labels MyGui_OnClose and MyGui_OnSize (if they exist) instead of MyGuiGuiClose and MyGuiGuiSize. In other words, the string "MyGuiGui" is replaced by "MyGui_On" in the names of all <a href="#Labels">special labels</a>. This can also be used to make multiple windows share the same set of labels (in which case the script may consult <a href="../Variables.htm#Gui">A_Gui</a> to determine which window launched the subroutine).</p> <p id="LastFound"><strong>LastFound</strong>: Sets the window to be the <a href="../misc/WinTitle.htm#LastFoundWindow">last found window</a> (though this is unnecessary in a <a href="#DefaultWin">Gui thread</a> because it is done automatically), which allows commands such as <a href="WinSet.htm">WinSet</a> to operate on it even if it is hidden (that is, <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> is not necessary). This is especially useful for changing the properties of the window before showing it. Por exemplo:</p> <pre>Gui +LastFound WinSet, TransColor, %CustomColor% 150 Gui Show</pre> <p id="LastFoundExist"><strong>LastFoundExist</strong> <span class="ver">[v1.0.43.09+]:</span> Unlike other options, LastFoundExist is recognized only when no other options appear on the same line. <em>+LastFoundExist</em> is the same as <em>+LastFound</em> except that the window is not created if it does not already exist. The main use for this is to detect whether a particular GUI window exists. Por exemplo:</p> <pre>Gui MyGui:+LastFoundExist if WinExist() MsgBox GUI "MyGui" already exists.</pre> <p><strong>MaximizeBox</strong>: Enables the maximize button in the title bar. This is also included as part of <em>Resize</em> below.</p> <p><strong>MinimizeBox</strong> (present by default): Enables the minimize button in the title bar.</p> <p id="MinSize"><strong>MinSize</strong> and <strong>MaxSize</strong> <span class="ver">[v1.0.44.13+]:</span> Determines the minimum and/or maximum size of the window, such as when the user drags its edges to resize it. Specify the word <em>MinSize</em> and/or <em>MaxSize</em> with no suffix to use the window's current size as the limit (if the window has no current size, it will use the size from the first use of <a href="#Show">Gui Show</a>). Alternatively, append the width, followed by an X, followed by the height; for example: <code>Gui +Resize +MinSize640x480</code>. The dimensions are in pixels, and they specify the size of the window's client area (which excludes borders, title bar, and <a href="#Menu">menu bar</a>). Specify each number as decimal, not hexadecimal.</p> <p>Either the width or the height may be omitted to leave it unchanged (e.g. <code>+MinSize640x</code> or <code>+MinSizex480</code>). Furthermore, Min/MaxSize can be specified more than once to use the window's current size for one dimension and an explicit size for the other. For example, <code>+MinSize +MinSize640x</code> would use the window's current size for the height and 640 for the width.</p> <p>If <em>MinSize</em> and <em>MaxSize</em> are never used, the operating system's defaults are used (similarly, <code>Gui -MinSize -MaxSize</code> can be used to return to the defaults).</p> <p class="note"><strong>Observação</strong>: the window must have <a href="#Resize">+Resize</a> to allow resizing by the user.</p> <p id="OwnDialogs"><strong>OwnDialogs</strong>: <code>Gui +OwnDialogs</code> should be specified in each <a href="../misc/Threads.htm">thread</a> (such as a ButtonOK subroutine) for which subsequently displayed <a href="MsgBox.htm">MsgBox</a>, <a href="InputBox.htm">InputBox</a>, <a href="FileSelectFile.htm">FileSelectFile</a>, and <a href="FileSelectFolder.htm">FileSelectFolder</a> dialogs should be owned by the window. Such dialogs become modal, meaning that the user cannot interact with the GUI window until dismissing the dialog. By contrast, <a href="ToolTip.htm">ToolTip</a>, <a href="Progress.htm">Progress</a>, and <a href="Progress.htm">SplashImage</a> windows do not become modal even though they become owned; they will merely stay always on top of their owner. In either case, any owned dialog or window is automatically destroyed when its GUI window is <a href="#Destroy">destroyed</a>.</p> <p>There is typically no need to turn this setting back off because it does not affect other <a href="../misc/Threads.htm">threads</a>. However, if a thread needs to display both owned and unowned dialogs, it may turn off this setting via <code>Gui -OwnDialogs</code>.</p> <p>If no window name prefix is specified -- such as using <code>Gui +OwnDialogs</code> rather than <code>Gui MyGui:+OwnDialogs</code> -- the <a href="#DefaultWin">thread's default window</a> will own the dialogs.</p> <p id="Owner"><strong>Owner</strong>: Use <em>+Owner</em> to make the window owned by another. An owned window has no taskbar button by default, and when visible it is always on top of its owner. It is also automatically destroyed when its owner is destroyed. <em>+Owner</em> must be used <u>after</u> the window's owner is created, but <span class="ver">[v1.1.05]</span> and later allow it to be used before or after the owned window is created. There are two ways to use <em>+Owner</em> as shown in these examples:</p> <pre>Gui, MyGui:+OwnerMyOtherGui <em>; Make <i>MyGui</i> owned by <i>MyOtherGui</i>.</em> Gui, MyGui:+Owner <em>; Make <i>MyGui</i> owned by <a href="Menu.htm#MainWindow">script's main window</a> to prevent display of a taskbar button.</em></pre> <p><span class="ver">[v1.1.03+]:</span> <code>+Owner</code> can be immediately followed by the <a href="#Name">name</a> or number of an existing Gui or the <a href="WinGet.htm#ID">HWND</a> of any top-level window.</p> <p class="note"><strong>Compatibility note</strong>: In <span class="ver">[v1.1.03]</span> and later, <code>+Owner</code> removes the WS_CHILD style and sets the WS_POPUP style. To set the parent window of a Gui, scripts must either use the <code>+Parent</code> option, or override the appropriate styles <em>after</em> the <code>+Owner</code> option.</p> <p>To prevent the user from interacting with the owner while one of its owned window is visible, disable the owner via <code>Gui +Disabled</code>. Later (when the time comes to cancel or destroy the owned window), re-enable the owner via <code>Gui -Disabled</code>. Do this prior to cancel/destroy so that the owner will be reactivated automatically.</p> <p id="Parent"><strong>Parent</strong> <span class="ver">[v1.1.03+]</span>: Use <code>+Parent</code> immediately followed by the <a href="#Name">name</a> or number of an existing Gui or the <a href="WinGet.htm#ID">HWND</a> of any window or control to use it as the parent of this window. To convert the Gui back into a top-level window, use <code>-Parent</code>. This option works even after the window is created.</p> <p id="Resize"><strong>Resize</strong>: Makes the window resizable and enables its maximize button in the title bar. To avoid enabling the maximize button, specify <code>+Resize -MaximizeBox</code>.</p> <p><strong>SysMenu</strong> (present by default): Specify <code>-SysMenu</code> (minus SysMenu) to omit the system menu and icon in the window's upper left corner. This will also omit the minimize, maximize, and close buttons in the title bar.</p> <p id="Theme"><strong>Theme</strong>: By specifying <code>-Theme</code>, all subsequently created controls in the window will have Classic Theme appearance on Windows XP and beyond. To later create additional controls that obey the current theme, turn it back on via <code>+Theme</code>.</p> <p class="note"><strong>Observação</strong>: The Theme option has no effect on operating systems older than Windows XP, nor does it have any effect on XP itself if the Classic Theme is in effect.</p> <p>Finally, this setting may be changed for an individual control by specifying <code>+Theme</code> or <code>-Theme</code> in its options when it is created.</p> <p><strong>ToolWindow</strong>: Provides a narrower title bar but the window will have no taskbar button. This always hides the maximize and minimize buttons, regardless of whether the <a href="../misc/Styles.htm#WS_MAXIMIZEBOX">WS_MAXIMIZEBOX</a> and <a href="../misc/Styles.htm#WS_MINIMIZEBOX">WS_MINIMIZEBOX</a> styles are present.</p> <p><strong>(Unnamed Style)</strong>: Specify a plus or minus sign followed immediately by a decimal or hexadecimal <a href="../misc/Styles.htm">style number</a>.</p> <p><strong>(Unnamed ExStyle)</strong>: Specify a plus or minus sign followed immediately by the letter E and a decimal or hexadecimal extended style number. For example, <code>+E0x40000</code> would add the WS_EX_APPWINDOW style, which provides a taskbar button for a window that would otherwise lack one. For other extended styles not documented here (since they are rarely used), see <a href="https://docs.microsoft.com/en-us/windows/win32/winmsg/extended-window-styles">Extended Window Styles | Microsoft Docs</a> for a complete list.</p> <h3 id="Menu">Menu</h3> <p>Attaches a menu bar to the window.</p> <pre class="Syntax"><span class="func">Gui</span>, Menu <span class="optional">, MenuName</span></pre> <p>Use the <a href="Menu.htm">Menu</a> command to create an ordinary menu for this purpose. Por exemplo:</p> <pre>Menu, FileMenu, Add, &amp;Open<a href="../misc/EscapeChar.htm">`t</a>Ctrl+O, MenuFileOpen <em>; See remarks below about Ctrl+O.</em> Menu, FileMenu, Add, E&amp;xit, MenuHandler Menu, HelpMenu, Add, &amp;About, MenuHandler Menu, MyMenuBar, Add, &amp;File, :FileMenu <em>; Attach the two sub-menus that were created above.</em> Menu, MyMenuBar, Add, &amp;Help, :HelpMenu Gui, Menu, MyMenuBar</pre> <p>In the first line above, notice that <code>&amp;Open</code> is followed by <code>Ctrl+O</code> (with a tab character in between). This indicates a keyboard shortcut that the user may press instead of selecting the menu item. <span class="ver">[v1.1.04+]:</span> If the shortcut uses only the standard modifier key names Ctrl, Alt and Shift, it is automatically registered as a <em>keyboard accelerator</em> for the GUI. Single-character accelerators with no modifiers are case-sensitive and can be triggered by unusual means such as IME or <kbd>Alt</kbd>+NNNN.</p> <p>If a particular key combination does not work automatically, the use of a <a href="_IfWinActive.htm">context-sensitive hotkey</a> may be required. However, such hotkeys typically cannot be triggered by <a href="Send.htm">Send</a> and are more likely to interfere with other scripts than a standard keyboard accelerator.</p> <p>To remove a window's current menu bar, use <code>Gui Menu</code> (that is, omit the last parameter).</p> <p>Once a menu has been used as a menu bar, it should not be used as a popup menu or a submenu. This is because menu bars internally require a different format (however, this restriction applies only to the menu bar itself, not its submenus). If you need to work around this, create one menu to use as the menu bar and another identical menu to use for everything else.</p> <p>The use of certain destructive <a href="Menu.htm">menu sub-commands</a> such as Delete and DeleteAll against a menu that is currently being used as a menu bar (and in some cases, its submenus) is not supported and will cause an error dialog to be displayed (unless <a href="Menu.htm">UseErrorLevel</a> is in effect). Use the following steps to make such changes: 1) detach the menu bar via <code>Gui Menu</code> (that is, omit <em>MenuName</em>); 2) make the changes; 3) reattach the menu bar via <code>Gui, Menu, MyMenuBar</code>.</p> <div id="Restore"><div id="Maximize"><h3 id="Minimize">Minimize / Maximize / Restore</h3></div></div> <p>Unhides the window (if necessary) then perform the indicated operation on it.</p> <pre class="Syntax"><span class="func">Gui</span>, Minimize <span class="func">Gui</span>, Maximize <span class="func">Gui</span>, Restore</pre> <p>If the window does not exist -- perhaps due to having been destroyed via <a href="#Destroy">Gui Destroy</a> -- this sub-command has no effect.</p> <h3 id="Flash">Flash</h3> <p>Blinks the window's button in the taskbar.</p> <pre class="Syntax"><span class="func">Gui</span>, Flash <span class="optional">, Off</span></pre> <p>This is done by inverting the color of the window's title bar and/or taskbar button (if it has one). The optional word OFF causes the title bar and taskbar button to return to their original colors (but the actual behavior might vary depending on OS version). In the below example, the window will blink three times because each pair of flashes inverts then restores its appearance:</p> <pre>Loop 6 { Gui Flash Sleep 500 <em>; It's quite sensitive to this value; altering it may change the behavior in unexpected ways.</em> }</pre> <h3 id="Default">Default</h3> <p>Changes the <a href="../misc/Threads.htm">current thread</a>'s default <a href="#MultiWin">GUI window name</a>.</p> <pre class="Syntax"><span class="func">Gui</span>, GuiName:Default</pre> <p>This is used whenever a window name is not specified for <a href="GuiControl.htm">GuiControl</a>, <a href="GuiControlGet.htm">GuiControlGet</a>, and the Gui command itself. In the following example, the default window name is changed to "MyGui": <code>Gui MyGui:Default</code>. See <a href="#DefaultWin">thread's default window</a> for more information about the default window.</p> <p><span class="ver">[v1.1.03+]:</span> <em>GuiName</em> can be the <a href="#GuiHwndOutputVar">HWND</a> of one of the script's GUI windows. If the window has a name, it becomes the default name and remains so even after the window itself is destroyed. If the window has no name, the default name reverts to 1 when the window is destroyed.</p> <p><span class="ver">[v1.1.23+]:</span> The built-in variable <strong>A_DefaultGui</strong> contains the name or number of the default GUI.</p> <h2 id="ControlOptions">Options for a Control (Gui Add)</h2> <h3 id="PosSize">Positioning and Sizing of Controls</h3> <p class="note"><strong>Note:</strong> Although the options described in this section are suitable for simple layouts, you may find it easier to use Rajat's SmartGUI Creator because it's entirely visual; that is, "what you see is what you get". SmartGUI Creator is free and can be downloaded from <a href="https://www.autohotkey.com/docs/SmartGUI/">www.autohotkey.com/docs/SmartGUI/</a></p> <p>If some dimensions and/or coordinates are omitted from <em>Options</em>, the control will be positioned relative to the previous control and/or sized automatically according to its nature and contents.</p> <p>The following options are supported:</p> <p id="R"><strong>R</strong>: Rows of text (can contain a floating point number such as R2.5). <strong>R</strong> is often preferable to specifying <strong>H</strong> (Height). If both the <strong>R</strong> and <strong>H</strong> options are present, <strong>R</strong> will take precedence. For a GroupBox, this setting is the number of controls for which to reserve space inside the box. For <a href="GuiControls.htm#DropDownList">DropDownLists</a>, <a href="GuiControls.htm#ComboBox">ComboBoxes</a>, and <a href="GuiControls.htm#ListBox">ListBoxes</a>, it is the number of items visible at one time inside the list portion of the control (but on Windows XP or later, it is often desirable to omit both the <strong>R</strong> and <strong>H</strong> options for DropDownList and ComboBox, which makes the popup list automatically take advantage of the available height of the user's desktop). For other control types, <strong>R</strong> is the number of rows of text that can visibly fit inside the control.</p> <p><strong>W</strong>: Width, in pixels. If omitted, the width is calculated automatically for some control types based on their contents; tab controls default to 30 times the current font size, plus 3 times the <a href="#Margin">X-margin</a>; vertical Progress Bars default to two times the current font size; and horizontal Progress Bars, horizontal Sliders, DropDownLists, ComboBoxes, ListBoxes, GroupBoxes, Edits, and Hotkeys default to 15 times the current font size (except GroupBoxes, which multiply by 18 to provide room inside for margins).</p> <p><strong>H</strong>: Height, in pixels. If both the <strong>H</strong> and <strong>R</strong> options are absent, DropDownLists, ComboBoxes, ListBoxes, and empty multi-line Edit controls default to 3 rows; GroupBoxes default to 2 rows; vertical Sliders and Progress Bars default to 5 rows; horizontal Sliders default to 30 pixels (except if a thickness has been specified); horizontal Progress Bars default to 2 times the current font size; Hotkey controls default to 1 row; and Tab controls default to 10 rows. For the other control types, the height is calculated automatically based on their contents. Note that for DropDownLists and ComboBoxes, <strong>H</strong> is the combined height of the control's always-visible portion and its list portion (but even if the height is set too low, at least one item will always be visible in the list). Also, for all types of controls, specifying the number of rows via the <strong>R</strong> option is usually preferable to using <strong>H</strong> because it prevents a control from showing partial/incomplete rows of text.</p> <p><strong>wp+n</strong>, <strong>hp+n</strong>, <strong>wp-n</strong>, <strong>hp-n</strong> (where <strong>n</strong> is any number) can be used to set the width and/or height of a control equal to the previously added control's width or height, with an optional plus or minus adjustment. For example, <code>wp</code> would set a control's width to that of the previous control, and <code>wp-50</code> would set it equal to 50 less than that of the previous control.</p> <p id="XY"><strong>X</strong>, <strong>Y</strong>: X-position, Y-position. For example, specifying <code>x0 y0</code> would position the control in the upper left corner of the window's client area, which is the area beneath the title bar and menu bar (if any).</p> <p id="PosPlus"><strong>x+n</strong>, <strong>y+n</strong> (where <strong>n</strong> is any number): An optional plus sign can be included to position a control relative to the right or bottom edge (respectively) of the control that was previously added. For example, specifying <code>Y+10</code> would position the control 10 pixels beneath the bottom of the previous control rather than using the standard padding distance. Similarly, specifying <code>X+10</code> would position the control 10 pixels to the right of the previous control's right edge. Since negative numbers such as <code>X-10</code> are reserved for absolute positioning, to use a negative offset, include a plus sign in front of it. Por exemplo: <code>X+-10</code>.</p> <p id="PosPlusMargin"><span class="ver">[v1.1.16+]:</span> For <strong>X+</strong> and <strong>Y+</strong>, the letter <strong>M</strong> can be used as a substitute for the window's current <a href="#Margin">margin</a>. For example, <code>x+m</code> uses the right edge of the previous control plus the standard padding distance. <code>xp y+m</code> positions a control below the previous control, whereas specifying a relative X coordinate on its own (with xp or x+) would normally imply <code>yp</code> by default.</p> <p id="xp"><strong>xp+n</strong>, <strong>yp+n</strong>, <strong>xp-n</strong>, <strong>yp-n</strong> (where <strong>n</strong> is any number) can be used to position controls relative to the previous control's upper left corner, which is often useful for enclosing controls in a <a href="GuiControls.htm#GroupBox">GroupBox</a>.</p> <p id="xm"><strong>xm</strong> and <strong>ym</strong> can be used to position a control at the leftmost and topmost <a href="#Margin">margins</a> of the window, respectively (these two may also be followed by a plus/minus sign and a number).</p> <p id="xs"><strong>xs</strong> and <strong>ys</strong>: these are similar to <strong>xm</strong> and <strong>ym</strong> except that they refer to coordinates that were saved by having previously added a control with the word <a href="#Section">Section</a> in its options (the first control of the window always starts a new section, even if that word isn't specified in its options). Por exemplo:</p> <pre>gui, add, edit, w600 <em>; Add a fairly wide edit control at the top of the window.</em> gui, add, text, <strong>section</strong>, First Name: <em>; Save this control's position and start a new section.</em> gui, add, text,, Last Name: gui, add, edit, <strong>ys</strong> <em>; Start a new column within this section.</em> gui, add, edit gui, show</pre> <p><strong>xs</strong> and <strong>ys</strong> may optionally be followed by a plus/minus sign and a number. Also, it is possible to specify both the word <a href="#Section">Section</a> and xs/ys in a control's options; this uses the previous section for itself but establishes a new section for subsequent controls.</p> <p>Omitting either <strong>X</strong>, <strong>Y</strong> or both is useful to make a GUI layout automatically adjust to any future changes you might make to the size of controls or font. By contrast, specifying an absolute position for every control might require you to manually shift the position of all controls that lie beneath and/or to the right of a control that is being enlarged or reduced.</p> <p>If both <strong>X</strong> and <strong>Y</strong> are omitted, the control will be positioned beneath the previous control using a standard padding distance (the current <a href="#Margin">margin</a>). Consecutive Text or Link controls are given additional vertical padding, so that they typically align better in cases where a column of Edit, DDL or similar-sized controls are later added to their right. To use only the standard vertical margin, specify <code>Y+M</code> or any value for X.</p> <p>If only one component is omitted, its default value depends on which option was used to specify the other component:</p> <table class="info"> <tr><th>Specified X</th><th>Default for Y</th></tr> <tr><td>x<em>n</em> or xm</td><td>Beneath all previous controls (maximum Y extent plus margin).</td></tr> <tr><td>xs</td><td>Beneath all previous controls since the most recent use of the <a href="#Section">Section</a> option.</td></tr> <tr><td>x+<em>n</em> or xp</td><td>Same as the previous control's top edge (<a href="#xp">yp</a>).</td></tr> <tr><th>Specified Y</th><th>Default for X</th></tr> <tr><td>y<em>n</em> or ym</td><td>To the right of all previous controls (maximum X extent plus margin).</td></tr> <tr><td>ys</td><td>To the right of all previous controls since the most recent use of the <a href="#Section">Section</a> option.</td></tr> <tr><td>y+<em>n</em> or yp</td><td>Same as the previous control's left edge (<a href="#xp">xp</a>).</td></tr> </table> <h3 id="Events">Storing and Responding to User Input</h3> <p id="var"><strong>V</strong>: Variable. Associates a variable with a control. Immediately after the letter V, specify the name of a global variable (or a <a href="../Functions.htm#ByRef">ByRef local</a> that points to a global, or <span class="ver">[in v1.0.46.01+]</span> a <a href="../Functions.htm#static">static variable</a>). For example, specifying <code><strong>v</strong>MyEdit</code> would store the control's contents in the variable <em>MyEdit</em> whenever the <a href="#Submit">Gui Submit</a> command is used. If a control is not input-capable -- such as a Text control or GroupBox -- associating a variable with it can still be helpful since that variable's name serves as the control's unique identifier for use with <a href="GuiControl.htm">GuiControl</a>, <a href="GuiControlGet.htm">GuiControlGet</a>, and <a href="../Variables.htm#GuiControl">A_GuiControl</a>.</p> <p class="note"><strong>Observação</strong>: <a href="#Submit">Gui Submit</a> does not change the contents of variables of non-input-capable controls (such as Text and GroupBox), nor certain others as documented in their sections (such as <a href="ListView.htm">ListView</a> and <a href="TreeView.htm">TreeView</a>).</p> <p id="label"><strong>G</strong>: Gosub (g-label). Launches a subroutine or function automatically when the user clicks or changes a control. Immediately after the letter G, specify the name of the <a href="../misc/Labels.htm">label</a> to execute. <code>gCancel</code> may be specified to perform an implicit <a href="#Cancel">Gui Cancel</a> (but if a label named "Cancel" exists in the script, it will be executed instead). The subroutine may consult the following built-in variables: <a href="../Variables.htm#Gui">A_Gui</a>, <a href="../Variables.htm#GuiControl">A_GuiControl</a>, <a href="../Variables.htm#GuiEvent">A_GuiEvent</a>, <a href="../Variables.htm#EventInfo">A_EventInfo</a>, and <a href="../Variables.htm#ThisLabel">A_ThisLabel</a>.</p> <p><span class="ver">[v1.1.20+]:</span> If not a valid label name, a function name can be used instead. Alternatively, the <a href="GuiControl.htm#Functor">GuiControl</a> command can be used to associate a <a href="../misc/Functor.htm">function object</a> with the control. The function can optionally accept the following parameters (where <code>gCtrlEvent</code> sets the function):</p> <pre class="Syntax"><span class="func">CtrlEvent</span>(CtrlHwnd, GuiEvent, EventInfo, ErrLevel:="")</pre> <p>The meanings of the parameters depends on the type of control. Note that if the fourth parameter is declared without a default value, the function will only be called by events which supply four parameters.</p> <h3 id="OtherOptions">Controls: Common Styles and Other Options</h3> <p class="note"><strong>Observação</strong>: In the absence of a preceding sign, a plus sign is assumed; for example, <code>Wrap</code> is the same as <code>+Wrap</code>. By contrast, <code>-Wrap</code> would remove the word-wrapping property.</p> <p id="AltSubmit"><strong>AltSubmit</strong>: Uses alternate submit method. For DropDownList, ComboBox, and ListBox this causes the <a href="#Submit">Gui Submit</a> command to store the position of the selected item rather than its text. If no item is selected, a ComboBox will still store the text in its edit field; similarly, a DropDownList or ListBox will still make its <a href="#var">output variable</a> blank. Observação: AltSubmit also affects the behavior of <a href="GuiControlGet.htm">GuiControlGet</a> when retrieves the contents of such a control.</p> <p><strong>C</strong>: Color of text (has no effect on <a href="GuiControls.htm#Button">buttons</a>). Specify the letter C followed immediately by a color name (see <a href="Progress.htm#colors">color chart</a>) or RGB value (the 0x prefix is optional). Examples: <code>cRed</code>, <code>cFF2211</code>, <code>c0xFF2211</code>, <code>cDefault</code>.</p> <p><strong>Choose</strong>: Pre-select a single item in a <a href="GuiControls.htm#ComboBox">ComboBox</a>, <a href="GuiControls.htm#DateTime">DateTime</a>, <a href="GuiControls.htm#DropDownList">DropDownList</a>, <a href="GuiControls.htm#ListBox">ListBox</a> or <a href="GuiControls.htm#Tab">Tab</a> control. Specify the word <code>Choose</code> followed immediately by the number of an item. Por exemplo: <code>Choose2</code></p> <p><strong>Disabled</strong>: Makes an input-capable control appear in a disabled state, which prevents the user from focusing or modifying its contents. Use <a href="GuiControl.htm#EnableDisable">GuiControl Enable</a> to enable it later. Observação: To make an Edit control read-only, specify the string <code>ReadOnly</code> instead. Also, the word Disabled may optionally be followed immediately by a 0 or 1 to indicate the starting state (0 for enabled and 1 for disabled). In other words, <code>Disabled</code> and <code>Disabled%VarContainingOne%</code> are the same.</p> <p><strong>Hidden</strong>: The control is initially invisible. Use <a href="GuiControl.htm#Show">GuiControl Show</a> to show it later. The word Hidden may optionally be followed immediately by a 0 or 1 to indicate the starting state (0 for visible and 1 for hidden). In other words, <code>Hidden</code> and <code>Hidden%VarContainingOne%</code> are the same.</p> <p><strong>Left</strong>: Left-justifies the control's text within its available width. This option affects the following controls: Text, Edit, Button, Checkbox, Radio, UpDown, Slider, Tab, Tab2, GroupBox, DateTime.</p> <p><strong>Right</strong>: Right-justifies the control's text within its available width. For checkboxes and radio buttons, this also puts the box itself on the right side of the control rather than the left. This option affects the following controls: Text, Edit, Button, Checkbox, Radio, UpDown, Slider, Tab, Tab2, GroupBox, DateTime, Link.</p> <p><strong>Center</strong>: Centers the control's text within its available width. This option affects the following controls: Text, Edit, Button, Checkbox, Radio, Slider, GroupBox.</p> <p id="Section"><strong>Section</strong>: Starts a new section and saves this control's position for later use with the <em>xs</em> and <em>ys</em> positioning options described <a href="#xs">above</a>.</p> <p id="Tabstop"><strong>Tabstop</strong>: Use <code>-Tabstop</code> (i.e. minus Tabstop) to have an input-capable control skipped over when the user presses <kbd>Tab</kbd> to navigate.</p> <p id="Wrap"><strong>Wrap</strong>: Enables word-wrapping of the control's contents within its available width. Since nearly all control types start off with word-wrapping enabled, use <code>-Wrap</code> to disable word-wrapping.</p> <p><strong>VScroll</strong>: Provides a vertical scroll bar if appropriate for this type of control.</p> <p><strong>HScroll</strong>: Provides a horizontal scroll bar if appropriate for this type of control. The rest of this paragraph applies to <a href="GuiControls.htm#ListBox">ListBox</a> only. The horizontal scrolling width defaults to 3 times the width of the ListBox. To specify a different scrolling width, include a number immediately after the word HScroll. For example, <code>HScroll500</code> would allow 500 pixels of scrolling inside the ListBox. However, if the specified scrolling width is smaller than the width of the ListBox, no scroll bar will be shown (though the mere presence of <em>HScroll</em> makes it possible for the horizontal scroll bar to be added later via <code><a href="GuiControl.htm">GuiControl</a>, +HScroll500, MyScrollBar</code>, which is otherwise impossible).</p> <h3 id="Controls_Uncommon_Styles_and_Options">Controls: Uncommon Styles and Options</h3> <p id="BackgroundTrans"><strong>BackgroundTrans</strong>: Uses a transparent background, which allows any control that lies behind a Text, Picture, or GroupBox control to show through. For example, a transparent Text control displayed on top of a Picture control would make the text appear to be part of the picture. Use <code><a href="GuiControl.htm">GuiControl</a> +Background</code> to remove this option later. See <a href="GuiControls.htm#PicAltSubmit">Picture control's AltSubmit section</a> for more information about transparent images. Known limitation: BackgroundTrans might not work properly for controls inside a <a href="GuiControls.htm#Tab">Tab control</a> that contains a <a href="ListView.htm">ListView</a>.</p> <p><strong>-Background</strong> (i.e. minus Background): Uses the standard background color rather than the one set by the <a href="#Color">Gui Color</a> command. This is most often used to make a Tab control have its standard color rather than the window color. Use <code><a href="GuiControl.htm">GuiControl</a> +Background</code> to remove this option later.</p> <p><strong>Border</strong>: Provides a thin-line border around the control. Most controls do not need this because they already have a type-specific border. When adding a border to an <em>existing</em> control, it might be necessary to increase the control's width and height by 1 pixel.</p> <p id="HwndOutputVar"><strong>Hwnd</strong><em>OutputVar</em> <span class="ver">[v1.0.46.01+]:</span> When used with <a href="#Add">Gui Add</a>, this option stores the window handle (HWND) of the newly created control in <em>OutputVar</em>. Por exemplo: <code>Gui, Add, Edit, vMyEdit HwndMyEditHwnd</code>. When within a function, <em>MyEditHwnd</em> is treated as a <a href="../Functions.htm#DynVar">function dynamic variable</a>. A control's HWND is often used with <a href="PostMessage.htm">PostMessage</a>, <a href="PostMessage.htm">SendMessage</a>, and <a href="DllCall.htm">DllCall()</a>. It can also be used directly as an <a href="../misc/WinTitle.htm#ahk_id">ahk_id WinTitle</a> (this also works on hidden controls even when <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> is Off) or <span class="ver">[in v1.1.04+]</span> with GuiControl and GuiControlGet as the <em>ControlID</em> parameter. On a related note, a parent window's HWND can be retrieved via <a href="#GuiHwndOutputVar">Gui MyGui:+HwndOutputVar</a>.</p> <p><strong>Theme</strong>: This option can be used to override the window's current theme setting for the newly created control. It has no effect when used on an existing control; however, this may change in a future version. See <a href="#Theme">Gui +/-Theme</a> for details.</p> <p><strong>(Unnamed Style)</strong>: Specify a plus or minus sign followed immediately by a decimal or hexadecimal <a href="../misc/Styles.htm">style number</a>. If the sign is omitted, a plus sign is assumed.</p> <p><strong>(Unnamed ExStyle)</strong>: Specify a plus or minus sign followed immediately by the letter E and a decimal or hexadecimal extended style number. If the sign is omitted, a plus sign is assumed. For example, <code>E0x200</code> would add the WS_EX_CLIENTEDGE style, which provides a border with a sunken edge that might be appropriate for pictures and other controls. Although the other extended styles are not documented here (since they are rarely used), they can be discovered by searching for WS_EX_CLIENTEDGE at <a href="https://www.microsoft.com">www.microsoft.com</a>.</p> <h2 id="Labels">Window Events</h2> <p>The following labels (subroutines) will be automatically associated with a GUI window if they exist in the script:</p> <ul> <li><a href="#GuiClose">GuiClose</a></li> <li><a href="#GuiEscape">GuiEscape</a></li> <li><a href="#GuiSize">GuiSize</a></li> <li><a href="#GuiContextMenu">GuiContextMenu</a></li> <li><a href="#GuiDropFiles">GuiDropFiles</a></li> </ul> <p><span class="ver">[v1.1.20+]:</span> If a label does not exist for a given event, a function with that name can be called instead. The function can optionally receive the <a href="#GuiHwndOutputVar">HWND</a> of the GUI as its first parameter. Some events have additional parameters.</p> <p>For windows <a href="#MultiWin">other than number 1</a>, the window's name or number (if it has one) is used as a prefix for the special labels mentioned above; for example, 2GuiEscape and 2GuiClose would be the default labels for window number 2, while <em>MyGui</em>GuiEscape and <em>MyGui</em>GuiClose would be the default labels for <em>MyGui</em>. To set a custom prefix, use <a href="#PlusLabel">Gui +Label</a>.</p> <h3 id="GuiClose">GuiClose</h3> <p>Launched when the window is closed by any of the following: pressing its X button in the title bar, selecting "Close" from its system menu, or closing it with <a href="WinClose.htm">WinClose</a>. If this label is absent, closing the window simply hides it, which is the same effect as <a href="#Cancel">Gui Cancel</a>. One of the most common actions to take in response to GuiClose is <a href="ExitApp.htm">ExitApp</a>; for example:</p> <pre>GuiClose: ExitApp</pre> <p><span class="ver">[v1.1.20+]:</span> If GuiClose is a function, the GUI is hidden by default. The function can prevent this by returning a non-zero integer, as in the example below:</p> <pre>GuiClose(GuiHwnd) { <em>; Declaring this parameter is optional.</em> MsgBox 4,, Are you sure you want to hide the GUI? IfMsgBox No return true <em>; true = 1</em> }</pre> <h3 id="GuiEscape">GuiEscape</h3> <p>Launched when the user presses <kbd>Esc</kbd> while the GUI window is active. If this label is absent, pressing <kbd>Esc</kbd> has no effect. Known limitation: If the first control in the window is disabled (possibly depending on control type), the GuiEscape label will not be launched. There may be other circumstances that produce this effect.</p> <h3 id="GuiSize">GuiSize</h3> <p>Launched when the window is resized, minimized, maximized, or restored. The built-in variables <a href="../Variables.htm#GuiWidth">A_GuiWidth</a> and <a href="../Variables.htm#GuiWidth">A_GuiHeight</a> contain the new width and height of the window's client area, which is the area excluding title bar, menu bar, and borders. In addition, <a href="../Variables.htm#EventInfo">A_EventInfo</a> and <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will both contain one of the following digits:</p> <ul> <li>0 = The window has been restored, or resized normally such as by dragging its edges.</li> <li>1 = The window has been minimized.</li> <li>2 = The window has been maximized.</li> </ul> <p>A script may use GuiSize to reposition and resize controls in response to the user's resizing of the window. This process can be made easier by using <a href="https://www.autohotkey.com/boards/viewtopic.php?f=6&amp;t=1079">AutoXYWH() by tmplinshi and toralf</a>.</p> <p>When the window is resized (even by the script), GuiSize might not be called immediately. As with other window events, if the current thread is <a href="Thread.htm#Interrupt">uninterruptible</a>, GuiSize won't be called until the thread becomes interruptible. If the script has just resized the window, follow this example to ensure GuiSize is called immediately:</p> <pre><a href="Critical.htm#Off">Critical</a> Off <em>; Even if Critical On was never used.</em> <a href="Sleep.htm">Sleep</a> -1</pre> <p><span class="ver">[v1.1.22.05+]:</span> <a href="#Show">Gui Show</a> automatically does a <code>Sleep -1</code>, so it is generally not necessary to call Sleep in that case.</p> <p><span class="ver">[v1.1.20+]:</span> If GuiSize is a function, its parameters are as follows:</p> <pre class="Syntax"><span class="func">GuiSize</span>(GuiHwnd, EventInfo, Width, Height)</pre> <h3 id="GuiContextMenu">GuiContextMenu</h3> <p>Launched whenever the user right-clicks anywhere in the window except the title bar and menu bar. It is also launched in response to pressing <kbd>Menu</kbd> or <kbd>Shift</kbd>+<kbd>F10</kbd>. Unlike most other GUI labels, GuiContextMenu can have more than one concurrent <a href="../misc/Threads.htm">thread</a>. The following built-in variables are available within GuiContextMenu:</p> <ol> <li><a href="../Variables.htm#GuiControl">A_GuiControl</a>, which contains the <a href="../Variables.htm#GuiControl">text or variable name</a> of the control that received the event (blank if none).</li> <li><a href="../Variables.htm#EventInfo">A_EventInfo</a>: When a ListBox, ListView, or TreeView is the target of the context menu (as determined by A_GuiControl above), A_EventInfo specifies which of the control's items is the target: <ul> <li><a href="GuiControls.htm#ListBox">ListBox</a> or <a href="ListView.htm">ListView</a>: A_EventInfo contains the number of the currently focused row (0 if none).</li> <li><a href="TreeView.htm">TreeView</a>: For right-clicks, A_EventInfo contains the clicked item's ID number (or 0 if the user clicked somewhere other than an item). For <kbd>Menu</kbd> and <kbd>Shift</kbd>+<kbd>F10</kbd>, A_EventInfo contains the selected item's ID number.</li> </ul></li> <li>A_GuiX and A_GuiY, which contain the X and Y coordinates of where the script should display the menu (e.g. <code><a href="Menu.htm">Menu</a>, MyContext, Show, %A_GuiX%, %A_GuiY%</code>). Coordinates are relative to the upper-left corner of the window.</li> <li>A_GuiEvent, which contains the word RightClick if the user right-clicked, or Normal if the menu was triggered by <kbd>Menu</kbd> or <kbd>Shift</kbd>+<kbd>F10</kbd>.</li> </ol> <p class="note"><strong>Observação</strong>: Since <a href="GuiControls.htm#Edit">Edit</a> and <a href="GuiControls.htm#MonthCal">MonthCal</a> controls have their own context menu, a right-click in one of them will not launch GuiContextMenu.</p> <p><span class="ver">[v1.1.20+]:</span> If GuiContextMenu is a function, its parameters are as follows:</p> <pre class="Syntax"><span class="func">GuiContextMenu</span>(GuiHwnd, CtrlHwnd, EventInfo, IsRightClick, X, Y)</pre> <p><em>CtrlHwnd</em> is blank if the event was not received by a control. <em>IsRightClick</em> is true if A_GuiEvent is RightClick.</p> <h3 id="GuiDropFiles">GuiDropFiles</h3> <p>Launched whenever files/folders are dropped onto the window as part of a drag-and-drop operation (but if the label is already running, drop events are ignored). The following built-in variables are available within GuiDropFiles:</p> <ol> <li><a href="../Variables.htm#GuiControl">A_GuiControl</a>, which contains the <a href="../Variables.htm#GuiControl">text or variable name</a> of the control upon which the files were dropped (blank if none).</li> <li><a href="../Variables.htm#EventInfo">A_EventInfo</a> and <a href="../misc/ErrorLevel.htm">ErrorLevel</a>, which both contain the number of files dropped.</li> <li>A_GuiX and A_GuiY, which contain the X and Y coordinates of where the files were dropped (relative to the window's upper left corner).</li> <li>A_GuiEvent, which contains the names of the files that were dropped, with each filename except the last terminated by a linefeed (`n).</li> </ol> <p>To extract the individual files, use a <a href="LoopParse.htm">parsing loop</a> as shown below:</p> <pre><em>; EXAMPLE #1:</em> Loop, Parse, A_GuiEvent, `n { MsgBox, 4,, File number %A_Index% is:`n%A_LoopField%.`n`nContinue? IfMsgBox, No, break } <em>; EXAMPLE #2: To extract only the first file, follow this example:</em> Loop, Parse, A_GuiEvent, `n { FirstFile := A_LoopField break } <em>; EXAMPLE #3: To process the files in alphabetical order, follow this example:</em> FileList := A_GuiEvent Sort, FileList Loop, Parse, FileList, `n MsgBox File number %A_Index% is:`n%A_LoopField%.</pre> <p>To temporarily disable drag-and-drop for a window, remove the WS_EX_ACCEPTFILES style via <code>Gui -E0x10</code>. To re-enable it later, use <code>Gui +E0x10</code>.</p> <p><span class="ver">[v1.1.20+]:</span> If GuiDropFiles is a function, the parameters are as shown in the example below. <em>CtrlHwnd</em> is blank if files were dropped on the GUI itself. <em>FileArray</em> is an <a href="../Objects.htm#Usage_Simple_Arrays">array (object)</a> of filenames, where <code>FileArray[1]</code> is the first file and <code>FileArray.MaxIndex()</code> returns the number of files. A <a href="For.htm">for-loop</a> can be used to iterate through the files:</p> <pre>GuiDropFiles(GuiHwnd, FileArray, CtrlHwnd, X, Y) { for i, file in FileArray MsgBox File %i% is:`n%file% } </pre> <h3 id="OtherEvents">Other Events</h3> <p>Other types of GUI events can be detected and acted upon via <a href="OnMessage.htm">OnMessage()</a>. For example, a script can display context-sensitive help via ToolTip whenever the user moves the mouse over particular controls in the window. This is demonstrated in the <a href="#ExToolTip">GUI ToolTip example</a>.</p> <h2 id="MultiWin">Creating Multiple GUI Windows</h2> <p>To operate upon a window other than the <a href="#DefaultWin">default</a>, include its name or number (or <span class="ver">[in v1.1.03+]</span> its <a href="#GuiHwndOutputVar">HWND</a>) followed by a colon in front of the sub-command, as in these examples:</p> <pre>Gui, <strong>MyGui:</strong>Add, Text,, Text for about-box. Gui, <strong>MyGui:</strong>Show</pre> <p><code><a href="#Default">Gui MyGui:Default</a></code> can be used to avoid the need for the "MyGui:" prefix above. In addition, the prefix is not necessary inside a <a href="#DefaultWin">GUI thread</a> that operates upon the same window that launched the thread.</p> <p id="Name"><span class="ver">[v1.1.03+]:</span> Gui names must conform to the same rules as <a href="../Concepts.htm#names">variable names</a>. Any number which is either not between 1 and 99 or is longer than two characters (such as 0x01) must be the HWND of an existing Gui, or the command will fail. The number of windows that can be created is limited only by available system resources.</p> <p><span class="ver">[v1.1.04+]:</span> Any number of unnamed GUI windows can be created using <a href="#New">Gui, New</a>.</p> <h2 id="DefaultWin">GUI Events, Threads, and Subroutines</h2> <p>A GUI <a href="../misc/Threads.htm">thread</a> is defined as any thread launched as a result of a GUI action. GUI actions include selecting an item from a GUI window's <a href="#Menu">menu bar</a>, or triggering one of its <a href="#label">g-labels</a> (such as by pressing a button).</p> <p>The <strong>default <a href="#MultiWin">window name</a></strong> for a GUI thread is that of the window that launched the thread. Non-GUI threads use 1 as their default.</p> <p>Whenever a GUI <a href="../misc/Threads.htm">thread</a> is launched, that thread's <a href="../misc/WinTitle.htm#LastFoundWindow">last found window</a> starts off as the GUI window itself. This allows commands for windows and controls -- such as <a href="WinMove.htm">WinMove</a>, <a href="WinHide.htm">WinHide</a>, <a href="WinSet.htm">WinSet</a>, <a href="WinSetTitle.htm">WinSetTitle</a>, and <a href="ControlGetFocus.htm">ControlGetFocus</a> -- to omit WinTitle and WinText when operating upon the GUI window itself (even if it is hidden).</p> <p>Clicking on a control while its <a href="#label">g-label</a> is already running from a prior click will have no effect and the event is discarded. To prevent this, use <a href="Critical.htm">Critical</a> as the subroutine's first line (however, this will also buffer/defer other <a href="../misc/Threads.htm">threads</a> such as the press of a hotkey).</p> <p>The built-in variables A_Gui and A_GuiControl contain the window name and Control ID that launched the current thread. For details see <a href="../Variables.htm#Gui">A_Gui</a> and <a href="../Variables.htm#GuiControl">A_GuiControl</a>.</p> <p>To have multiple events perform the same subroutine, specify their labels consecutively above the subroutine. Por exemplo:</p> <pre>GuiEscape: GuiClose: ButtonCancel: ExitApp <em>; All of the above labels will do this.</em></pre> <p>All GUI <a href="../misc/Threads.htm">threads</a> start off fresh with the default values for settings such as <a href="SendMode.htm">SendMode</a>. These defaults can be changed in the <a href="../Scripts.htm#auto">auto-execute section</a>.</p> <h2 id="Navigate">Keyboard Navigation</h2> <p>A GUI window may be navigated via <kbd>Tab</kbd>, which moves keyboard focus to the next input-capable control (controls from which the <a href="#Tabstop">Tabstop</a> style has been removed are skipped). The order of navigation is determined by the order in which the controls were originally added. When the window is shown for the first time, the first input-capable control that has the Tabstop style (which most control types have by default) will have keyboard focus.</p> <p id="ShortcutKey">Certain controls may contain an ampersand (&amp;) to create a keyboard shortcut, which might be displayed in the control's text as an underlined character (depending on system settings). A user activates the shortcut by holding down <kbd>Alt</kbd> then typing the corresponding character. For buttons, checkboxes, and radio buttons, pressing the shortcut is the same as clicking the control. For GroupBoxes and Text controls, pressing the shortcut causes keyboard focus to jump to the first input-capable <a href="#Tabstop">tabstop</a> control that was created after it. However, if more than one control has the same shortcut key, pressing the shortcut will alternate keyboard focus among all controls with the same shortcut.</p> <p>To display a literal ampersand inside the control types mentioned above, specify two consecutive ampersands as in this example: <code>Gui, Add, Button,, Save &amp;&amp; Exit</code>.</p> <h2 id="Appear">Window Appearance</h2> <p>For its icon, a GUI window uses the tray icon that was in effect at the time the window was created. Thus, to have a different icon, change the tray icon before creating the window. Por exemplo: <code><a href="Menu.htm">Menu</a>, Tray, Icon, MyIcon.ico</code>. It is also possible to have a different large icon for a window than its small icon (the large icon is displayed in the alt-tab task switcher). This can be done via <a href="LoadPicture.htm">LoadPicture()</a> and <a href="PostMessage.htm">SendMessage</a>; for example:</p> <pre>iconsize := 32 <em>; Ideal size for alt-tab varies between systems and OS versions.</em> hIcon := LoadPicture("My Icon.ico", "Icon1 w" iconsize " h" iconsize, imgtype) Gui +LastFound SendMessage 0x0080, 1, hIcon <em>; 0x0080 is WM_SETICON; and 1 means ICON_BIG (vs. 0 for ICON_SMALL).</em> Gui Show</pre> <p>Due to OS limitations, Checkboxes, Radio buttons, and GroupBoxes for which a non-default text color was specified will take on Classic Theme appearance on Windows XP and beyond.</p> <p>Related topic: <a href="#Margin">window's margin</a>.</p> <h2 id="GenRemarks">Observações Gerais</h2> <p>Use <a href="GuiControl.htm">GuiControl</a> and <a href="GuiControlGet.htm">GuiControlGet</a> to operate upon individual controls in a GUI window.</p> <p>Each GUI window may have up to 11,000 controls. However, use caution when creating more than 5000 controls because system instability may occur for certain control types.</p> <p>Any script that uses the GUI command anywhere is automatically <a href="_Persistent.htm">persistent</a> (even if the GUI command is never actually executed). It is also single-instance unless the <a href="_SingleInstance.htm">#SingleInstance</a> directive has been used to override that.</p> <h2 id="Related">Tópicos relacionados</h2> <p><a href="GuiControl.htm">GuiControl</a>, <a href="GuiControlGet.htm">GuiControlGet</a>, <a href="Menu.htm">Menu</a>, <a href="GuiControls.htm">Control Types</a>, <a href="ListView.htm">ListView</a>, <a href="TreeView.htm">TreeView</a>, <a href="Control.htm">Control</a>, <a href="ControlGet.htm">ControlGet</a>, <a href="Progress.htm">SplashImage</a>, <a href="MsgBox.htm">MsgBox</a>, <a href="FileSelectFile.htm">FileSelectFile</a>, <a href="FileSelectFolder.htm">FileSelectFolder</a></p> <h2 id="Examples">Exemplos</h2> <div class="ex" id="ExPopup"> <p><a class="ex_number" href="#ExPopup"></a> Creates a popup window similar to <a href="SplashTextOn.htm">SplashTextOn</a>.</p> <pre>Gui, +AlwaysOnTop +Disabled -SysMenu +Owner <em>; +Owner avoids a taskbar button.</em> Gui, Add, Text,, Some text to display. Gui, Show, NoActivate, Title of Window <em>; NoActivate avoids deactivating the currently active window.</em></pre> </div> <div class="ex" id="ExInputBox"> <p><a class="ex_number" href="#ExInputBox"></a> Creates a simple input-box that asks for the first and last name.</p> <pre>Gui, Add, Text,, First name: Gui, Add, Text,, Last name: Gui, Add, Edit, vFirstName ym <em>; The ym option starts a new column of controls.</em> Gui, Add, Edit, vLastName Gui, Add, Button, default, OK <em>; The label ButtonOK (if it exists) will be run when the button is pressed.</em> Gui, Show,, Simple Input Example return <em>; End of auto-execute section. The script is idle until the user does something.</em> GuiClose: ButtonOK: Gui, Submit <em>; Save the input from the user to each control's associated variable.</em> MsgBox You entered "%FirstName% %LastName%". ExitApp</pre> </div> <div class="ex" id="ExTab"> <p><a class="ex_number" href="#ExTab"></a> Creates a tab control with multiple tabs, each containing different controls to interact with.</p> <pre>Gui, Add, Tab2,, First Tab|Second Tab|Third Tab <em>; Tab2 vs. Tab requires <span class="ver">[v1.0.47.05+]</span>.</em> Gui, Add, Checkbox, vMyCheckbox, Sample checkbox Gui, Tab, 2 Gui, Add, Radio, vMyRadio, Sample radio1 Gui, Add, Radio,, Sample radio2 Gui, Tab, 3 Gui, Add, Edit, vMyEdit r5 <em>; r5 means 5 rows tall.</em> Gui, Tab <em>; i.e. subsequently-added controls will not belong to the tab control.</em> Gui, Add, Button, default xm, OK <em>; xm puts it at the bottom left corner.</em> Gui, Show return ButtonOK: GuiClose: GuiEscape: Gui, Submit <em>; Save each control's contents to its associated variable.</em> MsgBox You entered:`n%MyCheckbox%`n%MyRadio%`n%MyEdit% ExitApp</pre> </div> <div class="ex" id="ExListBox"> <p><a class="ex_number" href="#ExListBox"></a> Creates a ListBox control containing files in a directory.</p> <pre>Gui, Add, Text,, Pick a file to launch from the list below.`nTo cancel, press ESCAPE or close this window. Gui, Add, ListBox, vMyListBox gMyListBox w640 r10 Gui, Add, Button, Default, OK Loop, C:\*.* <em>; Change this folder and wildcard pattern to suit your preferences.</em> { GuiControl,, MyListBox, %A_LoopFileFullPath% } Gui, Show return MyListBox: if (A_GuiEvent != "DoubleClick") return <em>; Otherwise, the user double-clicked a list item, so treat that the same as pressing OK. ; So fall through to the next label.</em> ButtonOK: GuiControlGet, MyListBox <em>; Retrieve the ListBox's current selection.</em> MsgBox, 4,, Would you like to launch the file or document below?`n`n%MyListBox% IfMsgBox, No return <em>; Otherwise, try to launch it:</em> Run, %MyListBox%,, UseErrorLevel if (ErrorLevel = "ERROR") MsgBox Could not launch the specified file. Perhaps it is not associated with anything. return GuiClose: GuiEscape: ExitApp</pre> </div> <div class="ex" id="ExToolTip"> <p><a class="ex_number" href="#ExToolTip"></a> Displays a context-sensitive help (via ToolTip) whenever the user moves the mouse over a particular control.</p> <pre>Gui, Add, Edit, v<strong>MyEdit</strong> <strong>MyEdit</strong>_TT := "This is a tooltip for the control whose variable is MyEdit." Gui, Add, DropDownList, v<strong>MyDDL</strong>, Red|Green|Blue <strong>MyDDL</strong>_TT := "Choose a color from the drop-down list." Gui, Add, Checkbox, vMyCheck, This control has no tooltip. Gui, Show <a href="OnMessage.htm">OnMessage</a>(0x0200, "WM_MOUSEMOVE") return WM_MOUSEMOVE() { static CurrControl, PrevControl, _TT <em>; _TT is kept blank for use by the ToolTip command below.</em> CurrControl := A_GuiControl if (CurrControl != PrevControl and not InStr(CurrControl, " ")) { ToolTip <em>; Turn off any previous tooltip.</em> SetTimer, DisplayToolTip, 1000 PrevControl := CurrControl } return DisplayToolTip: SetTimer, DisplayToolTip, Off <a href="ToolTip.htm">ToolTip</a> % %CurrControl%_TT <em>; The leading percent sign tell it to use an expression.</em> SetTimer, RemoveToolTip, 3000 return RemoveToolTip: SetTimer, RemoveToolTip, Off ToolTip return } GuiClose: ExitApp</pre> </div> <div class="ex" id="OSD"> <p><a class="ex_number" href="#OSD"></a> Creates an On-screen display (OSD) via transparent window.</p> <pre>CustomColor := "EEAA99" <em>; Can be any RGB color (it will be made transparent below).</em> Gui +LastFound +AlwaysOnTop -Caption +ToolWindow <em>; +ToolWindow avoids a taskbar button and an alt-tab menu item.</em> Gui, Color, %CustomColor% Gui, Font, s32 <em>; Set a large font size (32-point).</em> Gui, Add, Text, vMyText cLime, XXXXX YYYYY <em>; XX &amp; YY serve to auto-size the window. ; Make all pixels of this color transparent and make the text itself translucent (150):</em> WinSet, TransColor, %CustomColor% 150 SetTimer, UpdateOSD, 200 Gosub, UpdateOSD <em>; Make the first update immediate rather than waiting for the timer.</em> Gui, Show, x0 y400 NoActivate <em>; NoActivate avoids deactivating the currently active window.</em> return UpdateOSD: MouseGetPos, MouseX, MouseY GuiControl,, MyText, X%MouseX%, Y%MouseY% return</pre> </div> <div class="ex" id="ExProgressBar"> <p><a class="ex_number" href="#ExProgressBar"></a> Creates a moving progress bar overlayed on a background image.</p> <pre>Gui, Color, White Gui, Add, Picture, x0 y0 h350 w450, %A_WinDir%\system32\ntimage.gif Gui, Add, Button, Default xp+20 yp+250, Start the Bar Moving Gui, Add, Progress, vMyProgress w416 Gui, Add, Text, vMyText wp <em>; wp means "use width of previous".</em> Gui, Show return ButtonStartTheBarMoving: Loop, %A_WinDir%\*.* { if (A_Index &gt; 100) break GuiControl,, MyProgress, %A_Index% GuiControl,, MyText, %A_LoopFileName% Sleep 50 } GuiControl,, MyText, Bar finished. return GuiClose: ExitApp</pre> </div> <div class="ex" id="ExImageViewer"> <p><a class="ex_number" href="#ExImageViewer"></a> Creates a simple image viewer.</p> <pre>Gui, +Resize Gui, Add, Button, default, &amp;Load New Image Gui, Add, Radio, ym+5 x+10 vRadio checked, Load &amp;actual size Gui, Add, Radio, ym+5 x+10, Load to &amp;fit screen Gui, Add, Pic, xm vPic Gui, Show return ButtonLoadNewImage: FileSelectFile, file,,, Select an image:, Images (*.gif; *.jpg; *.bmp; *.png; *.tif; *.ico; *.cur; *.ani; *.exe; *.dll) if not file return Gui, Submit, NoHide <em>; Save the values of the radio buttons.</em> if (Radio = 1) <em>; Display image at its actual size.</em> { Width := 0 Height := 0 } else <em>; Second radio is selected: Resize the image to fit the screen.</em> { Width := A_ScreenWidth - 28 <em>; Minus 28 to allow room for borders and margins inside.</em> Height := -1 <em>; "Keep aspect ratio" seems best.</em> } GuiControl,, Pic, *w%width% *h%height% %file% <em>; Load the image.</em> Gui, Show, xCenter y0 AutoSize, %file% <em>; Resize the window to match the picture size.</em> return GuiClose: ExitApp</pre> </div> <div class="ex" id="ExEditor"> <p><a class="ex_number" href="#ExEditor"></a> Creates a simple text editor with menu bar.</p> <pre><em>; Create the sub-menus for the menu bar:</em> Menu, FileMenu, Add, &amp;New, FileNew Menu, FileMenu, Add, &amp;Open, FileOpen Menu, FileMenu, Add, &amp;Save, FileSave Menu, FileMenu, Add, Save &amp;As, FileSaveAs Menu, FileMenu, Add <em>; Separator line.</em> Menu, FileMenu, Add, E&amp;xit, FileExit Menu, HelpMenu, Add, &amp;About, HelpAbout <em>; Create the menu bar by attaching the sub-menus to it:</em> Menu, MyMenuBar, Add, &amp;File, :FileMenu Menu, MyMenuBar, Add, &amp;Help, :HelpMenu <em>; Attach the menu bar to the window:</em> Gui, Menu, MyMenuBar <em>; Create the main Edit control and display the window:</em> Gui, +Resize <em>; Make the window resizable.</em> Gui, Add, Edit, vMainEdit WantTab W600 R20 Gui, Show,, Untitled CurrentFileName := "" <em>; Indicate that there is no current file.</em> return FileNew: GuiControl,, MainEdit <em>; Clear the Edit control.</em> return FileOpen: Gui +OwnDialogs <em>; Force the user to dismiss the FileSelectFile dialog before returning to the main window.</em> FileSelectFile, SelectedFileName, 3,, Open File, Text Documents (*.txt) if not SelectedFileName <em>; No file selected.</em> return Gosub FileRead return FileRead: <em>; Caller has set the variable SelectedFileName for us.</em> FileRead, MainEdit, %SelectedFileName% <em>; Read the file's contents into the variable.</em> if ErrorLevel { MsgBox Could not open "%SelectedFileName%". return } GuiControl,, MainEdit, %MainEdit% <em>; Put the text into the control.</em> CurrentFileName := SelectedFileName Gui, Show,, %CurrentFileName% <em>; Show file name in title bar.</em> return FileSave: if not CurrentFileName <em>; No filename selected yet, so do Save-As instead.</em> Goto FileSaveAs Gosub SaveCurrentFile return FileSaveAs: Gui +OwnDialogs <em>; Force the user to dismiss the FileSelectFile dialog before returning to the main window.</em> FileSelectFile, SelectedFileName, S16,, Save File, Text Documents (*.txt) if not SelectedFileName <em>; No file selected.</em> return CurrentFileName := SelectedFileName Gosub SaveCurrentFile return SaveCurrentFile: <em>; Caller has ensured that CurrentFileName is not blank.</em> if FileExist(CurrentFileName) { FileDelete %CurrentFileName% if ErrorLevel { MsgBox The attempt to overwrite "%CurrentFileName%" failed. return } } GuiControlGet, MainEdit <em>; Retrieve the contents of the Edit control.</em> FileAppend, %MainEdit%, %CurrentFileName% <em>; Save the contents to the file. ; Upon success, Show file name in title bar (in case we were called by FileSaveAs):</em> Gui, Show,, %CurrentFileName% return HelpAbout: Gui, About:+owner1 <em>; Make the main window (Gui #1) the owner of the "about box".</em> Gui +Disabled <em>; Disable main window.</em> Gui, About:Add, Text,, Text for about box. Gui, About:Add, Button, Default, OK Gui, About:Show return AboutButtonOK: <em>; This section is used by the "about box" above.</em> AboutGuiClose: AboutGuiEscape: Gui, 1:-Disabled <em>; Re-enable the main window (must be done prior to the next step).</em> Gui Destroy <em>; Destroy the about box.</em> return GuiDropFiles: <em>; Support drag &amp; drop.</em> Loop, Parse, A_GuiEvent, `n { SelectedFileName := A_LoopField <em>; Get the first file only (in case there's more than one).</em> break } Gosub FileRead return GuiSize: if (ErrorLevel = 1) <em>; The window has been minimized. No action needed.</em> return <em>; Otherwise, the window has been resized or maximized. Resize the Edit control to match.</em> NewWidth := A_GuiWidth - 20 NewHeight := A_GuiHeight - 20 GuiControl, Move, MainEdit, W%NewWidth% H%NewHeight% return FileExit: <em>; User chose "Exit" from the File menu.</em> GuiClose: <em>; User closed the window.</em> ExitApp</pre> </div> </body> </html>