Parameter order

Discuss the future of the AutoHotkey language
lexikos
Posts: 6652
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Parameter order

11 Apr 2017, 16:57

There are several commands which have a parameter order that seems awkward to me.

ControlMove, Control, X, Y, Width, Height [, WinTitle, WinText, ExcludeTitle, ExcludeText]
; I think the idea is that the Width and Height are omitted more often than Control. However, it is inconsistent with ControlGetPos.

ControlSend [, Control, Keys, WinTitle, WinText, ExcludeTitle, ExcludeText]
; I think many users confuse the order and put Keys first. Even I do. I haven't thought of a reason for this order. It makes no sense to omit Keys, and yet Control is often omitted.

ControlSetText [, Control, NewText, WinTitle, WinText, ExcludeTitle, ExcludeText]
; I'm not sure what the purpose is. Maybe just that when Control is the control's current text, we write the old text followed by the new text. Seems inconsistent with ControlGetText.

WinSetTitle, NewTitle
WinSetTitle, WinTitle, WinText, NewTitle [, ExcludeTitle, ExcludeText]
; It's like ControlSetText, only there are two Win parameters, two "modes" to remember, and it deviates from the usual Win pattern. Also inconsistent with WinGetTitle.

WinMove, X, Y
WinMove, WinTitle, WinText, X, Y [, Width, Height, ExcludeTitle, ExcludeText]
; I usually omit WinText, but often specify Width and Height. Even when omitting Width and Height, I think it's easier to remember X, Y, Width, Height as a set than it is to remember WinTitle and WinText are put first and split from Exclude'. It is inconsistent with WinGetPos.

Many commands have the sequence "Control, WinTitle, WinText, ExcludeTitle, ExcludeText" (or just the last four), so it may be counter-intuitive to deviate from that. Even if strictly sticking to this order increases the frequency of blank parameters/commas, it may be worthwhile because it is easier to remember a more common pattern. WinTitle is like the "namespace" for the Control, and sometimes even specifies the control itself (ahk_id), so it's probably better to keep them together.
guest3456
Posts: 2650
Joined: 09 Oct 2013, 10:31

Re: Parameter order

11 Apr 2017, 23:18

def WinMove

just me
Posts: 6511
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Parameter order

12 Apr 2017, 03:13

I'd prefer the order: command, command options, controlandorwindow criteria:

Code: Select all

