# gMap

Definition: | include xpGUI.e gMap(gdx id)
Description: | (semi-deprecated) Invoked automatically when needed, and (at the time of writing) there is no longer any need to call this explicitly in xpGUI, however it is an integral necessity to the fundamental inner workings of xpGUI, and (flw) little harm can arise from making it publically available. Creates (maps) the real native interface objects corresponding to the given xpGUI virtual interface elements, and applied recursively to also create the native elements of any children the element may have. id: Identifier of an interface element, usually a dialog or standalone menu. The element must be already attached to a mapped container, except for dialogs. A child can only be mapped if its parent is already mapped, hence this can only be invoked on a dialog, or perhaps more accurately there are as yet no observed or imagined cases where invoking this on an un-mapped non-dialog would not imminently and immediately conclude in a rather sudden and sticky end. While GTK and JavaScript are quite laissez-faire in such matters, WinAPI is however utterly adamant (error 1406) that creation must be performed parent-first, and arwen adhered itself to that policy, which was all rather quite a bit of fun to disentangle. Fundamentally and in short, GTK and JavaScript do/need this:
        child1 = some_control(...)
        child2 = some_control(...)
        parent = some_control(...)
        add_control(parent,child1)
        add_control(parent,child2)
whereas WinAPI demands
        parent = some_control(...)
        child1 = some_control(parent,...)
        child2 = some_control(parent,...)
The design decision was taken to permit a more natural declaration order, specifically child-first. Hence xpGUI.e defers actual creation until it has gathered enough information to appease WinAPI (etc), which is where the absolute necessity for a gMap() comes from. It permits the programmer to declare things in a more natural and relaxed fashion, before actually creating things in some order that actually works, and does so on all platforms, with any potential minor differences abstracted away and hidden out of sight and mind. Technically speaking, xpGUI.e interface element creation allocates an internal index/id immediately, but fills in the precise details at the last possible moment, via gMap(). This function is automatically called before the dialog is shown in gShow.
pwa/p2js: | Implemented as a dummy function, since there is no need for xpGUI.js to defer creation, and while (eg) gDialog() returns an internal index on the desktop(/xpGUI.e) in contrast xpGUI.js returns the actual/final HTMLElement.
Notes: | There is no equivalent for MAP_CB in xpGUI, or that matter the WID attribute, or IupUnmap(). pGUI had some apparently-always-the-same canvas mapping stuff that is now managed by xpGUI.e/js instead. (Besides, making say double-buffering optional is so 1980s, nobody wants or tolerates screen flicker anymore [granted it was at least 32 times less noticeable on a 320x200 CGA screen], even a hi-res 4K framebuffer is only 32MB, and not like you’ll need dozens of them, which all quite frankly ceased to be worth fretting over decades ago.)
See Also: | gShow