Add

Adds a control to the GUI window, and returns a GuiControl object.

Gui.Add(ControlType , Options, Text)
Gui.AddControlType(Options, Text)

ControlType

This is one of the following: Text, Edit, UpDown, Picture, Button, Checkbox, Radio, DropDownList, ComboBox, ListBox, ListView, TreeView, Link, Hotkey, DateTime, MonthCal, Slider, Progress, GroupBox, Tab, StatusBar, ActiveX, Custom

For example:

Gui := GuiCreate()
Gui.Add("Text",, "Please enter your name:")
Gui.AddEdit("vName")
Gui.Show

Options

Positioning and Sizing of Controls

If some dimensions and/or coordinates are omitted from Options, the control will be positioned relative to the previous control and/or sized automatically according to its nature and contents.

The following options are supported:

R: Rows of text (can contain a floating point number such as R2.5). R is often preferable to specifying H (Height). If both the R and H options are present, R will take precedence. For a GroupBox, this setting is the number of controls for which to reserve space inside the box. For DropDownLists, ComboBoxes, and ListBoxes, 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 R and H 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, R is the number of rows of text that can visibly fit inside the control.

W: Width, in pixels. If omitted, the width is calculated automatically for some control types based on their contents. The other controls types have the following default widths:
Tab controls: 30 times the current font size, plus 3 times the X-margin.
Vertical Progress Bars: Two times the current font size.
Horizontal Progress Bars, horizontal Sliders, DropDownLists, ComboBoxes, ListBoxes, GroupBoxes, Edits, and Hotkeys: 15 times the current font size (except GroupBoxes, which multiply by 18 to provide room inside for margins).

H: Height, in pixels. If both the H and R 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, H 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 R option is usually preferable to using H because it prevents a control from showing partial/incomplete rows of text.

wp+n, hp+n, wp-n, hp-n (where n 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, wp would set a control's width to that of the previous control, and wp-50 would set it equal to 50 less than that of the previous control.

X: X-position. For example, specifying x0 y0 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). If X is omitted but not Y, the control will be positioned to the right of all previously added controls, which can be thought of as starting a new "column".

Y: Y-position. If Y is omitted but not X, the control will be positioned beneath all previously added controls, which can be thought of as starting a new "row".

Omitting either X, Y 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.

If both X and Y are omitted, the control will be positioned beneath the previous control using a standard padding distance.

For X and Y, 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 Y+10 would position the control 10 pixels beneath the bottom of the previous control rather than using the standard padding distance. Similarly, specifying X+10 would position the control 10 pixels to the right of the previous control's right edge. Since negative numbers such as X-10 are reserved for absolute positioning, to use a negative offset, include a plus sign in front of it. For example: X+-10.

For X+ and Y+, the letter M can be used as a substitute for the window's current margin. For example, x+m uses the right edge of the previous control plus the standard padding distance. xp y+m positions a control below the previous control, whereas specifying an X coordinate on its own would normally imply yp by default.

