Skip to content

Commit

Permalink
Align texts + Change formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
Ragnar-F committed May 3, 2023
1 parent d0fc96f commit 7f8cac9
Show file tree
Hide file tree
Showing 5 changed files with 47 additions and 47 deletions.
4 changes: 2 additions & 2 deletions docs/lib/Gui.htm
Expand Up @@ -486,7 +486,7 @@ <h3 id="OtherEvents">Other Events</h3>
<p>Other types of GUI events can be detected and acted upon via <a href="OnMessage.htm">OnMessage()</a>. For example, a script can display context-sensitive help via ToolTip whenever the user moves the mouse over particular controls in the window. This is demonstrated in the <a href="#ExToolTip">GUI ToolTip example</a>.</p>

<h2 id="MultiWin">Creating Multiple GUI Windows</h2>
<p>To operate upon a window other than the <a href="#DefaultWin">default</a>, include its name or number (or <span class="ver">[in v1.1.03+]</span> its <a href="#GuiHwndOutputVar">HWND</a>) followed by a colon in front of the sub-command, as in these examples:</p>
<p>To operate upon a window other than the <a href="#DefaultWin">default</a>, include its name or number (or in <span class="ver">[v1.1.03+]</span> its <a href="#GuiHwndOutputVar">HWND</a>) followed by a colon in front of the sub-command, as in these examples:</p>
<pre>Gui, <strong>MyGui:</strong>Add, Text,, Text for about-box.
Gui, <strong>MyGui:</strong>Show</pre>
<p><code><a href="#Default">Gui MyGui:Default</a></code> can be used to avoid the need for the "MyGui:" prefix above. In addition, the prefix is not necessary inside a <a href="#DefaultWin">GUI thread</a> that operates upon the same window that launched the thread.</p>
Expand All @@ -495,7 +495,7 @@ <h2 id="MultiWin">Creating Multiple GUI Windows</h2>

<h2 id="DefaultWin">GUI Events, Threads, and Subroutines</h2>
<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 <a href="#Menu">menu bar</a>, or triggering one of its <a href="#label">g-labels</a> (such as by pressing a button).</p>
<p>The <strong>default <a href="#MultiWin">window name</a></strong> for a GUI thread is that of the window that launched the thread. Non-GUI threads use 1 as their default.</p>
<p>The <a href="#MultiWin">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>
<p>Whenever a GUI <a href="../misc/Threads.htm">thread</a> is launched, that thread's <a href="../misc/WinTitle.htm#LastFoundWindow">last found window</a> starts off as the GUI window itself. This allows commands for windows and controls -- such as <a href="WinMove.htm">WinMove</a>, <a href="WinHide.htm">WinHide</a>, <a href="WinSet.htm">WinSet</a>, <a href="WinSetTitle.htm">WinSetTitle</a>, and <a href="ControlGetFocus.htm">ControlGetFocus</a> -- to omit <em>WinTitle</em> and <em>WinText</em> when operating upon the GUI window itself (even if it is hidden).</p>
<p>Clicking on a control while its <a href="#label">g-label</a> is already running from a prior click will have no effect and the event is discarded. To prevent this, use <a href="Critical.htm">Critical</a> as the subroutine's first line (however, this will also buffer/defer other <a href="../misc/Threads.htm">threads</a> such as the press of a hotkey).</p>
<p>The built-in variables A_Gui and A_GuiControl contain the window name and Control ID that launched the current thread. For details see <a href="../Variables.htm#Gui">A_Gui</a> and <a href="../Variables.htm#GuiControl">A_GuiControl</a>.</p>
Expand Down
22 changes: 11 additions & 11 deletions docs/lib/GuiControl.htm
Expand Up @@ -22,7 +22,7 @@ <h2 id="Parameters">Parameters</h2>
<dd>These are dependent upon each other and their usage is described <a href="#SubCommands">below</a>.</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>
<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 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>Note</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>
Expand Down Expand Up @@ -57,13 +57,13 @@ <h3 id="Blank">(Blank)</h3>
<p class="note"><strong>Note</strong>: 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>/<a href="GuiControls.htm#Link">Link</a>: Specify for <em>Value</em> the control's new text. Since the control will not expand automatically, use <code><a href="#Move">GuiControl, Move</a>, MyText, W300</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>Value</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>Value</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 ^ (Ctrl), ! (Alt), and + (Shift). See the <a href="../KeyList.htm">key list</a> for available key names.</p>
<p><a href="GuiControls.htm#Hotkey">Hotkey</a>: <em>Value</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>Value</em> can be 0 to uncheck the button, 1 to check it, or -1 to give it a gray checkmark. Otherwise, <em>Value</em> is assumed to be the control's new caption/text. See the <a href="#Text">Text</a> sub-command 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>Value</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>Value</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>Value</em> should be the new position of the control. If a <em>Value</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>Value</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 "Red|Green|Blue" 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="GuiControls.htm#UpDown">UpDown</a>/<a href="GuiControls.htm#Slider">Slider</a>/<a href="GuiControls.htm#Progress">Progress</a>: <em>Value</em> should be the new position of the control. If a <em>Value</em>'s first character is a plus sign, the number will be assumed to be an offset from the current position. For example, <code class="no-highlight">+10</code> would increase the position by 10 and <code class="no-highlight">+-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>Value</em> should contain a pipe-delimited list of items 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 items 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 by using the GUI option <a href="Gui.htm#Delimiter">+Delimiter</a>. For example, <code>Gui +Delimiter`n</code> would change it to linefeed (`n) 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 <code>Red|Green|Blue</code> 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>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>

