Expand/Shrink

IupSetCallback

Definition: include pGUI.e

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

ih: identifier of the interface element(s) [can be a single Ihandle or a (flat) sequence of them].
name: name of the callback, see the documentation of each specific interface element for a list of valid/meaningful names.
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.
pwa/p2js: Supported.
Notes: All paranormalised functions permit an implit invocation of IupSetCallback, as per the paragraph starting "If any of this troubles you" half way down that page.

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 (other than IupSetCallbackf being a function rather than a procedure).
Example: 
IupSetCallback(canvas1,"ACTION",Icallback("redraw_cb"))
IupSetCallback({canvas1,canvas2},"ACTION",Icallback("redraw_cb"))
IupSetCallbacks({canvas1,canvas2},{"ACTION",Icallback("redraw_cb"),"MAP_CB",Icallback("map_cb")})

(set one callback on one interface element / the same callback on two elements / two callbacks on both elements)
See Also: IupGetCallback, IupSetGlobalFunction