xp+n, yp+n, xp-n, yp-n (where n 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 GroupBox.

xm and ym can be used to position a control at the leftmost and topmost margins of the window, respectively (these two may also be followed by a plus/minus sign and a number). By specifying ym without any x-position at all, the control will be positioned at the top margin but to the right of all previously added controls, which can be thought of as starting a new "column". The converse is also true.

xs and ys: these are similar to xm and ym except that they refer to coordinates that were saved by having previously added a control with the word Section in its options (the first control of the window always starts a new section, even if that word isn't specified in its options). By specifying ys without any x-position at all, the control will be positioned at the previously saved y-position, but to the right of all controls that have been added since the most recent use of the word Section; this can be thought of as starting a new column within the section. For example:

Gui := GuiCreate()
Gui.Add("Edit", "w600")  ; Add a fairly wide edit control at the top of the window.
Gui.Add("Text", "section", "First Name:")  ; Save this control's position and start a new section.
Gui.Add("Text",, "Last Name:")
Gui.Add("Edit", "ys")  ; Start a new column within this section.
Gui.Add("Edit")
Gui.Show()

The converse of the above (specifying xs but omitting the y-position) is also true.

xs and ys may optionally be followed by a plus/minus sign and a number. Also, it is possible to specify both the word Section and xs/ys in a control's options; this uses the previous section for itself but establishes a new section for subsequent controls.

Storing and Responding to User Input

V: Sets the control's Name. Specify the name immediately after the letter V, which is not included in the name. For example, specifying vMyEdit would name the control "MyEdit".

Events: Event handlers (such as a function which is called automatically when the user clicks or changes a control) cannot be set within the control's Options. Instead, OnEvent can be used to register a callback function or method for each event of interest.

Controls: Common Styles and Other Options

Note: In the absence of a preceding sign, a plus sign is assumed; for example, Wrap is the same as +Wrap. By contrast, -Wrap would remove the word-wrapping property.

AltSubmit: Uses alternate submit method. For DropDownList, ComboBox, ListBox and Tab, this causes Gui.Submit to store the position of the selected item rather than its text. If no item is selected, a ComboBox will still store the text of its edit field.

C: Color of text (has no effect on buttons). Specify the letter C followed immediately by a color name (see color chart) or RGB value (the 0x prefix is optional). Examples: cRed, cFF2211, c0xFF2211, cDefault.

Disabled: Makes an input-capable control appear in a disabled state, which prevents the user from focusing or modifying its contents. Use GuiCtrl.Enabled to enable it later. Note: To make an Edit control read-only, specify the string ReadOnly 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, Disabled and Disabled%VarContainingOne% are the same.

Hidden: The control is initially invisible. Use GuiCtrl.Visible 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, Hidden and Hidden%VarContainingOne% are the same.

Left: 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.

Right: 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.

Center: Centers the control's text within its available width. This option affects the following controls: Text, Edit, Button, Checkbox, Radio, Slider, GroupBox.

Section: Starts a new section and saves this control's position for later use with the xs and ys positioning options described above.

Tabstop: Use -Tabstop (i.e. minus Tabstop) to have an input-capable control skipped over when the user presses the TAB key to navigate.

Wrap: Enables word-wrapping of the control's contents within its available width. Since nearly all control types start off with word-wrapping enabled, use -Wrap to disable word-wrapping.

VScroll: Provides a vertical scroll bar if appropriate for this type of control.

HScroll: Provides a horizontal scroll bar if appropriate for this type of control. The rest of this paragraph applies to ListBox 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, HScroll500 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 HScroll makes it possible for the horizontal scroll bar to be added later via MyScrollBar.Opt("+HScroll500"), which is otherwise impossible).

Controls: Uncommon Styles and Options

BackgroundTrans: 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 GuiCtrl.Opt("+Background") to remove this option later. See Picture control's AltSubmit section for more information about transparent images. Known limitation: BackgroundTrans might not work properly for controls inside a Tab control that contains a ListView. If a control type does not support this option, an error is thrown.

BackgroundColor: Changes the background color of the control. Replace Color with a color name (see color chart) or RGB value (the 0x prefix is optional). Examples: BackgroundSilver, BackgroundFFDD99. If this option is not present, a Text, Picture, GroupBox, CheckBox, Radio, Slider, Tab or Link control initially defaults to the background color set by Gui.BackColor (or if none or other control type, the system's default background color). Specifying BackgroundDefault or -Background applies the system's default background color. For example, a control can be restored to the default color via LV.Opt("+BackgroundDefault"). Using +Background without specifying a color reverts -Background. If a control type does not support this option, an error is thrown.

Border: 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 existing control, it might be necessary to increase the control's width and height by 1 pixel.

Theme: 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 GUI's +/-Theme option for details.

(Unnamed Style): Specify a plus or minus sign followed immediately by a decimal or hexadecimal style number. If the sign is omitted, a plus sign is assumed.

(Unnamed ExStyle): 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, E0x200 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 www.microsoft.com.

Text

Depending on the specified control type, a string, number or an array.

Show

By default, this makes the window visible, unminimizes it (if necessary) and activates it.

Gui.Show(Options)

Options

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.

Zero or more of the following strings may be present in Options (specify each number as decimal, not hexadecimal):

Wn: Specify for n the width (in pixels) of the window's client area (the client area excludes the window's borders, title bar, and menu bar).

Hn: Specify for n the height of the window's client area, in pixels.

Xn: Specify for n the window's X-position on the screen, in pixels. Position 0 is the leftmost column of pixels visible on the screen.

Yn: Specify for n the window's Y-position on the screen, in pixels. Position 0 is the topmost row of pixels visible on the screen.

Center: Centers the window horizontally and vertically on the screen.

xCenter: Centers the window horizontally on the screen. For example: Gui.Show("xCenter y0").

yCenter: Centers the window vertically on the screen.

AutoSize: 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. For example:
Gui.Show("AutoSize Center")

One of the following may also be present:

Minimize: Minimizes the window and activates the one beneath it.

Maximize: Maximizes and activates the window.

Restore: Unminimizes or unmaximizes the window, if necessary. The window is also shown and activated, if necessary.

NoActivate: Unminimizes or unmaximizes the window, if necessary. The window is also shown without activating it.

NA: 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.

Hide: Hides the window and activates the one beneath it. This is identical in function to Gui.Hide except that it allows a hidden window to be moved or resized without showing it. For example: Gui.Show("Hide x55 y66 w300 h200").

Submit

Saves the contents of controls into an associative array (object) and returns it. By default, also hides the window.

NamedCtrlContents := Gui.Submit(Hide := true)

Hide

If this parameter is false, the window will not be hidden.

The returned array contains one element per control, usually like array[GuiCtrl.Name] := GuiCtrl.Value, with the exceptions noted below. Only input-capable controls which support GuiCtrl.Value and have been given a name are included.

For DropDownList, ComboBox, ListBox and Tab, the text of the selected item/tab is stored instead of its position number if the control lacks the AltSubmit option, or if the ComboBox's text does not match a list item. Otherwise, Value (the item's position number) is stored.