<h3 id="Text">Text</h3>
Expand Down Expand Up @@ -118,19 +118,19 @@ <h3 id="Delete">Delete</h3>
<p><strong>Not yet implemented</strong>: This sub-command does not yet exist. As a workaround, use the sub-commands <a href="#Hide">Hide</a> and/or <a href="#Disable">Disable</a> (above), or destroy and recreate the entire window via <a href="Gui.htm#Destroy">Gui Destroy</a>.</p>

<h3 id="Choose">Choose</h3>
<p>Sets the selection in a ListBox, DropDownList, ComboBox, or Tab control to be the Nth entry.</p>
<p>Sets the selection in a ListBox, DropDownList, ComboBox, or Tab control to be the Nth item.</p>
<pre class="Syntax"><span class="func">GuiControl</span>, Choose, ControlID, N</pre>
<p><em>N</em> should be 1 for the first entry, 2 for the second, etc. If <em>N</em> is not an integer, the <a href="#ChooseString">ChooseString</a> sub-command (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><em>N</em> should be 1 for the first item, 2 for the second, etc. If <em>N</em> is not an integer, the <a href="#ChooseString">ChooseString</a> sub-command (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 <strong>all</strong> items in a <a href="GuiControls.htm#ListBoxMulti">multi-select ListBox</a>, follow this example:</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>, 0x0185, 1, -1, ListBox1 <em>; Select all items. 0x0185 is LB_SETSEL.</em>
<a href="PostMessage.htm">PostMessage</a>, 0x0185, 0, -1, ListBox1 <em>; Deselect all items.</em>
GuiControl, Choose, ListBox1, 0 <em>; Deselect all items <span class="ver">[requires v1.1.06+]</span>.</em></pre>

<h3 id="ChooseString">ChooseString</h3>
<p>Sets the selection (choice) in a ListBox, DropDownList, ComboBox, or Tab control to be the entry whose leading part matches <em>String</em>.</p>
<p>Sets the selection (choice) in a ListBox, DropDownList, ComboBox, or Tab control to be the item whose leading part matches <em>String</em>.</p>
<pre class="Syntax"><span class="func">GuiControl</span>, ChooseString, ControlID, String</pre>
<p>The search is not case sensitive. For example, if a control contains the item "UNIX Text", specifying <code>GuiControl, ChooseString, <i>ControlID</i>, unix</code> would be enough to select it. The pipe and double-pipe prefix are also supported (see the <a href="#Choose">Choose</a> sub-command above for details).</p>

Expand Down Expand Up @@ -158,11 +158,11 @@ <h2 id="Error_Handling">Error Handling</h2>
<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, include its <a href="Gui.htm#MultiWin">name or number</a> (or <span class="ver">[in v1.1.03+]</span> its HWND) followed by a colon in front of the sub-command as in these examples:</p>
<p>To operate upon a window other than the <a href="Gui.htm#DefaultWin">default</a>, include its <a href="Gui.htm#MultiWin">name or number</a> (or in <span class="ver">[v1.1.03+]</span> its <a href="Gui.htm#GuiHwndOutputVar">HWND</a>) 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>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 <a href="Gui.htm#Menu">menu bar</a>, 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">Related</h2>
Expand Down

0 comments on commit 7f8cac9

Please sign in to comment.