Proposed New GUI API for AutoHotkey v2

[lexikos]

Due to the way Guis are implemented, retrieving the object associated to a control is only possible if you know which Gui they belong to.

The program always knows which Gui a control belongs to (unless you've changed the control's parent window). How do you think A_Gui works when a message is posted to a control?

Code: Select all

GuiFromHwndEx(hwnd) {
    local gui := ""
    while hwnd && !(gui := GuiFromHwnd(hwnd))
        hwnd := DllCall("GetParent", "ptr", hwnd, "ptr")
    return gui
}
GuiCtrlFromHwnd(hwnd) {
    local gui := GuiFromHwndEx(hwnd), ctrl
    if !gui
        return
    while hwnd && !(ctrl := gui.Control[hwnd])
        hwnd := DllCall("GetParent", "ptr", hwnd, "ptr")
}

I think it's counter-intuitive that control's have only Visible:=x while GUIs have only Show/Hide. Show/Hide feels more natural to me.

ctrl.Visible(0) and ctrl.Visible 0 ignore the parameter and return the current value, whereas ctrl.Visible[0] throws an error. It looks like you've modelled GuiControlType::Invoke after FileObject::Invoke, but FileObject treats file.x(y) as file.x := y when x is a property. I suppose the difference is that FileObject properties like Encoding check aParamCount, not IS_INVOKE_SET.

[mozmax]

hmmm... I do like fincs' gui api. Honestly, I refrained a lot from developing gui programs while I was using v1. I don't know, it just looked very complex to me. Stuff like g-labels, and v variables always kept me going back to the help documentation until I finally gave up. With this new api plus v2 syntax, I'm actually ENJOYING building gui's a lot! In fact, I'm already planning a lot of fancy stuff!

Probably, the only thing I find a bit annoying is the need to specify a variable to hold a new control's object when using the Gui.AddCtrl command whenever I need to use the control at a later time. Can't v variables be optionally used instead of classNN/HWND when addressing a control through Gui.Control[Name]? I think it would be nice if that were possible.

Also, possibly off-topic but I didn't know where to post this, besides it seems to be related only to v2-new-gui-api. Recently, I found a strange bug in the latest update (v2.0-a057). Also, all the previous versions of the new gui api except version 1 had this problem so I'm guessing something happened in the transition from version 1 to version 2. I'm using the version numbers based on the files in http://fincs.ahk4.net/files/.

I think anyone (or is it just me?) should be able to reproduce the problem with the following simple code:

Code: Select all

