Some functions have a ControlID parameter used to identify which control in a window to operate on. This parameter can be the text of the control or any other identifier described on this page.
The following identifiers are ordered by descending precedence. This detail is important in rare cases of ambiguity. For example, if a window has two edit controls, the first with the text "Edit2" and the second with ClassNN "Edit2", and ControlHide "Edit2" is used, the second control will be hidden, because ClassNN has higher precedence.
A control's HWND (short for handle to window) uniquely identifies that control for as long as it exists. Pass the HWND directly, or as an object with a Hwnd property such as a GuiControl object. This also works on hidden controls even when DetectHiddenWindows is turned off. Any subsequent window parameters are ignored. When passing an object, a PropertyError is thrown if the object has no Hwnd property, or TypeError if it does not return a pure integer.
A control's HWND can be retrieved via ControlGetHwnd, GuiControl.Hwnd, WinGetControlsHwnd, MouseGetPos, and DllCall.
A HWND is especially useful when sending messages directly to a control via PostMessage, SendMessage, or when calling native APIs with DllCall. It is also helpful when controls are dynamically created or reordered, since the HWND remains constant for the lifetime of the control.
Type: String
A control's ClassNN is the name of its window class followed by its sequence number within the top-level window which contains it. The sequence number reflects the control's position among controls of the same class, in the order they were created. For example, Edit1 is the first edit control in a window and Button12 is the twelfth button.
Some class names include digits which are not part of the control's sequence number. For example, SysListView321 is the window's first ListView control, not its 321st. To retrieve the class name without the sequence number, pass the control's HWND to WinGetClass.
A control's ClassNN can be determined via Window Spy, and retrieved via ControlGetClassNN, WinGetControls, and MouseGetPos.
The sequence number is not a persistent identifier. It may change if the application recreates controls, changes their order, or uses dynamic or virtualized UI elements. Some modern frameworks (such as WPF or Electron) may not expose traditional Win32 class names at all, or may reuse generic class names for multiple unrelated controls.
ClassNN is often convenient when controls do not have unique text and when the control order is stable. When stability cannot be guaranteed, consider using a HWND or another identifier.
Type: String
The text of a control may be used as a identifier, e.g. OK for an OK button. The matching behavior is determined by SetTitleMatchMode. Use text when it is unique and stable; many controls update it dynamically or do not expose meaningful text.
A control's text can be determined via Window Spy, and retrieved via ControlGetText, GuiControl.Text, and GuiControl.Value.
ControlClick, ControlSend, PostMessage, and SendMessage are able to operate on either a control or a top-level window. Omitting the ControlID parameter causes the function to use the target window (specified by WinTitle) instead of one of its controls.
The following functions have a ControlID parameter: ControlAddItem, ControlChooseIndex, ControlChooseString, ControlClick, ControlDeleteItem, ControlFindItem, ControlFocus, ControlGetChecked, ControlGetChoice, ControlGetClassNN, ControlGetEnabled, ControlGetHwnd, ControlGetIndex, ControlGetItems, ControlGetPos, ControlGetStyle, ControlGetText, ControlGetVisible, ControlHide, ControlHideDropDown, ControlMove, ControlSend, ControlSetChecked, ControlSetEnabled, ControlSetStyle, ControlSetText, ControlShow, ControlShowDropDown, EditGetCurrentCol, EditGetCurrentLine, EditGetLine, EditGetLineCount, EditGetSelectedText, EditPaste, ListViewGetContent, PostMessage, SendMessage. Most of these functions have examples on their corresponding page that demonstrate the use of control identifiers.
ClassNN and control text may change when applications recreate controls, alter their order, use dynamic or virtualized interfaces, or rely on frameworks that do not expose stable Win32 class names or text. When identifiers are unreliable, prefer using a HWND for lifetime-stable addressing or combine multiple criteria. As general guidance: use control text when it is unique and stable, use ClassNN when the control order is consistent and readability is desired, and use a HWND when maximum stability is required. Avoid hardcoding identifiers across application versions unless you control the target application.