If only one Radio button in a radio group has a name, Submit stores the number of the currently selected button instead of the control's Value. 1 is the first radio button (according to original creation order), 2 is the second, and so on. If there is no button selected, 0 is stored.

Excluded because they are not input-capable: Text, Pic, GroupBox, Button, Progress, Link, StatusBar.

Also excluded: ListView, TreeView, ActiveX, Custom.

Hide / Cancel

Hides the window.

Gui.Hide()
Gui.Cancel()

Destroy

Removes the window and all its controls, freeing the corresponding memory and system resources.

Gui.Destroy()

Note: 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 Gui.Destroy() is not used, all GUI windows are automatically destroyed when the script exits.

SetFont

Sets the font typeface, size, style, and/or color for controls added to the window from this point onward.

Note: Omit both parameters to restore the font to the system's default GUI typeface, size, and color. Otherwise, any font attributes which are not specified will be copied from the previous font.

Gui.SetFont(Options, FontName)

Options

Zero or more options. Each option is either a single letter immediately followed by a value, or a single word. To specify more than one option, include a space between each. For example: cBlue s12 bold.

The following words are supported: bold, italic, strike, underline, and norm. Norm 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 norm italic would set the font to normal then to italic.

C: Color name (see color chart) or RGB value -- or specify the word Default to return to the system's default color (black on most systems). Example values: cRed, cFFFFAA, cDefault. Note: Buttons 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. For example: Gui.Add("Text", "cRed", "My Text").

S: Size (in points). For example: s12 (specify decimal, not hexadecimal)

W: Weight (boldness), which is a number between 1 and 1000 (400 is normal and 700 is bold). For example: w600 (specify decimal, not hexadecimal)

