qml-qtquick-controls2-checkbox.html 12.2 KB
Newer Older
xuebingbing's avatar
xuebingbing committed
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 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qquickcheckbox.cpp -->
  <title>CheckBox QML Type | Qt Quick Controls 2 5.11</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="../qtdoc/index.html">Qt 5.11</a></td><td ><a href="qtquickcontrols2-index.html">Qt Quick Controls 2</a></td><td ><a href="qtquick-controls2-qmlmodule.html">QML Types</a></td><td >CheckBox QML Type</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.11.2 Reference Documentation</td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">CheckBox QML Type</h1>
<span class="subtitle"></span>
<!-- $$$CheckBox-brief -->
<p>Check button that can be toggled on or off. <a href="#details">More...</a></p>
<!-- @@@CheckBox -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import QtQuick.Controls 2.4</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign">  Qt 5.7</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Inherits:</td><td class="memItemRight bottomAlign"> <p><a href="qml-qtquick-controls2-abstractbutton.html">AbstractButton</a></p>
</td></tr></table></div><ul>
<li><a href="qml-qtquick-controls2-checkbox-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2 id="properties">Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-qtquick-controls2-checkbox.html#checkState-prop">checkState</a></b></b> : enumeration</li>
<li class="fn"><b><b><a href="qml-qtquick-controls2-checkbox.html#nextCheckState-prop">nextCheckState</a></b></b> : function</li>
<li class="fn"><b><b><a href="qml-qtquick-controls2-checkbox.html#tristate-prop">tristate</a></b></b> : bool</li>
</ul>
<!-- $$$CheckBox-description -->
<a name="details"></a>
<h2 id="details">Detailed Description</h2>
<p class="centerAlign"><img src="images/qtquickcontrols2-checkbox.gif" alt="" /></p><p><a href="qml-qtquick-controls2-checkbox.html">CheckBox</a> presents an option button that can be toggled on (checked) or off (unchecked). Check boxes are typically used to select one or more options from a set of options. For larger sets of options, such as those in a list, consider using <a href="qml-qtquick-controls2-checkdelegate.html">CheckDelegate</a> instead.</p>
<p><a href="qml-qtquick-controls2-checkbox.html">CheckBox</a> inherits its API from <a href="qml-qtquick-controls2-abstractbutton.html">AbstractButton</a>. For instance, the state of the checkbox can be set with the <a href="qml-qtquick-controls2-abstractbutton.html#checked-prop">checked</a> property.</p>
<p>In addition to the checked and unchecked states, there is a third state: partially checked. The partially checked state can be enabled using the <a href="qml-qtquick-controls2-checkbox.html#tristate-prop">tristate</a> property. This state indicates that the regular checked/unchecked state can not be determined; generally because of other states that affect the checkbox. This state is useful when several child nodes are selected in a treeview, for example.</p>
<pre class="cpp">

  ColumnLayout {
      CheckBox {
          checked: <span class="keyword">true</span>
          text: qsTr(<span class="string">&quot;First&quot;</span>)
      }
      CheckBox {
          text: qsTr(<span class="string">&quot;Second&quot;</span>)
      }
      CheckBox {
          checked: <span class="keyword">true</span>
          text: qsTr(<span class="string">&quot;Third&quot;</span>)
      }
  }

</pre>
<p>Hierarchical checkbox groups can be managed with a non-exclusive <a href="qml-qtquick-controls2-buttongroup.html">ButtonGroup</a>.</p>
<p class="centerAlign"><img src="images/qtquickcontrols2-checkbox-group.png" alt="" /></p><p>The following example illustrates how the combined check state of children can be bound to the check state of the parent checkbox:</p>
<pre class="qml">

  <span class="type"><a href="../qtquick/qml-qtquick-column.html">Column</a></span> {
      <span class="type"><a href="qml-qtquick-controls2-buttongroup.html">ButtonGroup</a></span> {
          <span class="name">id</span>: <span class="name">childGroup</span>
          <span class="name">exclusive</span>: <span class="number">false</span>
          <span class="name">checkState</span>: <span class="name">parentBox</span>.<span class="name">checkState</span>
      }

      <span class="type"><a href="qml-qtquick-controls2-checkbox.html">CheckBox</a></span> {
          <span class="name">id</span>: <span class="name">parentBox</span>
          <span class="name">text</span>: <span class="name">qsTr</span>(<span class="string">&quot;Parent&quot;</span>)
          <span class="name">checkState</span>: <span class="name">childGroup</span>.<span class="name">checkState</span>
      }

      <span class="type"><a href="qml-qtquick-controls2-checkbox.html">CheckBox</a></span> {
          <span class="name">checked</span>: <span class="number">true</span>
          <span class="name">text</span>: <span class="name">qsTr</span>(<span class="string">&quot;Child 1&quot;</span>)
          <span class="name">leftPadding</span>: <span class="name">indicator</span>.<span class="name">width</span>
          <span class="name">ButtonGroup</span>.group: <span class="name">childGroup</span>
      }

      <span class="type"><a href="qml-qtquick-controls2-checkbox.html">CheckBox</a></span> {
          <span class="name">text</span>: <span class="name">qsTr</span>(<span class="string">&quot;Child 2&quot;</span>)
          <span class="name">leftPadding</span>: <span class="name">indicator</span>.<span class="name">width</span>
          <span class="name">ButtonGroup</span>.group: <span class="name">childGroup</span>
      }
  }

