[Archived, Locked] Suggestions on documentation improvements

[just me]

Greed: By default, *, ?, +, and {min,max} are greedy because they consume all characters up through the last possible one that still satisfies the entire pattern. To instead have them stop at the first possible character, follow them with a question mark. For example, the pattern <.+> (which lacks a question mark) means: "search for a <, followed by one or more of any character, followed by a >". To stop this pattern from matching the entire string <em>text</em>, append a question mark to the plus sign: <.+?>. This causes the match to stop at the first '>' and thus it matches only the first tag <em>.

?

[nnnik]

OK missed that...

[guest3456]

Other useful remappings:

Capslock::Ctrl

Makes Capslock become a Control key. To retain the ability to turn Capslock on and off, also add the remapping +Capslock::Capslock (this toggles Capslock on and off when you hold down the shift key and press Capslock).

Should mention that you need to define +Capslock::Capslock BEFORE Capslock::Ctrl otherwise it doesn't work. Unless this is a bug on my system?

[trismarck]

Perhaps it could be documented which Gui commands create a new Gui window if that Gui window does not yet exist:

Gui commands that do create new gui window when gui window doesn't exist:

• new
• add
• show
• font
• color
• margin
• +-Option (w/o +LastFoundExist)
• Menu

Gui commands that don't create new gui window when gui window doesn't exist:

• submit
• cancel
• destroy
• Gui, +lastFoundExist
• Hide
• Minimize
• Maximize
• Restore
• Flash
• Default
• 1:Default

In example:

Code: Select all

Gui, 2:Default

won't switch the default Gui window to 2, because that Gui window does not yet exist, but:

Code: Select all

Gui, 2:Font, s10
Gui, 2:Default

will.

A related note would be, should Gui, GuiName:Default create the window or not?

[joedf]

Hmm... interesting point there!

[lexikos]

trismarck is mistaken about Gui, 2:Default.

Code: Select all

Gui, 2:Default
Gui, +LabelTest
Gui, Show, w100 h100
return
TestClose:
MsgBox % A_Gui  ; Shows 2
ExitApp

Gui Default doesn't create the window, but it does set the default name. The default name remains set even after the window is destroyed. Also, Gui numbers are really just Gui names which are numeric.

[trismarck]

Lexikos thanks, so there is a difference between:

• the start-off default Gui window name of the thread
• the current default Gui window name of the thread (== start-off name at beginning of thread)
• the existence of the default Gui window

Furthermore, Gui, Default doesn't _create_ the gui window if the window doesn't exist, but it _does_ apply the new default window name.
Fixed example:

Code: Select all

Gui, +LastFoundExist
MsgBox % WinExist() ; 0x0
Gui, Font, s9
Gui, +LastFoundExist
MsgBox % WinExist() ; 0x123456

As a related note, Gui, New (unlike all other Gui commands (besides Gui, GuiName:Default I guess)) _never_ uses the current default window name, which perhaps could also be documented pointed out in the documentation:

Code: Select all

Gui, 2:Default
Gui, new, +hwndh, new
Gui, 2:Show, w200 h100		; title: none
Gui, %h%:Show, w200 h100	; title: new

OTOH this could be inferred from:

If a name is specified, any existing GUI with that name is destroyed.

[lexikos]

Furthermore, Gui, Default doesn't _create_ the gui window if the window doesn't exist, but it _does_ apply the new default window name.

Btw, the documentation says "Changes the current thread's default GUI window name", and that's exactly what it does. Creating the window would be above and beyond that.

As a related note, Gui, New (unlike all other Gui commands (besides Gui, GuiName:Default I guess)) _never_ uses the current default window name, which perhaps could also be documented pointed out in the documentation:

Using the current default window name would 99% defeat the purpose of that command. The second line of its documentation says:

Code: Select all

Gui, New  ; Creates a new unnamed and unnumbered GUI.

Keywords: new, unnamed. The current default window name is clearly irrelevant.

Btw, Chris' comments in the source code are "If the window doesn't currently exist, don't auto-create it for those commands for which it wouldn't make sense." It simply doesn't make sense to auto-create the window for these commands, so there's no need to document it:

