1 // This may look like C code, but it's really -*- C++ -*-
2 /*
3  * Copyright (C) 2008 Emweb bv, Herent, Belgium.
4  *
5  * See the LICENSE file for terms of use.
6  */
7 #ifndef WCHECKBOX_H_
8 #define WCHECKBOX_H_
9 
10 #include <Wt/WAbstractToggleButton.h>
11 #include <Wt/WJavaScriptSlot.h>
12 
13 namespace Wt {
14 
15 /*! \class WCheckBox Wt/WCheckBox.h Wt/WCheckBox.h
16  *  \brief A user control that represents a check box.
17  *
18  * By default, a checkbox can have two states: Wt::CheckState::Checked or
19  * Wt::CheckState::Unchecked, which can be inspected using isChecked(), and set
20  * using setChecked().
21  *
22  * A checkbox may also provide a third state, Wt::CheckState::PartiallyChecked,
23  * which is useful to indicate that it is neither checked nor
24  * unchecked. %Wt will use native browser support for this HTML5
25  * extension when available (Safari and MS IE), and use an image-based
26  * workaround otherwise. You may enable support for the third state
27  * using setTristate(), and use setCheckState() and checkState() to
28  * read all three states.
29  * Once a tri-state checkbox is clicked, it cycles through the states
30  * Wt::CheckState::Checked and Wt::CheckState::Unchecked.
31  *
32  * A label is added as a sibling of the checkbox to the same parent.
33  *
34  * Usage example:
35  * \if cpp
36  * \code
37  * auto box = std::make_unique<Wt::WGroupBox>("In-flight options");
38  *
39  * Wt::WCheckBox *w1 = box->addWidget(std::make_unique<Wt::WCheckBox>("Vegetarian diet"));
40  * box->addWidget(std::make_unique<Wt::WBreak>());
41  * Wt::WCheckBox *w2 = box->addWidget(std::make_unique<Wt::WCheckBox>("WIFI access"));
42  * box->addWidget(std::make_unique<Wt::WBreak>());
43  * Wt::WCheckBox *w3 = box->addWidget(std::make_unique<Wt::WCheckBox>("AC plug"));
44  *
45  * w1->setChecked(false);
46  * w2->setChecked(true);
47  * w3->setChecked(true);
48  * \endcode
49  * \elseif java
50  * \code
51  * WGroupBox box = new WGroupBox("In-flight options");
52  *
53  * WCheckBox w1 = new WCheckBox("Vegetarian diet", box);
54  * box.addWidget(new WBreak());
55  * WCheckBox w2 = new WCheckBox("WIFI access", box);
56  * box.addWidget(new WBreak());
57  * WCheckBox w3 = new WCheckBox("AC plug", box);
58  *
59  * w1.setChecked(false);
60  * w2.setChecked(true);
61  * w3.setChecked(true);
62  * \endcode
63  * \endif
64  *
65  * %WCheckBox is an \link WWidget::setInline(bool) inline \endlink widget.
66  *
67  * <h3>CSS</h3>
68  *
69  * This widget is rendered using an HTML <tt>&lt;input
70  * type="checkbox"&gt;</tt> tag. When a label is specified, the input
71  * element is nested in a <tt>&lt;label&gt;</tt>.
72  *
73  * This widget does not provide styling, and can be styled using
74  * inline or external CSS as appropriate.
75  *
76  * \sa WAbstractToggleButton
77  */
78 class WT_API WCheckBox : public WAbstractToggleButton
79 {
80 public:
81   /*! \brief Creates a checkbox without label.
82    *
83    * A checkbox created by this constructor will not contain a placeholder
84    * for a label, and therefore it is not possible to assign a label to it
85    * later through setText().
86    */
87   WCheckBox();
88 
89   /*! \brief Creates a checkbox with given label.
90    */
91   WCheckBox(const WString& text);
92 
93   /*! \brief Makes a tristate checkbox.
94    *
95    * \note You should enable tristate functionality right after construction
96    *       and this cannot be modified later.
97    */
98   void setTristate(bool tristate = true);
99 
100   /*! \brief enable or disable cycling throught partial state
101    *
102    * \sa isPartialStateSelectable()
103    */
104   void setPartialStateSelectable(bool b);
105 
106   /*! \brief return partial state cycling
107    *
108    * \sa setPartialStateSelectable();
109    */
isPartialStateSelectable()110   bool isPartialStateSelectable() { return partialStateSelectable_; };
111 
112   /*! \brief Returns whether the checkbox is tristate.
113    *
114    * \sa setTristate()
115    */
isTristate()116   bool isTristate() const { return triState_; }
117 
118   /*! \brief Sets the check state.
119    *
120    * Unless it is a tri-state checkbox, only Wt::CheckState::Checked and Wt::CheckState::Unchecked are
121    * valid states.
122    */
123   void setCheckState(CheckState state);
124 
125   /*! \brief Returns the check state.
126    *
127    * \sa setCheckState(), isChecked()
128    */
checkState()129   CheckState checkState() const { return state_; }
130 
131 protected:
132   virtual void updateInput(DomElement& input, bool all) override;
133   void updateJSlot();
134   void updateNextState();
135 
136 private:
137   bool triState_;
138   bool partialStateSelectable_;
139   std::unique_ptr<JSlot> jslot_;
140 };
141 
142 }
143 
144 #endif // WCHECKBOX_H_
145