# IupClose

Definition: | include pGUI.e IupClose()
Description: | Shutdown IUP
pwa/p2js: | Implemented as a dummy function. See also the notes for IupMainLoop(). IupCloseOnEscape() [see below] is (more) faithfuly implemented.
Comments: | This procedure should be called at the end of the program. See also IupOpen, which should be called at the start of the program. Note that when IupMainLoop() returns, the main window is usually still visible until either IupClose() or IupDestroy() is invoked, and a (test) program that ends with wait_key() or similar will not have keyboard focus in the terminal, but that will still be with the otherwise non-responsive window.
Utility Routine | The following procedure can also be used, any time between creating the dialog and displaying it, to assign a standard escape key handler to the main dialog: IupCloseOnEscape(Ihandle dlg, bool bClose=true)) dlg: typically the result of an IupDialog() call. bClose: if false any K_ANY handler is removed, otherwise one is added. Note that, since 0.8.3, the bEsc parameter of IupDialog() controls whether this routine is invoked automatically (default true), and therefore can make further manual/explicit calls to it completely unnecessary. However, you may genuinely want an application to initially close on escape, particularly when it has been accidentally opened by mistake, but stop doing that the moment you actually start to enter or edit anything. This is implemented as and therefore behaves identially to declaring and using the following callback:
    function key_cb(Ihandle dlg, atom c)
        if c=K_ESC then
            atom close_cb = IupGetCallback(dlg,"CLOSE_CB")
            if close_cb!=NULL then
                c_proc(define_c_proc({},{'+',close_cb},{C_PTR}),{dlg})
            end if
            return IUP_CLOSE
        end if
        return IUP_DEFAULT
    //  return iff(c=K_ESC?close_cb(dlg):IUP_DEFAULT)
    end function
    IupSetCallback(dlg, "K_ANY", Icallback("key_cb"));
Since returning IUP_CLOSE does not invoke any CLOSE_CB callback, then as shown, if one is attached it is invoked automatically for you (as a proc because we would ignore any result anyway). The single commented-out line would normally be more appropriate in an application, ie invoke a known close_cb() directly in normal hll code, rather than using any messy IupGetCallback/c_proc shenanigans. Note that secondary dialogs may need to invoke IupHide() rather than using IUP_CLOSE or IupClose(), since that terminates the entire application unless there are nested IupMainLoop() calls. In other words use IupHide(1)-IupShow(2)-IupHide(2)-IupShow(1) instead of trying and failing with IupClose(1)-IupShow(2)-IupClose(2)-IupShow(1). Obviously, should you need any other key handling then take a copy of that and modify it, instead of invoking IupCloseOnEscape(). In truth, IupCloseOnEscape has almost nothing to do with IupClose and must not be considered a substitute or replacement for it. As of 0.8.3, IupCloseOnEscape() is applied by default in IupDialog() to all dialogs on creation. When porting to xpGUI, use the CLOSE_ON_ESCAPE attribute instead.
Example: |
    include pGUI.e

    IupOpen()
    Ihandle main_dialog = IupDialog(IupLabel("Hello","PADDING=80x10"),"TITLE=test")
    IupCloseOnEscape(main_dialog) -- (applies by default anyway)
    IupShow(main_dialog)
    if platform()!=JS then
        IupMainLoop()
        IupClose()
    end if
See Also: | IupOpen, IupMainLoop, IupSetCallback, Icallback, K_ANY, IupHide