# IupDestroy

Definition: | include pGUI.e Ihandlns ih = IupDestroy(Ihandlns ih)
Description: | Destroys an interface element and all its children. Only dialogs, timers, popup menus and images should normally be destroyed, but detached controls can also be destroyed. ih: Identifier of the interface element to be destroyed, or a sequence of such. Returns NULL replacement(s) for ih (changed to a function in 0.8.2, prior to that was a procedure). Invoking say `dlg = IupDestroy(dlg)` sets dlg to NULL, reducing the chance of accidentally referencing it ever again. There is no penalty or consequence for effectively invoking `NULL := IupDestroy(NULL)` and the {like}, in other words there is no need to laboriously check for elements which may or may not have already been destroyed, or never even created, and by using a sequence param/result you can destroy everything in just the one single statement, not that you need to for attached child elements. Upgrading from pre-0.8.2: ideally change all affected identifiers from Ihandle to Ihandln and correctly overwite them as above, however of course you can just do `{} = IupDestroy(..)` to quickly get things back up and running, hopefully as a temporary measure.
pwa/p2js: | Supported, note however that just as IupMainLoop() is invalid/must be surrounded by an `if platform()!=JS then` under pwa/p2js, so too must any IupDestroy() that follow it, otherwise the controls would get destroyed before they are displayed, or rather the variables referencing them would be nullified. In fact, IupDestroy() is a dummy function under pwa/p2js, returning null, and letting the browser’s garbage collector clean things up, assuming you are correctly assigning that null to the last/only reference to the control, and assuming that any needing to be detached have been.
Notes: | [The following notes cover (legacy) desktop/Phix behaviour, and do not apply to pwa/p2js, which does not use names either.] It will automatically unmap and [not p2js] detach the element if necessary, and then destroy the element. This function also deletes the main names associated to the interface element being destroyed, but if it has more than one name then some names may be left behind. Menu bars associated with dialogs are automatically destroyed when the dialog is destroyed. Images associated with controls are NOT automatically destroyed - because images can be reused in several controls, the application must destroy them when they are not used anymore. All dialogs and all elements that have names are automatically destroyed in IupClose.
See Also: | IupAppend, IupDetach, IupMap, IupUnmap, IupCreate