Expand/Shrink

IupSetHandle

Definition: include pGUI.e

IupSetHandle(string name, Ihandln ih)
-- or --
Ihandln ih = IupGetHandle(string name)
Description: Associates a name with an interface element, or retrieves the latter.

name: name of the interface element.
ih: identifier of the interface element. Use NULL to remove the association.
pwa/p2js: Not supported.
Notes: This function is used so it is possible to set attributes values that are in fact other elements that were created in C. For example:
IupSetHandle("test_image", image);
IupSetAttribute(button, "IMAGE", "test_image");

Note this code can (sometimes) be replaced by a more convenient function call:
IupSetAttributeHandle(button, "IMAGE", image);

However the SetHandle approach may still be more appropriate, for example when putting the same image on both a menu item and a button, especially if image is created/loaded deep inside a routine that creates the menu item and therefore it (image) is not immediately to hand for placing on the button.

In fact, any pointer can be stored and retrieved with IupSetHandle and IupGetHandle.

Also IupSetHandle can be called several times with the same pointer and different names.
There is no restriction for the number of names a pointer can have, but IupGetName() will return only the first name found.

The C function of the same name returns the previous association. In Phix, should that functionality actually be required, a preceding IupGetHandle must be used.

Especially when working on a large project, it should be pointed out that IupSetHandle has the same semantics and risks as the use of global variables.
See Also: IupSetAttributeHandle