GuiCreate and Gui.Add parameter order

Discuss the future of the AutoHotkey language

(Options, Text) or (Text, Options)?

Options, Text
Text, Options
Total votes: 15
Posts: 7088
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

GuiCreate and Gui.Add parameter order

09 Jun 2020, 20:35

The original Gui command uses the order Options, Text. When fincs first introduced the GUI objects, the order was swapped to Text, Options. However, I had doubts about the change (and so did fincs). I wrote about swapping it back, saw no objections, then swapped it back to Options, Text before officially including the GUI objects in an alpha release.

After the return of fincs ...
fincs wrote:
15 Oct 2019, 19:25
I still think Options should not be the first parameter for GuiCreate or Gui.AddCtrl.
... I made a note to review this at some point. So now I'm doing that.

I could go either way, so I have created a poll. I expect that anyone voting should have had plenty of time by now to use GuiCreate() and Gui.Add() and form their own opinion on the syntax.

I have collected some relevant points:
fincs wrote:
20 Feb 2015, 17:28
I am not sure if reversing the parameter order in AddCtrl() was a good idea (i.e. Options, Value vs Value, Options).
lexikos wrote:
23 Mar 2017, 21:38
Gui.AddCtrl(Text, Options) vs Gui Add, Ctrl, Options, Text is bound to cause confusion with users familiar with the old order. Since even fincs expressed doubt about it, I'd guess it should be swapped back. Perhaps Options would be omitted more often than Text, but usually there's at least one option. Another point is aesthetics (which can affect readability); with several controls on a Gui, the options parameters often line up (i.e. when they aren't preceded by text of varying length).

Similarly, GuiCreate(Title, Options) is opposite to Gui New, Options, Title. However, I think GuiCreate requires a different way of thinking than Gui New. Gui New is less familiar (since it's optional and relatively new) and called much less frequently than Gui Add, so less likely to be a problem. On the other hand, I'm not certain which parameter would be used on its own more often, though my instinct is to put Title first.
fincs wrote:
24 Mar 2017, 06:35
The main reason this was changed was that the syntax for specifying just the text and not the option (e.g. btn := gui.AddButton("", "Text") or gui.AddLabel,, Text) contained that extra empty parameter that looked ugly. I had always thought that the Text parameter was more used than the Options and thus it should be promoted to be the first parameter. However, it is indeed true that existing users would be confused by the change, so ultimately perhaps it should be changed back in gui.AddCtrl. But again, if GuiCreate keeps Title first, it would be inconsistent with it. I agree that gui.Show should lose its Text parameter since it's redundant.
just me wrote:
29 Apr 2017, 10:44
When I started to test the first test built I immediately got the impression that Text, Options would be the 'natural' order. But that might have had two main reasons:
  • I started testing with simple Gui examples.
  • I decided to not use vName and gEventhandler options in general.
The change of the order was surprising me, so I jumped in to question the reasons. After this discussion I cannot decide which order would be the 'better' or 'more natural'. But I can live with both of them.
Ragnar wrote:
25 Apr 2017, 02:22
In my opinion, the options are of secondary importance when creating Gui/controls. Additionally it's somewhat easier to read, especially for beginners (for example, GuiCreate("Title of Window") vs GuiCreate(, "Title of Window"))
just me wrote:
25 Apr 2017, 09:46
IMO, the previous order is looks and feels better. Very most of the controls will get a value when created. So (previous [order]) GuiAdd("Control", ,"Options") will be the exception. For the sake of consistency the previous order should be kept for GuiCreate(), too.
Posts: 4464
Joined: 17 Jul 2016, 01:02

Re: GuiCreate and Gui.Add parameter order

10 Jun 2020, 01:23

I was thinking that (text, option) was better, because when ( :?: ) the options parameter is changed to accept an object, it looks better to not have a trailing }, text_param. Example,

Code: Select all

aGui.addEdit {
		color : 'blue',
		disabled : true
	}, 'text'

aGui.addEdit 'text', {
		color : 'blue',
		disabled : true
But I suppose, with the text parameter last, you get a more consistent view regardless of how long text is.

I think it can be changed to be TextOrOptions, a string/number/array is text, an object is options, which could contain text. Example,

Code: Select all

; text and opt
aGui.addEdit {
	color : 'blue',
	disabled : true,
	text : 'text'
; opt
aGui.addEdit {
	color : 'blue',
	disabled : true,
; text
aGui.addEdit 'text'
Maybe value is a better name than text.

However, I would go with (text, options) if nothing about the options parameter is going to change, I think Ragnar put it well enough. And I think any arguments containing v1 are automatically disqualified.

Posts: 614
Joined: 13 Aug 2016, 21:04
GitHub: iseahound

Re: GuiCreate and Gui.Add parameter order

10 Jun 2020, 09:16

Parameter order:
Actions should be first.
Values are in the middle.
Optional Parameters should be last.

Sorry Helgef, I'm not a fan of TextOrOptions, since the text is more likely to change than the options (style). One suggestion would be to save the last options object (style) passed, such that repeated calls do not need to supply their own options object (style).

EDIT: The reason why an options object should be saved has to do with scope of the calling function. Options are highly localized, so it's very difficult to reference or pass the last known options object (style). Common code patterns would involve creating a GUI object, and letting the options object lose its reference. However, if the options object (style) is cached in the GUI object, as long as options remains unset the existing options object (style) should be used.
Posts: 614
Joined: 13 Aug 2016, 21:04
GitHub: iseahound

Re: GuiCreate and Gui.Add parameter order

10 Jun 2020, 12:03

Actually, I changed my mind after looking at some Flutter code examples. They mix Text and Options into a single object called a build context. Didn't look too deeply into the language, but I wouldn't mind if they were combined.
Posts: 7088
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: GuiCreate and Gui.Add parameter order

10 Jun 2020, 16:31

It occurred to me that one can test and prepare for the potential change by using a method hooking technique. This swaps the parameters for all GuiCreate, Gui.Add and Gui.AddCtrl calls:

Code: Select all


g := GuiCreate("HW")
g.Add "Text", "Hello", "cRed"
g.Add "Edit"
g.AddText "World!", "cBlue"
g.AddButton("Close").OnEvent("Click", (*) => ExitApp())

FutureSwapGuiParams() {
    g := GuiCreate(), b := g.base, g.Destroy()
    for mn, m in b.OwnMethods()
        if mn = "Add"
            m.DefineMethod "Call", Func("Swp").Bind(3, m.GetMethod("Call"))
        else if SubStr(mn, 1, 3) = "Add"
            m.DefineMethod "Call", Func("Swp").Bind(2, m.GetMethod("Call"))
    f := Func("GuiCreate")
    f.DefineMethod "Call", Func("Swp").Bind(1, f.GetMethod("Call"))
    Swp(np, call, f, p*) {
        ; Swp(@GuiCreate, Opt, Text, Evt)
        ; Swp([email protected], G, Type, Opt, Text)
        ; Swp([email protected], G, Opt, Text)
        np := f.Name = "GuiCreate" ? 1 : SubStr(f.Name, -3) = "Add" ? 3 : 2
        if p.Length >= np {
            if p.Length = np
                p.Length := np + 1
            p.InsertAt(np + 1, p.RemoveAt(np))
            return %call%(f, p*)
        catch e
            throw Exception(e.Message, -1, e.Extra)
One could also experiment with allowing an object for Options, adding redundant things like { OnClick: button => ExitApp() }, etc.
User avatar
Posts: 1195
Joined: 06 Oct 2015, 21:39

Re: GuiCreate and Gui.Add parameter order

10 Jun 2020, 20:49

I like Helgefs approach. However, I’m biased because it’s something I’m quite used to in JavaScript
User avatar
Posts: 4475
Joined: 30 Sep 2013, 01:01
Location: Germany

Re: GuiCreate and Gui.Add parameter order

11 Jun 2020, 04:01

I would very much like to have options be an object.
That beimg said text is an option.
It shouldnt receive any kind of special treatment.
Recommends AHK Studio
Posts: 7088
Joined: 30 Sep 2013, 04:07
GitHub: Lexikos

Re: GuiCreate and Gui.Add parameter order

11 Jun 2020, 15:27

Options object: If it can be done in a way that avoids duplicating much code, it's likely that I will accept a PR, or do it myself at some stage after v2 exits alpha. In theory, the option parsing could be abstracted to improve flexibility and maintainability, having option syntax (for strings and objects) similar across all functions.
Posts: 4070
Joined: 11 Jan 2017, 17:59

Re: GuiCreate and Gui.Add parameter order

11 Jun 2020, 17:42

i see no benefit to Text, Options over how it is now Options, Text. not in terms of readability, nor familiarity, nor user friendlyness. some times Text gets elided, other times Options. most of the times neither does. some times Text ends up being longer, and vice versa. choosing one over the other solely on the basis of this seems senseless to me.

moreover, if we eventually go through with @Helgef's proposal for configuring controls with an object, chances are both parameters get consolidated into a single one. if that happens, having changed the ordering now will have been pointless.
my take on it: stick with the status quo. saves me a bunch of gui rewrites(which in fairness will likely end up a search/replace operation, but one ill have to carry out nonetheless)
Posts: 10
Joined: 05 Dec 2018, 04:06

Re: GuiCreate and Gui.Add parameter order

12 Jun 2020, 15:11

I use alpha (for now) only for prototype testing. I don't need "Text" at all and don't want to spend any sec thinking about it. If I later decide to use the script I can easily jump to the end of the command and add what I want 😎.

Posts: 1
Joined: 12 Jun 2020, 16:50

Re: GuiCreate and Gui.Add parameter order

12 Jun 2020, 17:04

IMO Options, Text is better.
The example below is easier to read/refactor if Options is first.

Code: Select all

; Options first:
    g.Add("Text", "X## Y## W## H## +0x########", "long string long string long string long string")
    g.Add("Edit", "X## Y## W## H## +0x########", "")
    g.Add("Checkbox", "X## Y## W## H## +0x########", "")

; Text first:
    g.Add("Text", "long string long string long string long string", "X## Y## W## H## +0x########")
    g.Add("Edit", "", "X## Y## W## H## +0x########")
    g.Add("Checkbox", "", "X## Y## W## H## +0x########")
User avatar
Posts: 1123
Joined: 15 Aug 2014, 15:18

Re: GuiCreate and Gui.Add parameter order

12 Jun 2020, 20:08

I like to start writing scripts without any appellation. Therefore "Text" should be the last parameter.

Return to “AutoHotkey v2 Development”

Who is online

Users browsing this forum: No registered users and 3 guests