# gFrame

Definition: | include xpGUI.e gdx id = gFrame(gdx child, [nullable_string title=NULL, ] string attributes="", dword_seq args={})
Description: | Creates a native container, which draws a frame with a title around its child. Sometimes also known as a GroupBox. child: Identifier of an interface element (/subtree of such) which will be surrounded by the frame. title: Text to be shown on the label, can be NULL. Sets the TITLE attribute. For more information on the attributes and args parameters see gSetAttributes(). This is a paranormalised function. (see technicalia) Returns: the identifier of the created element.
pwa/p2js: | Supported.
Example: |
    -- demo\xpGUI\gFrame.exw
    include xpGUI.e
    gdx frame = gFrame(NULL,`gFrame`,`SIZE=110x40`),
        dlg = gDialog(frame,"gFrame","SIZE=240x80")
    gShow(dlg)
    gMainLoop()
Notes: | A child of NULL is permitted, for the trivial demo above and perhaps to ease development, but it is not optional.
Attributes: |
TITLE | (non inheritable) Text the user will see at the top of the frame. May need a gRedraw() when changed. GTK reduces the top margin when title is NULL, whereas WinAPI does not, since Visual Styles always reserves that vertical space. Aside: there is no deliberate intention to support flipping between text/NULL post-gShow(), ymmv.
also | ACTIVE, EXPAND, FONT, MARGIN, MINSIZE, MAXSIZE, SIZE, VISIBLE.
Technicalia | As this is a paranormalised function, and with no expectation that you should memorise this lot, except maybe "ctaa", you can assume that all of the following are potentially perfectly valid, with the fairly obvious restrictions that any parameters must be in strict ctaa-order, and no args without attributes:
                            gFrame(child)
                            gFrame(child, title)
                            gFrame(child, attributes)               -- (see last note)
                            gFrame(child, attributes, args)
                            gFrame(child, title, attributes)
                            gFrame(child, title, attributes, args)  -- (the full set)
Note that in practice title is actually defined as object and attributes as sequence, but verified to be of the documented types, after being repositioned via xpGUI.e/paranormalise_taa(). Also note the child is non-optional, although it can be NULL, and takes no part in the paranormalisation handling. Also note that child, which is typically a gHbox or gVbox, is not optional, and not passed to paranormalise_taa(). Finally note that gFrame(child,attributes) is distinguished from gFrame(child,title) by the presence of an '=', see here. PS: pGUI resorted to completely disabling the Windows Visual Styles (on Windows) for TITLE=NULL at creation, which looked ugly and made things worse in my opinion, so xpGUI does not replicate that.