GuiCreate and Gui.Add parameter order

[lexikos]

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

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:

I am not sure if reversing the parameter order in AddCtrl() was a good idea (i.e. Options, Value vs Value, Options).

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.

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.

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.

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

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.

[Helgef]

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.

Cheers.

[iseahound]

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.

[iseahound]

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.

[lexikos]

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

FutureSwapGuiParams()

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

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(G.@Add, G, Type, Opt, Text)
        ; Swp(G.@AddCtrl, 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))
        }
        try
            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.

[kczx3]

I like Helgefs approach. However, I’m biased because it’s something I’m quite used to in JavaScript

[nnnik]

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.

[lexikos]

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.

[swagfag]

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)

[heavyhotuser]

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 .

Salute!

[gosso]

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########")

[rommmcek]

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