ControlGet

Retrieves various types of information about a control.

ControlGet, OutputVar, Cmd [, Value, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]

Parameters

OutputVar	The name of the variable in which to store the result of Cmd.
Cmd, Value	See list below.
Control	Can be either ClassNN (the classname and instance number of the control) or the name/text of the control, both of which can be determined via Window Spy. When using name/text, the matching behavior is determined by SetTitleMatchMode. If this parameter is blank, the target window's topmost control will be used.
WinTitle	The title or partial title of the target window (the matching behavior is determined by SetTitleMatchMode). If this and the next 3 parameters are omitted, the Last Found Window will be used. If this is the letter A and the next 3 parameters are omitted, the active window will be used. To use a window class, specify ahk_class ExactClassName (shown by Window Spy). To use a process identifier (PID), specify ahk_pid %VarContainingPID%. To use a window group, specify ahk_group GroupName. To use a window's unique ID number, specify ahk_id %VarContainingID%. The search can be narrowed by specifying multiple criteria. For example: My File.txt ahk_class Notepad
WinText	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.
ExcludeTitle	Windows whose titles include this value will not be considered.
ExcludeText	Windows whose text include this value will not be considered.

Cmd, Value

The Cmd and Value parameters are dependent upon each other and their usage is described below.

List: Retrieves a list of items from a ListView, ListBox, ComboBox, or DropDownList.

ListView [v1.0.37+]: The most common example of a ListView is Explorer's list of files and folders (the desktop is also a ListView). The syntax for ListView retrieval is:

ControlGet, OutputVar, List, Options, SysListView321, WinTitle, WinText

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, OutputVar is made blank.
Focused: Retrieves only the focused row. If none, OutputVar is made 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. Also note that ListView text retrieval is not restricted by #MaxMem.

Upon success, ErrorLevel is set to 0. Upon failure, it is set to 1 and OutputVar is made 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:

ControlGet, List, List, 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.

ListBox, ComboBox, DropDownList [v1.0.25.09+]: 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:

ControlGet, List, List,, ComboBox1, WinTitle
Loop, Parse, List, `n
	MsgBox Item number %A_Index% is %A_LoopField%.

Checked: Sets OutputVar to be 1 if the checkbox or radio button is checked or 0 if not.

Enabled: Sets OutputVar to be 1 if Control is enabled, or 0 if disabled.

Visible: Sets OutputVar to be 1 if Control is visible, or 0 if hidden.

Tab: Sets OutputVar to the tab number of a SysTabControl32 control. The first tab is 1, the second is 2, etc. To instead discover how many tabs (pages) exist in a tab control, follow this example:
SendMessage, 0x1304,,, SysTabControl321, WinTitle ; 0x1304 is TCM_GETITEMCOUNT.
TabCount = %ErrorLevel%

FindString, String: Sets OutputVar to the entry number of a ListBox or ComboBox that is an exact match for String. The first entry in the control is 1, the second 2, and so on. If no match is found, OutputVar is made blank and ErrorLevel is set to 1.

Choice: Sets OutputVar to be the name of the currently selected entry in a ListBox or ComboBox. To instead retrieve the position of the selected item, follow this example (use only one of the first two lines):
SendMessage, 0x188, 0, 0, ListBox1, WinTitle ; 0x188 is LB_GETCURSEL (for a ListBox).
SendMessage, 0x147, 0, 0, ComboBox1, WinTitle ; 0x147 is CB_GETCURSEL (for a DropDownList or ComboBox).
ChoicePos = %ErrorLevel% ; It will be -1 if there is no item selected.
ChoicePos += 1; Convert from 0-based to 1-based, i.e. so that the first item is known as 1, not 0.

LineCount: Sets OutputVar to be the number of lines in an Edit control. All Edit controls have at least 1 line, even if the control is empty.

CurrentLine: Sets OutputVar to be the line number in an Edit control where the caret (insert point) resides. The first line is 1. If there is text selected in the control, OutputVar is set to the line number where the selection begins.

CurrentCol: Sets OutputVar to be the column number in an Edit control where the caret (insert point) resides. The first column is 1. If there is text selected in the control, OutputVar is set to the column number where the selection begins.

Line, N: Sets OutputVar to be the text of line N in an Edit control. Line 1 is the first line. Depending on the nature of the control, OutputVar might end in a carriage return (`r) or a carriage return + linefeed (`r`n).

Selected: Sets OutputVar to be the selected text in an Edit control. If no text is selected, OutputVar will be made blank and ErrorLevel will be 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).

Style: Retrieves an 8-digit hexadecimal number representing the style of the control. See the styles table for a listing of some styles.

ExStyle: Retrieves an 8-digit hexadecimal number representing the extended style of the control.

ErrorLevel

Upon success, ErrorLevel is set to 0. If a problem occurred -- such as a nonexistent window or control -- ErrorLevel is set to 1 and OutputVar is made blank.

Remarks

Unlike commands that change a control, ControlGet does not have an automatic delay; that is, SetControlDelay does not affect it.

To discover the name of the control that the mouse is currently hovering over, use MouseGetPos. To get a list of controls in a window, use WinGet ControlList.

Window titles and text are always case sensitive. Hidden windows are not detected unless DetectHiddenWindows has been turned on.

Example

ControlGet, OutputVar, Line, 1, Edit1, Some Window Title

ControlGet, WhichTab, Tab, , SysTabControl321, Some Window Title
if ErrorLevel <> 0
	MsgBox There was a problem.
else
	MsgBox Tab #%WhichTab% is active.