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><input 70 * type="checkbox"></tt> tag. When a label is specified, the input 71 * element is nested in a <tt><label></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