function timeouts: remove '0 is the same as specifying 0.5'

[jeeswg]

There are around 8 functions with a timeout parameter, with a stipulation such as:

Specifying 0 is the same as specifying 0.5.

I would make 0 mean 0 in AHK v2.

The reasons for this proposal:
- Simplicity.
- Consistency across functions with a timeout parameter. Not having to remember which treat 0 literally, and which don't.
- Sometimes 0 is useful, e.g. it makes ClipWait into an IsClipboardEmpty function.
- Avoid confusion. Many are confused by the significance of '0 is the same as specifying 0.5', why is it like that, and wonder if they have understood the documentation correctly.

For AHK v1, for any commands where '0 is the same as specifying 0.5', it would help to add a consistent line, to reassure users reading the documentation. I'd suggest something like:
To wait for approximately 0 seconds, use 0.001.

I checked the AHK v2 chm file for functions with parameters containing Sec/Timeout/Wait:

Code: Select all

;did have '0 same as 0.5' stipulation:

ClipWait [Timeout, WaitForAnyData]
StatusBarWait [BarText, Timeout, Part#, WinTitle, WinText, Interval, ExcludeTitle, ExcludeText]
WinClose [WinTitle, WinText, SecondsToWait, ExcludeTitle, ExcludeText]
WinKill [WinTitle, WinText, SecondsToWait, ExcludeTitle, ExcludeText]
WinWait [WinTitle, WinText, Timeout, ExcludeTitle, ExcludeText]
WinWaitActive [WinTitle, WinText, Timeout, ExcludeTitle, ExcludeText]
WinWaitNotActive [WinTitle, WinText, Timeout, ExcludeTitle, ExcludeText]
WinWaitClose [WinTitle, WinText, Timeout, ExcludeTitle, ExcludeText]

;didn't have '0 same as 0.5' stipulation:

ProcessWait(PIDOrName [, Timeout])
ProcessWaitClose(PIDOrName [, Timeout])
SendMessage(Msg [, wParam, lParam, Control, WinTitle, WinText, ExcludeTitle, ExcludeText, Timeout])
Sleep DelayInMilliseconds
#ClipboardTimeout Milliseconds
#HotkeyInterval Milliseconds
#HotkeyModifierTimeout Milliseconds
#IfTimeout Timeout

Some other functions with timeouts: Input, InputBox, InputHook, KeyWait, MsgBox, SetTimer.
(I've tried my best to list all relevant functions/functionality, it's possible I've missed some.)

For reference: SendMessage, SetTimer and Sleep are unusual in accepting values in milliseconds. (I'm not proposing to change this.)

I used this code to retrieve text from the syntax blocks:

Code: Select all

SetBatchLines, -1
ListLines, Off

;get syntax text from AutoHotkey.chm (note: decompile AutoHotkey.chm using 7-Zip)
vDir1 := A_Desktop "\AutoHotkey_2.0-a107"
vOutput := ""
VarSetCapacity(vOutput, 1000000*2)
vPfx := "==================================================`r`n"
vSfx := ""
;vPfx := vSfx := ""
Loop Files, % vDir1 "\*.htm", % "FR"
{
	vPath := A_LoopFileFullPath

	oDoc := ComObjCreate("HTMLFile")
	vMeta := "<meta http-equiv='X-UA-Compatible' content='IE=9'>"
	oDoc.Write(vMeta)
	FileRead, vHtml, % vPath
	oDoc.Write(vHtml)

	oElts := oDoc.getElementsByClassName("optional")
	Loop % oElts.length
	{
		oElt := oElts[A_Index-1]
		oElt.innerText := "[" oElt.innerText "]"
	}

	oElts := oDoc.getElementsByClassName("Syntax")
	Loop % oElts.length
	{
		oElt := oElts[A_Index-1]
		vCode := oElt.outerText
		if !(vCode = "")
			vOutput .= vPfx vCode vSfx "`r`n"
	}
	oDoc := oElts := oElt := ""
}
Clipboard := vOutput vPfx
MsgBox, % "done"
return