• Submit: there are no controls to submit and no window to hide.
• Hide/Cancel (they are the same command): no window to hide.
• Minimize, Maximize, Restore, Flash: even if the window was created, it would be hidden and therefore none of these commands would have any effect.
• Destroy: this command could create and destroy the window, and you'd never know. Common sense tells us that it doesn't create a window, so the documentation doesn't need to.
• +LastFoundExist: its entire reason for existing is that it doesn't create the window. It's also documented.

[trismarck]

Thanks.

Using the current default window name would 99% defeat the purpose of that command.

I agree.

The other context of writing about that Gui, New doesn't use the current default gui window was this:
contrary to some settings which can be set as defaults for every new AHK thread, there is no way to set the default margin size or color of the Gui for all threads:

Every thread launched by a hotkey, hotstring, menu item, GUI event, or timer starts off fresh with the default values for the following attributes as set in the auto-execute section. If unset, the standard defaults will apply (as documented on each of the following pages): DetectHiddenWindows, DetectHiddenText, SetTitleMatchMode, SetBatchLines, SendMode, SetKeyDelay, SetMouseDelay, SetWinDelay, SetControlDelay, SetDefaultMouseSpeed, CoordMode, SetStoreCapslockMode, AutoTrim, SetFormat, StringCaseSense, Thread, and Critical.

