Options, Text vs Text, Options
I scanned for Gui Add lines in the documentation and my script collection (mostly my own scripts). There were 418 total Gui Add lines detected (but some lines might have been missed).
just me wrote:Button, Checkbox, Radio, Text, Picture, ListBox, DDL, ComboBox controls without initial contents / captions?
In fact, yes. But only 12 of 274 lines. Sometimes I use Text for output, in which case the value is only set afterward (perhaps repeatedly). Pic is created without initial contents in the "Simple image viewer" example.
Just within the documentation, 12% omitted options, and 17% omitted text. However, supposing that the name (v) and event handler (g) options are replaced with separate parameters, 25% would omit options (i.e. more often than text). That really doesn't help the case for putting options second, since omitting options and specifying a name/event handler would require
"", or (empty)
, for options either way. Beside that, within my collection, 14% would omit options vs 21% omitting text. So like I said, in my experience, text is omitted more often than options.
The statistics don't represent each control equally, because some controls are used much more often than others. 61% of the lines which had no initial text were Edit controls. Edit controls account for 19% of the sample (i.e. they're very common) and only 36% had Text, while 94% had Options (99% if you include v, which was used by 86% of those Edit controls).
Of the remaining controls, 91% had Text and 86% had options. That's not much difference.
There are a few control types where it stands to reason that Text will be omitted often:
- TreeView, because Text isn't meaningful.
- Custom, either because Text isn't meaningful or because specific messages are needed to populate the control.
- Progress, because it generally starts at 0%.
- StatusBar, because there probably isn't any status to show as the GUI is created.
On the other hand, Button and Text account for 49% of the sample (i.e. they are by far the most commonly used controls), and almost never (4%) have Text omitted. However, if the g option is kept, Button controls will nearly always have it. (Only 19% had the g option, probably because the documentation has lots of Buttons, and it tends toward using automatic labels.) Still, 83% of Button and Text controls had options other than v and g.
ListView, Checkbox and Radio controls are the next most common, accounting for around 17% of the sample. 96% had text and 81% had options other than v/g. So the trend seems to be that if you ignore Edit, the most common controls use Text more often than Options. (But then again, Options is application to every control type, whereas Text is not.)
Ragnar wrote:In my opinion, the options are of secondary importance when creating Gui/controls.
What I meant about "I disagree" is that options can be more important than the initial value. Where the method name (or first parameter) identifies the type of control, the options may specify a sub-type, or the nature of the control. The position and other options are also important, and depending on the control or the author's mindset, may be more-so than the text. For controls that take input or raise events, the v and g options are of central importance.
Event Handling
When I started thinking about adding the Name and Event parameters (like just me suggested), it initially seemed odd to put Text between Options and Name. Now I think that was just because I was stuck in an old mindset (v and g being options). I often specify almost the same string for the control's name, g-label and caption, and in such cases I think
x%x% y%y% +%style% vDoStuff gDoStuff, Do &Stuff or
x%x% y%y% +%style%, Do &Stuff, DoStuff, DoStuff is more natural than
Do &Stuff, x%x% y%y% +%style%, DoStuff, DoStuff.
It also got me thinking that maybe controls should
all allow automatic event handlers, but based on the control's name (and only if it has one) and the event names, not the control's text. For instance, the
ControlName_EventName pattern is pretty common in Microsoft languages, and it's almost the same as what each Gui already has (consistency between the Gui and its controls would be a plus). This would provide convenience for the common cases, while OnEvent() would allow more flexibility. It would encourage script authors to follow this pattern, which would probably help when reading someone else's script. There would be only one mechanism for explicitly setting or removing an event handler (OnEvent), which simplifies the implementation and documentation. It would also mean only one new parameter instead of two.
For Gui events, there would no longer be a +Label/Prefix option; that would become the purpose of Gui.Name, similar to the default labels in v1. Though in that case, it would be inefficient to create the GUI with a default name and then set the name afterward, so a parameter of GuiCreate() would be best (perhaps consistent with Gui.Add()).
Another way was for +/-g to set an event handler for the control's "default" event (usually Click or Change). Because event registration would allow multiple handlers (as with OnMessage, OnExit and OnClipboardChange),
-g requires a
little more complexity (identifying which handler was the default/+g handler).
As for suppressing events temporarily, I realised that -g .. +g
Handler was always less than ideal because it requires specifying the label/function name. Instead, I'm changing Edit.Value/Text to avoid triggering the Change event, making -g somewhat less needed. I also realised that OnEvent(event, handler, -1) .. OnEvent(event, handler, 0) can be used to suppress an event temporarily, by having the handler return a value. (Like OnMessage/OnExit/OnClipboardChange, a negative final parameter means "call it before the others".)
Another point in favour of removing +g and +v is that they will not behave identically to v1, so keeping them around could be confusing.
just me wrote:IMO, the combination [Delete, Add] is sufficient as well as clear.
I agree.
Also, I thought about allowing method chaining by having these methods return the control object. For instance,
ListBox.Delete().Add(Items).
I wondered whether it shouldn't be Add(Item) rather than Add(Items). Currently I think it's necessary to write
Add([Item]) if Item might contain a pipe/delimiter. And it's inconsistent with ListView.