[v2] Specify default value for WinSetAlwaysOnTop Topic is solved

[mikeyww]

[v2] Specify the default value for WinSetAlwaysOnTop. As far as I can tell, the default value is True.

[swagfag]

it is
https://github.com/AutoHotkey/AutoHotkeyDocs/pull/629

[mikeyww]

Thank you, swagfag.

[lexikos]

v2-changes indicates that the default should be -1, equivalent to what it was in v1.

WinSetAlwaysOnTop([TrueFalseToggle := -1, ...])

It currently defaults to 1 because of the following commit:
https://github.com/AutoHotkey/AutoHotkey/commit/ec92ed9edc06d8c6e01263627b1726737c5120cb

There's no note about the change, so I suppose either it was unintentional or I'd forgotten the old default. I might have figured that "WinSetAlwaysOnTop" can be read like "set window [to be] always on top". Prior to that commit, the parameter was marked as optional but invoked undefined behaviour (probably a crash) if it was omitted. In other words, it's likely that WinSetAlwaysOnTop never defaulted to toggling (in contrast with WinSet AlwaysOnTop in v1, which does).

Is it better to document the current behaviour (and fix v2-changes) or restore the v1 default?

[mikeyww]

My vote is to document the current behavior.

Rationale:
1. I, too, read it as "set the window to be always on top".
2. This makes behavior consistent with Pause, which has the same parameters and uses True as its default.

[Ragnar]

I agree with @mikeyww, although unlike Pause, Suspend toggles without its parameter.

[mikeyww]

Good point. For consistency, I would actually vote to have all of these use the same default (as they did in v1, but with a different default).

[lexikos]

N.B. Pause does not default to true, or any other value.

If unset or omitted, the current thread is paused. Otherwise, specify one of the following values:
1 or True: Marks the thread beneath the current thread as paused

Pause and Suspend are often used without parameters, with different usage. Something like ^1::Suspend might be common, with ^2::Pause -1 being similar while Pause on its own would more often be used for debugging, paired with ListVars, for instance. For WinSetAlwaysOnTop, it is probably more typical to include the WinTitle parameter, which may create a bias toward specifying the first parameter as well. I suppose that ^3::WinSetAlwaysOnTop would work with #HotIf WinActive(...).

[mikeyww]

I stand corrected! I should say that Pause does not default to a toggle.

I'll maintain my current vote for WinSetAlwaysOnTop.