</head> <body> <h1>GuiControlGet</h1> <p>Retrieves various types of information about a control in a GUI window.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar <span class="optional">, <a href="#SubCommands">SubCommand</a>, ControlID, Value</span></pre> <h2 id="Parameters">Parâmetros</h2> <dl> <dt>OutputVar</dt> <dd>The name of the output 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>ControlID</dt> <dd><p>If blank or omitted, it behaves as though the name of the output variable was specified. For example, <code>GuiControlGet, MyEdit</code> is the same as <code>GuiControlGet, MyEdit,, MyEdit</code>.</p> <p>If the target control has an associated variable, specify the variable's name as the <em>ControlID</em> (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).</p> <p>Otherwise, <em>ControlID</em> 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>.</p> <p class="note"><strong>Observação</strong>: A picture control's file name (as it was specified at the time the control was created) may be used as its <em>ControlID</em>.</p> <p><span class="ver">[v1.1.04+]:</span> <em>ControlID</em> can be the <a href="Gui.htm#HwndOutputVar">HWND</a> of a control.</p> <p>If the control is not on the default GUI, <strong>the name of the GUI must also be specified</strong> -- except on <span class="ver">[v1.1.20+]</span> when <em>ControlID</em> is a HWND, since each HWND is unique. See <a href="#Remarks">Remarks</a> for details.</p> </dd> </dl> <h2 id="SubCommands">Sub-commands</h2> <p>For <em>SubCommand</em>, specify one of the following:</p> <ul> <li><a href="#Blank">(Blank)</a>: Retrieves the contents of the control.</li> <li><a href="#Pos">Pos</a>: Retrieves the position and size of the control.</li> <li><a href="#Focus">Focus</a>: Retrieves the control identifier (ClassNN) for the control that currently has keyboard focus.</li> <li><a href="#FocusV">FocusV</a> <span class="ver">[v1.0.43.06+]</span>: Retrieves the name of the focused control's associated variable.</li> <li><a href="#Enabled">Enabled</a>: Retrieves 1 if the control is enabled or 0 if it is disabled.</li> <li><a href="#Visible">Visible</a>: Retrieves 1 if the control is visible or 0 if it is hidden.</li> <li><a href="#Hwnd">Hwnd</a> <span class="ver">[v1.0.46.16+]</span>: Retrieves the window handle (HWND) of the control.</li> <li><a href="#Name">Name</a> <span class="ver">[v1.1.03+]</span>: Retrieves the name of the control's associated variable.</li> </ul> <h3 id="Blank">(Blank)</h3> <p>Retrieves the contents of the control.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar <span class="optional">,, ControlID, Value</span></pre> <p>Leave <em>SubCommand</em> blank to retrieve the control's contents. All control types are self-explanatory except the following:</p> <p><a href="GuiControls.htm#Picture">Picture</a>: 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.</p> <p><a href="GuiControls.htm#Edit">Edit</a>: 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 <a href="ControlGetText.htm">ControlGetText</a> and <a href="ControlSetText.htm">ControlSetText</a>.</p> <p><a href="GuiControls.htm#Hotkey">Hotkey</a>: Retrieves a blank value if there is no hotkey in the control. Otherwise it retrieves the modifiers and key name. Examples: <code>^!C</code>, <code>^Home</code>, <code>+^NumpadHome</code>.</p> <p><a href="GuiControls.htm#Checkbox">Checkbox</a>/<a href="GuiControls.htm#Radio">Radio</a>: 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 <em>Value</em>. Observação: Unlike the <a href="Gui.htm#Submit">Gui Submit</a> command, radio buttons are always retrieved individually, regardless of whether they are in a radio group.</p> <p><a href="GuiControls.htm#UpDown">UpDown</a>/<a href="GuiControls.htm#Slider">Slider</a>/<a href="GuiControls.htm#Progress">Progress</a>: Retrieves the control's current position.</p> <p><a href="GuiControls.htm#Tab">Tab</a>/<a href="GuiControls.htm#DropDownList">DropDownList</a>/<a href="GuiControls.htm#ComboBox">ComboBox</a>/<a href="GuiControls.htm#ListBox">ListBox</a>: Retrieves the text of the currently selected item/tab (or its position if the control has the <a href="Gui.htm#AltSubmit">AltSubmit</a> property). For a ComboBox, if there is no selected item, the text in the control's edit field is retrieved instead. For a <a href="GuiControls.htm#ListBoxMulti">multi-select ListBox</a>, the output uses the window's <a href="Gui.htm#Delimiter">current delimiter</a>.</p> <p><a href="ListView.htm">ListView</a> and <a href="TreeView.htm">TreeView</a>: These are not supported when <em>SubCommand</em> is blank. Instead, use the built-in <a href="ListView.htm#BuiltIn">ListView functions</a> and <a href="TreeView.htm#BuiltIn">TreeView functions</a>.</p> <p><a href="GuiControls.htm#StatusBar">StatusBar</a>: Retrieves only the first part's text.</p> <p><a href="GuiControls.htm#ActiveX">ActiveX</a>: Retrieves a new wrapper object for the control's ActiveX component.</p> <p class="note"><strong>Observação</strong>: To unconditionally retrieve the text/caption of a CheckBox, Radio, DropDownList or ComboBox rather than its contents, specify the word Text for <em>Value</em>.</p> <h3 id="Pos">Pos</h3> <p>Retrieves the position and size of the control.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar, Pos <span class="optional">, ControlID</span></pre> <p>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 <em>OutputVar</em>. Por exemplo:</p> <pre>GuiControlGet, MyEdit, Pos MsgBox The X coordinate is %MyEditX%. The Y coordinate is %MyEditY%. The width is %MyEditW%. The height is %MyEditH%.</pre> <p>Within a <a href="../Functions.htm">function</a>, to create a set of variables that is global instead of local, <a href="../Functions.htm#Global">declare</a> <em>OutputVar</em> as a global variable prior to using this command (the converse is true for <a href="../Functions.htm#AssumeGlobal">assume-global</a> functions). However, it is often also necessary to declare each variable in the set, due to a <a href="../Functions.htm#ArrayConfusion">common source of confusion</a>.</p> <h3 id="Focus">Focus</h3> <p>Retrieves the control identifier (ClassNN) for the control that currently has keyboard focus.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar, Focus <span class="optional">, ControlID</span></pre> <p>Since the specified GUI window must be <a href="WinActivate.htm">active</a> for one of its controls to have focus, <em>OutputVar</em> will be made blank if it is not active. Example usage: <code>GuiControlGet, focused_control, Focus</code>.</p> <h3 id="FocusV">FocusV <span class="ver">[v1.0.43.06+]</span></h3> <p>Retrieves the name of the focused control's <a href="Gui.htm#Events">associated variable</a>.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar, FocusV <span class="optional">, ControlID</span></pre> <p>See the <a href="#Focus">Focus</a> 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).</p> <h3 id="Enabled">Enabled</h3> <p>Retrieves 1 if the control is enabled or 0 if it is disabled.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar, Enabled <span class="optional">, ControlID</span></pre> <h3 id="Visible">Visible</h3> <p>Retrieves 1 if the control is visible or 0 if it is hidden.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar, Visible <span class="optional">, ControlID</span></pre> <h3 id="Hwnd">Hwnd <span class="ver">[v1.0.46.16+]</span></h3> <p>Retrieves the window handle (HWND) of the control.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar, Hwnd <span class="optional">, ControlID</span></pre> <p>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>. Observação: <a href="Gui.htm#HwndOutputVar">HwndOutputVar</a> is usually a more concise way to get the HWND.</p> <h3 id="Name">Name <span class="ver">[v1.1.03+]</span></h3> <p>Retrieves the name of the control's <a href="Gui.htm#Events">associated variable</a>.</p> <pre class="Syntax"><span class="func">GuiControlGet</span>, OutputVar, Name <span class="optional">, ControlID</span></pre> <p>If it doesn't have one, <em>OutputVar</em> is made blank.</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><a href="../misc/ErrorLevel.htm">ErrorLevel</a> 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.</p> <h2 id="Remarks">Remarks</h2> <p>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:</p> <pre>GuiControlGet, MyEdit, MyGui: GuiControlGet, MyEdit, MyGui:Pos GuiControlGet, OutputVar, MyGui:Focus</pre> <p>This is required even if <em>ControlID</em> is a control's associated variable, since any one variable can be used on multiple GUI windows. In <span class="ver">[v1.1.20+]</span>, the GUI name can be omitted if <em>ControlID</em> is a control's HWND.</p> <p>A GUI <a href="../misc/Threads.htm">thread</a> 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 <a href="Gui.htm#label">g-labels</a> (such as by pressing a button).</p> <p>The <a href="Gui.htm#DefaultWin">default window name</a> for a GUI thread is that of the window that launched the thread. Non-GUI threads use 1 as their default.</p> <h2 id="Related">Tópicos relacionados</h2> <p><a href="Gui.htm">Gui</a>, <a href="GuiControl.htm">GuiControl</a>, <a href="ControlGet.htm">ControlGet</a></p> <h2 id="Examples">Exemplos</h2> <div class="ex" id="ExNoControlID"> <p><a class="ex_number" href="#ExNoControlID"></a> Retrieves the text of an Edit control and stores it in <var>MyEdit</var>.</p> <pre>GuiControlGet, MyEdit</pre> </div> <div class="ex" id="ExEdit"> <p><a class="ex_number" href="#ExEdit"></a> Same as above but stores the text in <var>CtrlContents</var>.</p> <pre>GuiControlGet, CtrlContents,, MyEdit</pre> </div> <div class="ex" id="ExCheckBox"> <p><a class="ex_number" href="#ExCheckBox"></a> Retrieves 1 if a checkbox is checked or 0 if it is unchecked.</p> <pre>GuiControlGet, MyCheckbox1</pre> </div> <div class="ex" id="ExCheckBoxText"> <p><a class="ex_number" href="#ExCheckBoxText"></a> Retrieves the caption/text of a checkbox.</p> <pre>GuiControlGet, MyCheckbox1,,, Text</pre> </div> <div class="ex" id="ExPos"> <p><a class="ex_number" href="#ExPos"></a> Stores the position and size in <var>PicX</var>, <var>PicY</var>, <var>PicW</var>, and <var>PicH</var>.</p> <pre>GuiControlGet, Pic, Pos, Static4</pre> </div> </body> </html>