# gButton

Definition: | include xpGUI.e gdx id = gButton([nullable_string title=NULL,] [rtn action=NULL,] string attributes="" dword_seq args={})
Description: | Creates an interface element that is a button. When selected, this element activates a function in the application. The visual presentation can contain text and/or an image. title: Text to be shown to the user. It can be NULL. It will set the TITLE attribute. action: a function which is invoked when activated, see ACTION 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: | gImage, gCheckbox, gLabel
Example: |
    -- demo\xpGUI\gButton.exw (simplified)
    include xpGUI.e

    function action(gdx btn)
        ?"action"
        return XPG_DEFAULT
    end function

    gdx btn = gButton(`port from pGUI`,action),
        hbx = gHbox({btn},`MARGIN=11x11`),
        dlg = gDialog(hbx,`gButton`,`SIZE=240x80`)
    gShow(dlg)
    gMainLoop()
Notes: | Buttons can also be activated using Enter or Space keys when they have focus, or via Enter/Escape keys when they have been specified as DEFAULTENTER/DEFAULTESC on the dialog, as well as clicking on them, obviously.
Shorthand: | Use gQuit as a simple shorthand for "Close"/"Cancel"/"Quit"(etc) buttons, when nowt else needs doing:
                global function gQuit(gdx /*id*/)
                    return XPG_CLOSE
                end function
Attributes: |
? FLAT | (creation only) Hides the button borders until the mouse enter the button area. Can be YES or NO. Default: NO. [DEV we’ll need this for a toobar?]
IMAGE | (non inheritable) a gImage. Obviously attributes/args would need to be in one of the leading '=' forms to specify an image in the initial creation call. Whether a button contains text, an image, or both, is fixed at creation. Both may be substituted, but the (space for or size of) an image cannot be added/removed, and if the text is NULL or "" when first displayed then attempts to set it will/may be quietly ignored. You could perhaps hide one button and instead show a different one, in roughly the same place, should that help any. If TITLE is also defined and not empty both will be shown.
TITLE | (non inheritable) Button’s text. If IMAGE is not defined before map, then the default behavior is to contain only text. The natural size will be large enough to include all the text in the selected font, even using multiple lines, plus when specified an image, and the button borders. The '\n' character is accepted for line change. The "&" character can be used to define a mnemonic, the next character will be used as key. Use "&&" to show the "&" character instead of defining a mnemonic. The button can be activated from any control in the dialog using the "Alt+key" combination.
also | ACTIVE, CANFOCUS, FONT, EXPAND, MARGIN, TIP, SIZE, VISIBLE.
Handlers: |
ACTION | Event generated when the button is activated, similar to "click" events in other systems. When using a mouse, the event is only triggered when release occurs inside the button area, but you can also (tab-to and) activate a button using the keyboard, or use an accelerator key, or even ENTER/ESC when specified as that default on the dialog, via DEFAULTENTER/DEFAULTESC. Note that in xpGUI "CLICK" is a lower-level event that applies to pretty much all controls except menus, including left/middle/right and single/double/release events as well as ctrl/shift/alt, and only a selected few of those w/should match/justify what/when triggers "ACTION", and also in any case such an event would never cover button activation via the keyboard. function action(gdx id) id: identifier of the element that activated the event. Returns of XPG_CLOSE will be processed, closing whatever dialog the button is a part of, all other values are ignored.
also | CLICK, 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 "traa", you can assume that all of the following are potentially perfectly valid, with the fairly obvious restrictions that any parameters must be in strict traa-order, and no args without attributes:
                            gButton()
                            gButton(action)
                            gButton(action, attributes)
                            gButton(action, attributes, args)
                            gButton(attributes, args)
                            gButton(attributes)                      -- (see 2nd note)
                            gButton(title)
                            gButton(title, action)
                            gButton(title, attributes)
                            gButton(title, attributes, args)
                            gButton(title, action, attributes)
                            gButton(title, action, attributes, args)  -- (the full set)
Note that in practice title and action 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_traa(). Note that gButton(attributes) is distinguished from gButton(title) by the presence of an '=' character, see here. While in xpGUI a return of XPG_IGNORE from the ACTION handler somewhat more logically simply ignores the event (aka behaves identically to a return rand(57) statement), in pGUI a similar IUP_IGNORE completely removed the callback, and hence effectively disabled the button, and without any visual feedback of that I might add. To achieve that same sort of effect in xpGUI one would have to explicitly invoke gSetHandler(id,"ACTION",NULL), and/or (but with some visual feedback) gSetAttribute(id,"ACTIVE",false).