docs/commands/GuiControl.htm

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>GuiControl</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>GuiControl</h1>

<p>Makes a variety of changes to a control in a GUI window.</p>

<pre class="Syntax">GuiControl, Sub-command, ControlID [, Param3]</pre>
<h3>Parameters</h3>
<dl>

  <dt>Sub-command</dt>
  <dd><p>See list below.</p></dd>

  <dt>ControlID</dt>
  <dd><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 an input-capable type (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>. Note: 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>

  <dt>Param3</dt>
  <dd><p>This parameter is omitted except where noted in the list of sub-commands below.</p></dd>

</dl>

<h3>ErrorLevel</h3>
<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>
<h3>Sub-commands</h3>
<p><strong>(Blank)</strong>: Leave <em>Sub-command</em> blank to put new contents into the control via <em>Param3</em>. Specifically:</p>
<p><a href="GuiControls.htm#Picture">Picture</a>: <em>Param3</em> should be the filename (or <a href="../misc/ImageHandles.htm">handle</a>) of the new image to load (see <a href="GuiControls.htm#Picture">Gui Picture</a> for supported file types). Zero or more of the following options may be specified immediately in front of the filename: <code>*wN</code> (width N), <code>*hN</code> (height N), and <code>*IconN</code> (icon group number N in a DLL or EXE file).  In the following example, the default icon from the second icon group is loaded with a width of 100 and an automatic height via &quot;keep aspect ratio&quot;: <code>GuiControl,, MyPic, *icon2 *w100 *h-1 C:\My Application.exe</code>. Specify <code>*w0 *h0</code> to use the image's actual width and height. If <code>*w</code> and <code>*h</code> are omitted, the image will be scaled to fit the current size of the control. When loading from a multi-icon .ICO file, specifying a width and height also determines which icon to load. Note: Use only one space or tab between the final option and the filename itself; any other spaces and tabs are treated as part of the filename.</p>
<p><a href="GuiControls.htm#Text">Text</a>/<a href="GuiControls.htm#Button">Button</a>/<a href="GuiControls.htm#GroupBox">GroupBox</a>/<a href="GuiControls.htm#StatusBar">StatusBar</a>: Specify for <em>Param3</em> the control's new text. Since the control will not expand automatically, use <code><a href="#Move">GuiControl, Move, MyText, W300</a></code> if the control needs to be widened. For <a href="GuiControls.htm#StatusBar">StatusBar</a>, this sets the text of the first part only (use <a href="GuiControls.htm#SB_SetText">SB_SetText()</a> for greater flexibility).</p>
<p><a href="GuiControls.htm#Edit">Edit</a>: Any linefeeds (`n) in <em>Param3</em> that lack a preceding carriage return (`r) are automatically translated to CR+LF (`r`n) to make them display properly. However, this is usually not a concern because the <code>Gui Submit</code> and <code>GuiControlGet OutputVar</code> commands will automatically undo this translation by replacing CR+LF with LF (`n).</p>
<p><a href="GuiControls.htm#Hotkey">Hotkey</a>: <em>Param3</em> can be blank to clear the control, or a set of modifiers with a key name. Examples: <code>^!c</code>, <code>^Numpad1</code>, <code>+Home</code>. The only modifiers supported are ^ (Control), ! (Alt), and + (Shift). See the <a href="../KeyList.htm">key list</a> for available key names.</p>
<p><a href="GuiControls.htm#Checkbox">Checkbox</a>: <em>Param3</em> can be 0 to uncheck the button, 1 to check it, or -1 to give it a gray checkmark. Otherwise, <em>Param3</em> is assumed to be the control's new caption/text. See <strong>Text</strong> below for how to override this behavior.</p>
<p><a href="GuiControls.htm#Radio">Radio</a>: Same as Checkbox above. However, if the radio button is being checked (turned on) and it is a member of a multi-radio group, the other radio buttons in its group will be automatically unchecked. To check a new button within a radio group that only has one variable, specify for <em>ControlID</em> the name/text of the button if it is not the button with which the variable is directly associated.</p>
<p><a href="GuiControls.htm#DateTime">DateTime</a>/<a href="GuiControls.htm#MonthCal">MonthCal</a>: Specify for <em>Param3</em> a date-time stamp in <a href="FileSetTime.htm#YYYYMMDD">YYYYMMDDHH24MISS</a> format. Specify <code>%A_Now%</code> to use the current date and time (today). For DateTime controls, <em>Param3</em> may be omitted to cause the control to have no date/time selected (if it was created with <a href="GuiControls.htm#ChooseNone">that ability</a>). For MonthCal controls, a range may be specified if the control is <a href="GuiControls.htm#MonthCalMulti">multi-select</a>.</p>
<p><a href="GuiControls.htm#UpDown">UpDown</a>/<a href="GuiControls.htm#Slider">Slider</a>/<a href="GuiControls.htm#Progress">Progress</a>: <em>Param3</em> should be the new position of the control. If a <em>Param3</em>'s first character is a plus sign, the number will be assumed to be an offset from the current position. For example, <code>+10</code> would increase the position by 10 and <code>+-10</code> (plus minus ten) would decrease it by 10. If the new position would be outside the range of the control, the control is generally set to the nearest valid value.</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>: <em>Param3</em> should contain a pipe-delimited list of entries to be appended at the end of the control's list. To replace (overwrite) the list instead, include a pipe as the first character (e.g. <code>|Red|Green|Blue</code>). To make the control empty, specify only a pipe character (|). To have one of the entries pre-selected, include two pipes after it (e.g. <code>Red|Green||Blue</code>). The separator between fields may be changed to something other than pipe. For example, <code><a href="Gui.htm#Delimiter">Gui +Delimiter`n</a></code> would change it to linefeed and <code>Gui +DelimiterTab</code> would change it to tab (`t).</p>
<p><a href="GuiControls.htm#Tab">Tab controls</a>: In addition to the behavior described in the paragraph above, a tab's sub-controls stay associated with their original tab number; that is, they are never associated with their tab's actual display-name. For this reason, renaming or removing a tab will not change the tab number to which the sub-controls belong. For example, if there are three tabs &quot;Red|Green|Blue&quot; and the second tab is removed by means of <code>GuiControl,, MyTab, |Red|Blue</code>, the sub-controls originally associated with Green will now be associated with Blue. Because of this behavior, only tabs at the end should generally be removed. Tabs that are removed in this way can be added back later, at which time they will reclaim their original set of controls.</p>
<p><a href="ListView.htm">ListView</a> and <a href="TreeView.htm">TreeView</a>: These are not supported when <em>Sub-command</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><br>
    <strong><a name="Text"></a>GuiControl, Text</strong>: Behaves the same as the above except for:<br>
<a href="GuiControls.htm#Checkbox">Checkbox</a>/<a href="GuiControls.htm#Radio">Radio</a>: <em>Param3</em> is treated as the new text/caption even if it is -1, 0, or 1.<br>
<a href="GuiControls.htm#DateTime">DateTime</a>: <em>Param3</em> is treated as the new <a href="GuiControls.htm#DateTimeFormat">date/time format</a> displayed by the control. If Param3 is omitted, any custom format is removed and the short-date format is put into effect.<br>
<a href="GuiControls.htm#ComboBox">ComboBox</a>: <em>Param3</em> is treated as the text to put directly into the ComboBox's Edit control.</p>
<p><strong><a name="Move"></a>GuiControl, Move</strong>: Moves and/or resizes the control. Specify one or more of the following option letters in <em>Param3</em>: X (the x-coordinate relative to the GUI window's client area, which is the area not including title bar, menu bar, and borders); Y (the y-coordinate), W (Width), H (Height). (Specify each number as decimal, not hexadecimal.) For example:</p>
<pre>GuiControl, Move, MyEdit, x10 y20 w200 h100
GuiControl, Move, MyEdit, % &quot;x&quot; VarX+10 &quot;y&quot; VarY+5 &quot;w&quot; VarW*2 &quot;h&quot; VarH*1.5 <em>; Uses an <a href="../Variables.htm#Expressions">expression</a> via &quot;% &quot; prefix.</em></pre>
<p><strong><a name="MoveDraw" id="MoveDraw"></a>GuiControl, MoveDraw</strong>: Same as &quot;Move&quot; (above) except that it also repaints the region of the GUI window occupied by the control. Although this may cause an unwanted flickering effect when called repeatedly and rapidly, it solves painting artifacts for certain control types such as <a href="GuiControls.htm#GroupBox">GroupBoxes</a>. In v1.0.48.04+, the last parameter may be omitted to redraw the control without moving it.</p>
<p id="Focus"><strong>GuiControl, Focus</strong>: Sets keyboard focus to the control. To be effective, the window generally must not be minimized or hidden.</p>
<p><strong><a name="Enable"></a><a name="Disable"></a>GuiControl, Enable / Disable</strong>: Enables or disables (grays out) the control. For Tab controls, this will also enable or disable all of the tab's sub-controls. However, any sub-control explicitly disabled via <code>GuiControl Disable</code> will remember that setting and thus remain disabled even after its Tab control is re-enabled. The word Disable or Enable may optionally be followed immediately by a 0 or 1. A zero causes the effect to be inverted. For example, <code>Enable</code> and <code>Enable%VarContainingOne%</code> would both enable the control, but <code>Enable%VarContainingZero%</code> would disable it.</p>
<p><strong><a name="Hide"></a><a name="Show"></a>GuiControl, Hide / Show</strong>: Hides or shows the control. For Tab controls, this will also show or hide all of the tab's sub-controls. If you additionally want to prevent a control's shortcut key (underlined letter) from working, disable the control via <code>GuiControl Disable</code>. The word Hide or Show may optionally be followed immediately by a 0 or 1. A zero causes the effect to be inverted. For example, <code>Show</code> and <code>Show%VarContainingOne%</code> would both show the control, but <code>Show%VarContainingZero%</code> would hide it.</p>
<p><strong>GuiControl, Delete (not yet implemented)</strong>: This sub-command does not yet exist. As a workaround, use <strong>Hide</strong> and/or <strong>Disable</strong> (above), or destroy and recreate the entire window via <a href="Gui.htm#Destroy">Gui Destroy</a>.</p>
<p id="Choose"><strong>GuiControl, Choose, ControlID, N</strong>: Sets the selection in a ListBox, DropDownList, ComboBox, or Tab control to be the Nth entry. <em>N</em> should be 1 for the first entry, 2 for the second, etc. If <em>N</em> is not an integer, the ChooseString method described below will be used instead. <span class="ver">[v1.1.06+]:</span> If <em>N</em> is zero, the ListBox, DropDownList or ComboBox's current selection is removed.</p>
<p>Unlike <a href="Control.htm">Control Choose</a>, this sub-command will not trigger any <a href="Gui.htm#label">g-label</a> associated with the control unless <em>N</em> is preceded by a pipe character (even then, the g-label is triggered only when the new selection is different than the old one, at least for <a href="GuiControls.htm#Tab">Tab controls</a>). For example: <code>GuiControl, Choose, MyListBox, <strong>|3</strong></code>.</p>
<p>To additionally cause a finishing event to occur (a double-click in the case of ListBox), include two leading pipes instead of one (this is not supported for Tab controls).</p>
<p>To select or deselect <u>all</u> items in a <a href="GuiControls.htm#ListBoxMulti">multi-select ListBox</a>, follow this example:</p>
<pre>Gui +LastFound  <em>; Avoids the need to specify WinTitle below.</em>
<a href="PostMessage.htm">PostMessage</a>, 0x185, 1, -1, ListBox1  <em>; Select all items. 0x185 is LB_SETSEL.</em>
<a href="PostMessage.htm">PostMessage</a>, 0x185, 0, -1, ListBox1  <em>; Deselect all items.</em>
GuiControl, Choose, ListBox1, 0  <em>; Deselect all items (requires v1.1.06+).</em></pre>
<p id="ChooseString"><strong>GuiControl, ChooseString, ControlID, String</strong>: Sets the selection (choice) in a ListBox, DropDownList, ComboBox, or Tab control to be the entry whose leading part matches <em>String</em>. The search is not case sensitive. For example, if a the control contains the item &quot;UNIX Text&quot;, specifying the word unix (lowercase) would be enough to select it. The pipe and double-pipe prefix are also supported (see &quot;Choose&quot; above for details).</p>
<p id="Font"><strong>GuiControl, Font</strong>: Changes the control's font to the typeface, size, color, and style currently in effect for its window. For example:</p>
<pre><a href="Gui.htm#Font">Gui, Font</a>, s18 cRed Bold, Verdana  <em>; If desired, use a line like this to set a new default font for the window.</em>
GuiControl, Font, MyEdit  <em>; Put the above font into effect for a control.</em></pre>
<p><strong>GuiControl, +/-Option1 +/-Option2 ...</strong>: Add or remove various <a href="GuiControls.htm">control-specific</a> or <a href="Gui.htm#OtherOptions">general</a> options and styles.</p>
<p>In the following example, the <a href="Gui.htm#AltSubmit">AltSubmit</a> option is enabled but control's <a href="Gui.htm#label">g-label</a> is removed:</p>
<pre>GuiControl,  +AltSubmit -g, MyListBox</pre>
<p>In the next example, the OK button is made the new default button:</p>
<pre>GuiControl, +Default, OK</pre>
<p>Although <a href="../misc/Styles.htm">styles</a> and extended styles are also recognized, some of them cannot be applied or removed after a control has been created. ErrorLevel is set to 0 if at least one of the specified changes was successfully applied. Otherwise, it is set to 1 to indicate that none of the changes could be applied. Even if a change is successfully applied, the control might choose to ignore it.</p>
<p id="Functor"><span class="ver">[v1.1.20+]:</span> To set a <a href="../objects/Functor.htm">function object</a> for handling <a href="Gui.htm#label">the control's events</a>, <em>Param3</em> must be a single variable reference, as in either of the following examples. Other expressions which return objects are currently unsupported.</p>
<pre>GuiControl +g, <i>ControlID</i>, %FuncObj%
GuiControl +g, <i>ControlID</i>, % FuncObj
</pre>

<h3 id="Remarks">Remarks</h3>
<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>GuiControl, MyGui:Show, MyButton
GuiControl, MyGui:, MyListBox, Item1|Item2</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>

<h3>Related</h3>
<p><a href="Gui.htm">Gui</a>, <a href="GuiControlGet.htm">GuiControlGet</a>, <a href="Control.htm">Control</a></p>
<h3>Examples</h3>
<pre class="NoIndent">GuiControl,, MyListBox, |Red|Green|Blue  <em>; Replace the current list with a new list.</em>
GuiControl,, MyEdit, New text line 1.`nNew text line 2.
GuiControl,, MyRadio2, 1  <em>; Turn on this radio button and turn off all the others in its group.</em>
GuiControl, Move, OK, x100 y200  <em>; Move the OK button to a new location.</em>
GuiControl, Focus, LastName  <em>; Set keyboard focus to the control whose variable or text is &quot;LastName&quot;.</em></pre>

</body>
</html>