Expand/Shrink

gCheckbox

Definition: include xpGUI.e

gdx id = gCheckbox( [nullable_string title=NULL, ] [rtn value_changed=NULL, ] string attributes="", dword_seq args={})
Description: Creates a checkbox interface element, also known as a toggle. It is a two-state (on/off) button.

title: Text to be shown, can be NULL. Sets the TITLE attribute.
value_changed: an (optional) procedure invoked when toggled, 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: gImage, gButton, gLabel
Example: 
-- demo\xpGUI\gCheckbox.exw
include xpGUI.e

procedure value_changed(gdx chk, bool bState)
    gdx dlg = gGetDialog(chk)
    gSetAttribute(dlg,"TITLE","gCheckbox:%t",{bState})
end procedure

gdx chk = gCheckbox("Is this checked?",value_changed),
    hbx = gHbox({chk},"MARGIN=9x18"),
    dlg = gDialog(hbx,"gCheckbox","SIZE=240x80")
gShow(dlg)
gMainLoop()
gCheckbox
Notes: Checkboxes are activated/toggled using the Space key, or by being clicked.

Since GTK offers no apparent facility for checkboxes on the right of the text, the native support for such in WinAPI is not exposed, and all I can suggest is emulating that with something perhaps like gHbox({gLabel(txt),gCheckbox("")}).
Radio Groups: gRadio(gdx ids) specifies a set of mutually exclusive toggles, where ids is a (flat) sequence of toggles which have already been added to the dialog hierarchy by some other means. Note that radio groups (and checkboxes) are handled quite differently on menus.

Should a dialog contain more than one radio group, be aware the first element of ids and the tab order of the dialog determine radio groups under WinAPI, whereas they are more explicitly managed under GTK and JavaScript. A toggle cannot be part of more than one radio group.

Use gdx selected = gRadioItem(gdx id), where id is any element of ids, to obtain the currently selected radio button from that group, 0 if none, or -1 if it is not part of any radio group. Note that within a VALUE_CHANGED handler, where it is not really needed anyway, under WinAPI it returns the previous (off) selection, whereas under GTK and JavaScript [DEV testme] it gets the id of the latest (on). Also note that results from gRadioItem() before the dialog has been mapped/displayed are officially undefined/unsupported.

You would normally set a default explicitly, otherwise different backends may default differently, and otherwise the VALUE attribute may be used as normal, except it is illegal to set a radio group toggle off, and that any multiple pre-mapping ons would be applied in mapping rather than chronological order. 

-- demo\xpGUI\gRadio.exw
include xpGUI.e

procedure radio_changed(gdx toggle, bool bState)
    string title = gGetAttribute(toggle,"TITLE")
    printf(1,"toggle(%s), state:%t\n",{title,bState})
end procedure

gdx y = gCheckbox(`You`,radio_changed),
    g = gCheckbox(`get`,radio_changed,`VALUE=ON`),
    i = gCheckbox(`in`,radio_changed),
    t = gCheckbox(`the`,radio_changed),
    b = gCheckbox(`bowl`,radio_changed),
ygitb = {y,g,i,t,b},
 hbox = gHbox(ygitb,"MARGIN=9x8"),
  dlg = gDialog(hbox,"gRadio","SIZE=240x80")
gRadio(ygitb)
gSetAttribute(y,"FONT","Arial, italic 9")
gShow(dlg)
gMainLoop()
gRadio
Attributes:
VALUE Toggle’s state. Can be true/"ON", false/"OFF" or "TOGGLE" (inverts the current state). Default: false.
A toggle in a radio group cannot be set to false/off, setting it on automatically clears the "previously on" toggle.
also ACTIVE, CANFOCUS, FONT, EXPAND, TIP, TITLE SIZE, VISIBLE.
Handlers:
VALUE_CHANGED Called after the value was interactively changed by the user.

procedure value_changed(gdx id[, bool bChecked])
id: identifier of the element that activated the event.
bChecked: true(1) if the toggle’s state is on; false(0) if it is off.

Note that in a radio group, the raw WinAPI has a tendency to send "off" signals to all other toggles, whereas GTK more sensibly only signals the one off toggle that actually changed, hence xpGUI deliberately only forwards the "on" signal for toggles that are part of a radio group. As mentioned above, using gRadioItem() within a VALUE_CHANGED handler (for an item of that very same radio group) is rather foolish, and thankfully completely pointless, since you have already been (/only get) passed the "on" id anyway. For that reason, bChecked can be omitted, however a fatal error occurs should a handler without it ever be triggered on a non-radio checkbox.
also KEY: All common handlers are supported.
Expand/Shrink