# gDropDown

Definition: | include xpGUI.e gdx id = gDropDown([sequence options={},] [rtn changed=NULL,] string attributes="" dword_seq args={})
Description: | Creates an interface element that is a simple text-only dropdown selector. options: a sequence of text strings to populate the dropdown. It can be empty. It will set the OPTIONS attribute. changed: a procedure which is invoked when the selection is changed, see 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: | gButton, gCheckbox, gRadio, gLabel, gList
Example: |
    -- demo\xpGUI\gDropDown.exw
    include xpGUI.e

    procedure changed(gdx id)
        ?{"changed",gGetAttribute(id,"VALINT"),
                    gGetAttribute(id,"VALSTR")}
    end procedute

    gdx drop1 = gDropDown({"one","two","three"},changed),
        drop2 = gDropDown({"one","two","three"},changed),
        hbox = gHbox({drop1,drop2},"MARGIN=13x13"),
        dlg = gDialog(hbox,"gDropDown",`SIZE=240x80`)
    gSetAttribute(drop2,"VALINT",3) -- (else it’s blank)
    gShow(dlg)
    gMainLoop()
Attributes: |
EDITABLE | (creation only) Specifies whether the user can type in a new value (true/"YES") or only select one of the given options (the default, false/"NO"). Note that when true there is no implicit validation or checking whether the entered value is or is not one of the specified options, and no facility for automatically "adding" the entered item, instead that would have to be done explicitly (by replacing the lot).
OPTIONS | (write only) A list of text strings to populate the dropdown. Same as the first parameter on creation. This can also be called later to purge the dropdown and re-populate it with an entirely different set of options.
VALINT | Get/Set the selected item as a (1-based) pseudo-index into OPTIONS. Returns NULL/0 if no entry is selected. Note that setting VALINT longer than or before OPTIONS is [currently] quietly ignored.
VALSTR | (read only) Return the selected item (from OPTIONS) as a string, or "" if no entry is selected.
also | ACTIVE, CANFOCUS, FONT, EXPAND, TIP, SIZE, VISIBLE.
Handlers: |
CHANGED | Event generated when the selection or entry is changed. procedure changed(gdx id) id: identifier of the element (dropdown) that activated the event.
also | KEY: All common handlers are supported.
Technicalia | As this is a paranormalised function, and with no expectation that you should attempt to memorise this lot, except maybe "qraa", you can assume that all of the following are potentially perfectly valid, with the fairly obvious restrictions that any parameters must be in strict qraa-order, and no args without attributes:
                            gDropDown()
                            gDropDown(changed)
                            gDropDown(changed, attributes)
                            gDropDown(changed, attributes, args)
                            gDropDown(attributes, args)
                            gDropDown(attributes)
                            gDropDown(options)
                            gDropDown(options, changed)
                            gDropDown(options, attributes)
                            gDropDown(options, attributes, args)
                            gDropDown(options, changed, attributes)
                            gDropDown(options, changed, attributes, args)  -- (the full set)
Note that in practice options and changed are actually defined as object, and attributes as a sequence rather than a string, but they are all manually and thoroughly verified to be of the documented types, after being repositioned via xpGUI.e/paranormalise_qraa().