Skip to content

Latest commit

 

History

History
177 lines (145 loc) · 8.83 KB

checkbox.md

File metadata and controls

177 lines (145 loc) · 8.83 KB

Checkbox Widget

A Checkbox is a Widget that can be left-clicked to change its state between being checked and unchecked, emitting a cooresponding Signal when the state changes. A Checkbox may also be locked, so that it cannot be manipulated until it is unlocked.

There are a variety of Checkbox designs implemented by the library, as well as a set of pre-defined Labeled Checkboxes for common combinations.

Checkbox Interface

/// Checkbox Widget that is either checked or not checked.
/** Uses mouse left button click to toggle between states. */
template <template <typename> typename Layout_t>
class Checkbox : public Label<Layout_t> {
   public:
    enum class State : bool { Unchecked, Checked };

    struct Display {
        Glyph_string checked;
        Glyph_string unchecked;
    };

    struct Parameters {
        State initial_state;
        Display display;
        bool locked;
    };

   public:
    /// Emitted when box becomes checked.
    sl::Signal<void()> checked;

    /// Emitted when box becomes unchecked.
    sl::Signal<void()> unchecked;

    /// Emitted every time the box changes state.
    sl::Signal<void()> toggled;

   public:
    explicit Checkbox(State initial_state, Display display, bool locked);
    explicit Checkbox(Parameters p);

   public:
    /// Set the state to be checked.
    void check();

    /// Set the state to be unchecked.
    void uncheck();

    /// Change state to be unchecked if currently checked, checked otherwise.
    void toggle();

    /// Return the current state of the Checkbox as Checkbox::State enum value.
    auto get_state() const -> State;

    /// Lock the Checkbox, it can not be toggled when locked.
    void lock();

    /// Unlock the Checkbox, allowing it to be toggled.
    void unlock();

    /// Return true if the Checkbox is locked.
    auto is_locked() const -> bool;

    /// Set the look of each Checkbox State.
    void set_display(Display d);

    /// Return the look of each Checkbox State.
    auto get_display() -> Display;
};

Checkbox Library Types

Widget Type Unchecked Display Checked Display
Checkbox1 ☐ ☒
Checkbox2 [ ] [x]
Checkbox3 ┌

└		 ┌
x
└
Checkbox4 ┐

┘		 ┐
x
┘
Checkbox5 ┌ ┐ ┌x┐
Checkbox6 └ ┘ └x┘
Checkbox7 ╭

╰		 ╭
x
╰
Checkbox8 ╮

╯		 ╮
x
╯
Checkbox9 ╭ ╮ ╭x╮
Checkbox10 ╰ ╯ ╰x╯
Checkbox11 ┘

┐		 ┘
╴
┐
Checkbox12 └

┌		 └
╶
┌
Checkbox13 ┘ └ ┘╵└
Checkbox14 ┐ ┌ ┐╷┌
Checkbox15 ╯

╮		 ╯
╴
╮
Checkbox16 ╰

╭		 ╰
╶
╭
Checkbox17 ╯ ╰ ╯╵╰
Checkbox18 ╮ ╭ ╮╷╭
Checkbox19 ├ ┤ ├x┤
Checkbox20 ┤ ├ ┤x├
HCheckbox
VCheckbox

Each of these types has an identically named lower-case function that returns an initialized std::unique_ptr object of the corresponding type. They each have a signature that looks like the below:

auto checkbox_type(Checkbox::Parameters) -> std::unique_ptr<Checkbox_type>;

Labeled Checkbox Interface

When using any of the below Labeled Checkboxes, the following interface will be available.

/// Pseudo-code, there is no class named Labeled_checkbox
class Labeled_checkbox {
   public:
    using Checkbox_t;
    using Label_t;

   public:
    Checkbox_t& checkbox;
    Label_t& label;

   public:
    explicit Labeled_checkbox(
        typename Label_t::Parameters    label_parameters    = {},
        typename Checkbox_t::Parameters checkbox_parameters = {});
};

Labeled Checkbox Library Types

