# gText

Definition: | include xpGUI.e gdx id = gText([rtn value_changed=NULL,] string attributes="", dword_seq args={})
Description: | Creates an editable single line text input field. value_changed: (optional) a procedure to be invoked when the contents are changed, see VALUE_CHANGED below. 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.
See Also: | gList, gCanvasText
Example: |
    -- demo\xpGUI\gText.exw
    include xpGUI.e
    gdx txt = gText(`VALUE="one two three"`),
        hbx = gHbox({txt},"MARGIN=13x13"),
        dlg = gDialog(hbx,"gText","SIZE=240x80")
    gShow(dlg)
    gMainLoop()
Attributes: |
SIZE | (non inheritable) Since the contents can be changed by the user, the Natural Size is not affected by the text contents. The (natural) size defaults to sufficient for about 20 characters under the default font, or (not guaranteed) about 158x22 pixels under GTK2, 168x34 under GTK3, and 151x20 under WinAPI. While the natural width does not change, the natural height does respect FONT changes, with said height preserved by (say) gSetAttribute(id,"SIZE",250).
VALUE | (non inheritable) Text displayed to or entered/modified by the user.
Also | ACTIVE, BGCOLOR, CANFOCUS, FONT, EXPAND, MARGIN, MINSIZE, MAXSIZE, SIZE, TIP, VISIBLE. ? Drag & Drop attributes are supported. See Notes above.
Handlers: |
VALUE_CHANGED | Called after the value was interactively changed by the user (and on initial setup, and sometimes on focus/for no obvious reason). function value_changed(gdx id) id: identifier of the element that activated the event.
also | CLICK, KEY: All common handlers are supported.
Technicalia | As this is a paranormalised function, and with no expectation that you should memorise this lot, except maybe "raa", you can assume that all of the following are potentially perfectly valid, with the fairly obvious restrictions that any parameters must be in strict raa-order, and no args without attributes:
                            gText()
                            gText(rid)
                            gText(attributes)
                            gText(attributes, args)
                            gText(rid, attributes)
                            gText(rid, attributes, args)    -- (the full set)
Note that in practice rid is actually defined as object, and attributes as a sequence rather than a string, but verified to be of the documented types, after being repositioned via xpGUI.e/paranormalise_raa().