Paranormalisation
Several routines perform a little trickery that, once you get used to the idea, make them easier to use. For instance:
The idea is that (in this specific case) title and action are doubly-optional, as in standard optional parameter handling + extra logic.
You might want to study gLabel() first, as perhaps the simplest possible use case for this concept.
On first reading, all you need to take away is "bit more flexible, it’ll probably cope" and not really care how.
I made up the term paranormalise as a jokey way to explain you have more flexibility than usual in providing the parameters.
In short, and with no expectation that you should attempt to memorise this lot, you can assume that any and all of the following are perfectly valid, via shared "shuffle arguments into the right place" routines using a wee bit of good old crafty/common sense logic:
Having two dozen ways to call something might not sound like fun, but it is really pretty nifty once you get used to the idea.
Named parameters carry some additional risk of confusion, and are probably just simply more trouble than worth, at least here.
The title and action parameters are actually declared as object, attributes as sequence, and args as dword_seq, but carefully and
thoroughly verified to be of the documented types, after they have all been properly repositioned.
An assertion failure is shown on the gButton() call itself for any parameter it failed to understand, along with what it would have found acceptable in that parameter position. That can also occur if it has decided you must be passing, say, at most 3 parameters, but the 4th is not the usual default. Let me know of any such messages that don’t make perfect sense, and/or could be improved.
In other words when attributes is still "" (ie you need none), a title containing an '=' replaces it (and becomes "" itself).
Naturally such a so-moved string could easily be `TITLE="The title",...` so that behaviour is often exactly what we want.
Should you actually want '=' in the title (and no attributes), using either of the (newer) leading '=' variants of gSetAttributes() is now the recommended way to avoid potential mishap. Also applies to (at least) gDialog, gCheckbox, gFrame, and gLabel.
While pGUI had just one paranormalise() routine which only dealt with [action,func,attr,args], xpGUI.e has relaxed the "always present" restrictions on preceding arguments and now has (at least) five (private) versions:
firstly paranormalise_traa() which is used by (at least) gButton(), gCheckbox(), and gSlider(),
secondly paranormalise_qraa() for (at least) gDropDown() and gTreeView(),
thirdly paranormalise_raa() for (at least) gSpin(), gText(), gDatePick(), gCanvas(), and gList(),
fourth paranormalise_taa() for (at least) gFrame(), gLabel(), and
fifth and lastly paranormalise_paab() currently just for gDialog().
In those you can find the the precise nitty-gritty details of this handling, which is of course generally speaking pretty much identical across all the interface elements that use it, plus a full set of unit tests.
Note that should you modify those in xpGUI.e, xpGUI.js contains the equivalent manually transpiled and pasted into JavaScript.
If any of this troubles you, just provide the full set of parameters every time, and re-visit this once you get bored with that.
Alternatively, a control declaration can be broken up into several discrete statements, ie/eg:
All paranormalised functions should be clearly marked as such, and linked here. Some xpGUI handlers such as gCanvas()/REDRAW also use [] to indicate different supported signatures.
gButton([nullable_string title=NULL,]
[rtn action=NULL,]
string attributes="",
dword_seq args={})
The idea is that (in this specific case) title and action are doubly-optional, as in standard optional parameter handling + extra logic.
You might want to study gLabel() first, as perhaps the simplest possible use case for this concept.
On first reading, all you need to take away is "bit more flexible, it’ll probably cope" and not really care how.
I made up the term paranormalise as a jokey way to explain you have more flexibility than usual in providing the parameters.
In short, and with no expectation that you should attempt to memorise this lot, you can assume that any and all of the following are perfectly valid, via shared "shuffle arguments into the right place" routines using a wee bit of good old crafty/common sense logic:
gButton()
gButton(title)
gButton(title, action)
gButton(title, attributes)
gButton(title, attributes, args)
gButton(title, action, attributes)
gButton(title, action, attributes, args)
gButton(action)
gButton(action, attributes)
gButton(action, attributes, args)
gButton(attributes) -- [see note regarding '=']
gButton(attributes, args)
gButton(attributes:="SIZE=60x40", action:=action, title:="OK") -- [an example of using named parameters]
Fairly obviously and as per all subroutine calls in Phix, no other (unnamed) ordering of the parameters will be successful.Having two dozen ways to call something might not sound like fun, but it is really pretty nifty once you get used to the idea.
Named parameters carry some additional risk of confusion, and are probably just simply more trouble than worth, at least here.
The title and action parameters are actually declared as object, attributes as sequence, and args as dword_seq, but carefully and
thoroughly verified to be of the documented types, after they have all been properly repositioned.
An assertion failure is shown on the gButton() call itself for any parameter it failed to understand, along with what it would have found acceptable in that parameter position. That can also occur if it has decided you must be passing, say, at most 3 parameters, but the 4th is not the usual default. Let me know of any such messages that don’t make perfect sense, and/or could be improved.
'=' characters in titles, etc.
Note that gButton(str) is treated as gButton(attributes) if str contains one or more '=', or gButton(title) when it does not.In other words when attributes is still "" (ie you need none), a title containing an '=' replaces it (and becomes "" itself).
Naturally such a so-moved string could easily be `TITLE="The title",...` so that behaviour is often exactly what we want.
Should you actually want '=' in the title (and no attributes), using either of the (newer) leading '=' variants of gSetAttributes() is now the recommended way to avoid potential mishap. Also applies to (at least) gDialog, gCheckbox, gFrame, and gLabel.
While pGUI had just one paranormalise() routine which only dealt with [action,func,attr,args], xpGUI.e has relaxed the "always present" restrictions on preceding arguments and now has (at least) five (private) versions:
firstly paranormalise_traa() which is used by (at least) gButton(), gCheckbox(), and gSlider(),
secondly paranormalise_qraa() for (at least) gDropDown() and gTreeView(),
thirdly paranormalise_raa() for (at least) gSpin(), gText(), gDatePick(), gCanvas(), and gList(),
fourth paranormalise_taa() for (at least) gFrame(), gLabel(), and
fifth and lastly paranormalise_paab() currently just for gDialog().
In those you can find the the precise nitty-gritty details of this handling, which is of course generally speaking pretty much identical across all the interface elements that use it, plus a full set of unit tests.
Note that should you modify those in xpGUI.e, xpGUI.js contains the equivalent manually transpiled and pasted into JavaScript.
If any of this troubles you, just provide the full set of parameters every time, and re-visit this once you get bored with that.
Alternatively, a control declaration can be broken up into several discrete statements, ie/eg:
gdx button = gButton([title])
gSetHandler(button, "ACTION", btn_clicked)
gSetAttributes(button, attributes[, args])
gSetAttribute(button, name, v)
Of course when you are not entirely sure which attributes are needed, multiple calls to gSetAttribute
are easier to comment in/out for testing, and several handlers can only be set via gSetHandler[s] anyway.
All paranormalised functions should be clearly marked as such, and linked here. Some xpGUI handlers such as gCanvas()/REDRAW also use [] to indicate different supported signatures.