</pre>
<p><b>See also </b><a href="qtquickcontrols2-customize.html#customizing-checkbox">Customizing CheckBox</a>, <a href="qml-qtquick-controls2-buttongroup.html">ButtonGroup</a>, and <a href="qtquickcontrols2-buttons.html">Button Controls</a>.</p>
<!-- @@@CheckBox -->
<h2>Property Documentation</h2>
<!-- $$$checkState -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="checkState-prop">
<td class="tblQmlPropNode"><p>
<a name="checkState-prop"></a><span class="name">checkState</span> : <span class="type"><a href="../qtqml/qml-enumeration.html">enumeration</a></span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property holds the check state of the checkbox.</p>
<p>Available states:</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>Qt.Unchecked</code></td><td class="topAlign">The checkbox is unchecked.</td></tr>
<tr><td class="topAlign"><code>Qt.PartiallyChecked</code></td><td class="topAlign">The checkbox is partially checked. This state is only used when <a href="qml-qtquick-controls2-checkbox.html#tristate-prop">tristate</a> is enabled.</td></tr>
<tr><td class="topAlign"><code>Qt.Checked</code></td><td class="topAlign">The checkbox is checked.</td></tr>
</table></div>
<p><b>See also </b><a href="qml-qtquick-controls2-checkbox.html#tristate-prop">tristate</a> and <a href="qml-qtquick-controls2-abstractbutton.html#checked-prop">checked</a>.</p>
</div></div><!-- @@@checkState -->
<br/>
<!-- $$$nextCheckState -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="nextCheckState-prop">
<td class="tblQmlPropNode"><p>
<a name="nextCheckState-prop"></a><span class="name">nextCheckState</span> : <span class="type">function</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property holds a callback function that is called to determine the next check state whenever the checkbox is interactively toggled by the user via touch, mouse, or keyboard.</p>
<p>By default, a normal checkbox cycles between <code>Qt.Unchecked</code> and <code>Qt.Checked</code> states, and a tri-state checkbox cycles between <code>Qt.Unchecked</code>, <code>Qt.PartiallyChecked</code>, and <code>Qt.Checked</code> states.</p>
<p>The <code>nextCheckState</code> callback function can override the default behavior. The following example implements a tri-state checkbox that can present a partially checked state depending on external conditions, but never cycles to the partially checked state when interactively toggled by the user.</p>
<pre class="cpp">

  CheckBox {
      tristate: <span class="keyword">true</span>
      checkState: allChildrenChecked <span class="operator">?</span> <span class="type"><a href="../qtqml/qml-qtqml-qt.html">Qt</a></span><span class="operator">.</span>Checked :
                     anyChildChecked <span class="operator">?</span> <span class="type"><a href="../qtqml/qml-qtqml-qt.html">Qt</a></span><span class="operator">.</span>PartiallyChecked : <span class="type"><a href="../qtqml/qml-qtqml-qt.html">Qt</a></span><span class="operator">.</span>Unchecked

      nextCheckState: function() {
          <span class="keyword">if</span> (checkState <span class="operator">=</span><span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="../qtqml/qml-qtqml-qt.html">Qt</a></span><span class="operator">.</span>Checked)
              <span class="keyword">return</span> <span class="type"><a href="../qtqml/qml-qtqml-qt.html">Qt</a></span><span class="operator">.</span>Unchecked
          <span class="keyword">else</span>
              <span class="keyword">return</span> <span class="type"><a href="../qtqml/qml-qtqml-qt.html">Qt</a></span><span class="operator">.</span>Checked
      }
  }

</pre>
<p>This property was introduced in  QtQuick.Controls 2.4 (Qt 5.11).</p>
</div></div><!-- @@@nextCheckState -->
<br/>
<!-- $$$tristate -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="tristate-prop">
<td class="tblQmlPropNode"><p>
<a name="tristate-prop"></a><span class="name">tristate</span> : <span class="type"><a href="../qtqml/qml-bool.html">bool</a></span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property holds whether the checkbox is a tri-state checkbox.</p>
<p>In the animation below, the first checkbox is tri-state:</p>
<p class="centerAlign"><img src="images/qtquickcontrols2-checkbox-tristate.gif" alt="" /></p><p>The default is <code>false</code>, i.e&#x2e;, the checkbox has only two states.</p>
</div></div><!-- @@@tristate -->
<br/>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2018 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br/>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br/>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>