ControlMove [, X, Y, Width, Height, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
ControlSend [, Keys, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
ControlSetText [, NewText, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]

WinSetTitle, NewTitle [, WinTitle, WinText, ExcludeTitle, ExcludeText]
WinMove [, X, Y, Width, Height, WinTitle, WinText, ExcludeTitle, ExcludeText]
Also, if it isn't implemented already, ahk_id %ControlID% (or similar) should be permitted for the Control parameter of Control... commands.

Another related command:

Code: Select all

ControlClick [, Control-or-Pos, WinTitle, WinText, WhichButton, ClickCount, Options, ExcludeTitle, ExcludeText]
lexikos
Posts: 6652
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Parameter order

12 Apr 2017, 03:32

just me wrote:I'd prefer the order:
That order is exactly what I was thinking.

The "ahk_" keywords are for WinTitle, and have never had meaning anywhere else. GuiControl and GuiControlGet in v1.1.04+ accept a HWND directly, without any special prefix. I think it would be reasonable to give these commands the same treatment, but on the other hand, WinTitle parameters haven't been afforded that convenience (yet?).

I intentionally avoided mentioning ControlClick because I think it needs more than reordering, such as combining WhichButton, ClickCount and Options. I suppose it should also be made consistent with whatever click command v2 will have, or either one if Click and MouseClick are both kept in some form. At the moment it's inconsistent with both.
just me
Posts: 6511
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Parameter order

12 Apr 2017, 03:52

lexikos wrote:GuiControl and GuiControlGet in v1.1.04+ accept a HWND directly, without any special prefix. I think it would be reasonable to give these commands the same treatment, ...
should be sufficient.
just me
Posts: 6511
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Parameter order

12 Apr 2017, 04:24

Because we're just talking about it:

Code: Select all

ControlMove [, X, Y, Width, Height, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
Did you consider to replace the first four parameters with one 'option string' as used with the (old and new) GUI interface?
User avatar
Exaskryz
Posts: 2876
Joined: 17 Oct 2015, 20:28

Re: Parameter order

12 Apr 2017, 06:12

tl;dr There's probably no optimal solution. I like the Control parameter being first, but also appreciate the logic of WinTitle being immediately after Control. If, in a bigger change, ExcludeTitle and ExcludeText could be omitted by merging them into WinTitle and WinText, it'd reduce the number of omitted parameters and they can be shifted toward the front of the command parameters immediately after Control.




For ControlMove, ControlSend, and ControlSetText, I have found it intuitive for the first parameter to be the control. "What am I moving/sending to/setting?" "OK, to where/what/to what?"

But at the same time, I do see the use for specifying Control and WinTitle/text/excludes in a consecutive order.

I can easily wrap my head around the ControlSend change with Keys coming first, as it is like the Send command that way. I can not-as-easily wrap my head around the ControlSetText change, in the same light as the ControlSend even if Control will be included very often, if not always. But I'm struggling with the ControlMove. It seems weird to do the mental/human-read process "Move something to X and Y with this Width and Height. Oh, and that something is Control."

I wonder if it'd be feasible, but admittedly a bigger change, to condense the WinTitle/Text/Exclude parameters? What if there was a syntax for WinTitle and WinText that had an Exclude portion, like ahk_exclude as a prefix? While we can specify WinTitles as ahk_exe chrome.exe YouTube, it'd just be a matter of putting in ahk_exclude as like ahk_exe chrome.exe YouTube ahk_exclude Music.

Doing that, it'd open up the possibility of keeping Control as the first parameter, making an optional WinTitle and WinText, and then specifying things like coordinates.

ControlMove, Control, WinTitle, WinText, X, Y, Width, Height could be written as an example with Notepad: ControlMove, Edit1, Notepad ahk_exclude Notepad++,,45,50,100,100. And if you didn't want to even specify a wintitle as it'd be optional, then ControlMove, Edit1,,,45,50,100,100. 3 consecutive commas is more manageable to me than 5.

But that'd on the flipside be unintuitive to a ControlSend; it may need a short-hand syntax like WinMove, X, Y of just ControlSend, Keys.
User avatar
jeeswg
Posts: 6819
Joined: 19 Dec 2016, 01:58
Location: UK

Re: Parameter order

12 Apr 2017, 07:55

Code: Select all

WWEE: WinTitle, WinText, ExcludeTitle, ExcludeText
XYWH: X, Y, Width, Height
Note: these are abbreviations for 4 parameters, not a call for a merged parameter.

Control, Cmd [, Value, Control, WWEE]
ControlGet, OutputVar, Cmd [, Value, Control, WWEE]
--> ControlCmd [, Value, Control, WWEE]
--> ControlGetCmd, OutputVar [, Value, Control, WWEE]

ControlClick [, Control-or-Pos, WW, WhichButton, ClickCount, Options, EE]
ControlSend [, Control, Keys, WWEE]
ControlSendRaw [, Control, Keys, WWEE]
--> ControlSend [, Keys, Control, WWEE]
--> ControlSendRaw [, Keys, Control, WWEE]

ControlGetFocus, OutputVar [, WWEE]
ControlFocus [, Control, WWEE]

ControlGetPos [, XYWH, Control, WWEE]
ControlMove, Control, XYWH [, WWEE]
--> ControlMove, XYWH, Control [, WWEE]

ControlGetText, OutputVar [, Control, WWEE]
ControlSetText [, Control, NewText, WWEE]
--> ControlSetText [, NewText, Control, WWEE]

WinGetPos [, XYWH, WWEE]
WinMove, XY
WinMove, WW, XY [, WH, EE]
--> WinMove, XYWH [, WWEE] ;(square brackets placed differently if needed)

WinGetTitle, OutputVar [, WWEE]
WinSetTitle, NewTitle
WinSetTitle, WW, NewTitle [, EE]
--> WinSetTitle, NewTitle [, WWEE]
People always expect 'Control, WWEE', i.e. 'control, window'. Also, ideally, 'get' and 'set' commands should be mirror images of each other.

For ControlXXX and WinXXX commands where the WW and EE are split, and for commands generally, it makes sense just to remove the EE parameters (and bring in new 'ahk_' syntax like 'ahk_notclass' or 'ahk_!class' https://autohotkey.com/boards/viewtopic ... 19#p141819), rather than rearrange the parameters to get WWEE together in every command. In theory, if ExcludeTitle were kept, its abilities should mirror those of WinTitle, although I don't personally use it.

==================================================

Re. just me's comments. I feel that ahk_id %ControlHWnd% should remain possible in the WinTitle parameter as it is now, although logically speaking you might not be able to prevent the WinTitle parameter from taking a control's hWnd (rather than a window's hWnd), controls are windows after all. Theoretically you could have ahk_id %hCtl% in both the Control and WinTitle parameters!?

Unless I misunderstood just me, and he was referring to vCtlID := DllCall("user32\GetDlgCtrlID", Ptr,hCtl), in that case, I'm unsure of what 'ahk_' syntax to add, since control 'ID' and control 'HWnd', can cause confusion.

[EDIT:] Re. just me's proposal.
ControlGetText, OutputVar, Control, WinTitle
ControlGetText, vText, % "ahk_id " hCtl, % "ahk_id " hWnd ;just me's proposal
ControlGetText, vText,, % "ahk_id " hCtl ;currently possible
I'm not for or against this proposal: it is kind of redundant, but, it might be more intuitive in certain circumstances. I suppose in such a situation, AHK would ignore the WWEE parameters.

==================================================

In my opinion, XYWH should stay as 4 parameters, partly because otherwise you get: "x" x "y" y "w" w "h" h, or, "x%x% y%y% w%w% h%h%", which are awkward.

While generally loath to reorder parameters, I agree that these changes are worth it.
Last edited by jeeswg on 12 Apr 2017, 16:28, edited 5 times in total.
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
nnnik
Posts: 4272
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Parameter order

12 Apr 2017, 09:33

I'd prefer the order: command, command options, controlandorwindow criteria:
Do you guys also prefer

Code: Select all

Variable, Value =: [ selector* ]
Recommends AHK Studio
guest3456
Posts: 2650
Joined: 09 Oct 2013, 10:31

Re: Parameter order

12 Apr 2017, 10:16

lexikos wrote: I intentionally avoided mentioning ControlClick because I think it needs more than reordering, such as combining WhichButton, ClickCount and Options. I suppose it should also be made consistent with whatever click command v2 will have, or either one if Click and MouseClick are both kept in some form. At the moment it's inconsistent with both.
if ControlClick will undergo some refactoring, i'd just like to re-request the addition of a WM_MOUSEMOVE option

just me
Posts: 6511
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Parameter order

12 Apr 2017, 10:51

jeeswg wrote:Unless I misunderstood just me, and he was referring to vCtlID := DllCall("user32\GetDlgCtrlID", Ptr,hCtl) ...
Where did you read that?
nnnik wrote:Do you guys also prefer ...
As far as I can see this thread is related to Win... and Control... commands.
User avatar
nnnik
Posts: 4272
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Parameter order

12 Apr 2017, 11:31

Let me clarify my point:
Within Object based syntax and operator based syntax the order is the other way around - it tells you what is changing before it tells you how exactly it is changing.( Which towards me is a much more logical approach )
Of course function/command based syntax is slightly different and can be used to create a variety of meanings but breaking it down to "tells you which action is taken" makes more logical to specify the action before the target.
And yes everything you just mentioned is a function/command.
However if AutoHotkey has a future it will slowly and gradually move towards more OOP styled approach for a lot of things. And specifically Windows APIs are basically made for that.
So if you ask me changing parameter order now might not be a complete mistake but breaks the habits of everybody using it and the order will be changed back in the future again.
So why do you even bother to change it?
Recommends AHK Studio
guest3456
Posts: 2650
Joined: 09 Oct 2013, 10:31

Re: Parameter order

12 Apr 2017, 11:42

just me wrote:I'd prefer the order: command, command options, controlandorwindow criteria:

Code: Select all

ControlMove [, X, Y, Width, Height, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
ControlSend [, Keys, Control, WinTitle, WinText, ExcludeTitle, ExcludeText]
i think i prefer it too, but consider, in v2 all commands can/will be used as functions too. in my mind i don't really care too much about command param order, but for functions i do.

what would i rather write/read?

Code: Select all

		
ControlSend("hello world", "Edit1", "ahk_class Notepad")

;or

ControlSend("Edit1", "hello world", "ahk_class Notepad")
i'm not sure. does the 2nd make more sense when read in conjunction with the actual command/func name itself? and i guess this relates to nnnik's point about "it tells you what is changing before it tells you how exactly it is changing"

but really i dont care either way. i think i like the proposed changes
nnnik wrote: So if you ask me changing parameter order now might not be a complete mistake but breaks the habits of everybody using it and the order will be changed back in the future again.
can you give an example of how you envision it "changing back in the future"?

User avatar
nnnik
Posts: 4272
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: Parameter order

12 Apr 2017, 11:48

Code: Select all

Window[ controlSpecifier ].action( parameters* )
control := Window[ controlSpecifier ]
controlAttribute := control.getterFunction( parameters* )
control.setterFunction( controlAttribute, parameters* )
actionResult := control.takeAction( parameters* )
This would reverse the order as the target is always first.
Recommends AHK Studio
Helgef
Posts: 3981
Joined: 17 Jul 2016, 01:02
Contact:

Re: Parameter order

12 Apr 2017, 11:52

I like the suggestion to condense the parameters. My suggestion,

Code: Select all

Command, Target,command-specific-parameters, Exclude
for example, (which doesn't look condensed since I'm examplifying everything at once)

Code: Select all

ControlMove, "ahk_ctrl" edit1 "ahk_title" a.txt "ahk_exe" notepad.exe, x, y, w, h, "ahk_text" once upon a time "ahk_id" %somespecificid% ; quotation marks for highlighting purposes only
Clarification, there is one parameter for identifying the target of the command, and one for excluding targets. The Control parameter is removed, and replaced by ahk_ctrl controlName. ahk_title is added for specifying that you mean the actual text in the caption of a window. Similarly, ahk_text would specify that you refer to the text found in the window.
So Target is an extension of WinTitle but renamed since the parameter name WinTitle is to narrow. And the fact that ExcludeTitle only refers to the text in the window caption is confusing/limiting, hence the suggestion for the Exclude parameter, which would behave as Target but for excluding :crazy: (I guess the Exclude parameter is slightly off topic).

In any case, we who cannot remember anything needs to check the documentation anyways :D
Cheers.
guest3456 wrote: i don't really care too much about command param order, but for functions i do.
+1
just me
Posts: 6511
Joined: 02 Oct 2013, 08:51
Location: Germany

Re: Parameter order

12 Apr 2017, 16:11

To clarify my point of view:

Code: Select all

ControlGet, OutputVar, Cmd , Value, Control, WinTitle, WinText, ExcludeTitle, ExcludeText ; at present
                      > what       <> which control                                       <
Control, Cmd , Value, Control, WinTitle, WinText, ExcludeTitle, ExcludeText ; at present
        > what       <> which control                                       <
ControlSetText , NewText, Control, WinTitle, WinText, ExcludeTitle, ExcludeText ; in future
                > what   <> which control                                       <
ControlMove, X, Y, Width, Height, Control, WinTitle, WinText, ExcludeTitle, ExcludeText ; in future
            > what              <> which control                                       <
lexikos
Posts: 6652
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Parameter order

12 Apr 2017, 17:05

Exaskryz wrote:If, in a bigger change, ExcludeTitle and ExcludeText could be omitted by merging them into WinTitle and WinText,
See WinTitle and Window Groups.
For ControlMove, ControlSend, and ControlSetText, I have found it intuitive for the first parameter to be the control. "What am I moving/sending to/setting?" "OK, to where/what/to what?"
That same logic is not applied to WinSet, Control, or any of the "Get" commands. For the "Get" commands, if that's only to follow the pattern that OutputVars come first, how is that more important than the Control, WinTitle, etc. pattern?
I can not-as-easily wrap my head around the ControlSetText change,
Even though it mirrors the "Get" commands?
It seems weird to do the mental/human-read process "Move something to X and Y with this Width and Height. Oh, and that something is Control."
But it's fine to say "Get the position into variables X, Y, Width and Height, of the window W"?

I've never found it particularly necessary to follow the word order of how a function is explained in English. It is constraining, and the English language is weird.
3 consecutive commas is more manageable to me than 5.
When would there be 5? We wouldn't be omitting all of the coordinates.
But that'd on the flipside be unintuitive to a ControlSend;
I think that sticking to one consistent and easy to remember rule is ultimately more intuitive.
lexikos
Posts: 6652
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: Parameter order

12 Apr 2017, 17:18

nnnik wrote:So why do you even bother to change it?
It wouldn't break habit for me. I have to look up the usage of those commands every time I use them, because they deviate from common patterns in hap-hazard ways.

Objects follow a common and obvious pattern: the target object always comes first. The window and control commands currently follow a few different patterns, which is harder to remember than just one pattern. If they all had the (control and) window parameters at the end, it would be easier to translate to object syntax if the time comes: just remove the parameters from the end and replace "Win" or "Control" with the object.
guest3456 wrote:does the 2nd make more sense when read in conjunction with the actual command/func name itself?
I say no, it doesn't. I see the window title as a secondary value for identifying the control. If the parameter order is based on logic rather than just frequency of use (optimising for omitting parameters), why is the window title separated from the control?

For instance, ControlSend("Edit1", "hello world", "ahk_class Notepad") is something like "send to the control Edit1 the text hello world, and the control is on the Notepad window".
User avatar
Exaskryz
Posts: 2876
Joined: 17 Oct 2015, 20:28

Re: Parameter order

12 Apr 2017, 18:00

lexikos wrote:
Exaskryz wrote:If, in a bigger change, ExcludeTitle and ExcludeText could be omitted by merging them into WinTitle and WinText,
See WinTitle and Window Groups.
Will do.
For ControlMove, ControlSend, and ControlSetText, I have found it intuitive for the first parameter to be the control. "What am I moving/sending to/setting?" "OK, to where/what/to what?"
That same logic is not applied to WinSet, Control, or any of the "Get" commands. For the "Get" commands, if that's only to follow the pattern that OutputVars come first, how is that more important than the Control, WinTitle, etc. pattern?
I can not-as-easily wrap my head around the ControlSetText change,
Even though it mirrors the "Get" commands?
It seems weird to do the mental/human-read process "Move something to X and Y with this Width and Height. Oh, and that something is Control."
But it's fine to say "Get the position into variables X, Y, Width and Height, of the window W"?
I do see your point, but the solutions would be throwing omittable parameters to the front of the command, which can then be confusing and make the overall code look intimidating to someone new. (All these commas? What does that mean? Why do I need N commas for one command and M for another? Then they learn there's optional parameters that explain it.)
I've never found it particularly necessary to follow the word order of how a function is explained in English. It is constraining, and the English language is weird.
It totally is, yep. Spanish could be more intuitive to me for a coding process as well, with the Noun followed by the Adjectives.
3 consecutive commas is more manageable to me than 5.
When would there be 5? We wouldn't be omitting all of the coordinates.
I was thinking on a command like ControlSend. If the syntax were ControlSend, WinTitle, WinText, ExcludeTitle, ExcludeText, Control, Keys. We'd omit the first 4 parameters, leaving 4 (or 5) commas... and the first parameter being omittable would actually be a mess, so, this approach probably can't even be done from what I was thinking this morning. So, it may have no bearing at all, unless we require hard commas after command names.
But that'd on the flipside be unintuitive to a ControlSend;
I think that sticking to one consistent and easy to remember rule is ultimately more intuitive.
[/quote]

I agree, it will be once your intuition is to use the syntax. I'm thinking for a brand new comer who has been able to play with loose syntax, it wouldn't be quite as intuitive.

I ultimately will be alright with any decision myself, I was just throwing out some ideas and thoughts. I'll trust anyone else's judgement, as I just think irrationally sometimes ;)
guest3456
Posts: 2650
Joined: 09 Oct 2013, 10:31

Re: Parameter order

12 Apr 2017, 19:02

lexikos wrote:
guest3456 wrote:does the 2nd make more sense when read in conjunction with the actual command/func name itself?
I say no, it doesn't. I see the window title as a secondary value for identifying the control. If the parameter order is based on logic rather than just frequency of use (optimising for omitting parameters), why is the window title separated from the control?

For instance, ControlSend("Edit1", "hello world", "ahk_class Notepad") is something like "send to the control Edit1 the text hello world, and the control is on the Notepad window".
Yep makes sense. I think I agree


Return to “AutoHotkey v2 Development”

Who is online

Users browsing this forum: No registered users and 8 guests