But no Gui, Margin or Gui, Font.
In example, doing this in the auto-execute section only sets the margin size for the currently default Gui window (~for _one_ window) (if the current default gui window doesn't exist, the window is created*):

Code: Select all

Gui, Margin, 20, 20

* - if one didn't know of whether Gui, Margin creates a new Gui window if that window doesn't exist, one could interpret this line of code as setting the default margin size for all gui windows in the thread / for all threads.
The problem I had with Gui, Margin was that, at first glance, it is not obvious of whether Gui, Margin pertains to all subsequent windows or to just one window. At that time, I've thought that the 'ambiguity' could be fixed by adding Gui, [GuiName:]Param1 to every gui command in the documentation. But thinking about this now, in case of Gui, Margin, I guess this wouldn't help much, as the square brackets still make the name _optional_ (~what's the meaning of the command when no name). So perhaps [GuiName:] or [:GuiIdentifier] could be added to all Gui commands in the documentation (to denote that all gui commands pertain only to _one_ particular gui window).
A related note to this context is: where to put the name of the gui window in GuiControl:

[v1.1.04+]: ControlID can be the HWND of a control. As with any other value for ControlID, the Gui must also be specified if the control is not on the default Gui.

This is invalid:

Code: Select all

GuiControlGet, OutputVar , Pos, Name:%hwnd%

Solution

Code: Select all

GuiControlGet, OutputVar , Name:Pos, %hwnd%

But again, all of this information is really inside of the documentation already - Gui, Margin only pertains to _one_ window:

If this command is not used, when the first control is added to a window, _the window_ acquires a default margin on all sides proportional to the size of the currently selected font (0.75 times font-height for top & bottom, and 1.25 times font-height for left & right).

Actually, reading Gui, Color in the context of a command similar to Gui, Margin would help to solve this:

Sets the background color of the window and/or its controls.

; but not Gui, Font ?

Sets the font typeface, size, style, and/or color for controls created _from this point onward_.

On a yet related note, the only command where the name of the Gui _is_ required seems to be Gui, GuiName:Default.

This is just the context of all of this.

[lexikos]

* - if one didn't know of whether Gui, Margin creates a new Gui window if that window doesn't exist, one could interpret this line of code as setting the default margin size for all gui windows in the thread / for all threads.

I think it's unlikely. There's nothing in the documentation hinting that this might happen. It's more logical to assume that it sets the margin for the Gui window when it is created. It sets parameters for AutoHotkey's control sizing - this does not require creating an actual window, since the window isn't changed in any way.

The problem I had with Gui, Margin was that, at first glance, it is not obvious of whether Gui, Margin pertains to all subsequent windows or to just one window.

Like all Gui commands (except New), it pertains to the default Gui window (when no name is given). We could perhaps solve that problem by stating "Sets the margins for the given Gui" or similar in its documentation, but then what about every other sub-command, or for instance, Gui +Option? Does it set options for the default Gui, or the default for all subsequent windows? It would potentially be a lot of redundant text to state this every time, when the documentation already implies the command will operate on the default window, not default settings for all windows:

To operate upon a window other than the default, include its name or number
...
[Gui Default] Changes the current thread's default GUI window name, which is used whenever a window name is not specified for GuiControl, GuiControlGet, and the Gui command itself.

A related note to this context is: where to put the name of the gui window in GuiControl:

The same place it's always put. I agree the text could be more clear. Why would you think to prefix it to the HWND with ':' as a separator? If someone gets that far, they've obviously done that before, so there's a good chance they already know it's supposed to go on the sub-command.

On a yet related note, the only command where the name of the Gui _is_ required seems to be Gui, GuiName:Default.

You are mistaken!

Of course, Gui, Default is not very useful.

[lexikos]

Gui commands that don't create new gui window when gui window doesn't exist:

• submit
• cancel
• destroy
• Gui, +lastFoundExist
• Hide
• Minimize
• Maximize
• Restore

I just realized that it's basically already documented that these commands don't create a new GUI window. The line used for most of them is:
"If the window does not exist -- perhaps due to having been destroyed via Gui Destroy -- this command has no effect."

(to denote that all gui commands pertain only to _one_ particular gui window).

As I noted above, it's implied by the documentation for multiple windows/Gui Default. I think that is sufficient, because the question of which window it applies to is not relevant to new users until they learn how to create multiple windows.

[joedf]

... Of course, Gui, Default is not very useful.

[trismarck]

* - if one didn't know of whether Gui, Margin creates a new Gui window if that window doesn't exist, one could interpret this line of code as setting the default margin size for all gui windows in the thread / for all threads.

I think it's unlikely. There's nothing in the documentation hinting that this might happen.

If there is Gui, Default, which can modify settings of the thread, perhaps there are other Gui commands that also change the per-thread settings. Also, if it is possible to set a default setting so that all subsequent gui commands will use that setting (default gui window), perhaps there are other settings like this.

Lets however suppose the quote was written in the context of the documentation on Gui, Margin solely:

If this command is not used, when the first control is added to a window, the window acquires a default margin on all sides proportional to the size of the currently selected font (0.75 times font-height for top & bottom, and 1.25 times font-height for left & right).

The window acquires a default margin, but is that default margin per-_window_ or per-_thread_.

X and Y are the number of pixels of space to leave at the left/right and top/bottom sides of the window when auto-positioning any control that lacks an explicit X or Y coordinate.

'of the window', but for _every_ window from this point onward, or for _one particular_ window from this point onward. I just find this ambiguous. Even though 'Creating Multiple GUI Windows' explicitly says that all gui commands operate upon just one particular window:

To operate upon a window other than the default

, I still find that sentence not explicit enough.
So for the problem of 'gui command only works for _one_ window', perhaps only that sentence could be changed to something like:

Every Gui command operates upon performs over? one particular gui window. That window is:
- the default window, if no colon was used
- the name or number (or in v1.1.03+, the HWND) followed by a colon in front of the sub-command, as in ...

Note to self: it is the _colon_ that denotes of whether the default gui window or something else is used by the gui command. Thus the following does _not_ operate upon a gui window whose name is an empty string:

Code: Select all

Gui, Default

but this does and produces a compilation error:

Code: Select all

Gui, :Default

Also, the above doesn't mean that this:

Code: Select all

Gui, Default

can't operate upon an _unnamed_ gui window - it can, if the unnamed window was set as the current default window of the thread.

Only that one sentence, because adding this to every Gui command would be redundant, as, unlike with the problem of only _some_ gui commands creating the gui window if the window doesn't exist, the proposed changed sentence applies to _all_ (vs some) gui commands.

---------

It's more logical to assume that it [Gui, Margin/this line of code?] sets the margin for the Gui window when it is [already?] created. It sets parameters for AutoHotkey's control sizing - this does not require creating an actual window, since the window isn't changed in any way.

I'm not sure if I understand the last sentence correctly: [supposing the current default gui window of the thread does not yet exist]Gui, Margin sets the margin for the internal structure that (the structure) represents the Gui window. At the same time (or actually, _before_ setting the margin (or actually2 - the order of this is irrelevant as the margin is only used when adding gui _controls_), Gui, Margin _does_ create the gui window (if the window doesn't exist). The creation of the gui window is however not _required_ (Gui, Margin could be like Gui, Default - change the setting, but do _not_ create the window if that window doesn't exist, as it's not required to create the window - the decision of whether to create the window or not is made purely out of 'intuitive' reasons).

The problem I had with Gui, Margin was that, at first glance, it is not obvious of whether Gui, Margin pertains to all subsequent windows or to just one window.

Like all Gui commands (except New), it pertains to the default Gui window (when no name is given). We could perhaps solve that problem by stating "Sets the margins for the given Gui" or similar in its documentation, but then what about every other sub-command, or for instance, Gui +Option? Does it set options for the default Gui, or the default for all subsequent windows? It would potentially be a lot of redundant text to state this every time, when the documentation already implies the command will operate on the default window, not default settings for all windows:

To operate upon a window other than the default, include its name or number
...
[Gui Default] Changes the current thread's default GUI window name, which is used whenever a window name is not specified for GuiControl, GuiControlGet, and the Gui command itself.

Ok, redundant, I agree.

A related note to this context is: where to put the name of the gui window in GuiControl:

The same place it's always put. I agree the text could be more clear. Why would you think to prefix it to the HWND with ':' as a separator? If someone gets that far, they've obviously done that before, so there's a good chance they already know it's supposed to go on the sub-command

Yes, that was exactly the case - it was discovered where to put the gui identifier. The intention was to make a suggestion so that, perhaps, that sentence could be made more clear or explicit.

On a yet related note, the only command where the name of the Gui _is_ required seems to be Gui, GuiName:Default.

You are mistaken!

Of course, Gui, Default is not very useful.

Ok, I give up. (;


------------------
Aside of all of this, I also have one minor suggestion about Creating Multiple GUI Windows - could the following be moved downward:



-----------------
As for the 'create window if window doesn't exist' context:

I just realized that it's basically already documented that these commands don't create a new GUI window. The line used for most of them is:
"If the window does not exist -- perhaps due to having been destroyed via Gui Destroy -- this command has no effect."

This definitely solves it, thank you very much Lexikos.

[lexikos]

The window acquires a default margin, but is that default margin per-_window_ or per-_thread_.

It says "the window acquires", not "the thread acquires". Also, it's based on "the currently selected font", which is another per-window setting (though that mightn't be clear).

It's more logical to assume that it [Gui, Margin/this line of code?] sets the margin for the Gui window when it is [already?] created.

No, I think you've misinterpreted "when" to mean "if". I'm saying that one could assume the settings will be applied to the window at some later time, when some other command causes the window to be created. The margin only takes effect when you add controls or Show the GUI (and it auto-sizes).

could the following be moved downward

I think it was written that way because the "Creating Multiple GUI Windows" section follows on immediately from the "Window Events" section, but your suggestion makes a lot more sense.

[trismarck]

It says "the window acquires", not "the thread acquires". Also, it's based on "the currently selected font", which is another per-window setting (though that mightn't be clear).