if regexmatch('ABC',"^(\S+)$",m){
  chars := m[1]
  msgbox ``%m[1]%`' should be ``ABC`', ``%strlower(chars)%`' should be ``abc`'
}

The original binary by Lexikos runs fine but I like the new gui api a lot so I'm sticking to version 1 of the new-gui-api binary for now.

[lexikos]

Gui Submit is useful in v1.x because the only other way to retrieve the value of a control is using an incredibly clunky GuiControlGet command. Not anymore in my Gui API, since it's a trivial ctrl.Value (and it is a get/set property, meaning it works exactly the same way as a variable).

Thinking more about this, I disagree. Gui Submit was designed that way because it's useful. Ctrl.Value is more convenient than GuiControlGet if you're using the value only once, but there's no way that it's more convenient than Gui Submit and Ctrl when you have more than a couple of controls. The ".Value" part certainly does not improve readability.

If Ctrl.Value needs to be used multiple times, I would tend to store it in another variable. In such cases, it may be less convenient than GuiControlGet Ctrl or Gui Submit.

The event handling system introduces complexity in the form of a good number of built-in variables that should have been implemented as function parameters

Appropriately-named built-in variables are often more convenient than function parameters. Information can be readily available without having to declare parameters (and remember the order), or to pick any particular order; even if the information isn't important enough to make it a parameter, such as with A_Gui and A_GuiControl in OnMessage.

I agree that passing what are essentially event parameters via generically named variables (A_EventInfo and ErrorLevel) is not ideal, especially since ErrorLevel gets overwritten, but that's fairly trivial and may be solved in the near v1.1.x future.

I think you mentioned per-GUI (or per-control?) message handlers, but having a single OnMessage handler might better fit the design of some scripts. Not having A_GuiControl or equivalent is inconvenient, though that can be alleviated by making it easier to get a control from a HWND.

Probably, the only thing I find a bit annoying is the need to specify a variable to hold a new control's object when using the Gui.AddCtrl command whenever I need to use the control at a later time. Can't v variables be optionally used instead of classNN/HWND when addressing a control through Gui.Control[Name]? I think it would be nice if that were possible.

I agree that being unable to name controls is inconvenient.

For instance, Obj[A_GuiControl "_" x]() or goto % A_GuiControl "_" x can be a useful pattern (in my recent case, x was a key name such as "Enter"), but requires knowing the "name" of the control when the script is written and being able to get that name from a control/hwnd at runtime. Without control names, it seems that SomeVar := Gui.AddCtrl() will be a common pattern, in effect just giving a different syntax to the associated variable and making it less convenient by not being able to ask a control for its name.

If the GUI or control objects supported user-defined properties, storing a name in the control object would be one fairly obvious solution. Since those objects don't support it, one would need to use wrapper classes or separate arrays.

The Gui Submit pattern could still be supported even without dynamic variables, by returning an associative array.

I think anyone (or is it just me?) should be able to reproduce the problem

I couldn't, using the latest binary from the first post in this thread, or my own based on fincs' latest source.

[fincs]

I think you mentioned per-GUI (or per-control?) message handlers, but having a single OnMessage handler might better fit the design of some scripts.

While single OnMessage handlers would benefit some scripts, other scripts would be better off with per-GUI or per-control handlers. I think it'd be best if both global and specific message handlers were available.

Without control names, it seems that SomeVar := Gui.AddCtrl() will be a common pattern, in effect just giving a different syntax to the associated variable and making it less convenient by not being able to ask a control for its name.

If the GUI or control objects supported user-defined properties, storing a name in the control object would be one fairly obvious solution. Since those objects don't support it, one would need to use wrapper classes or separate arrays.

The Gui Submit pattern could still be supported even without dynamic variables, by returning an associative array.

I think control names could be reintroduced using the vName syntax; however that has nothing to do with variables, so it may be better to use a different letter.
Gui Submit returning an associative array seems a good idea to me. It could return key-value pairs for all named controls. This could even be expanded with adding support for the inverse operation, receiving an associative array and loading control values from it.
I will implement GuiCtrlFromHwnd().

[toralf]

In case a function is called by different controls. The function has to know which control triggered the call. Similarly to A_GuiControl.
Forgive me but I do not know anymore if this is already possible in your API.

[fincs]

The control object is passed as the first parameter to control event handler functions/methods.

[mozmax]

I couldn't, using the latest binary from the first post in this thread, or my own based on fincs' latest source.

hmmm... ok, perhaps the OS I'm using (Windows 7 Professional 32-bit) might be a factor. I don't know. I keep getting an empty string in place of 'strlower(chars)'. But that's ok, I'm using the first version and I'm happy with it.

[lexikos]

While single OnMessage handlers would benefit some scripts, other scripts would be better off with per-GUI or per-control handlers.

Yes, yes; my point was about A_GuiControl in OnMessage. The rest was just context. GuiCtrlFromHwnd() is an adequate solution.

[lexikos]

ControlEvent(ctrl, eventInfo, guiEvent)

Is there a particular reason that you put eventInfo before guiEvent? It seems more logical to put the type of event first, followed by the parameter for that event. MonthCal, Text, Picture and perhaps others use A_GuiEvent but not A_EventInfo. I think only the Link control uses A_EventInfo (though I just realized that's not documented) without having multiple values for A_GuiEvent.

Is information still passed via ErrorLevel in some cases? I think there's just Link and ListView (for the "I" event).

Is the function return value used for the Custom control, or does it still use ErrorLevel?

[fincs]

Is there a particular reason that you put eventInfo before guiEvent?

No. Coming to think of it, it does make more sense to put guiEvent first. I'll change it.

Is information still passed via ErrorLevel in some cases? I think there's just Link and ListView (for the "I" event).

No, it gets appended as a fourth parameter. I forgot to document this.

Is the function return value used for the Custom control (...)?

Yes (used in WM_NOTIFY aka GuiEvent 'N').

[lexikos]

OK, thanks.

What do you think about adding a third parameter to AddCtrl() and/or a property to set/get the control's event handler? Once user-defined function objects are supported (as in the v1.1.x test builds), this could be used to associate arbitrary data with the control via an object. (The object's Call() method would handle the control's events.)

[fincs]

What do you think about adding a third parameter to AddCtrl() and/or a property to set/get the control's event handler? Once user-defined function objects are supported (as in the v1.1.x test builds), this could be used to associate arbitrary data with the control via an object. (The object's Call() method would handle the control's events.)

I originally planned adding a third parameter to AddCtrl() to replace the g option syntax, but decided it would be superfluous for the most common use cases. If I get to add support for arbitrary function objects (which is probably going to happen), I'll add this.

By the way, I am not sure if reversing the parameter order in AddCtrl() was a good idea (i.e. Options, Value vs Value, Options). Additionally, it may be a good idea to also allow for specifying the control type as a parameter as in v1.1, i.e. gui.Add(type, value, options), so that adding dynamic controls is easier.

[lexikos]

I did think there didn't seem to be a good enough reason to change the parameter order. At the very least, old habits will cause problems.

N.B. GuiCreate() and Gui.AddCtrl() have Options second, but Gui.Show() has Options first (as in v1).

Gui.Add(type,...) isn't much easier than Gui["Add" type](...), but I think some users might prefer it as a parameter anyway. I suppose it's easy to support both.

[fincs]

I just uploaded a new test build, with the following changes:

• Based on v2.0-a058-fa7ed04
• Added GuiCtrlFromHwnd() and a 'RecurseParent' option to GuiFromHwnd()
• Switched order of 'eventInfo' and 'guiEvent' in Control event handlers
• Allow gui.Add(CtrlName, ...)
• Control names reintroduced using vName option syntax -- gui.Control["Name"] also supported
• Added gui.Submit(Hide := true) -- returns an associative array containing the values of all explicitly named controls
• Added ctrl.Name (get/set)
• Added support for arbitrary callable objects as event handlers
• Added ctrl.Event (get/set)
• Added gui.OnClose/OnEscape/OnSize/OnDropFiles/OnContextMenu (get/set)

[toralf]

The OP says that the binaries are from 2014, but the text reflects the latest changes.

[fincs]

I updated the binaries with the latest v2.0-a060 changes.

[lexikos]

Update: This test build is obsolete. See the next test build.

AutoHotkey_2.0-a078-1+g72dc326.zip

---

I have merged fincs/v2-new-gui-api with v2.0-a078 to create this test build, which will become v2.0-a079. Currently the only form of documentation is fincs' first post in this topic. I have not changed the API at all, though I may.

After converting a couple of scripts to the new API, I have some comments.

The point is to replace the Gui commands with an OOP Gui API that does not have any of the quirks/eccentricities of the old Gui command set; yet retaining familiarity, ease of use and certain aspects of AutoHotkey's Gui implementation.

Yet some of the changes appear to be sacrificing familiarity without any apparent reason (perhaps to cater to someone's tastes). Specifically;

• [Update: Label was renamed back to Text.] Renaming Text to Label. Authors who knew the old name will now have to unlearn it, and what do they gain? Nothing. I guess that fincs believes "Label" to be more fitting, but I disagree. In my opinion, a "label" is generally attached to something else, to identify it, whereas "text" is just text. "Gui Add, Text" just adds text to a Gui. Maybe that text is used as a label, maybe it isn't.

[Update: OnEvent must be used to register a callback for each event, so this is now irrelevant.]

Spoiler

• Gui events such as GuiSize have a mandatory "On" prefix. Although it's trivial to use GuiOnSize() rather than GuiSize() (where "Gui" is specified as the prefix), and some scripts will need labels converted to functions anyway, it seems like one difference that we don't need. Authors who are used to the old convention may write event handlers that never get called. If one wants an "On" prefix in v1, one can use an option like +LabelGuiOn.

If the Gui has a function name prefix for events (GuiCreate's third parameter), it is used for all Gui events and all control events. It isn't possible to use the EventSource_EventName naming convention, because the Gui's prefix is used even when a control is the source of the event. By contrast, v1 had +Label for Gui events and control events had no implicit prefix. On the other hand, controls have a single handler for all events (though some controls, like Button, only have one event), so the GuiName_ControlName convention might be more suitable. In the end, I'm not sure what to do about it.

An author can give each control event handler a meaningful name without being forced to apply a common prefix to all of them (or use a class). But without the prefix, the Gui does not automatically register its own event handlers (like OnClose), so the only way to handle events is to explicitly set each event handler. This seems inconsistent. It could also be a source of confusion, in that adding a prefix will cause the gFunctionName options to stop working. If the author tests the script immediately after adding the prefix, the error messages will probably make it obvious that the new prefix must be added to each control function, but maybe not; the author might not test immediately, or might not make that connection for whatever reason.

In some scripts, it might make sense to have the events of multiple GUIs handled by a single object. In such a case, it would be helpful to be able to provide both an event handling object and a function/method name prefix. The prefix could easily be specified the way it was in v1: with the LabelPrefix option. Since event handlers aren't labels anymore, maybe PrefixPrefix or some other string would be more appropriate. gPrefix would be familiar. It would prevent the addition of any options beginning with "G", but what are the chances of that?

[Update: The order has been swapped back to Options, Text.] 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).

[Update: The order has been swapped back to Options, Title.] 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.

[Update: Title parameter was removed.] Currently Gui.Show(Options, Title) is inconsistent with GuiCreate and Gui.AddCtrl. It won't be a problem if those are changed, but does having a Title parameter really make sense in the first place? It did in v1, when a Gui was created automatically (rather than explicitly by Gui New), but now we must always call GuiCreate, which has a Title parameter. Gui.Show can be used to change the title of an existing Gui, but so can Gui.Title, which is more obvious.

[fincs]

First of all, thank you for considering my Gui work to be worth including in v2, despite it not having been updated in two years. I'd like to address some of your comments:

Renaming Text to Label. Authors who knew the old name will now have to unlearn it, and what do they gain? Nothing. I guess that fincs believes "Label" to be more fitting, but I disagree. In my opinion, a "label" is generally attached to something else, to identify it, whereas "text" is just text. "Gui Add, Text" just adds text to a Gui. Maybe that text is used as a label, maybe it isn't.

This change was mostly an experiment since other programming languages or frameworks generally call this control "Label" even if it is not attached to any control. WinForms calls it Label. Qt calls it QLabel. GTK calls it GtkLabel. Apple calls it UILabel. In Tkinter, you use a Label widget. Wikipedia calls the concept a Label control. On the other hand, the Win32 control is Static, and the MFC class is CStatic. Ultimately, I don't really mind either name, so feel free to change it back.

Gui events such as GuiSize have a mandatory "On" prefix. (...)

This was inspired by OnExit, OnClipboardChange and OnMessage. Without the "On" prefix, the Gui event names would be 'Close', 'Escape', 'Size', 'ContextMenu' and 'DropFiles'. These are very generic words that could cause trouble if the Gui handler class contains a similarly named member. Think of a "contextMenu" field, or a "size" field, or a "Close" method that is called by other parts of the script. On the other hand, you proposed to introduce PrefixPrefix or gPrefix in order to add a prefix to Gui event handler names. This would effectively solve the issue if On is removed. Also, I suppose the names of the event getters/setters (e.g. gui.OnClose := Func("somefunc").Bind("Close")) will keep the On prefix.

If the Gui has a function name prefix for events (GuiCreate's third parameter), it is used for all Gui events and all control events. It isn't possible to use the EventSource_EventName naming convention, because the Gui's prefix is used even when a control is the source of the event. By contrast, v1 had +Label for Gui events and control events had no implicit prefix. On the other hand, controls have a single handler for all events (though some controls, like Button, only have one event), so the GuiName_ControlName convention might be more suitable. In the end, I'm not sure what to do about it.

This was mostly preference. I tended to give my control's g-label names the same prefixes I used in their parent Guis, mostly to keep the code somewhat organized. In the case of non-object-based event handling, I guess it's not really necessary to prepend the parent Gui's prefix to the function names; and if the beforementioned Prefix/g option were introduced for (non-control) Gui event handlers, there would be no need whatsoever for a Gui event prefix. Also, I think that the current single-event-handler model for controls somewhat falls apart in the case of complex controls such as ListView, where the same event handler is responsible for absolutely all possible (and unrelated) events that can be triggered in the control. In fact there were so many possible events that a certain group of them have to be explicitly enabled with the AltSubmit option. Perhaps this should be broken up in smaller, single-purpose handlers just like the set of event handlers that Gui themselves have.

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

Similarly, GuiCreate(Title, Options) is opposite to Gui New, Options, Title. (...)

Currently Gui.Show(Options, Title) is inconsistent with GuiCreate and Gui.AddCtrl. It won't be a problem if those are changed, but does having a Title parameter really make sense in the first place? It did in v1, when a Gui was created automatically (rather than explicitly by Gui New), but now we must always call GuiCreate, which has a Title parameter. Gui.Show can be used to change the title of an existing Gui, but so can Gui.Title, which is more obvious.

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.

[joedf]

I agree with swapping addCrtl.

[just me]

Hi fincs & lexikos,

after a short test using a modified example from the OP I like it, good job.

Code: Select all

; Converted Example: A moving progress bar overlayed on a background image.

MyGui := GuiCreate("Progress Example", , "Gui")
MyGui.BgColor := "White"
MyGui.MarginX := 0
MyGui.MarginY := 0
MyGui.AddPicture("%A_WinDir%\web\screen\img101.png", "h350 w450")
MyGui.AddButton("Start the Bar Moving", "gBtnStartClicked Default xp+20 yp+250")
MyGui.AddProgress( , "vMyProgress w416")
MyGui.AddLabel( , "vMyText wp")  ; wp means "use width of previous".
MyGui.Show()
; ========================================================================
GuiOnClose() {
   MsgBox("This Gui cannot be closed this way!", "Attention!")
   Return 1 ; it feels strange to return a value which is evaluated to "True" in AHK to prevent closing.
}
; ========================================================================
GuiBtnStartClicked(Ctrl) {
   ThisText := Ctrl.Gui.Control["MyText"]
   ThisProgress := Ctrl.Gui.Control["MyProgress"]
   Loop Files, %A_WinDir%\System32\*.*
   {
      ThisProgress.Value := A_Index
      ThisText.Value := A_LoopFileName
      Sleep 50
   } Until (A_Index = 100)
   ThisText.Value := "Bar finished."
   MsgBox(ThisProgress.Value, "Progress Value")
}

My first wish list:

• GUI:

  • Code: Select all

    GuiCreate([Title, Options, FuncPrefixOrObj := "Gui"])

    It would retain the v1 defaults for GUI event handlers.
    IMO, the prefix should not be used as prefix for control event handlers.

  • Code: Select all

    Gui.Pos()   ; Returns the position in an object containing x,y,w,h fields.
    Gui.Size()  ; Returns the size of the client area in an object containing w,h fields

    Any chance to implement it?
• Controls:

  • Code: Select all

    Gui.Add(Ctrl [, Text, Options, Name, Eventhandler])

    I'd prefer to separate vName and gEventHandler from Options.