Parameter order

[lexikos]

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]

def WinMove

[just me]

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]

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]

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]

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?

[Exaskryz]

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.

[jeeswg]

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.

[nnnik]

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

Do you guys also prefer

Code: Select all

Variable, Value =: [ selector* ]

[guest3456]

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]

Unless I misunderstood just me, and he was referring to vCtlID := DllCall("user32\GetDlgCtrlID", Ptr,hCtl) ...

Where did you read that?

Do you guys also prefer ...

As far as I can see this thread is related to Win... and Control... commands.

[nnnik]

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?

[guest3456]

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

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"?

[nnnik]

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.

[Helgef]

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 (I guess the Exclude parameter is slightly off topic).

In any case, we who cannot remember anything needs to check the documentation anyways
Cheers.

i don't really care too much about command param order, but for functions i do.

+1

[just me]

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]

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]

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.

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".

[Exaskryz]

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]

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