Skip to content

Radio buttons

The radio buttons element is an input element and displays up to three mutually exclusive options.

Configure

Warning

Ensure the GUI library is included and initialised according to the configuration procedure.

RadioButtons myRadioButtons(&myGUI);

The constructor RadioButtons() creates a radio-button and sets the link to the GUI myGUI.

1
2
3
4
5
myRadioButtons.dDefine(10, 10, 80, 60,
     setItem(0x0101, "Radio 1"),
     setItem(0x0102, "Radio 2"),
     setItem(0x0103, "Radio 3"),
     fontSizeAutomatic);

dDefine() defines the radio-button with vector coordinates.

The required parameters are

  • The first line specifies the vector coordinates: top-left coordinates x-y then width and height in pixels;

  • The second line contains the item of the first option, here built with setItem() with an index and a text;

  • The third line contains the item of the second option, here built with setItem() with an index and a text.

The optional parameters are

  • The fourth line contains the item of the third option, here built with setItem() with an index and a text. The value can be itemEmpty to get access to the fifth line;

  • The fifth line is optional: the size of the font, by default fontSizeAutomatic for automatic.

By default, the element is enabled according to the GUI setting and no option is selected.

As an alternative,

radioButtons myRadioButtons;
myRadioButtons.dStringDefine(10, 10, 80, 60,
     "Radio 1",
     "Radio 2",
     "Radio 3",
     fontSizeAutomatic);

The required parameters are

  • The first line specifies the vector coordinates: top-left coordinates x-y then width and height in pixels;

  • The second line contains the text of the first option, with index set to 0x0001;

  • The third line contains the text of the second option, with index set to 0x0002;

The optional parameters are

  • The fourth line contains the text of the third option, with index set to 0x0003;

  • The fifth line is optional: the size of the font, by default fontSizeAutomatic for automatic.

By default, the element is oriented horizontally, not enabled, and with no option selected.

Then,

myRadioButtons.setOption(optionVertical);
myRadioButtons.setState(stateEnabled);
myRadioButtons.setValue(0);

setOption() defines the orientation of the bar-graph:

  • optionHorizontal or false for horizontal orientation;

  • optionVertical or true for vertical orientation.

Note

Use literals instead of values for upward compatibility.

Default is false for horizontal orientation.

setState() defines whether touch is enabled for the element.

Select

  • stateDisabled or false for touch disabled;

  • stateEnabled or true for touch enabled.

Note

Use literals instead of values for upward compatibility.

Default is false for touch disabled.

setValue() sets the initial selected option of the radio-buttons element:

  • 0 for no option selected;

  • 1, 2 or 3 for the first, second or third option selected.

Default is 0 for no option selected.

Use

myRadioButtons.draw();
bool result = myRadioButtons.check();
uint8_t value = myRadioButtons.getValue();
uint32_t index = myRadioButtons.getIndex();

draw() displays the check-box.

check() polls the touch controller and returns true is the button is pressed.

An optional parameter defines the mode of how the element is checked:

  • checkNormal for normal check mode;

  • checkInstant for instant check mode;

  • checkSpecial for special check mode.

Default mode is normal check mode.

In normal check mode, the element requires the finger to be hold for a momenet and raises the event when the finger is released. Additionally, the element goes through a cinematic sequence.

Going from option 2 to 3: start, press, hold, release

In instant check mode, the element raises the event when the finger touches the element. No cinematic sequence is performed.

Going from option 1 to 2: start, press

In special check mode, the element raises the event when the finger is released from the element. A simplified cinematic sequence is performed.

Going from option 1 to 2: start, press, release

The technical note Optimise GUI speed provides more details on the cinematic sequences of each check mode.

getValue() gets the value of the selected option:

  • 0 for no option selected;

  • 1, 2 or 3 for the first, second or third option selected.

getIndex() returns the index of the selected option, set at dDefine().

Example

This is the core of the code from example GUI_Radio.ino.

void displayRadioButtons()
{
    myScreen.setOrientation(myOrientation);
    uint16_t x, y, dx, dy;

    x = myScreen.screenSizeX();
    y = myScreen.screenSizeY();
    dx = x / 3;
    dy = y / 4;

    // myGUI.begin();
    myGUI.delegate(false);

    myGUI.dLabel(0, 0, x, dy, "Radio buttons", myColours.black, myColours.white, -1, 1, fontLarge);

    Text myText1(&myGUI);
    myText1.dDefine(dx * 0, dy, dx * 1, dy, 0, 0, fontLarge);
    myText1.setOption(optionWithoutFrame);
    myText1.draw("Normal");

    Text myText2(&myGUI);
    myText2.dDefine(dx * 1, dy, dx * 1, dy, 0, 0, fontLarge);
    myText2.setOption(optionWithoutFrame);
    myText2.draw("Instant");

    Text myText3(&myGUI);
    myText3.dDefine(dx * 2, dy, dx * 1, dy, 0, 0, fontLarge);
    myText3.setOption(optionWithoutFrame);
    myText3.draw("Special");

    RadioButtons myRadioButtons1(&myGUI);
    myRadioButtons1.dStringDefine(dx * 0, dy * 2, dx * 1, dy * 2, "Normal 1", "Normal 2", "Normal 3", fontMedium);
    myRadioButtons1.setOption(optionVertical);
    myRadioButtons1.setValue(0);
    myRadioButtons1.setState(stateEnabled);
    myRadioButtons1.draw();

    RadioButtons myRadioButtons2(&myGUI);
    myRadioButtons2.dStringDefine(dx * 1, dy * 2, dx * 1, dy * 2, "Instant 1", "Instant 2", "Instant 3", fontMedium);
    myRadioButtons2.setOption(optionVertical);
    myRadioButtons2.setValue(0);
    myRadioButtons2.setState(stateEnabled);
    myRadioButtons2.draw();

    RadioButtons myRadioButtons3(&myGUI);
    myRadioButtons3.dStringDefine(dx * 2, dy * 2, dx * 1, dy * 2, "Special 1", "Special 2", "Special 3", fontMedium);
    myRadioButtons3.setOption(optionVertical);
    myRadioButtons3.setValue(0);
    myRadioButtons3.setState(stateEnabled);
    myRadioButtons3.draw();

    drawNext();
    myScreen.flushFast();

    myGUI.delegate(true);
    while (!checkNext())
    {
        if (myRadioButtons1.check())
        {
            myText1.draw(formatString("Normal %i", myRadioButtons1.getValue()));
        }
        else if (myRadioButtons2.check(checkInstant))
        {
            myText2.draw(formatString("Instant %i", myRadioButtons2.getValue()));
        }
        else if (myRadioButtons3.check(checkSpecial))
        {
            myText3.draw(formatString("Special %i", myRadioButtons3.getValue()));
        }
        hV_HAL_delayMilliseconds(10);
    }
}