Q: Text rendering quality. For example: q3. Q should be followed by a number from the following table:

0 = DEFAULT_QUALITY	Appearance of the font does not matter.
1 = DRAFT_QUALITY	Appearance of the font is less important than when the PROOF_QUALITY value is used.
2 = PROOF_QUALITY	Character quality of the font is more important than exact matching of the logical-font attributes.
3 = NONANTIALIASED_QUALITY	Font is never antialiased, that is, font smoothing is not done.
4 = ANTIALIASED_QUALITY	Font is antialiased, or smoothed, if the font supports it and the size of the font is not too small or too large.
5 = CLEARTYPE_QUALITY	Windows XP and later: If set, text is rendered (when possible) using ClearType antialiasing method.

For more details of what these values mean, see MSDN: CreateFont.

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.

FontName

FontName may be the name of any font, such as one from the font table. If FontName 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:

Gui.SetFont(, "MS sans serif")
Gui.SetFont(, "Arial")
Gui.SetFont(, "Verdana")  ; Preferred font.

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 DllCall() as demonstrated at www.autohotkey.com/forum/topic17230.html.

BackColor

Retrieves or sets the background color of the window.

RetrievedColor := Gui.BackColor

Gui.BackColor := NewColor

RetrievedColor is a 6-digit RGB value of the current color previously set by this property.

NewColor is one of the 16 primary HTML color names, a hexadecimal RGB color value (the 0x prefix is optional), a pure numeric RGB color value, or the word Default for its default color. Example values: "Silver", "FFFFAA", 0xFFFFAA, "Default".

By default, the window's background color is the system's color for the face of buttons.

The color of the menu bar and its submenus can be changed as in this example: Menu, MyMenuBar, Color, White.

To make the background transparent, use WinSetTransColor. However, if you do this without first having assigned a custom window via Gui.BackColor(), buttons will also become transparent. To prevent this, first assign a custom color and then make that color transparent. For example:

Gui.BackColor("EEAA99")
WinSetTransColor("EEAA99")

To additionally remove the border and title bar from a window with a transparent background, use the following after the window has been made transparent: Gui.Opt("-Caption")

To illustrate the above, there is an example of an on-screen display (OSD) near the bottom of this page.

MarginX

Retrieves or sets the size of horizontal margins between sides and subsequently created controls.

RetrievedValue := Gui.MarginX

Gui.MarginX := NewValue

RetrievedValue is the number of pixels of the current horizontal margin.

NewValue is the number of pixels of space to leave at the left and right side of the window when auto-positioning any control that lacks an explicit X coordinate. Also, the margin is used to determine the horizontal distance that separates auto-positioned controls from each other. Finally, the margin is taken into account by the first use of Gui.Show to calculate the window's size (when no explicit size is specified).

By default, this margin is proportional to the size of the currently selected font (1.25 times font-height for left & right).

MarginY

Retrieves or sets the size of vertical margins between sides and subsequently created controls.

RetrievedValue := Gui.MarginY

Gui.MarginY := NewValue

RetrievedValue is the number of pixels of the current vertical margin.

NewValue is the number of pixels of space to leave at the top and bottom side of the window when auto-positioning any control that lacks an explicit Y coordinate. Also, the margin is used to determine the vertical distance that separates auto-positioned controls from each other. Finally, the margin is taken into account by the first use of Gui.Show to calculate the window's size (when no explicit size is specified).

By default, this margin is proportional to the size of the currently selected font (0.75 times font-height for top & bottom).

Opt

Sets one or more options for the GUI window.

Gui.Opt(Options)
Gui.Options(Options)

Options

This parameter can contain any of the options supported by GuiCreate.

For performance reasons, it is better to set all options before creating the window (that is, before any use of other methods such as Gui.Add).

FocusedCtrl

Retrieves the GuiControl object of the GUI's focused control.

GuiCtrlObj := Gui.FocusedCtrl

