GuiControl

Makes a variety of changes to a control in a GUI window.

GuiControl, Sub-command, ControlID [, Param3]

Parameters

Sub-command

See list below.

ControlID

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

Param3

This parameter is omitted except where noted in the list of sub-commands below.

ErrorLevel

[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.

Sub-commands

(Blank): Leave Sub-command blank to put new contents into the control via Param3. Specifically:

Picture: Param3 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 Param3 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 Param3 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: Param3 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: Param3 can be 0 to uncheck the button, 1 to check it, or -1 to give it a gray checkmark. Otherwise, Param3 is assumed to be the control's new caption/text. See Text 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 Param3 a date-time stamp in YYYYMMDDHH24MISS format. Specify %A_Now% to use the current date and time (today). For DateTime controls, Param3 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: Param3 should be the new position of the control. If a Param3'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: Param3 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 Sub-command is blank. Instead, use the built-in ListView functions and TreeView functions.

GuiControl, Text: Behaves the same as the above except for:
Checkbox/Radio: Param3 is treated as the new text/caption even if it is -1, 0, or 1.
DateTime: Param3 is treated as the new date/time format displayed by the control. If Param3 is omitted, any custom format is removed and the short-date format is put into effect.
ComboBox: Param3 is treated as the text to put directly into the ComboBox's Edit control.

GuiControl, Move: Moves and/or resizes the control. Specify one or more of the following option letters in Param3: 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.

GuiControl, MoveDraw: Same as "Move" (above) except that it also repaints the region of the GUI window occupied by the control. 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 it.

GuiControl, Focus: Sets keyboard focus to the control. To be effective, the window generally must not be minimized or hidden.

GuiControl, Enable / Disable: Enables or disables (grays out) the control. For Tab controls, this will also enable or disable all of the tab's sub-controls. However, any sub-control explicitly disabled via GuiControl Disable will remember that setting and thus remain disabled even after its Tab control is re-enabled. The word Disable or 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.

GuiControl, Hide / Show: Hides or shows the control. For Tab controls, this will also show or 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 GuiControl Disable. The word Hide or 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.

GuiControl, Delete (not yet implemented): This sub-command does not yet exist. As a workaround, use Hide and/or Disable (above), or destroy and recreate the entire window via Gui Destroy.

GuiControl, Choose, ControlID, N: Sets the selection in a ListBox, DropDownList, ComboBox, or Tab control to be the Nth entry. N should be 1 for the first entry, 2 for the second, etc. If N is not an integer, the ChooseString method described 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, 0x185, 1, -1, ListBox1  ; Select all items. 0x185 is LB_SETSEL.
PostMessage, 0x185, 0, -1, ListBox1  ; Deselect all items.
GuiControl, Choose, ListBox1, 0  ; Deselect all items [requires v1.1.06+].

GuiControl, ChooseString, ControlID, String: Sets the selection (choice) in a ListBox, DropDownList, ComboBox, or Tab control to be the entry whose leading part matches String. The search is not case sensitive. For example, if a the 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 "Choose" above for details).

GuiControl, Font: Changes the control's font to the typeface, size, color, and style currently in effect for its window. 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.

GuiControl, +/-Option1 +/-Option2 ...: Add or remove various control-specific or general options and styles.

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, Param3 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

Remarks

To operate upon a window other than the default (see below), include its name or number 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.

Related

Gui, GuiControlGet, Control

Examples

GuiControl,, MyListBox, |Red|Green|Blue  ; Replace the current list with a new list.
GuiControl,, MyEdit, New text line 1.`nNew text line 2.
GuiControl,, MyRadio2, 1  ; Turn on this radio button and turn off all the others in its group.
GuiControl, Move, OK, x100 y200  ; Move the OK button to a new location.
GuiControl, Focus, LastName  ; Set keyboard focus to the control whose variable or text is "LastName".