parameter order

Discuss the future of the AutoHotkey language
User avatar
jeeswg
Posts: 5403
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
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)
User avatar
nnnik
Posts: 3526
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
lexikos
Posts: 6207
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
jeeswg
Posts: 5403
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, ...)

Return to “AutoHotkey v2 Development”

Who is online

Users browsing this forum: No registered users and 39 guests