Ξ
Δ
◄
►
¬
Ѕ
Filter
Directives
Built-in Variables
Built-in Functions
Control Flow Statements
Operators
Declarations
Commands
Sub-commands
Built-in Methods/Properties
Ahk2Exe Compiler
Highlight keywords
</head> <body> <h1>ControlGet</h1> <p>Retrieves various types of information about a control.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, <a href="#SubCommands">SubCommand</a> <span class="optional">, Value, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <h2 id="Parameters">Parameters</h2> <dl> <dt>OutputVar</dt> <dd>The name of the variable in which to store the result of <em>SubCommand</em>.</dd> <dt>SubCommand, Value</dt> <dd>These are dependent upon each other and their usage is described <a href="#SubCommands">below</a>.</dd> <dt>Control</dt> <dd> <p>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 <a href="SetTitleMatchMode.htm">SetTitleMatchMode</a>. If this parameter is blank, the target window's topmost control will be used.</p> <p>To operate upon a control's HWND (window handle), leave the <em>Control</em> parameter blank and specify <code>ahk_id %ControlHwnd%</code> for the <em>WinTitle</em> parameter (this also works on hidden controls even when <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> is Off). The HWND of a control is typically retrieved via <a href="ControlGet.htm#Hwnd">ControlGet Hwnd</a>, <a href="MouseGetPos.htm">MouseGetPos</a>, or <a href="DllCall.htm">DllCall()</a>.</p> </dd> <dt>WinTitle</dt> <dd>A window title or other criteria identifying the target window. See <a href="../misc/WinTitle.htm">WinTitle</a>.</dd> <dt>WinText</dt> <dd>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 <a href="DetectHiddenText.htm">DetectHiddenText</a> is ON.</dd> <dt>ExcludeTitle</dt> <dd>Windows whose titles include this value will not be considered.</dd> <dt>ExcludeText</dt> <dd>Windows whose text include this value will not be considered.</dd> </dl> <h2 id="SubCommands">Sub-commands</h2> <p>For <em>SubCommand</em>, specify one of the following:</p> <ul> <li><a href="#List">List</a>: Retrieves a list of items from a ListView, ListBox, ComboBox, or DropDownList.</li> <li><a href="#Checked">Checked</a>: Retrieves 1 if the checkbox or radio button is checked or 0 if not.</li> <li><a href="#Enabled">Enabled</a>: Retrieves 1 if the control is enabled, or 0 if disabled.</li> <li><a href="#Visible">Visible</a>: Retrieves 1 if the control is visible, or 0 if hidden.</li> <li><a href="#Tab">Tab</a>: Retrieves the tab number of a SysTabControl32 control.</li> <li><a href="#FindString">FindString</a>: Retrieves the entry number of a ListBox or ComboBox that is an exact match for the string.</li> <li><a href="#Choice">Choice</a>: Retrieves the name of the currently selected entry in a ListBox or ComboBox.</li> <li><a href="#LineCount">LineCount</a>: Retrieves the number of lines in an Edit control.</li> <li><a href="#CurrentLine">CurrentLine</a>: Retrieves the line number in an Edit control where the caret resides.</li> <li><a href="#CurrentCol">CurrentCol</a>: Retrieves the column number in an Edit control where the caret resides.</li> <li><a href="#Line">Line</a>: Retrieves the text of the specified line number in an Edit control.</li> <li><a href="#Selected">Selected</a>: Retrieves the selected text in an Edit control.</li> <li><a href="#Style">Style</a>: Retrieves an 8-digit hexadecimal number representing the style of the control.</li> <li><a href="#ExStyle">ExStyle</a>: Retrieves an 8-digit hexadecimal number representing the extended style of the control.</li> <li><a href="#Hwnd">Hwnd</a> <span class="ver">[v1.1.04+]</span>: Retrieves the window handle (HWND) of the control.</li> </ul> <h3 id="List">List</h3> <p>Retrieves a list of items from a ListView, ListBox, ComboBox, or DropDownList. For ListView, additional options can be specified.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, List <span class="optional">, Options, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <h4 id="ListView">ListView</h4> <p>If the <em>Options</em> 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).</p> <p>Specify for <em>Options</em> zero or more of the following words, each separated from the next with a space or tab:</p> <table class="info"> <tr> <th>Option</th> <th abbr="Descr">Description</th> </tr> <tr> <td>Selected</td> <td>Retrieves only the selected (highlighted) rows rather than all rows. If none, <em>OutputVar</em> is made blank.</td> </tr> <tr> <td>Focused</td> <td>Retrieves only the focused row. If none, <em>OutputVar</em> is made blank.</td> </tr> <tr id="ColN"> <td>Col4</td> <td>Retrieves only the fourth column (field) rather than all columns (replace 4 with a number of your choice).</td> </tr> <tr> <td>Count</td> <td>Retrieves a single number that is the total number of rows in the control.</td> </tr> <tr> <td>Count Selected</td> <td>Retrieves the number of selected (highlighted) rows.</td> </tr> <tr> <td>Count Focused</td> <td>Retrieves the row number (position) of the focused row (0 if none).</td> </tr> <tr> <td>Count Col</td> <td>Retrieves the number of columns in the control (or -1 if the count cannot be determined).</td> </tr> </table> <p class="note"><strong>Note</strong>: 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 <a href="_MaxMem.htm">#MaxMem</a>.</p> <p>Upon success, ErrorLevel is set to 0. Upon failure, it is set to 1 and <em>OutputVar</em> 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 <a href="#ColN">Col<em>N</em> option</a> specifies a nonexistent column.</p> <p>To extract the individual rows and fields out of a ListView, use a <a href="LoopParse.htm">parsing loop</a> as in this example:</p> <pre>ControlGet, SelectedItems, List, Selected, SysListView321, <i>WinTitle</i> Loop, Parse, SelectedItems, `n <em>; Rows are delimited by linefeeds (`n).</em> { RowNumber := A_Index Loop, Parse, A_LoopField, %A_Tab% <em>; Fields (columns) in each row are delimited by tabs (A_Tab).</em> MsgBox Row #%RowNumber% Col #%A_Index% is %A_LoopField%. }</pre> <p>On a related note, the columns in a ListView can be resized via <a href="PostMessage.htm">SendMessage</a> as shown in this example:</p> <pre>SendMessage, 0x101E, 0, 80, SysListView321, <i>WinTitle</i> <em>; 0x101E is LVM_SETCOLUMNWIDTH.</em></pre> <p>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.</p> <h4 id="ListBox_ComboBox_DropDownList">ListBox, ComboBox, DropDownList</h4> <p>All the text is retrieved from the control (that is, the ListView options above such as <em>Count</em> and <em>Selected</em> are not supported).</p> <p>Each item except the last will be terminated by a linefeed character (`n). To access the items individually, use a <a href="LoopParse.htm">parsing loop</a> as in this example:</p> <pre>ControlGet, Items, List,, ComboBox1, <i>WinTitle</i> Loop, Parse, Items, `n MsgBox Item number %A_Index% is %A_LoopField%.</pre> <h3 id="Checked">Checked</h3> <p>Retrieves 1 if the checkbox or radio button is checked or 0 if not.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Checked <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <h3 id="Enabled">Enabled</h3> <p>Retrieves 1 if <em>Control</em> is enabled, or 0 if disabled.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Enabled <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <h3 id="Visible">Visible</h3> <p>Retrieves 1 if <em>Control</em> is visible, or 0 if hidden.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Visible <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <h3 id="Tab">Tab</h3> <p>Retrieves the tab number of a SysTabControl32 control.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Tab <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>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:</p> <pre><a href="PostMessage.htm">SendMessage</a>, 0x1304,,, SysTabControl321, <i>WinTitle</i> <em>; 0x1304 is TCM_GETITEMCOUNT.</em> TabCount := ErrorLevel</pre> <h3 id="FindString">FindString</h3> <p>Retrieves the entry number of a ListBox or ComboBox that is an exact match for <em>String</em>.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, FindString, String <span class="optional">, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>The first entry in the control is 1, the second 2, and so on. If no match is found, <em>OutputVar</em> is made blank and ErrorLevel is set to 1.</p> <h3 id="Choice">Choice</h3> <p>Retrieves the name of the currently selected entry in a ListBox or ComboBox.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Choice <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>To instead retrieve the position of the selected item, follow this example (use only one of the first two lines):</p> <pre><a href="PostMessage.htm">SendMessage</a>, 0x0188, 0, 0, ListBox1, <i>WinTitle</i> <em>; 0x0188 is LB_GETCURSEL (for a ListBox).</em> <a href="PostMessage.htm">SendMessage</a>, 0x0147, 0, 0, ComboBox1, <i>WinTitle</i> <em>; 0x0147 is CB_GETCURSEL (for a DropDownList or ComboBox).</em> ChoicePos := ErrorLevel<<32>>32 <em>; Convert UInt to Int to have -1 if there is no item selected.</em> ChoicePos += 1 <em>; Convert from 0-based to 1-based, i.e. so that the first item is known as 1, not 0.</em></pre> <h3 id="LineCount">LineCount</h3> <p>Retrieves the number of lines in an Edit control.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, LineCount <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>All Edit controls have at least 1 line, even if the control is empty.</p> <h3 id="CurrentLine">CurrentLine</h3> <p>Retrieves the line number in an Edit control where the caret (insert point) resides.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, CurrentLine <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>The first line is 1. If there is text selected in the control, <em>OutputVar</em> is set to the line number where the selection begins.</p> <h3 id="CurrentCol">CurrentCol</h3> <p>Retrieves the column number in an Edit control where the caret (text insertion point) resides.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, CurrentCol <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>The first column is 1. If there is text selected in the control, <em>OutputVar</em> is set to the column number where the selection begins.</p> <h3 id="Line">Line</h3> <p>Retrieves the text of line <em>N</em> in an Edit control.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Line, N <span class="optional">, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>Line 1 is the first line. Depending on the nature of the control, <em>OutputVar</em> might end in a carriage return (`r) or a carriage return + linefeed (`r`n). If the specified line number is blank or does not exist, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 and <em>OutputVar</em> is made blank.</p> <h3 id="Selected">Selected</h3> <p>Retrieves the selected text in an Edit control.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Selected <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>If no text is selected, <em>OutputVar</em> 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).</p> <h3 id="Style">Style</h3> <p>Retrieves an 8-digit hexadecimal number representing the style of the control.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Style <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>See the <a href="../misc/Styles.htm">styles table</a> for a listing of some styles.</p> <h3 id="ExStyle">ExStyle</h3> <p>Retrieves an 8-digit hexadecimal number representing the extended style of the control.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, ExStyle <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>See the <a href="../misc/Styles.htm">styles table</a> for a listing of some styles.</p> <h3 id="Hwnd">Hwnd <span class="ver">[v1.0.43.06+]</span></h3> <p>Retrieves the window handle (HWND) of the control.</p> <pre class="Syntax"><span class="func">ControlGet</span>, OutputVar, Hwnd <span class="optional">,, Control, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre> <p>For example: <code>ControlGet, OutputVar, Hwnd,, Edit1, <i>WinTitle</i></code>. A control's HWND is often used with <a href="PostMessage.htm">PostMessage</a>, <a href="PostMessage.htm">SendMessage</a>, and <a href="DllCall.htm">DllCall()</a>. On a related note, a control's HWND can also be retrieved via <a href="MouseGetPos.htm">MouseGetPos</a>. Finally, a control's HWND can be used directly as an <a href="../misc/WinTitle.htm#ahk_id">ahk_id WinTitle</a> (this also works on hidden controls even when <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> is Off).</p> <h2 id="Error_Handling">Error Handling</h2> <p><span class="ver">[v1.1.04+]</span>: This command is able to throw an exception on failure. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p> <p>Upon success, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 0. If a problem occurred -- such as a nonexistent window or control -- <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 and <em>OutputVar</em> is made blank.</p> <h2 id="Remarks">Remarks</h2> <p>Unlike commands that change a control, ControlGet does not have an automatic delay; that is, <a href="SetControlDelay.htm">SetControlDelay</a> does not affect it.</p> <p>To discover the ClassNN or HWND of the control that the mouse is currently hovering over, use <a href="MouseGetPos.htm">MouseGetPos</a>. To retrieve a list of all controls in a window, use <a href="WinGet.htm#ControlList">WinGet ControlList</a>.</p> <p>Window titles and text are case sensitive. Hidden windows are not detected unless <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> has been turned on.</p> <h2 id="Related">Related</h2> <p><a href="Control.htm">Control</a>, <a href="GuiControlGet.htm">GuiControlGet</a>, <a href="ControlMove.htm">ControlMove</a>, <a href="ControlGetText.htm">ControlGetText</a>, <a href="ControlSetText.htm">ControlSetText</a>, <a href="ControlGetPos.htm">ControlGetPos</a>, <a href="ControlClick.htm">ControlClick</a>, <a href="ControlFocus.htm">ControlFocus</a>, <a href="ControlSend.htm">ControlSend</a>, <a href="WinGet.htm">WinGet</a></p> <h2 id="Examples">Examples</h2> <div class="ex" id="ExLine"> <p><a class="ex_number" href="#ExLine"></a> Retrieves the first line of the first Edit control.</p> <pre>ControlGet, OutputVar, Line, 1, Edit1, Some Window Title</pre> </div> <div class="ex" id="ExTab"> <p><a class="ex_number" href="#ExTab"></a> Retrieves the currently active tab of the first Tab control.</p> <pre>ControlGet, WhichTab, Tab,, SysTabControl321, Some Window Title if ErrorLevel MsgBox There was a problem. else MsgBox Tab #%WhichTab% is active.</pre> </div> </body> </html>