class Gui.Control extends Object
Provides an interface for modifying GUI controls and retrieving information about them. Gui.Add, Gui.__Item and GuiCtrlFromHwnd return an object of this type.
"GuiCtrl" is used below as a placeholder for instances of the Gui.Control class.
Gui.Control serves as the base class for all GUI controls, but each type of control has its own class. Some of the following methods are defined by the prototype of the appropriate class, or the Gui.List base class. See Built-in Classes for a full list.
In addition to the methods and properties inherited from Object, GuiControl objects may have the following predefined methods and properties.
Appends new items to a multi-item control (ListBox, DropDownList, ComboBox, or Tab).
GuiCtrl.Add(Items)
Type: Array
An array of strings to be inserted as items at the end of the control's list. For example, ["Red", "Green", "Blue"].
To replace (overwrite) the list instead, use GuiControl.Delete beforehand.
To add new items to a ListView or TreeView control, use LV.Add or TV.Add.
See example #1 for a demonstration.
Selects an item in a multi-item control (ListBox, DropDownList, ComboBox, or Tab).
GuiCtrl.Choose(Item)
Specify 1 for the first item, 2 for the second, and so on. Specify 0 to deselect all items.
If a string is specified (even a numeric string), the item whose name starts with the string will be 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. For a multi-select ListBox, all matching items are selected.
To select all items in a multi-select ListBox, use PostMessage(0x0185, 1, -1, GuiCtrl), where 0x0185 is LB_SETSEL. As an alternative, call this method for each item in the array returned by ControlGetItems:
for index, text in ControlGetItems(GuiCtrl)
GuiCtrl.Choose(index)
Unlike ControlChooseIndex, this method does not raise a Change or DoubleClick event.
To select an item in a ListView or TreeView control, use LV.Modify or TV.Modify with the Select option.
Deletes one or all items from a multi-item control (ListBox, DropDownList, ComboBox, or Tab).
GuiCtrl.Delete(Item)
Type: Integer
If omitted, all items will be deleted. Otherwise, specify 1 for the first item, 2 for the second, etc.
For Tab controls, 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 GuiCtrl.Delete(2), 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.
To delete an item in a ListView or TreeView control, use LV.Delete or TV.Delete.
See example #1 for a demonstration.
Sets keyboard focus to a control.
GuiCtrl.Focus()
To be effective, the window generally must not be minimized or hidden.
To get the currently focused control in a GUI window, use Gui.FocusedCtrl.
To get whether a control has keyboard focus, use GuiControl.Focused.
See example #6 for a demonstration.
Retrieves the position and size of a control.
GuiCtrl.GetPos(&X, &Y, &Width, &Height)
Type: VarRef
If omitted, the corresponding value will not be stored. Otherwise, specify references to the output variables in which to store the X and Y coordinates (in pixels) of the control's upper left corner. These coordinates are relative to the upper-left corner of the window's client area, which is the area not including title bar, menu bar, and borders.
Type: VarRef
If omitted, the corresponding value will not be stored. Otherwise, specify references to the output variables in which to store the control's width and height (in pixels).
Unlike ControlGetPos, this method applies DPI scaling to the returned coordinates (unless the -DPIScale option was used).
See example #5 or example #10 for a demonstration.
Moves and/or resizes a control.
GuiCtrl.Move(X, Y, Width, Height)
Type: Integer
If either is omitted, the control's position in that dimension will not be changed. Otherwise, specify the X and Y coordinates (in pixels) of the upper left corner of the control's new location. The coordinates are relative to the upper-left corner of the window's client area, which is the area not including title bar, menu bar, and borders.
Type: Integer
If either is omitted, the control's size in that dimension will not be changed. Otherwise, specify the new width and height of the control (in pixels).
Unlike ControlMove, this method applies DPI scaling to the coordinates (unless the -DPIScale option was used).
See example #4 or example #5 for a demonstration.
Registers a function or method to be called when a control notification is received via the WM_COMMAND message.
GuiCtrl.OnCommand(NotifyCode, Callback , AddRemove)
See OnCommand for details.
Registers a function or method to be called when the given event is raised.
GuiCtrl.OnEvent(EventName, Callback , AddRemove)
See OnEvent for details.
Registers a function or method to be called when a control notification is received via the WM_NOTIFY message.
GuiCtrl.OnNotify(NotifyCode, Callback , AddRemove)
See OnNotify for details.
Adds or removes various options and styles.
GuiCtrl.Opt(Options)
Type: String
Specify one or more control-specific or general options and styles, each separated from the next with one or more spaces or tabs.
For example, "+Disabled -Background" would both disable a control and restore its background to the system default, while "+Default" would make a button the new default button.
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 GuiControl.GetPos for relative adjustments.
If a change could not be applied, an exception is thrown. Even if a change is successfully applied, the control might choose to ignore it.
Redraws the region of the GUI window occupied by a control.
GuiCtrl.Redraw()
Although this may cause an unwanted flickering effect when called repeatedly and rapidly, it solves display artifacts for certain control types such as GroupBoxes.
When adding a large number of items to a control (such as a ListView, TreeView or ListBox), performance can be improved by preventing the control from being redrawn while the changes are being made. This is done by using GuiCtrl.Opt("-Redraw") before adding the items and GuiCtrl.Opt("+Redraw") afterward. Changes to the control which have not yet become visible prior to disabling redraw will generally not become visible until after redraw is re-enabled.
For performance reasons, changes to a control's content generally do not cause the control to be immediately redrawn even if redraw is enabled. Instead, a portion of the control is "invalidated" and is usually repainted after a brief delay, when the program checks its internal message queue. The script can force this to take place immediately by calling Sleep -1.
Changes a control's font typeface, size, color, and/or style.
GuiCtrl.SetFont(Options, FontName)
Omit both parameters to set the font to the GUI's current font, as set by Gui.SetFont. Otherwise, any font attributes which are not specified will be copied from the control's previous font. Text color is changed only if specified in Options.
For details about both parameters, see Gui.SetFont.
See example #7 for a demonstration.
Gets or sets whether a control is enabled.
IsEnabled := GuiCtrl.Enabled
GuiCtrl.Enabled := NewState
IsEnabled is 1 if the control is enabled, or 0 if disabled. The Disabled option affects the initial setting.
NewState should be a boolean value. If true, the control is enabled. If false, the control is disabled.
For Tab controls, this will also enable or disable all of the tab's sub-controls. However, any sub-control explicitly disabled via GuiCtrl.Enabled := false will remember that setting and thus remain disabled even after its Tab control is re-enabled.
Gets whether a control has keyboard focus.
IsFocused := GuiCtrl.Focused
IsFocused is 1 if the control has keyboard focus, or 0 if not.
To be effective, the window generally must not be minimized or hidden.
To get the currently focused control in a GUI window, use Gui.FocusedCtrl.
To focus a control, use GuiControl.Focus.
Gets the parent window of a control.
GuiObj := GuiCtrl.Gui
GuiObj is the Gui object of the parent window.
Gets or sets the explicit name of a control.
CurrentName := GuiCtrl.Name
GuiCtrl.Name := NewName
CurrentName is the control's current name, or an empty string if it has no name. The V option affects the initial setting.
NewName is the control's new name.
This name can be used with Gui.__Item to retrieve the corresponding GuiControl object. For most input-capable controls, the name is also used by Gui.Submit.
Gets or sets the text/caption of a control.
CurrentText := GuiCtrl.Text
GuiCtrl.Text := NewText
CurrentText and NewText depend on the current control. If the control has no visible caption text and no (single) text value, such as MonthCal, this property corresponds to the control's hidden caption text (similar to ControlGetText and ControlSetText). See example #9 for a demonstration.
CurrentText and NewText are the current and new caption/display text, respectively. Since the control will not expand automatically, use GuiControl.Move if the control needs to be widened.
CurrentText is the current formatted text displayed by the control. NewText is invalid and throws an exception. To change the date/time being displayed, use GuiControl.Value to set a date-time stamp in YYYYMMDDHH24MISS format.
CurrentText is the text of the currently selected item or tab, or blank if none is selected. For a ComboBox, if no item is selected, it is the text in the edit field. For a multi-select ListBox, it is an array containing the text of each selected item, or blank if none is selected.
NewText is the full text (case-insensitive) of the item or tab to select, or blank to clear the current selection. For a multi-select ListBox, all items that fully match the text are selected. To select multiple items with different text, call GuiControl.Choose repeatedly. GuiControl.Value selects an item or tab by index.
CurrentText and NewText are the current and new text, respectively. As with other controls, the text is retrieved or set as-is; no end-of-line translation is performed. To get or set the text of a multi-line Edit control while also translating between CR+LF (`r`n) and LF (`n), use GuiControl.Value.
CurrentText and NewText are the current and new text of the first part, respectively. Use StatusBar.SetText for greater flexibility.
Gets the type of a control.
CurrentType := GuiCtrl.Type
CurrentType is one of the following strings, depending on the control type: ActiveX, Button, CheckBox, ComboBox, Custom, DateTime, DDL, Edit, GroupBox, Hotkey, Link, ListBox, ListView, MonthCal, Pic, Progress, Radio, Slider, StatusBar, Tab, Tab2, Tab3, Text, TreeView, UpDown.
Gets or sets the contents of a value-capable control.
CurrentValue := GuiCtrl.Value
GuiCtrl.Value := NewValue
CurrentValue and NewValue depend on the current control. If the control is not value-capable, CurrentValue will be blank and assigning NewValue will raise an error. Invalid values throw an exception. See example #2, example #3, example #8, or example #9 for a demonstration.
CurrentValue is the ActiveX object. For example, if the control was created with the component name "Shell.Explorer", this is a WebBrowser object. The same wrapper object is returned each time. NewValue is invalid and throws an exception.
CurrentValue and NewValue are the current and new setting, respectively: 1 for checked, 0 for unchecked, or -1 for indeterminate. For radio buttons, if one 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 get or set the control's text/caption instead, use GuiControl.Text.
CurrentValue is the index of the currently selected item or tab, or 0 if none is selected. For a ComboBox, if text is entered, it is the index of the first item that fully matches the text (case-insensitive), or 0 if there is no match. For a multi-select ListBox, it is an array containing the index of each selected item, or an empty array if none is selected.
NewValue is the index of an item or tab to select, or 0 to clear the current selection (this is valid even for Tab controls). For a multi-select ListBox, to select multiple items, call GuiControl.Choose repeatedly. GuiControl.Text selects an item or tab by text.
CurrentValue and NewValue are date-time stamps in YYYYMMDDHH24MISS format representing the date/time currently selected and to be selected in the control, respectively. Specify A_Now for NewValue to use the current date and time (today). For DateTime controls, NewValue can be blank 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.
CurrentValue is the current content. For multi-line controls, any line breaks will be represented as plain linefeeds (`n) rather than the traditional CR+LF (`r`n) used by non-GUI functions such as ControlGetText and ControlSetText.
NewValue is the new content. For multi-line controls, any linefeeds (`n) 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 when using Gui.Submit or when retrieving this value this translation will be reversed automatically by replacing CR+LF (`r`n) with LF (`n).
To get or set the text without translating LF (`n) to or from CR+LF (`r`n), use GuiControl.Text.
CurrentValue and NewValue are strings composed of modifiers and a key name, representing the hotkey currently displayed and to be displayed in the control, respectively. For example, ^!c, ^Numpad1, or +Home. CurrentValue is blank if there is no hotkey in the control. NewValue can be blank to clear the control. The only modifiers supported are ^ (Control), ! (Alt), and + (Shift). See the key list for available key names.
CurrentValue is the picture's file name as it was originally specified when the control was created. This name does not change even if a new picture file name is specified.
NewValue is the filename or a handle of the new image to load (see 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). For example, "*icon2 *w100 *h-1 C:\My Application.exe" loads the default icon from the second icon group with a width of 100 and an automatic height via "keep aspect ratio". 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.
CurrentValue and NewValue are the current and new position of the control, respectively. If the new position would be outside the range of the control, the control is generally set to the nearest valid value.
CurrentValue and NewValue are the current and new text/caption, respectively. Since the control will not expand automatically, use GuiControl.Move if the control needs to be widened.
Gets or sets whether a control is visible.
IsVisible := GuiCtrl.Visible
GuiCtrl.Visible := NewState
IsVisible is 1 if the control is visible, or 0 if hidden. The Hidden option affects the initial setting.
NewState should be a boolean value. If true, the control is visible. If false, the control is hidden.
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 GuiCtrl.Enabled := false.
Each method and property listed here can only be used with controls in a GUI window, i.e. a window that was created with the Gui function. For non-GUI controls, use the Control functions instead.
GUI control types, Gui object, GuiCtrlFromHwnd, Control functions
Replaces a ListBox control's current list with a new one using GuiControl.Delete and GuiControl.Add.
MyGui := Gui()
MyListBox := MyGui.Add("ListBox",, ["Black", "White"])
MyGui.Show()
Sleep 1000 ; Wait for demonstration purposes.
MyListBox.Delete()
MyListBox.Add(["Red", "Green", "Blue"])
Puts new text into an Edit control using GuiControl.Value.
MyGui := Gui()
MyEdit := MyGui.Add("Edit", "r2 w100", "Old text line.")
MyGui.Show()
Sleep 1000 ; Wait for demonstration purposes.
MyEdit.Value := "New text line 1.`nNew text line 2."
Checks (turns on) a Radio control and unchecks all the others in its group using GuiControl.Value.
MyGui := Gui()
MyRadio1 := MyGui.Add("Radio", "Checked", "Radio button 1")
MyRadio2 := MyGui.Add("Radio",, "Radio button 2")
MyRadio3 := MyGui.Add("Radio",, "Radio button 3")
MyGui.Show()
Sleep 1000 ; Wait for demonstration purposes.
MyRadio2.Value := 1
Moves a Button control to a new position using GuiControl.Move.
MyGui := Gui()
MyButton := MyGui.Add("Button",, "OK")
MyGui.Show("w300 h300")
Sleep 1000 ; Wait for demonstration purposes.
MyButton.Move(100, 200)
Moves and resizes an Edit control relative to its current position and size using GuiControl.GetPos and GuiControl.Move.
MyGui := Gui()
MyEdit := MyGui.Add("Edit")
MyGui.Show("w300 h300")
Sleep 1000 ; Wait for demonstration purposes.
MyEdit.GetPos(&X, &Y, &W, &H)
MyEdit.Move(X+10, Y+5, W*2, H*1.5)
Sets keyboard focus to an Edit control using GuiControl.Focus.
MyGui := Gui()
MyGui.Add("Text", "Section", "First name:")
MyGui.Add("Text",, "Last name:")
EditFirstName := MyGui.Add("Edit", "ys")
EditLastName := MyGui.Add("Edit")
MyGui.Show()
Sleep 1000 ; Wait for demonstration purposes.
EditLastName.Focus()
Changes the font and text color of a Text control using GuiControl.SetFont.
MyGui := Gui()
MyGui.SetFont("s14")
MyGui.Add("Text",, "This is a test.")
MyText := MyGui.Add("Text",, "This is a test.")
MyGui.Add("Text",, "This is a test.")
MyGui.Show()
Sleep 1000 ; Wait for demonstration purposes.
MyText.SetFont("cRed", "Times New Roman")
Retrieves the text of an Edit control by using GuiControl.Value.
MyGui := Gui()
MyEdit := MyGui.Add("Edit",, "This is a test.")
MyGui.Show()
MsgBox MyEdit.Value
Reports the caption and current state of a CheckBox control when clicked.
MyGui := Gui()
MyCheckBox1 := MyGui.Add("CheckBox",, "CheckBox 1")
MyCheckBox2 := MyGui.Add("CheckBox",, "CheckBox 2")
MyCheckBox1.OnEvent("Click", ReportState)
MyCheckBox2.OnEvent("Click", ReportState)
MyGui.Show()
ReportState(MyCheckBox, *)
{
Caption := MyCheckBox.Text
State := MyCheckBox.Value
MsgBox Caption " is " (State = 0 ? "unchecked" : "checked")
}
Retrieves the position and size of a Picture control by using GuiControl.GetPos and stores the values in the X, Y, W, and H variables.
MyGui := Gui()
MyPicture := MyGui.Add("Picture",, A_AhkPath)
MyGui.Show()
MyPicture.GetPos(&X, &Y, &W, &H)
MsgBox "x" X ", y" Y ", w" W ", h" H