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 property inherited from Object, GuiControl objects may have the following predefined methods and properties.
Appends 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, e.g. ["Red", "Green", "Blue"].
To replace (overwrite) the list instead, use the Delete method beforehand. To select an item, use the Choose method.
Selects an item in a multi-item control (ListBox, DropDownList, ComboBox, or Tab).
GuiCtrl.Choose(Value)
Specify 1 for the first item, 2 for the second, etc.
If Value is a string (even a numeric string), the item whose leading name part matches Value will be selected. The search is not case-sensitive. For example, if the 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.
If Value is zero or empty, the current selection is removed.
To select or deselect all items in a multi-select ListBox, follow this example:
PostMessage 0x0185, 1, -1, ListBox ; Select all items. 0x0185 is LB_SETSEL. PostMessage 0x0185, 0, -1, ListBox ; Deselect all items. ListBox.Choose(0) ; Deselect all items.
Unlike ControlChooseIndex, this method does not raise a Change or DoubleClick event.
Deletes one or all items from a multi-item control (ListBox, DropDownList, ComboBox, or Tab).
GuiCtrl.Delete(Value)
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 MyTab.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.
Sets keyboard focus to the control.
GuiCtrl.Focus()
To be effective, the window generally must not be minimized or hidden.
To retrieve the focus state of the control, use the Focused property.
Retrieves the position and size of the 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).
MyEdit.GetPos(&x, &y, &w, &h) MsgBox "The X coordinate is " x ". The Y coordinate is " y ". The width is " w ". The height is " h "."
Moves and/or resizes the 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).
MyEdit.Move(10, 20, 200, 100) MyEdit.Move(VarX+10, VarY+5, VarW*2, VarH*1.5)
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.
Sets various options and styles for the appearance and behavior of the control.
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.
In the following example, the control is disabled and its background is restored to the system default:
MyEdit.Opt("+Disabled -Background")
In the next example, the OK button is made the new default button:
OKButton.Opt("+Default")
Although styles and extended styles are also recognized, some of them cannot be applied or removed after a control has been created. Even if a change is successfully applied, the control might choose to ignore it.
Redraws the region of the GUI window occupied by the 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.
Sets the font typeface, size, style, and/or color for the control.
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.
Retrieves the class name and sequence number (ClassNN) of the control.
ClassNN := GuiCtrl.ClassNN
A control's ClassNN is the name of its window class followed by its sequence number within the top-level window which contains it. For example, "Edit1" is the first Edit control on a window and "Button12" is the twelth button.
Related: ControlGetClassNN
Retrieves or sets the interaction state of the control.
CurrentSetting := GuiCtrl.Enabled
GuiCtrl.Enabled := NewSetting
CurrentSetting is NewSetting if assigned, otherwise 1 (true) by default unless overwritten by the Disabled option.
NewSetting is a boolean value that enables or disables this setting. 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.
Retrieves the focus state of the control.
IsFocused := GuiCtrl.Focused
IsFocused is 1 (true) if the control has the keyboard focus, otherwise 0 (false).
To be effective, the window generally must not be minimized or hidden.
To focus the control, use the Focus method.
Retrieves the window handle (HWND) of the control.
Hwnd := GuiCtrl.Hwnd
A control's HWND is often used with PostMessage, SendMessage, and DllCall. It can also be used directly in a Control parameter.
Retrieves or sets the explicit name of the control.
CurrentName := GuiCtrl.Name
GuiCtrl.Name := NewName
CurrentName is NewName if assigned, otherwise an empty string by default unless overwritten by the V option.
NewName is the control's new name, which can be used with Gui.__Item to retrieve the GuiControl object. For most input-capable controls, the name is also used by Gui.Submit.
Retrieves or sets the text/caption of the control.
CurrentText := GuiCtrl.Text
GuiCtrl.Text := NewText
Note: If the control has no visible caption text and no (single) text value, this property corresponds to the control's hidden caption text (like ControlGetText/ControlSetText).
CurrentText and NewText depend on the control type:
Button / CheckBox / Edit / GroupBox / Link / Radio / Text
CurrentText and NewText are the caption/display text of the Button, CheckBox, Edit, GroupBox, Link, Radio or Text control. Since the control will not expand automatically, use GuiCtrl.Move(,, 300) or similar if the control needs to be widened.
DateTime
CurrentText and NewText are the formatted text displayed by the DateTime control. Assigning a formatted date/time string to the control is not supported. To change the date/time being displayed, assign the Value property a date-time stamp in YYYYMMDDHH24MISS format.
DropDownList / ComboBox / ListBox / Tab
CurrentText and NewText are the text of the currently selected item/tab of the DropDownList, ComboBox, ListBox or Tab control.
NewText should be the full text (case-insensitive) of the item/tab to select.
For a ComboBox, if there is no selected item, the text in the control's edit field is retrieved instead. For other controls, CurrentText is empty/blank. Similarly, if NewText is empty/blank, the current item/tab will be deselected.
For a multi-select ListBox, CurrentText is an array. NewText cannot be an array, but if multiple items match, they are all selected. To select multiple items with different text, call the Choose method repeatedly.
To select an item by its position number instead of its text, use the Value property.
Edit
CurrentText and NewText are the text of the Edit control. As with other controls, the text is retrieved or set as-is; no end-of-line translation is performed. To retrieve or set the text of a multi-line Edit control while also translating between `r`n and `n, use the Value property.
StatusBar
CurrentText and NewText are the text of the StatusBar control's first part only (use SB.SetText for greater flexibility).
Retrieves the type of the control.
CurrentType := GuiCtrl.Type
Depending on the control type, CurrentType is one of the following strings: 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.
Retrieves or sets the contents of a value-capable control.
CurrentValue := GuiCtrl.Value
GuiCtrl.Value := NewValue
Note: If the control is not value-capable, CurrentValue will be blank and assigning NewValue will raise an error. Invalid values throw an exception.
CurrentValue and NewValue depend on the control type:
ActiveX
CurrentValue is the ActiveX object of the ActiveX control. For example, if the control was created with the text Shell.Explorer, this is a WebBrowser object. The same wrapper object is returned each time.
NewValue is invalid and throws an exception.
CheckBox / Radio
CurrentValue is 1 if the CheckBox or Radio control is checked, 0 if it is unchecked, or -1 if it has a gray checkmark.
NewValue can be 0 to uncheck the button, 1 to check it, or -1 to give it a gray checkmark. 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 control's text/caption instead, use the Text property.
ComboBox / DropDownList / ListBox / Tab
CurrentValue is the position number of the currently selected item/tab in the ComboBox, DropDownList, ListBox or Tab control. If none is selected, zero is returned. If text is entered into a ComboBox, the first item with matching text is used. If there is no matching item, the result is zero even if there is text in the control. For a multi-select ListBox, the result is an array of numbers (which is empty if no items are selected).
NewValue is the position number of a single item/tab to select, or zero to clear the current selection (this is valid even for Tab controls). To select multiple items, call the Choose method repeatedly.
To get or set the selected item given its text instead of its position, use the Text property.
DateTime / MonthCal
CurrentValue is a date-time stamp in YYYYMMDDHH24MISS format currently selected in the DateTime or MonthCal control.
NewValue is a date-time stamp in YYYYMMDDHH24MISS format. Specify A_Now to use the current date and time (today). For DateTime controls, NewValue may be an empty string 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.
Edit
CurrentValue is the current content of the Edit control. For multi-line controls, any line breaks in the text 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) in NewValue 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 with LF (`n).
To retrieve or set the text without translating `n to or from `r`n, use the Text property.
Hotkey
CurrentValue is the modifiers and key name if there is a hotkey in the Hotkey control; otherwise blank. Examples: ^!C, ^Home, +^NumpadHome.
NewValue can be a set of modifiers with a key name, or blank to clear the control. Examples: ^!c, ^Numpad1, +Home. The only modifiers supported are ^ (Control), ! (Alt), and + (Shift). See the key list for available key names.
Picture
CurrentValue is the picture's file name as it was originally specified when the Picture control was created. This name does not change even if a new picture file name is specified.
NewValue is the filename (or 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). 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": MyPic.Value := "*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.
Progress / Slider / UpDown
CurrentValue is the current position of the Progress, Slider or UpDown control.
NewValue is the new position of the control, for example MySlider.Value := 10. To adjust the value by a relative amount, use the operators +=, -=, ++ or -- instead of :=. If the new position would be outside the range of the control, the control is generally set to the nearest valid value.
Text
CurrentValue is the text/caption of the Text control.
NewValue is the control's new text. Since the control will not expand automatically, use GuiCtrl.Move(,, 300) if the control needs to be widened.
Retrieves or sets the visibility state of the control.
CurrentSetting := GuiCtrl.Visible
GuiCtrl.Visible := NewSetting
CurrentSetting is NewSetting if assigned, otherwise 1 (true) by default unless overwritten by the Hidden option.
NewSetting is a boolean value that enables or disables this setting. 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.
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.