Expand/Shrink

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()
gButton
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.
Expand/Shrink