parameter order

Discuss the future of the AutoHotkey language
User avatar
Posts: 5956
Joined: 19 Dec 2016, 01:58
Location: UK

parameter order

02 Mar 2018, 09:24

- In the previous 'Parameter order' thread, inconsistencies in the ControlXXX functions parameter orders were discussed.
Parameter order - AutoHotkey Community ... 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 ... m#Priority
- This would also be inconsistent with a possible future ProcessGetPriority function, e.g.:

Code: Select all

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

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

	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 ... 37&t=39809

- Also, there is a quote here re. OnMessage:
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)
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA
User avatar
Posts: 3986
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: parameter order

02 Mar 2018, 19:05

It would be better both for ControlXXX and Process to become objects due to the way they work.
Recommends AHK Studio
Posts: 6214
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: parameter order

05 Mar 2018, 03:50

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).
User avatar
Posts: 5956
Joined: 19 Dec 2016, 01:58
Location: UK

Re: parameter order

13 Mar 2018, 01:23

- 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, ...)
homepage | tutorials | wish list | fun threads | donate
WARNING: copy your posts/messages before hitting Submit as you may lose them due to CAPTCHA

Return to “AutoHotkey v2 Development”

Who is online

Users browsing this forum: No registered users and 15 guests