Widget Type Unchecked Display Checked Display
HCheckbox1_label
HCheckbox_label		 ☐ Label ☒ Label
HLabel_checkbox1
HLabel_checkbox		 Label ☐ Label ☒
VCheckbox1_label
VCheckbox_label		 ☐
L
a
b
e
l		 ☒
L
a
b
e
l
VLabel_checkbox1
VLabel_checkbox		 L
a
b
e
l
☐		 L
a
b
e
l
☒
HCheckbox2_label [ ] Label [x] Label
HLabel_checkbox2 Label [ ] Label [x]
VCheckbox2_label [ ]
L
a
b
e
l		 [x]
L
a
b
e
l
VLabel_checkbox2 L
a
b
e
l
[ ]		 L
a
b
e
l
[x]
HCheckbox3_label ┌⠀⠀⠀⠀⠀
⠀⠀Label
└⠀⠀⠀⠀⠀		 ┌⠀⠀⠀⠀⠀
x Label
└⠀⠀⠀⠀⠀
HLabel_checkbox4 ⠀⠀⠀⠀⠀┐
Label⠀⠀
⠀⠀⠀⠀⠀┘		 ⠀⠀⠀⠀⠀┐
Label x
⠀⠀⠀⠀⠀┘
VCheckbox5_label ┌ ┐
L
a
b
e
l		 ┌x┐
L
a
b
e
l
VLabel_checkbox6 L
a
b
e
l
└ ┘		 L
a
b
e
l
└x┘
HCheckbox7_label ╭⠀⠀⠀⠀⠀
⠀⠀Label
╰⠀⠀⠀⠀⠀		 ╭⠀⠀⠀⠀⠀
x Label
╰⠀⠀⠀⠀⠀
HLabel_checkbox8 ⠀⠀⠀⠀⠀╮
Label⠀⠀
⠀⠀⠀⠀⠀╯		 ⠀⠀⠀⠀⠀╮
Label x
⠀⠀⠀⠀⠀╯
VCheckbox9_label ╭ ╮
L
a
b
e
l		 ╭x╮
L
a
b
e
l
VLabel_checkbox10 L
a
b
e
l
╰ ╯		 L
a
b
e
l
╰x╯
HCheckbox11_label ┘⠀⠀⠀⠀⠀
⠀⠀Label
┐⠀⠀⠀⠀⠀		 ┘⠀⠀⠀⠀⠀
╴ Label
┐⠀⠀⠀⠀⠀
HLabel_checkbox12 ⠀⠀⠀⠀⠀└
Label⠀⠀
⠀⠀⠀⠀⠀┌		 ⠀⠀⠀⠀⠀└
Label ╶
⠀⠀⠀⠀⠀┌
VCheckbox13_label ┘ └
L
a
b
e
l		 ┘╵└
L
a
b
e
l
VLabel_checkbox14 L
a
b
e
l
┐ ┌		 L
a
b
e
l
┐╷┌
HCheckbox15_label ╯⠀⠀⠀⠀⠀
⠀⠀Label
╮⠀⠀⠀⠀⠀		 ╯⠀⠀⠀⠀⠀
╴ Label
╮⠀⠀⠀⠀⠀
HLabel_checkbox16 ⠀⠀⠀⠀⠀╰
Label⠀⠀
⠀⠀⠀⠀⠀╭		 ⠀⠀⠀⠀⠀╰
Label ╶
⠀⠀⠀⠀⠀╭
VCheckbox17_label ╯ ╰
L
a
b
e
l		 ╯╵╰
L
a
b
e
l
VLabel_checkbox18 L
a
b
e
l
╮ ╭		 L
a
b
e
l
╮╷╭
HCheckbox19_label ├ ┤ Label ├x┤ Label
HLabel_checkbox19 Label ├ ┤ Label ├x┤
VCheckbox19_label ├ ┤
L
a
b
e
l		 ├x┤
L
a
b
e
l
VLabel_checkbox19 L
a
b
e
l
├ ┤		 L
a
b
e
l
├x┤
HCheckbox20_label ┤ ├ Label ┤x├ Label
HLabel_checkbox20 Label ┤ ├ Label ┤x├
VCheckbox20_label ┤ ├
L
a
b
e
l		 ┤x├
L
a
b
e
l
VLabel_checkbox20 L
a
b
e
l
┤ ├		 L
a
b
e
l
┤x├

Each of these types has an identically named lower-case function that returns an initialized std::unique_ptr object of the corresponding type. They each have a signature that looks like the below:

auto labeled_checkbox_type(Label::Parameters, Checkbox::Parameters) -> std::unique_ptr<Labeled_checkbox_type>;