IupSetCallback

Definition: include pGUI.e

IupSetCallback(Ihandle ih, string name, cbfunc func)
-- or --
Ihandle ih = IupSetCallbackf(Ihandle ih, string name, cbfunc func)
-- or --
Ihandle ih = IupSetCallbacks(Ihandle ih, sequence namefuncpairs)
Description: Associates a callback to an event.

ih: identifier of the interface element.
name: name of the callback.
func: a callback address (atom) from Icallback("name"), or NULL. If NULL removes the association.
namefuncpairs: a flat sequence, where the odd elements are string names and even elements cbfunc callbacks. Length must be even.
Notes: This function replaces the deprecated combination:
IupSetFunction(global_name, func)
IupSetAttribute(ih, name, global_name)

Hence it eliminates the need for a global name. (Note that IupSetFunction has been renamed/wrapped as IupSetGlobalFunction() in pGUI, hence the red/invalid colour.)

Callbacks set using IupSetCallback cannot be retrieved using IupGetFunction (which is likewise now named IupGetGlobalFunction).

The C function of the same name returns the address of the previous function associated to the action, whereas the Phix function IupSetCallbackf returns ih, to help make it a bit easier to declare dialogs. Note that IupSetCallbackf() can usually be replaced with something more succinct: see the examples in IupSetAttributes, and paranormalised functions. .

Note that in C, IupSetCallbacks(ih,name,func,NULL) is surprisingly common (in fact the only way I have ever seen it used), presumably because, in C, the IupSetCallback(ih,name,func) routine yields a less helpful return value (which is ignored in all the C samples I have studied, and explains why the Phix version is a procedure).
When translating C code to Phix such calls can/should be replaced with IupSetCallback[f](ih,name,func), in preference to IupSetCallbacks(ih,{name,func}), not that there should ever be a significant difference.
See Also: IupGetCallback, IupSetGlobalFunction