parameter order

[jeeswg]

- In the previous 'Parameter order' thread, inconsistencies in the ControlXXX functions parameter orders were discussed.
Parameter order - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 37&t=30439
- I noticed a similar inconsistency with the ProcessXXX functions: all of them have PID-or-Name as the first parameter except for ProcessSetPriority. This is unhelpful in terms of a mnemonic device, and arguably breaks the principle of least astonishment/surprise.
Process
https://lexikos.github.io/v2/docs/comma ... m#Priority
- This would also be inconsistent with a possible future ProcessGetPriority function, e.g.:

Code: Select all

JEE_ProcessGetPriority(vPIDOrName:="")
{
	static oArray := {0x40:"Low", 0x4000:"BelowNormal", 0x20:"Normal", 0x8000:"AboveNormal", 0x80:"High", 0x100:"Realtime"}
	;ABOVE_NORMAL_PRIORITY_CLASS := 0x8000 ;BELOW_NORMAL_PRIORITY_CLASS := 0x4000
	;REALTIME_PRIORITY_CLASS := 0x100 ;HIGH_PRIORITY_CLASS := 0x80
	;IDLE_PRIORITY_CLASS := 0x40 ;NORMAL_PRIORITY_CLASS := 0x20 ;(idle: low)

	local vPriority
	if !(vPID := ProcessExist(vPIDOrName))
		return 0

	;PROCESS_QUERY_INFORMATION := 0x400
	hProc := DllCall("kernel32\OpenProcess", UInt,0x400, Int,0, UInt,vPID, Ptr)
	vPriority := DllCall("kernel32\GetPriorityClass", Ptr,hProc, UInt)
	DllCall("kernel32\CloseHandle", Ptr,hProc)
	return oArray.HasKey(vPriority) ? oArray[vPriority] : vPriority
}

- Also, in my opinion, this important change needs more discussion:
InputBox parameter order - AutoHotkey Community
https://autohotkey.com/boards/viewtopic ... 37&t=39809

- Also, there is a quote here re. OnMessage:
v2-thoughts
https://autohotkey.com/v2/v2-thoughts.htm

OnMessage: Someone (I was unable to find the post) suggested the parameter order for the callback functions be changed, possibly because hwnd is needed more often due to the removal of A_Gui.

- I rarely use OnMessage for the AHK Gui v1 commands, and have been happy with the current parameter order.
- Although I would welcome radical changes if beneficial, I believe that this change would cause a lot of bother to users for no clear gain. AFAICS it's simple enough to just include all 4 parameters when you define the callback function. Also, there are good examples at the documentation page that omit certain parameters, suggesting that the current set-up has some advantages.
MsgMonitor(wParam, lParam, uMsg, hWnd)

[nnnik]

It would be better both for ControlXXX and Process to become objects due to the way they work.

[lexikos]

ProcessSetPriority follows the same pattern as the WinSet and ControlSet functions, and is also ordered this way because only the Priority parameter is mandatory.

ProcessSetPriority is already consistent with ProcessGetPriority([Name]). They would both follow the same patterns as WinSet/WinGet. They would both have the process name last.

nnnik's idea side-steps the issue by removing the parameters, at least for some of the functions.

A Process object might have these members:

• Exist/Status: redundant if the object was just retrieved/created, since that would mean the process exists/is running.
• Close
• Priority
• WaitClose

I doubt that these would be combined often. One would generally retrieve the object only to call a single member. This does not seem useful to me.

ProcessWait, ProcessWaitClose and ProcessExist would still be separate functions. ProcessExist (or its replacement) would be used to retrieve a Process object. ProcessWaitClose, like WinWaitClose, waits for all matching processes to close.

Hypothetically, if the Control functions are replaced with a Control object, it makes sense to do the same for the Win functions. I'm not sure I'd want this even if it came for free (with someone else doing all the work, which seems very uninteresting). Perhaps if someone else implemented it, and the API was clearly easier to use (but even that's subjective).

[jeeswg]

- Here's the fuller context for my suggestion, qualified by 'in my opinion' in each case.
- Choosing a function name and parameter order can be difficult.
- Over time I've found the best approach to be: ItemOperationProperty(Item, ...).
- Furthermore: ItemIsProperty(Item)/ItemGetProperty(Item) and ItemSetProperty(Item, NewValue).
- In the list below, functions that don't conform to that pattern, are good candidates for a parameter reordering.
- There's a simple principle for remembering what the first parameter is for all of the functions, with the ControlXXX/WinXXX functions being the only exceptions.

Code: Select all

DateXXX(Date, ...) / FormatTime(Date, ...)
DirXXX(Dir, ...)
DriveXXX(Drive, ...)
... apart from (DriveGetList)
FileXXX(Path, ...)
... apart from FileAppend/FileCreateShortcut/(FileEncoding)/(FileRecycleEmpty)/(FileSelect)/FileSetAttrib/FileSetTime
GroupActivate(Group, ...)
IniXXX(Path, ...)
... apart from IniWrite
MouseXXX(X, Y, ...)
... apart from MouseClick/MouseClickDrag
PixelXXX(X, Y, ...)
ProcessXXX(PIDOrName, ...)
... apart from ProcessSetPriority
RegXXX(Key, ...)
... apart from RegWrite
StrXXX(String, ...)
... apart from (StringCaseSense)/(StrGet)
ControlXXX(..., Control, WinTitle, WinText, ExcludeTitle, ExcludeText)
... apart from ControlClick/(ControlGetFocus)
... in my functions: CtlXXX(hCtl, ...)
WinXXX(..., WinTitle, WinText, ExcludeTitle, ExcludeText)
... in my functions: WinXXX(hWnd, ...)