Note: To be effective, the window generally must not be minimized or hidden.

Menu

Attaches a menu bar to the window.

Gui.Menu := MenuName

MenuName is the name of an ordinary menu created by the Menu command. For example:

Menu("FileMenu", "Add", "&Open`tCtrl+O", "MenuFileOpen")  ; See remarks below about Ctrl+O.
Menu("FileMenu", "Add", "E&xit", "MenuHandler")
Menu("FileMenu", "Add", "&About", "MenuHandler")
Menu("MyMenuBar", "Add", "&File", ":FileMenu")  ; Attach the two sub-menus that were created above.
Menu("MyMenuBar", "Add", "&Help", ":HelpMenu")
Gui.Menu := "MyMenuBar"

In the first line above, notice that &Open is followed by Ctrl+O (with a tab character in between). This indicates a keyboard shortcut that the user may press instead of selecting the menu item. If the shortcut uses only the standard modifier key names Ctrl, Alt and Shift, it is automatically registered as a keyboard accelerator for the GUI. Single-character accelerators with no modifiers are case-sensitive and can be triggered by unusual means such as IME or Alt+NNNN.

If a particular key combination does not work automatically, the use of a context-sensitive hotkey may be required. However, such hotkeys typically cannot be triggered by Send and are more likely to interfere with other scripts than a standard keyboard accelerator.

To remove a window's current menu bar, use Gui.Menu := "" (that is, assign an empty string).

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.

The use of certain destructive menu sub-commands 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 UseErrorLevel is in effect). Use the following steps to make such changes: 1) detach the menu bar via Gui.Menu := ""; 2) make the changes; 3) reattach the menu bar via Gui.Menu := "MyMenuBar".

Minimize

Unhides the window (if necessary) and minimizes it.

Gui.Minimize()

Maximize

Unhides the window (if necessary) and maximizes it.

Gui.Maximize()

Restore

Unhides the window (if necessary) and restores it, if it was minimized or maximized beforehand.

Gui.Restore()

Pos

Retrieves the position and size of the window.

PosSizeObj := Gui.Pos

PosSizeObj is an object with the keys X (x coordinate), Y (y coordinate), W (width) and H (height). The coordinates are the upper left corner of the window. Width is the horizontal distance between the left and right side of the window, and height the vertical distance between the top and bottom side (in pixels).

ClientPos

Retrieves the position and size of the window's client area.

PosSizeObj := Gui.ClientPos

PosSizeObj is an object with the keys X (x coordinate), Y (y coordinate), W (width) and H (height). The coordinates are the upper left corner of the window's client area, which is the area not including title bar, menu bar, and borders. Width is the horizontal distance between the left and right side of the client area, and height the vertical distance between the top and bottom side (in pixels).

Flash

Blinks the window's button in the taskbar.

Gui.Flash(Blink := true)

Blink

If this parameter is omitted or true, the window's button in the taskbar will blink. This is done by inverting the color of the window's title bar and/or taskbar button (if it has one). Specify false to restore the original colors of the title bar and taskbar button (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:

Loop(6)
{
  Gui.Flash()
  Sleep(500)  ; It's quite sensitive to this value; altering it may change the behavior in unexpected ways.
}

Hwnd

Retrieves the window handle (HWND) of the GUI window.

CurrentHwnd := Gui.Hwnd

A GUI's HWND is often used with PostMessage, SendMessage, and DllCall. It can also be used directly as an ahk_id WinTitle.

Title

Retrieves or sets the GUI's title.

RetrievedTitle := Gui.Title

Gui.Title := NewTitle

Name

Retrieves or sets a custom name for the GUI window.

RetrievedName := Gui.Name

Gui.Name := NewName

Control

Retrieves the GuiControl object associated with the specified name, ClassNN or HWND.

GuiCtrlObj := Gui.ControlName

_NewEnum

Iterates through the GUI's controls.

Gui._NewEnum()

Note: The first output variable is the HWND, and the second is the GuiControl object.