Makes a variety of changes to a control in a GUI window.
GuiControl, SubCommand, ControlID , Value
If the target control has an associated variable, specify the variable's name as the ControlID (this method takes precedence over the ones described next). For this reason, it is usually best to assign a variable to any control that will later be accessed via GuiControl or GuiControlGet, even if that control is not an input-capable type (such as GroupBox or Text).
Otherwise, ControlID can be either ClassNN (the classname and instance number of the control) or the control's text, both of which can be determined via Window Spy. When using text, the matching behavior is determined by SetTitleMatchMode.
Note: A picture control's file name (as it was specified at the time the control was created) may be used as its ControlID.
[v1.1.04+]: ControlID can be the HWND of a control.
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 the control.
GuiControl,, ControlID , Value
Leave SubCommand blank to put new contents into the control via Value. Specifically:
Picture: Value should be the filename (or 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 OutputVar 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 ^ (Ctrl), ! (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 give it a gray checkmark. Otherwise, Value is assumed to be the control's new caption/text. See the Text sub-command below for how to override this behavior.
Radio: Same as Checkbox 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 entries 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 entries pre-selected, include two pipes after it (e.g. Red|Green||Blue). The separator between fields may be changed to something other than pipe. For example, Gui +Delimiter`n would change it to linefeed and Gui +DelimiterTab would change it to tab (`t).
Tab controls: 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 and TreeView: These are not supported when SubCommand is blank. Instead, use the built-in ListView functions and TreeView functions.
Changes the text/caption of the control.
GuiControl, Text, ControlID , Value
Behaves the same as the blank sub-command above 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 the control.
GuiControl, Move, ControlID, Options
Specify one or more of the following option letters in Options: X (the x-coordinate relative to the GUI window's client area, which is the area not including title bar, menu bar, and borders); Y (the y-coordinate), W (Width), H (Height). (Specify each number as decimal, not hexadecimal.) For example:
GuiControl, Move, MyEdit, x10 y20 w200 h100 GuiControl, Move, MyEdit, % "x" VarX+10 "y" VarY+5 "w" VarW*2 "h" VarH*1.5 ; Uses an expression via "% " prefix.
Moves and/or resizes the control and repaints the region of the GUI window occupied by the control.
GuiControl, MoveDraw, ControlID , Options
See the Move sub-command (above) 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 the control.
GuiControl, Focus, ControlID
To be effective, the window generally must not be minimized or hidden.
Disables (grays out) the 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 the control.
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 (above) 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 the 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 the control.
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.
Not yet implemented: This sub-command does not yet exist. As a workaround, use the sub-commands Hide and/or Disable (above), or destroy and recreate the entire window via Gui Destroy.
Sets the selection in a ListBox, DropDownList, ComboBox, or Tab control to be the Nth entry.
GuiControl, Choose, ControlID, N
N should be 1 for the first entry, 2 for the second, etc. If N is not an integer, the ChooseString sub-command (below) 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+].
Sets the selection (choice) in a ListBox, DropDownList, ComboBox, or Tab control to be the entry whose leading part matches String.
GuiControl, ChooseString, ControlID, String
The search is not case sensitive. For example, if a control contains the item "UNIX Text", specifying GuiControl, ChooseString, ControlID, unix would be enough to select it. The pipe and double-pipe prefix are also supported (see the Choose sub-command above for details).
Changes the control's font to the typeface, size, color, and style currently in effect for its window.
GuiControl, Font, ControlID
For example:
Gui, Font, s18 cRed Bold, Verdana ; If desired, use a line like this to set a new default font for the window. GuiControl, Font, MyEdit ; Put the above font into effect for a control.
Add or remove 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
Although styles and extended styles are also recognized, some of them cannot be applied or removed after a control has been created. 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.
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.