Paranormalised Functions
Several routines perform a little trickery that, once you get used to the idea, make them easier to use. For example this help contains:
The idea is that [action, func] are doubly-optional. Any items before the "[[" are element-specific; this note covers the handling of {action,func,attributes,args}. If you want to provide any of the parameters after the "[[", you must provide everything before it, unless using named parameters. I made up the term paranormalise as a jokey way to explain that you have more flexibility than normal in how you can provide the parameters. In short you can assume the following are all valid:
Note that, unless using named parameters, you cannot change the order, eg:
There is an underlying assumption that if func is NULL then action is meaningless; what that specifically means is
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, break the line up into several discrete statements, ie/eg:
What this mechanism really attacks is the use of nested IupSetCallbackf() and IupSetAttributesf(), with all the extra parenthesis and indentation that requires, which can get real ugly real fast.
Admittedly paranormalisation is less useful on more complex elements and containers, especially if there are multiple callbacks required, or no callbacks at all, or any slightly fiddly or non-string attributes. This mechanism has not been applied where it has not yet proved useful, for example IupMatrix, IupTree, and IupRadio. In fact I originally made IupDialog paranormalised, before realising that was not helpful.
Technicalia: Most elements have more than one callback, and the action name is used to distinguish them - see the documentation of the specific interface element. pGUI replaces a NULL action name with "ACTION", which is suitable for IupButton, IupCanvas, IupList, IupMenuItem(aka IupItem), IupText, and IupToggle, but meaningless on most other elements. The C API strongly implies you can override "ACTION" (or "ACTION_CB") with a name of your choosing on selected interface elements: I cannot see that as useful (in my personal opinion it probably originates from a pre-IupSetAttributeHandle era, when all handles had to be explicitly named and set via two or even three separate function calls, and/or the deprecated combination mentioned in the Notes of IupSetCallback()), and pGUI effectively prohibits it.
IupButton(nullable_string title=NULL,
[[nullable_string action=NULL,]
cbfunc func=NULL,]
string attributes="",
dword_seq args={})
IupText([[nullable_string action=NULL,]
cbfunc func=NULL,]
string attributes="",
dword_seq args={})
The idea is that [action, func] are doubly-optional. Any items before the "[[" are element-specific; this note covers the handling of {action,func,attributes,args}. If you want to provide any of the parameters after the "[[", you must provide everything before it, unless using named parameters. I made up the term paranormalise as a jokey way to explain that you have more flexibility than normal in how you can provide the parameters. In short you can assume the following are all valid:
IupButton() [NB title/NULL must be provided in all other cases] IupButton(title) IupButton(title,action,func) [NB func is /not/ optional in this case] IupButton(title,func) IupButton(title,attributes[,args]) IupButton(title,func,attributes[,args]) IupButton(title,action,func,attributes[,args]) [ditto: func not optional]You can imagine the same less "title" for IupText.
Note that, unless using named parameters, you cannot change the order, eg:
IupButton(title,attributes[,args][,action],func) -- !INVALID! IupButton(title,func,attributes,args,action) -- !Stop this madness! IupButton(action,attributes,args,func,title) -- !You're being silly now! IupButton(attributes:="FLAT=YES",func:=ok_cb,title:="OK") -- but this is fineThe action and func parameters are actually declared as object, attributes as sequence, and args as dword_seq, but manually and thoroughly verified to be of the documented types, after they have all been repositioned. See pGUI.e/paranormalise() for the precise details of this handling, which is of course absolutely identical across all the interface elements that use it, plus a full set of unit tests. Same in pGUI.js, less the tests.
There is an underlying assumption that if func is NULL then action is meaningless; what that specifically means is
IupButton(title,action,func)
is ok, however IupButton(title,action)
is not
supported - it would in fact be misinterpreted as IupButton(title,attributes)
. (In general the
ability to override action names is discouraged and sometimes outright prohibited in pGUI, as below.)
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, break the line up into several discrete statements, ie/eg:
Ihandle button = IupButton([title]) IupSetCallback(button, "action name", Icallback("function name")) IupSetAttributes(button, attributes[, args]) IupSetAttribute(button, name, v)Of course when you are not entirely sure which attributes are needed, multiple calls to IupSetAttribute are easier to comment in/out for testing, and multiple callbacks can only be set via IupSetCallback[s] anyway.
What this mechanism really attacks is the use of nested IupSetCallbackf() and IupSetAttributesf(), with all the extra parenthesis and indentation that requires, which can get real ugly real fast.
Admittedly paranormalisation is less useful on more complex elements and containers, especially if there are multiple callbacks required, or no callbacks at all, or any slightly fiddly or non-string attributes. This mechanism has not been applied where it has not yet proved useful, for example IupMatrix, IupTree, and IupRadio. In fact I originally made IupDialog paranormalised, before realising that was not helpful.
Technicalia: Most elements have more than one callback, and the action name is used to distinguish them - see the documentation of the specific interface element. pGUI replaces a NULL action name with "ACTION", which is suitable for IupButton, IupCanvas, IupList, IupMenuItem(aka IupItem), IupText, and IupToggle, but meaningless on most other elements. The C API strongly implies you can override "ACTION" (or "ACTION_CB") with a name of your choosing on selected interface elements: I cannot see that as useful (in my personal opinion it probably originates from a pre-IupSetAttributeHandle era, when all handles had to be explicitly named and set via two or even three separate function calls, and/or the deprecated combination mentioned in the Notes of IupSetCallback()), and pGUI effectively prohibits it.