Makes a variety of changes to a control in a GUI window.
GuiControl, SubCommand, ControlID , Value
The control's associated variable name (if any), ClassNN, text, or in [v1.1.04+] the control's HWND. For details, see Control Identifiers.
If the control is not on the default GUI, the name or HWND of the GUI must also be specified -- except on [v1.1.20+] when ControlID is a HWND, since each HWND is unique. See Remarks for details.
For SubCommand, specify one of the following:
Puts new contents into a control.
GuiControl,, ControlID , Value
Leave SubCommand blank to put new contents into the control via Value. Specifically:
Picture: Value should be the filename or in [v1.1.23+] a handle of the new image to load (see Gui Picture for supported file types). Zero or more of the following options may be specified immediately in front of the filename: *wN (width N), *hN (height N), and *IconN (icon group number N in a DLL or EXE file). In the following example, the default icon from the second icon group is loaded with a width of 100 and an automatic height via "keep aspect ratio": GuiControl,, MyPic, *icon2 *w100 *h-1 C:\My Application.exe. Specify *w0 *h0 to use the image's actual width and height. If *w and *h are omitted, the image will be scaled to fit the current size of the control. When loading from a multi-icon .ICO file, specifying a width and height also determines which icon to load. Note: Use only one space or tab between the final option and the filename itself; any other spaces and tabs are treated as part of the filename.
Text/Button/GroupBox/StatusBar/Link: Specify for Value the control's new text. Since the control will not expand automatically, use GuiControl, Move, MyText, W300 if the control needs to be widened. For StatusBar, this sets the text of the first part only; use SB_SetText() for greater flexibility.
Edit: Any linefeeds (`n) in Value that lack a preceding carriage return (`r) are automatically translated to CR+LF (`r`n) to make them display properly. However, this is usually not a concern because the Gui Submit and GuiControlGet commands will automatically undo this translation by replacing CR+LF with LF (`n).
Hotkey: Value can be blank to clear the control, or a set of modifiers with a key name. Examples: ^!c, ^Numpad1, +Home. The only modifiers supported are ^ (Control), ! (Alt), and + (Shift). See the key list for available key names.
CheckBox: Value can be 0 to uncheck the button, 1 to check it, or -1 to make it indeterminate. Otherwise, Value is assumed to be the control's new caption/text. See the Text sub-command for how to override this behavior.
Radio: Same as the CheckBox paragraph above. However, if the radio button is being checked (turned on) and it is a member of a multi-radio group, the other radio buttons in its group will be automatically unchecked. To check a new button within a radio group that only has one variable, specify for ControlID the name/text of the button if it is not the button with which the variable is directly associated.
DateTime/MonthCal: Specify for Value a date-time stamp in YYYYMMDDHH24MISS format. Specify %A_Now% to use the current date and time (today). For DateTime controls, Value may be omitted to cause the control to have no date/time selected (if it was created with that ability). For MonthCal controls, a range may be specified if the control is multi-select.
UpDown/Slider/Progress: Value should be the new position of the control. If a Value's first character is a plus sign, the number will be assumed to be an offset from the current position. For example, +10 would increase the position by 10 and +-10 (plus minus ten) would decrease it by 10. If the new position would be outside the range of the control, the control is generally set to the nearest valid value.
Tab/DropDownList/ComboBox/ListBox: Value should contain a pipe-delimited list of items to be appended at the end of the control's list. To replace (overwrite) the list instead, include a pipe as the first character (e.g. |Red|Green|Blue). To make the control empty, specify only a pipe character (|). To have one of the items pre-selected, include two pipes after it (e.g. Red|Green||Blue). The separator between fields may be changed to something other than pipe by using the GUI option +Delimiter. For example, Gui +Delimiter`n would change it to linefeed (`n), and Gui +DelimiterTab would change it to tab (`t).
Tab: In addition to the behavior described in the paragraph above, a tab's sub-controls stay associated with their original tab number; that is, they are never associated with their tab's actual display-name. For this reason, renaming or removing a tab will not change the tab number to which the sub-controls belong. For example, if there are three tabs Red|Green|Blue and the second tab is removed by means of GuiControl,, MyTab, |Red|Blue, the sub-controls originally associated with Green will now be associated with Blue. Because of this behavior, only tabs at the end should generally be removed. Tabs that are removed in this way can be added back later, at which time they will reclaim their original set of controls.
ListView/TreeView: These are not supported when SubCommand is blank. Instead, use the built-in ListView functions and TreeView functions.
Changes the text/caption of a control.
GuiControl, Text, ControlID , Value
Behaves the same as the blank sub-command except for:
CheckBox/Radio: Value is treated as the new text/caption even if it is -1, 0, or 1.
DateTime: Value is treated as the new date/time format displayed by the control. If Value is omitted, any custom format is removed and the short-date format is put into effect.
ComboBox: Value is treated as the text to put directly into the ComboBox's Edit control.
Moves and/or resizes a control.
GuiControl, Move, ControlID, Options
Specify for Options one or more of the following option letters, each followed by a decimal number (not hexadecimal), each separated from the next by zero or more spaces or tabs:
For example, x10 y20 w200 h100. The numbers are in pixels. The coordinates are relative to the window's client area, which is the area not including title bar, menu bar, and borders.
See example #4 for various demonstrations.
Moves and/or resizes a control and repaints the region of the GUI window occupied by the control.
GuiControl, MoveDraw, ControlID , Options
See the Move sub-command for details.
Although this may cause an unwanted flickering effect when called repeatedly and rapidly, it solves painting artifacts for certain control types such as GroupBoxes.
[v1.0.48.04+]: The last parameter may be omitted to redraw the control without moving or resizing it.
Sets keyboard focus to a control.
GuiControl, Focus, ControlID
To be effective, the window generally must not be minimized or hidden.
When a control is focused in response to user input, such as pressing Tab, the dialog manager applies additional effects which are not applied by this sub-command. See ControlFocus for details. AutoHotkey v2 replaces this sub-command with a method which does apply the additional effects.
See example #5 for a demonstration.
Disables (grays out) a control.
GuiControl, Disable, ControlID
For Tab controls, this will also disable all of the tab's sub-controls.
The word Disable may optionally be followed immediately by a 0 or 1. A zero causes the effect to be inverted. For example, Disable and Disable%VarContainingOne% would both disable the control, but Disable%VarContainingZero% would enable it.
Enables a control if it was previously disabled.
GuiControl, Enable, ControlID
For Tab controls, this will also enable all of the tab's sub-controls. However, any sub-control explicitly disabled via the Disable sub-command will remember that setting and thus remain disabled even after its Tab control is re-enabled.
The word Enable may optionally be followed immediately by a 0 or 1. A zero causes the effect to be inverted. For example, Enable and Enable%VarContainingOne% would both enable the control, but Enable%VarContainingZero% would disable it.
Hides a control.
GuiControl, Hide, ControlID
For Tab controls, this will also hide all of the tab's sub-controls.
If you additionally want to prevent a control's shortcut key (underlined letter) from working, disable the control via the Disable sub-command.
The word Hide may optionally be followed immediately by a 0 or 1. A zero causes the effect to be inverted. For example, Hide and Hide%VarContainingOne% would both hide the control, but Hide%VarContainingZero% would show it.
Shows a control if it was previously hidden.
GuiControl, Show, ControlID
For Tab controls, this will also show all of the tab's sub-controls.
The word Show may optionally be followed immediately by a 0 or 1. A zero causes the effect to be inverted. For example, Show and Show%VarContainingOne% would both show the control, but Show%VarContainingZero% would hide it.
Selects an item in a multi-item control (ListBox, DropDownList, ComboBox, or Tab).
GuiControl, Choose, ControlID, N
N should be 1 for the first item, 2 for the second, etc. If N is not an integer, the ChooseString sub-command will be used instead. [v1.1.06+]: If N is zero, the ListBox, DropDownList or ComboBox's current selection is removed.
Unlike Control Choose, this sub-command will not trigger any g-label associated with the control unless N is preceded by a pipe character (even then, the g-label is triggered only when the new selection is different than the old one, at least for Tab controls). For example: GuiControl, Choose, MyListBox, |3.
To additionally cause a finishing event to occur (a double-click in the case of ListBox), include two leading pipes instead of one (this is not supported for Tab controls).
To select or deselect all items in a multi-select ListBox, follow this example:
Gui +LastFound ; Avoids the need to specify WinTitle below.
PostMessage, 0x0185, 1, -1, ListBox1 ; Select all items. 0x0185 is LB_SETSEL.
PostMessage, 0x0185, 0, -1, ListBox1 ; Deselect all items.
GuiControl, Choose, ListBox1, 0 ; Deselect all items, requires [v1.1.06+].
Selects an item in a multi-item control (ListBox, DropDownList, ComboBox, or Tab) by string.
GuiControl, ChooseString, ControlID, String
The search stops at the first item whose text begins with the specified string. In other words, if String matches multiple items, the first one is selected.
The search is not case-sensitive. For example, if a multi-item control contains the item "UNIX Text", specifying the word unix (lowercase) would be enough to select it.
The pipe and double-pipe prefix are also supported (see the Choose sub-command for details).
Applies the window's current font settings to a control.
GuiControl, Font, ControlID
See example #6 for a demonstration.
Adds or removes various control-specific or general options and styles.
GuiControl, +/-Option1 +/-Option2 ..., ControlID , Value
In the following example, the AltSubmit option is enabled but control's g-label is removed:
GuiControl, +AltSubmit -g, MyListBox
In the next example, the OK button is made the new default button:
GuiControl, +Default, OK
All valid options and styles are usually recognized. However, this does not mean that all of them are applied or removed after a control has been created. Some styles cannot be changed retroactively. For positioning and sizing options, use GuiControl Move instead, optionally with GuiControlGet Pos for relative adjustments.
ErrorLevel is set to 0 if at least one of the specified changes was successfully applied. Otherwise, it is set to 1 to indicate that none of the changes could be applied. Even if a change is successfully applied, the control might choose to ignore it.
[v1.1.20+]: To set a function object for handling the control's events, Value must be a single variable reference, as in either of the following examples. Other expressions which return objects are currently unsupported.
GuiControl +g, ControlID, %FuncObj% GuiControl +g, ControlID, % FuncObj
[v1.1.04+]: This command is able to throw an exception on failure. For more information, see Runtime Errors.
ErrorLevel is set to 1 if the specified window/control does not exist or some other problem prevented the command from working. Otherwise, it is set to 0.
This command can only be used with controls in a GUI window, i.e. a window that was created with the Gui command. For non-GUI controls, use Control, ControlFocus, ControlMove, ControlSetText, and so on.
To operate upon a window other than the default, include its name or number (or in [v1.1.03+] its HWND) followed by a colon in front of the sub-command as in these examples:
GuiControl, MyGui:Show, MyButton GuiControl, MyGui:, MyListBox, Item1|Item2
This is required even if ControlID is a control's associated variable, since any one variable can be used on multiple GUI windows. In [v1.1.20+], the GUI name can be omitted if ControlID is a control's HWND.
A GUI thread is defined as any thread launched as a result of a GUI action. GUI actions include selecting an item from a GUI window's menu bar, or triggering one of its g-labels (such as by pressing a button).
The default window name for a GUI thread is that of the window that launched the thread. Non-GUI threads use 1 as their default.
There is no Delete sub-command to delete a control. As a workaround, use the sub-commands Hide and/or Disable, or destroy and recreate the entire window via Gui Destroy.
Gui, GuiControlGet, GUI control types, Control, ControlFocus, ControlMove, ControlSetText
Replaces a ListBox control's current list with a new one using its associated variable.
Gui, Add, ListBox, vMyListBox, Black|White Gui, Show Sleep 1000 ; Wait for demonstration purposes. GuiControl,, MyListBox, |Red|Green|Blue
Puts new text into an Edit control using its ClassNN.
Gui, Add, Edit, r2 w100, Old text line. Gui, Show Sleep 1000 ; Wait for demonstration purposes. GuiControl,, Edit1, New text line 1.`nNew text line 2.
Checks (turns on) a Radio control and unchecks all the others in its group using its associated variable.
Gui, Add, Radio, vMyRadio1 Checked, Radio button 1 Gui, Add, Radio, vMyRadio2, Radio button 2 Gui, Add, Radio, vMyRadio3, Radio button 3 Gui, Show Sleep 1000 ; Wait for demonstration purposes. GuiControl,, MyRadio2, 1
Examples for the Move sub-command.
Moves a Button control to a new position using its text.
Gui, Add, Button,, OK Gui, Show, w300 h300 Sleep 1000 ; Wait for demonstration purposes. GuiControl, Move, OK, x100 y200
Moves and resizes an Edit control relative to its current position and size using its associated variable.
Gui, Add, Edit, vMyEdit Gui, Show, w300 h300 Sleep 1000 ; Wait for demonstration purposes. GuiControlGet, Var, Pos, MyEdit GuiControl, Move, MyEdit, % "x" VarX+10 "y" VarY+5 "w" VarW*2 "h" VarH*1.5
Sets keyboard focus to an Edit control using its associated variable.
Gui, Add, Text, Section, First name: Gui, Add, Text,, Last name: Gui, Add, Edit, ys vFirstName Gui, Add, Edit, vLastName Gui, Show Sleep 1000 ; Wait for demonstration purposes. GuiControl, Focus, LastName
Changes the font and text color of a Text control using its associated variable.
Gui, Font, s14 Gui, Add, Text,, This is a test. Gui, Add, Text, vMyText, This is a test. Gui, Add, Text,, This is a test. Gui, Show Sleep 1000 ; Wait for demonstration purposes. Gui, Font, cRed, Times New Roman ; Set a new default font for the window. GuiControl, Font, MyText ; Put the above font into effect for MyText.