Functions to retrieve information about a control, or make a variety of changes to a control.
; General (all control types):
Boolean := ControlGetEnabled(...)
ControlSetEnabled(TrueFalseToggle, ...)
Boolean := ControlGetVisible(...)
ControlHide(...)
ControlShow(...)
Integer := ControlGetHwnd(...)
Integer := ControlGetStyle(...)
ControlSetStyle(Value, ...)
Integer := ControlGetExStyle(...)
ControlSetExStyle(Value, ...)
; Edit:
Integer := ControlGetCurrentCol(...)
Integer := ControlGetCurrentLine(...)
Integer := ControlGetLineCount(...)
String := ControlGetLine(Index, ...)
String := ControlGetSelected(...)
ControlEditPaste(String, ...)
; Checkbox and radio buttons:
Boolean := ControlGetChecked(...)
ControlSetChecked(TrueFalseToggle, ...)
; ListBox and ComboBox:
String := ControlGetChoice(...)
ControlChoose(Index, ...)
ControlChooseString(String, ...)
Index := ControlAddItem(String, ...)
ControlDeleteItem(Index, ...)
Index := ControlFindItem(String, ...)
; ListView, ListBox and ComboBox:
String := ControlGetList(Options, ...)
; ComboBox:
ControlShowDropDown(...)
ControlHideDropDown(...)
; Tab (SysTabControl32):
Integer := ControlGetTab(...)
ControlSetTab(N, ...)
Replace ... with the standard optional parameters:
Control, WinTitle, WinText, ExcludeTitle, ExcludeText
Returns 1 (true) if Control is enabled, or 0 (false) if disabled.
ControlGetEnabled(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
Enables or disables a control.
ControlSetEnabled Value , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
One of the following case-insensitive strings or numbers:
ON or 1 (true) turns on the setting.
OFF or 0 (false) turns off the setting.
TOGGLE or -1 sets it to the opposite of its current state.
See Standard Parameters.
Returns 1 (true) if Control is visible, or 0 (false) if hidden.
ControlGetVisible(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
Hides a control. If you additionally want to prevent a control's shortcut key (underlined letter) from working, disable the control via ControlSetEnabled.
ControlHide Control, WinTitle, WinText, ExcludeTitle, ExcludeText
See Standard Parameters.
Shows a control if it was previously hidden.
ControlShow Control, WinTitle, WinText, ExcludeTitle, ExcludeText
See Standard Parameters.
Retrieves the window handle (HWND) of the specified control.
ControlGetHwnd(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
For example: editHwnd := ControlGetHwnd("Edit1", WinTitle).
A control's HWND is often used with PostMessage, SendMessage, and DllCall. On a related note, a control's HWND can also be retrieved via MouseGetPos. Finally, a control's HWND can be used directly as an ahk_id WinTitle (this also works on hidden controls even when DetectHiddenWindows is Off).
Retrieves an integer representing the style or extended style of the control.
ControlGetStyle(Control, WinTitle, WinText, ExcludeTitle, ExcludeText) ControlGetExStyle(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
See the styles table for a listing of some styles.
Changes the style or extended style of a control, respectively.
ControlSetStyle Value , Control, WinTitle, WinText, ExcludeTitle, ExcludeText ControlSetExStyle Value , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
Pass a positive integer to completely overwrite the window's style; that is, to set it to Value.
To easily add, remove or toggle styles, pass a numeric string prefixed with a plus sign (+), minus sign (-) or caret (^), respectively. The new style value is calculated as shown below (where CurrentStyle could be retrieved with ControlGetStyle/ControlGetExStyle or WinGetStyle/WinGetExStyle):
| Operation | Prefix | Example String | Formula |
|---|---|---|---|
| Add | + | +0x80 | NewStyle := CurrentStyle | Value |
| Remove | - | -0x80 | NewStyle := CurrentStyle & ~Value |
| Toggle | ^ | ^0x80 | NewStyle := CurrentStyle ^ Value |
If Value is a negative integer, it is treated the same as the corresponding numeric string.
To use the + or ^ prefix literally in an expression, the prefix or value must be enclosed in quote marks. For example: WinSetStyle("+0x80") or WinSetStyle("^" StylesToToggle). This is because the expression +123 produces 123 (without a prefix) and ^123 is a syntax error.
See Standard Parameters.
ErrorLevel is set to 1 if the target window/control is not found or the style is not allowed to be applied.
Certain style changes require that the entire window be redrawn using WinRedraw. Also, the styles table lists some of the style numbers. For example:
ControlSetStyle("^0x800000", "Edit1", "WinTitle") ; Set the WS_BORDER style to its opposite state.
Returns 1 (true) if the checkbox or radio button is checked or 0 (false) if not.
ControlGetChecked(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
Turns on (checks) or turns off (unchecks) a radio button or checkbox.
ControlSetChecked Value , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
One of the following case-insensitive strings or numbers:
ON or 1 (true) turns on the setting.
OFF or 0 (false) turns off the setting.
TOGGLE or -1 sets it to the opposite of its current state.
See Standard Parameters.
Returns the column number in an Edit control where the caret (text insertion point) resides.
ControlGetCurrentCol(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
The first column is 1. If there is text selected in the control, the return value is the column number where the selection begins.
Returns the line number in an Edit control where the caret (insert point) resides.
ControlGetCurrentLine(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
The first line is 1. If there is text selected in the control, the return value is the line number where the selection begins.
Returns the number of lines in an Edit control.
ControlGetLineCount(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
All Edit controls have at least 1 line, even if the control is empty.
Returns the text of line N in an Edit control.
ControlGetLine(N , Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
The line number. Line 1 is the first line.
See Standard Parameters.
Depending on the nature of the control, the return value might end in a carriage return (`r) or a carriage return + linefeed (`r`n).
An exception is thrown if N negative or not a number.
For example: line1 := ControlGetLine(1, "Edit1", "ahk_class Notepad")
Returns the selected text in an Edit control.
ControlGetSelected(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
If no text is selected, an empty string is returned and ErrorLevel is set to 0 (i.e. no error). Certain types of controls, such as RichEdit20A, might not produce the correct text in some cases (e.g. Metapad).
Pastes String at the caret/insert position in an Edit control.
ControlEditPaste String , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
The string to paste.
See Standard Parameters.
The effect is similar to pasting by pressing Ctrl+V, but this function does not affect the contents of the clipboard or require the control to have the keyboard focus.
Returns the name of the currently selected entry in a ListBox or ComboBox.
ControlGetChoice(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
To instead retrieve the position of the selected item, follow this example (use only one of the first two lines):
ChoicePos := SendMessage(0x188, 0, 0, "ListBox1", WinTitle) ; 0x188 is LB_GETCURSEL (for a ListBox). ChoicePos := SendMessage(0x147, 0, 0, "ComboBox1", WinTitle) ; 0x147 is CB_GETCURSEL (for a DropDownList or ComboBox). ChoicePos += 1 ; Convert from 0-based to 1-based, i.e. so that the first item is known as 1, not 0. ; ChoicePos is now 0 if there is no item selected.
Sets the selection in a ListBox or ComboBox to be the Nth entry. N should be 1 for the first entry, 2 for the second, etc.
ControlChoose N , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
The index of the item, where 1 is the first entry, 2 is the second, etc.
To deselect all items, specify 0.
See Standard Parameters.
To select all items in a multi-select listbox, follow this example:
PostMessage(0x185, 1, -1, "ListBox1", WinTitle) ; Select all listbox items. 0x185 is LB_SETSEL.
Sets the selection in a ListBox or ComboBox to be the first entry whose leading part matches String.
ControlChooseString String , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
The string to choose (see above). The search is not case sensitive. For example, if a ListBox/ComboBox contains the item "UNIX Text", specifying the word "unix" (lowercase) would be enough to select it.
See Standard Parameters.
Returns the index of the chosen item, where 1 is the first item, 2 is the second, etc. If an error occurred, the return value is blank and ErrorLevel is set to 1.
Adds String as a new entry at the bottom of a ListBox or ComboBox.
N := ControlAddItem(String , Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
Returns the index of the new item, where 1 is the first item, 2 is the second, etc. If an error occurred, the return value is blank and ErrorLevel is set to 1.
Deletes the Nth entry from a ListBox or ComboBox.
ControlDeleteItem N , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
The index of the item, where 1 is the first entry, 2 is the second, etc.
See Standard Parameters.
Returns the entry number of a ListBox or ComboBox that is a complete match for String.
ControlFindItem String , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
The string to find. The search is case-insensitive. Unlike ControlChooseString, the entry's entire text must match, not just the leading part.
See Standard Parameters.
The first entry in the control is 1, the second 2, and so on. If no match is found, the return value is blank and ErrorLevel is set to 1.
Retrieves a list of items from a ListView, ListBox, ComboBox, or DropDownList.
ControlGetList(Options, Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
Specifices what to retrieve if the control is a ListView (see below). For other control types, Options should be blank/empty.
See Standard Parameters.
If the Options parameter is blank or omitted, all the text in the control is retrieved. Each row except the last will end with a linefeed character (`n). Within each row, each field (column) except the last will end with a tab character (`t).
Specify for Options zero or more of the following words, each separated from the next with a space or tab:
Selected: Retrieves only the selected (highlighted) rows rather than all rows. If none, the return value is blank.
Focused: Retrieves only the focused row. If none, the return value is blank.
Col4: Retrieves only the fourth column (field) rather than all columns (replace 4 with a number of your choice).
Count: Retrieves a single number that is the total number of rows in the control.
Count Selected: Retrieves the number of selected (highlighted) rows.
Count Focused: Retrieves the row number (position) of the focused row (0 if none).
Count Col: Retrieves the number of columns in the control (or -1 if the count cannot be determined).
NOTE: Some applications store their ListView text privately, which prevents their text from being retrieved. In these cases, ErrorLevel will usually be set to 0 (indicating success) but all the retrieved fields will be empty.
Upon success, ErrorLevel is set to 0. Upon failure, it is set to 1 and the return value is blank. Failure occurs when: 1) the target window or control does not exist; 2) the target control is not of type SysListView32; 3) the process owning the ListView could not be opened, perhaps due to a lack of user permissions or because it is locked; 4) the ColN option specifies a nonexistent column.
To extract the individual rows and fields out of a ListView, use a parsing loop as in this example:
List := ControlGetList("Selected", "SysListView321", WinTitle)
Loop Parse, List, "`n" ; Rows are delimited by linefeeds (`n).
{
RowNumber := A_Index
Loop Parse, A_LoopField, A_Tab ; Fields (columns) in each row are delimited by tabs (A_Tab).
MsgBox "Row #" RowNumber " Col #" A_Index " is " A_LoopField
}
On a related note, the columns in a ListView can be resized via SendMessage as shown in this example:
SendMessage(4126, 0, 80, "SysListView321", WinTitle) ; 4126 is the message LVM_SETCOLUMNWIDTH. ; In the above, 0 indicates the first column (specify 1 for the second, 2 for the third, etc.) Also, 80 is the new width. ; Replace 80 with -1 to autosize the column. Replace it with -2 to do the same but also take into account the header text width.
All the text is retrieved from the control (that is, the ListView options above such as Count and Selected are not supported).
Each row except the last will be terminated by a linefeed character (`n). To access the items individually, use a parsing loop as in this example:
List := ControlGetList("", "ComboBox1", WinTitle)
Loop Parse, List, "`n"
MsgBox "Item number " A_Index " is " A_LoopField
Drops a ComboBox so that its choices become visible.
ControlShowDropDown Control, WinTitle, WinText, ExcludeTitle, ExcludeText
See Standard Parameters.
Example:
Send "#r" ; Display the Run dialog.
WinWaitActive "ahk_class #32770" ; Wait for the dialog to appear.
ControlShowDropDown "ComboBox1" ; Show the DropDown list. The second parameter is omitted so that the last found window is used.
Sleep 2000
ControlHideDropDown "ComboBox1" ; Hide the DropDown list.
Sleep 1000
Send "{Esc}" ; Hide the dialog window.
Reverses the above.
ControlHideDropDown Control, WinTitle, WinText, ExcludeTitle, ExcludeText
See Standard Parameters.
Returns the position number of the selected tab in a SysTabControl32.
ControlGetTab(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
See Standard Parameters.
The first tab is 1, the second is 2, etc. If no tab is selected (rare), the return value is 0.
To instead discover how many tabs (pages) exist in a tab control, follow this example:
TabCount := SendMessage(0x1304,,, "SysTabControl321", WinTitle) ; 0x1304 is TCM_GETITEMCOUNT.
Example:
WhichTab := ControlGetTab("SysTabControl321", "Some Window Title")
if ErrorLevel
MsgBox("There was a problem.")
else
MsgBox("Tab #" WhichTab " is active.")
Selects the Nth tab in a SysTabControl32.
ControlSetTab N , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
See Standard Parameters.
All of the functions on this page utilize the following parameters to identify the target control and window:
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. If this parameter is blank, the target window's topmost control will be used.
To operate upon a control's HWND (window handle), leave the Control parameter blank and specify "ahk_id " ControlHwnd for the WinTitle parameter (this also works on hidden controls even when DetectHiddenWindows is Off). The HWND of a control is typically retrieved via ControlGetHwnd, MouseGetPos, or DllCall.
A window title or other criteria identifying the target window. See WinTitle.
If present, this parameter must be a substring from a single text element of the target window (as revealed by the included Window Spy utility). Hidden text elements are detected if DetectHiddenText is ON.
Windows whose titles include this value will not be considered.
Windows whose text include this value will not be considered.
ErrorLevel is set to 1 if there was a problem or 0 otherwise. Unless specified otherwise, each function also returns 1 (true) to indicate success or 0 (false) to indicate failure.
An exception is thrown if invalid parameters are detected.
To improve reliability, a delay is done automatically after each use of a Control function that changes a control (except for ControlSetStyle and ControlSetExStyle). That delay can be changed via SetControlDelay or by assigning a value to A_ControlDelay. For details, see SetControlDelay remarks.
To discover the ClassNN or HWND of the control that the mouse is currently hovering over, use MouseGetPos.
Window titles and text are case sensitive. Hidden windows are not detected unless DetectHiddenWindows has been turned on.
SetControlDelay, WinSet functions, WinGet functions, GuiControl object (for controls created by the script)
Other Control functions: ControlGetFocus, ControlFocus, ControlGetPos, ControlMove, ControlGetText, ControlSetText, ControlClick, ControlSend