GuiControlGet

Retrieves various types of information about a control in a GUI window.

GuiControlGet, OutputVar , SubCommand, ControlID, Value

Parameters

OutputVar

The name of the variable in which to store the result of SubCommand.

SubCommand, Value

These are dependent upon each other and their usage is described below.

ControlID

If blank or omitted, it behaves as though the name of the output variable was specified. For example, GuiControlGet, MyEdit is the same as GuiControlGet, MyEdit,, MyEdit.

If the target control has an associated variable, specify the variable's name as the ControlID (this method takes precedence over the ones described next). For this reason, it is usually best to assign a variable to any control that will later be accessed via GuiControl or GuiControlGet, even if that control is not input-capable (such as GroupBox or Text).

Otherwise, ControlID 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.

Note: A picture control's file name (as it was specified at the time the control was created) may be used as its ControlID.

[v1.1.04+]: ControlID can be the HWND of a control.

If the control is not on the default GUI, the name of the GUI must also be specified -- except on [v1.1.20+] when ControlID is a HWND, since each HWND is unique. See Remarks for details.

Sub-commands

For SubCommand, specify one of the following:

• (Blank): Retrieves the contents of the control.
• Pos: Retrieves the position and size of the control.
• Focus: Retrieves the control identifier (ClassNN) for the control that currently has keyboard focus.
• FocusV [v1.0.43.06+]: Retrieves the name of the focused control's associated variable.
• Enabled: Retrieves 1 if the control is enabled or 0 if it is disabled.
• Visible: Retrieves 1 if the control is visible or 0 if it is hidden.
• Hwnd [v1.0.46.16+]: Retrieves the window handle (HWND) of the control.
• Name [v1.1.03+]: Retrieves the name of the control's associated variable.

(Blank)

Retrieves the contents of the control.

GuiControlGet, OutputVar ,, ControlID, Value

Leave SubCommand blank to retrieve the control's contents. All control types are self-explanatory except the following:

Picture: Retrieves the picture's file name as it was originally specified when the control was created. This name does not change even if a new picture file name is specified.

Edit: Retrieves the contents but 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 commands such as ControlGetText and ControlSetText.

Hotkey: Retrieves a blank value if there is no hotkey in the control. Otherwise it retrieves the modifiers and key name. Examples: ^!C, ^Home, +^NumpadHome.

Checkbox/Radio: Retrieves 1 if the control is checked, 0 if it is unchecked, or -1 if it has a gray checkmark. To retrieve the control's text/caption instead, specify the word Text for Value. Note: Unlike the Gui Submit command, radio buttons are always retrieved individually, regardless of whether they are in a radio group.

UpDown/Slider/Progress: Retrieves the control's current position.

Tab/DropDownList/ComboBox/ListBox: Retrieves the text of the currently selected item/tab (or its position if the control has the AltSubmit property). For a ComboBox, if there is no selected item, the text in the control's edit field is retrieved instead. For a multi-select ListBox, the output uses the window's current delimiter.

ListView and TreeView: These are not supported when SubCommand is blank. Instead, use the built-in ListView functions and TreeView functions.

StatusBar: Retrieves only the first part's text.

ActiveX: Retrieves a new wrapper object for the control's ActiveX component.

Note: To unconditionally retrieve the text/caption of a CheckBox, Radio, DropDownList or ComboBox rather than its contents, specify the word Text for Value.

Pos

Retrieves the position and size of the control.

GuiControlGet, OutputVar, Pos , ControlID

The position is relative to the GUI window's client area, which is the area not including title bar, menu bar, and borders. The information is stored in four variables whose names all start with OutputVar. For example:

GuiControlGet, MyEdit, Pos
MsgBox The X coordinate is %MyEditX%. The Y coordinate is %MyEditY%. The width is %MyEditW%. The height is %MyEditH%.

Within a function, to create a set of variables that is global instead of local, declare OutputVar as a global variable prior to using this command (the converse is true for assume-global functions). However, it is often also necessary to declare each variable in the set, due to a common source of confusion.

Focus

Retrieves the control identifier (ClassNN) for the control that currently has keyboard focus.

GuiControlGet, OutputVar, Focus , ControlID

Since the specified GUI window must be active for one of its controls to have focus, OutputVar will be made blank if it is not active. Example usage: GuiControlGet, focused_control, Focus.

FocusV [v1.0.43.06+]

Retrieves the name of the focused control's associated variable.

GuiControlGet, OutputVar, FocusV , ControlID

See the Focus sub-command (above) for details. If that control lacks an associated variable, the first 63 characters of the control's text/caption is retrieved instead (this is most often used to avoid giving each button a variable name).

Enabled

Retrieves 1 if the control is enabled or 0 if it is disabled.

GuiControlGet, OutputVar, Enabled , ControlID

Visible

Retrieves 1 if the control is visible or 0 if it is hidden.

GuiControlGet, OutputVar, Visible , ControlID

Hwnd [v1.0.46.16+]

Retrieves the window handle (HWND) of the control.

GuiControlGet, OutputVar, Hwnd , ControlID

A control's HWND is often used with PostMessage, SendMessage, and DllCall. Note: HwndOutputVar is usually a more concise way to get the HWND.

Name [v1.1.03+]

Retrieves the name of the control's associated variable.

GuiControlGet, OutputVar, Name , ControlID

If it doesn't have one, OutputVar is made blank.

ErrorLevel

[v1.1.04+]: This command is able to throw an exception on failure. For more information, see Runtime Errors.

ErrorLevel is set to 1 if the specified window/control does not exist or some other problem prevented the command from working. Otherwise, it is set to 0.

Remarks

To operate upon a window other than the default (see below), include its name or number followed by a colon in front of the sub-command as in these examples:

GuiControlGet, MyEdit, MyGui:
GuiControlGet, MyEdit, MyGui:Pos
GuiControlGet, OutputVar, MyGui:Focus

This is required even if ControlID is a control's associated variable, since any one variable can be used on multiple GUI windows. In [v1.1.20+], the GUI name can be omitted if ControlID is a control's HWND.

A GUI thread is defined as any thread launched as a result of a GUI action. GUI actions include selecting an item from a GUI window's menu bar, or triggering one of its g-labels (such as by pressing a button).

The default window name for a GUI thread is that of the window that launched the thread. Non-GUI threads use 1 as their default.

Related

Gui, GuiControl, ControlGet

Examples

Example #1: Miscellaneous

GuiControlGet, MyEdit
GuiControlGet, CtrlContents,, MyEdit  ; Same as the above except uses a non-default output variable.
GuiControlGet, MyCheckbox1 ; Retrieves 1 if it is checked, 0 if it is unchecked.
GuiControlGet, MyCheckbox1,,, Text  ; Retrieves the caption/text of the checkbox.
GuiControlGet, Pic, Pos, Static4  ; The position/size will be stored in PicX, PicY, PicW, and PicH