QStandardItem: add user-tristate and auto-tristate getters/setters

and deprecate isTristate()/setTristate() which isn't specific enough.

This matches the changes to the flags themselves.

Change-Id: I0ba592af340cb81fc9f4d483569844fe8d7510c3
Reviewed-by: Jarek Kobus <jaroslaw.kobus@theqtcompany.com>

src/gui/itemmodels/qstandarditemmodel.cpp

@@ -1224,7 +1224,7 @@ void QStandardItem::setSelectable(bool selectable)
   The item delegate will render a checkable item with a check box next to the
   item's text.
 
-  \sa isCheckable(), setCheckState(), setTristate()
+  \sa isCheckable(), setCheckState(), setUserTristate(), setAutoTristate()
 */
 void QStandardItem::setCheckable(bool checkable)
 {
@@ -1244,34 +1244,87 @@ void QStandardItem::setCheckable(bool checkable)
 
   The default value is false.
 
-  \sa setCheckable(), checkState(), isTristate()
+  \sa setCheckable(), checkState(), isUserTristate(), isAutoTristate()
 */
 
 /*!
-  Sets whether the item is tristate. If \a tristate is true, the
+  \fn void QStandardItem::setTristate(bool tristate)
-  item is checkable with three separate states; otherwise, the item
+  \obsolete
-  is checkable with two states. (Note that this also requires that
-  the item is checkable; see isCheckable().)
 
-  \sa isTristate(), setCheckable(), setCheckState()
+  Use QStandardItem::setAutoTristate(bool tristate) instead.
+  For a tristate checkbox that the user can change between all three
+  states, use QStandardItem::setUserTristate(bool tristate) instead.
 */
-void QStandardItem::setTristate(bool tristate)
+
+/*!
+  \fn void QStandardItem::isTristate() const
+  \obsolete
+
+  Use QStandardItem::isAutoTristate() instead.
+  For a tristate checkbox that the user can change between all three
+  states, use QStandardItem::isUserTristate() instead.
+*/
+
+/*!
+  Sets whether the item is tristate and controlled by QTreeWidget.
+  This enables automatic management of the state of parent items in QTreeWidget
+  (checked if all children are checked, unchecked if all children are unchecked,
+  or partially checked if only some children are checked).
+
+  \since 5.6
+  \sa isAutoTristate(), setCheckable(), setCheckState()
+*/
+void QStandardItem::setAutoTristate(bool tristate)
 {
     Q_D(QStandardItem);
     d->changeFlags(tristate, Qt::ItemIsAutoTristate);
 }
 
 /*!
-  \fn bool QStandardItem::isTristate() const
+  \fn bool QStandardItem::isAutoTristate() const
 
-  Returns whether the item is tristate; that is, if it's checkable with three
+  Returns whether the item is tristate and is controlled by QTreeWidget.
-  separate states.
 
   The default value is false.
 
-  \sa setTristate(), isCheckable(), checkState()
+  \since 5.6
+  \sa setAutoTristate(), isCheckable(), checkState()
 */
 
+/*!
+  Sets whether the item is tristate and controlled by the user.
+  If \a tristate is true, the user can cycle through three separate states;
+  otherwise, the item is checkable with two states.
+  (Note that this also requires that the item is checkable; see isCheckable().)
+
+  \since 5.6
+  \sa isUserTristate(), setCheckable(), setCheckState()
+*/
+void QStandardItem::setUserTristate(bool tristate)
+{
+    Q_D(QStandardItem);
+    d->changeFlags(tristate, Qt::ItemIsUserTristate);
+}
+
+/*!
+  \fn bool QStandardItem::isUserTristate() const
+  \since 5.6
+
+  Returns whether the item is tristate; that is, if it's checkable with three
+  separate states and the user can cycle through all three states.
+
+  The default value is false.
+
+  \sa setUserTristate(), isCheckable(), checkState()
+*/
+
+#if QT_DEPRECATED_SINCE(5, 6)
+void QStandardItem::setTristate(bool tristate)
+{
+    setAutoTristate(tristate);
+}
+#endif
+
 #ifndef QT_NO_DRAGANDDROP
 
 /*!

src/gui/itemmodels/qstandarditemmodel.h

@@ -158,10 +158,20 @@ public:
     }
     void setCheckable(bool checkable);
 
-    inline bool isTristate() const {
+    inline bool isAutoTristate() const {
         return (flags() & Qt::ItemIsAutoTristate) != 0;
     }
-    void setTristate(bool tristate);
+    void setAutoTristate(bool tristate);
+
+    inline bool isUserTristate() const {
+        return (flags() & Qt::ItemIsUserTristate) != 0;
+    }
+    void setUserTristate(bool tristate);
+
+#if QT_DEPRECATED_SINCE(5, 6)
+    QT_DEPRECATED bool isTristate() const { return isAutoTristate(); }
+    QT_DEPRECATED void setTristate(bool tristate);
+#endif
 
 #ifndef QT_NO_DRAGANDDROP
     inline bool isDragEnabled() const {

tests/auto/gui/itemmodels/qstandarditem/tst_qstandarditem.cpp

@@ -277,8 +277,11 @@ void tst_QStandardItem::getSetFlags()
     QVERIFY(item.isCheckable());
     QCOMPARE(item.checkState(), Qt::Unchecked);
     QVERIFY(item.flags() & Qt::ItemIsUserCheckable);
-    item.setTristate(true);
+    item.setUserTristate(true);
-    QVERIFY(item.isTristate());
+    QVERIFY(item.isUserTristate());
+    QVERIFY(item.flags() & Qt::ItemIsUserTristate);
+    item.setAutoTristate(true);
+    QVERIFY(item.isAutoTristate());
     QVERIFY(item.flags() & Qt::ItemIsAutoTristate);
 #ifndef QT_NO_DRAGANDDROP
     item.setDragEnabled(true);
@@ -305,9 +308,11 @@ void tst_QStandardItem::getSetFlags()
     item.setCheckable(false);
     QVERIFY(!item.isCheckable());
     QVERIFY(!(item.flags() & Qt::ItemIsUserCheckable));
-    QVERIFY(item.isTristate());
+    item.setUserTristate(false);
-    item.setTristate(false);
+    QVERIFY(!item.isUserTristate());
-    QVERIFY(!item.isTristate());
+    QVERIFY(!(item.flags() & Qt::ItemIsUserTristate));
+    item.setAutoTristate(false);
+    QVERIFY(!item.isAutoTristate());
     QVERIFY(!(item.flags() & Qt::ItemIsAutoTristate));
 #ifndef QT_NO_DRAGANDDROP
     QVERIFY(item.isDragEnabled());
@@ -324,6 +329,13 @@ void tst_QStandardItem::getSetFlags()
     item.setCheckState(Qt::Checked);
     item.setCheckable(true);
     QCOMPARE(item.checkState(), Qt::Checked);
+
+    // deprecated API
+    item.setTristate(true);
+    QVERIFY(item.isTristate());
+    QVERIFY(item.flags() & Qt::ItemIsTristate);
+    item.setTristate(false);
+    QVERIFY(!(item.flags() & Qt::ItemIsTristate));
 }
 
 void tst_QStandardItem::getSetRowAndColumnCount()