Control Functions

Auto Hotkey

previous page next page

Control Functions

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

All Controls

ControlGetEnabled

Returns 1 (true) if Control is enabled, or 0 (false) if disabled.

ControlGetEnabled(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: See Standard Parameters.

ControlSetEnabled

Enables or disables a control.

ControlSetEnabled Value , Control, WinTitle, WinText, ExcludeTitle, ExcludeText

Value: 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.
Control, WinTitle, etc.: See Standard Parameters.

ControlGetVisible

Returns 1 (true) if Control is visible, or 0 (false) if hidden.

ControlGetVisible(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: See Standard Parameters.

ControlHide

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

Control, WinTitle, etc.: See Standard Parameters.

ControlShow

Shows a control if it was previously hidden.

ControlShow Control, WinTitle, WinText, ExcludeTitle, ExcludeText

Control, WinTitle, etc.: See Standard Parameters.

ControlGetHwnd

Retrieves the window handle (HWND) of the specified control.

ControlGetHwnd(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: 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).

ControlGetStyle / ControlGetExStyle

Retrieves an integer representing the style or extended style of the control.

ControlGetStyle(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
ControlGetExStyle(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: See Standard Parameters.

See the styles table for a listing of some styles.

ControlSetStyle / ControlSetExStyle

Changes the style or extended style of a control, respectively.

ControlSetStyle Value , Control, WinTitle, WinText, ExcludeTitle, ExcludeText
ControlSetExStyle Value , Control, WinTitle, WinText, ExcludeTitle, ExcludeText

Value

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.

Control, WinTitle, etc.

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.

CheckBox and Radio Buttons

ControlGetChecked

Returns 1 (true) if the checkbox or radio button is checked or 0 (false) if not.

ControlGetChecked(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: See Standard Parameters.

ControlSetChecked

Turns on (checks) or turns off (unchecks) a radio button or checkbox.

ControlSetChecked Value , Control, WinTitle, WinText, ExcludeTitle, ExcludeText

Value: 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.
Control, WinTitle, etc.: See Standard Parameters.

Edit

ControlGetCurrentCol

Returns the column number in an Edit control where the caret (text insertion point) resides.

ControlGetCurrentCol(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: 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.

ControlGetCurrentLine

Returns the line number in an Edit control where the caret (insert point) resides.

ControlGetCurrentLine(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: 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.

ControlGetLineCount

Returns the number of lines in an Edit control.

ControlGetLineCount(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: See Standard Parameters.

All Edit controls have at least 1 line, even if the control is empty.

ControlGetLine

Returns the text of line N in an Edit control.

ControlGetLine(N , Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

N: The line number. Line 1 is the first line.
Control, WinTitle, etc.: 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")

ControlGetSelected

Returns the selected text in an Edit control.

ControlGetSelected(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: 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).

ControlEditPaste

Pastes String at the caret/insert position in an Edit control.

ControlEditPaste String , Control, WinTitle, WinText, ExcludeTitle, ExcludeText

String: The string to paste.
Control, WinTitle, etc.: 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.

ListBox and ComboBox

ControlGetChoice

Returns the name of the currently selected entry in a ListBox or ComboBox.

ControlGetChoice(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: 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.

ControlChoose

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

N

The index of the item, where 1 is the first entry, 2 is the second, etc.

To deselect all items, specify 0.

Control, WinTitle, etc.

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.

ControlChooseString

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

String: 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.
Control, WinTitle, etc.: 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.

ControlAddItem

Adds String as a new entry at the bottom of a ListBox or ComboBox.

N := ControlAddItem(String , Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: 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.

ControlDeleteItem

Deletes the Nth entry from a ListBox or ComboBox.

ControlDeleteItem N , Control, WinTitle, WinText, ExcludeTitle, ExcludeText

N: The index of the item, where 1 is the first entry, 2 is the second, etc.
Control, WinTitle, etc.: See Standard Parameters.

ControlFindItem

Returns the entry number of a ListBox or ComboBox that is a complete match for String.

ControlFindItem String , Control, WinTitle, WinText, ExcludeTitle, ExcludeText

String: The string to find. The search is case-insensitive. Unlike ControlChooseString, the entry's entire text must match, not just the leading part.
Control, WinTitle, etc.: 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.

ListView, ListBox and ComboBox

ControlGetList

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

ControlGetList(Options, Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Options: Specifices what to retrieve if the control is a ListView (see below). For other control types, Options should be blank/empty.
Control, WinTitle, etc.: See Standard Parameters.

ListView

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.

ListBox and ComboBox (includes DropDownList)

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

ComboBox

ControlShowDropDown

Drops a ComboBox so that its choices become visible.

ControlShowDropDown Control, WinTitle, WinText, ExcludeTitle, ExcludeText

Control, WinTitle, etc.: 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 forth 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.

ControlHideDropDown

Reverses the above.

ControlHideDropDown Control, WinTitle, WinText, ExcludeTitle, ExcludeText

Control, WinTitle, etc.: See Standard Parameters.

Tab

ControlGetTab

Returns the position number of the selected tab in a SysTabControl32.

ControlGetTab(Control, WinTitle, WinText, ExcludeTitle, ExcludeText)

Control, WinTitle, etc.: 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.")

ControlSetTab

Selects the Nth tab in a SysTabControl32.

ControlSetTab N , Control, WinTitle, WinText, ExcludeTitle, ExcludeText

Control, WinTitle, etc.: See Standard Parameters.

General

Standard Parameters

All of the functions on this page utilize the following parameters to identify the target control and window:

Control

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.

WinTitle

A window title or other criteria identifying the target window. See WinTitle.

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.

ErrorLevel

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.

Remarks

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

previous page start next page

Control Functions

Auto Hotkey

Control Functions

All Controls

ControlGetEnabled

ControlSetEnabled

ControlGetVisible

ControlHide

ControlShow

ControlGetHwnd

ControlGetStyle / ControlGetExStyle

ControlSetStyle / ControlSetExStyle

CheckBox and Radio Buttons

ControlGetChecked

ControlSetChecked

Edit

ControlGetCurrentCol

ControlGetCurrentLine

ControlGetLineCount

ControlGetLine

ControlGetSelected

ControlEditPaste

ListBox and ComboBox

ControlGetChoice

ControlChoose

ControlChooseString

ControlAddItem

ControlDeleteItem

ControlFindItem

ListView, ListBox and ComboBox

ControlGetList

ListView

ListBox and ComboBox (includes DropDownList)

ComboBox

ControlShowDropDown

ControlHideDropDown

Tab

ControlGetTab

ControlSetTab

General

Standard Parameters

ErrorLevel

Remarks

Related