Ok.

I'm saying that one could assume the settings will be applied to the window at some later time, when some other command causes the window to be created. The margin only takes effect when you add controls or Show the GUI (and it auto-sizes).

Ok, [safe to] assume (infer the assumption from the documentation) that the settings might not apply instantly, but they will eventually be applied when needed, ~regardless of the actual implementation, thanks.

[geek]

The remarks on FileGetSize has FolderSize += %A_LoopFileSize%, but it should be FolderSize += A_LoopFileSize

http://ahkscript.org/docs/commands/FileGetSize.htm

[lexikos]

GeekDude: They both do the same thing. That's just the old way of doing it. There are numerous other instances of it in the help file.

[guest3456]

Hrm, I would've expected that to double deref the A_LoopFileSize variable in the expression

[just me]

Slider

Slider Options
ToolTip: Creates a tooltip that reports the numeric position of the slider as the user is dragging it. To have the tooltip appear in a non-default position, specify one of the following instead: ToolTipLeft or ToolTipRight (for horizontal sliders); ToolTipTop or ToolTipBottom (for vertical sliders).

horizontal <-> vertical

[lexikos]

guest3456: It's not an expression. It's the EnvAdd command.

Var += Value [, TimeUnits]
...
%Var%: For backward compatibility, command parameters that are documented as "can be an expression" treat an isolated name in percent signs (e.g. %Var%, but not Array%i%) as though the percent signs are absent.