Skip to content

ACheckBox#

Checkboxes let users select one or more items from a list, or turn an item on or off.

Header:#include <AUI/View/ACheckBox.h>
CMake:aui_link(my_target PUBLIC aui::views)

Detailed Description#

A check box is an input control that allows the user to select or deselect an option. Unlike ARadioButton buttons—which are mutually exclusive within a group, multiple check boxes may be checked independently.

Use check boxes to enable or disable features, options, or actions in your UI.

Create a basic check box#

The following code snippet shows a minimal check box implementation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
#include <AUI/Platform/Entry.h>
#include <AUI/Platform/AWindow.h>
#include <AUI/Util/UIBuildingHelpers.h>
#include <AUI/View/ACheckBox.h>

using namespace ass;
using namespace declarative;

struct State {
    AProperty<bool> checked = false;
};

_<AView> minimalCheckBox(_<AProperty<bool>> state) {
    return CheckBox {
        .checked = AUI_REACT(*state),
        .onCheckedChange = [state](bool checked) { *state = checked; },
        .content = Label { "Minimal checkbox" },
    };
}

AUI_ENTRY {
    auto window = _new<AWindow>("Checkbox", 300_dp, 100_dp);
    auto state = _new<State>();
    window->setContents(
        Vertical {
            minimalCheckBox(AUI_PTR_ALIAS(state, checked)),
            Label { AUI_REACT(state->checked ? "Checkbox is checked" : "Checkbox is not checked") },
        }
    );
    window->show();
    return 0;
}

Key points about this code#

  • struct State holds a reactive property checked representing the check box's state. When checked changes, the UI updates reactively.
  • The CheckBox view binds .checked to the state's property, so the check mark is kept in sync with the data.
  • .onCheckedChange toggles the state when the check box is clicked.
  • Content (label or any view) can be provided using .content.
  • The UI updates automatically based on the state because of AUI's reactive system.

Result#

This example produces the following component when unchecked:

And this is how the same checkbox appears when checked:

Advanced example#

The following is a more complex example of how you can implement checkboxes in your app. In this snippet, there is a parent checkbox and a series of child checkboxes. When the user activates the parent checkbox, the app checks all child checkboxes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
#include <AUI/Platform/Entry.h>
#include <AUI/Platform/AWindow.h>
#include <AUI/Util/UIBuildingHelpers.h>
#include <AUI/View/ACheckBox.h>

using namespace ass;
using namespace declarative;

struct State {
    AProperty<bool> option1 = false;
    AProperty<bool> option2 = false;
    AProperty<bool> option3 = false;

    bool isAllOptionsSelected() const {
        return option1 && option2 && option3;
    }
};

_<AView> parentCheckBox(_<State> state) {
    return Vertical {
        CheckBox {
            .checked = AUI_REACT(state->isAllOptionsSelected()),
            .onCheckedChange = [state](bool checked) {
              state->option1 = checked;
              state->option2 = checked;
              state->option3 = checked;
            },
            .content = Label { "Select all" },
        },
        CheckBox {
            .checked = AUI_REACT(state->option1),
            .onCheckedChange = [state](bool checked) { state->option1 = checked; },
            .content = Label { "Option 1" },
        },
        CheckBox {
            .checked = AUI_REACT(state->option2),
            .onCheckedChange = [state](bool checked) { state->option2 = checked; },
            .content = Label { "Option 2" },
        },
        CheckBox {
            .checked = AUI_REACT(state->option3),
            .onCheckedChange = [state](bool checked) { state->option3 = checked; },
            .content = Label { "Option 3" },
        },
    };
}

AUI_ENTRY {
    auto window = _new<AWindow>("Checkbox", 300_dp, 100_dp);
    auto state = _new<State>();
    window->setContents(
        Vertical {
            parentCheckBox(state),
            Label { AUI_REACT(state->isAllOptionsSelected() ? "All options selected" : "Please select all options") },
        }
    );
    window->show();
    return 0;
}

Key points about this code#

  • State Management:
    • A State structure keeps three Boolean properties (option1, option2, option3), each wrapped with AProperty for reactive (observable) updates.
    • The utility method isAllOptionsSelected() quickly checks if all options are selected.
  • "Select All" Parent Checkbox:
    • The first CheckBox (labeled "Select all") is linked to isAllOptionsSelected() using a reactive binding (AUI_REACT).
    • When toggled, it sets all three state options to the new value, effectively selecting or deselecting all options at once.
  • Individual Option Checkboxes:
    • Each subsequent CheckBox is bound to its individual option (option1, option2, option3) via AUI_REACT.
    • Changing any option updates its respective state property.
  • Synchronized Selection:
    • If all individual checkboxes are checked, the "Select all" parent checkbox is also checked automatically (and vice versa).
  • Dynamic Status Label:
    • A Label below the checkbox group reflects the selection status in real-time (shows "All options selected" or "Please select all options") using a reactive binding.

Result#

This example produces the following component when all checkboxes are unchecked.

Likewise, this is how the component appears when all options are checked, as when the user taps select all:

When only one option is checked the parent checkbox appears unchecked:

Styling#

Both ACheckBox and ACheckBox::Box are exposed only for styling purposes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
{
    t<ACheckBox>(), // styles the checkbox + contents container
    LayoutSpacing { 4_dp }, // specifies space between ACheckBox::Box and contents
},
{
    t<ACheckBox::Box>(), // styling box itself
    BackgroundSolid { 0xffffff_rgb },
    Border { 1_dp, 0x333333_rgb },
    FixedSize { 14_dp, 14_dp },
    BackgroundImage { {}, 0x333333_rgb },
    BorderRadius { 3_dp },
},
{
    t<ACheckBox>::active() >> t<ACheckBox::Box>(),
    BackgroundSolid { AColor::GRAY.transparentize(0.8f) },
},
{
    Selected(t<ACheckBox::Box>()),
    BackgroundImage { ":uni/svg/checkbox.svg", getOsThemeColor().readableBlackOrWhite() },
    Border { nullptr },
    BackgroundGradient { getOsThemeColorLighter(), getOsThemeColor(), 180_deg },
},
{
    t<ACheckBox>::active() > Selected(t<ACheckBox::Box>()),
    BackgroundSolid { AColor::GRAY.transparentize(0.8f) },
    BackgroundGradient { getOsThemeColorLighter().lighter(0.3f), getOsThemeColor(), 180_deg },
},
{
    t<ACheckBox::Box>::disabled(),
    BackgroundSolid { 0xe5e5e5_rgb },
    Border { 1_px, 0xa0a0a0_rgb },
},
{
    Selected(t<ACheckBox::Box>::disabled()),
    BackgroundGradient { AColor::GRAY.lighter(0.1f), AColor::GRAY.darker(0.1f), 0_deg },
},

Public Types#

Box#

class ACheckBox::Box

Represents the box/drawing part of the checkbox itself; without labels or other decorations.

Exposed for styling purposes.

AProperty<bool> checked
emits<bool> userCheckedChange