CheckBox QML Type

Bouton de contrôle qui peut être activé ou désactivé. Plus d'informations...

• Liste de tous les membres, y compris les membres hérités

Propriétés

• checkState : enumeration
• nextCheckState : function (since QtQuick.Controls 2.4 (Qt 5.11))
• tristate : bool

Description détaillée

CheckBox présente un bouton d'option qui peut être activé (coché) ou désactivé (décoché). Les cases à cocher sont généralement utilisées pour sélectionner une ou plusieurs options parmi un ensemble d'options. Pour des ensembles d'options plus importants, comme ceux d'une liste, il est préférable d'utiliser CheckDelegate.

CheckBox hérite de l'API de AbstractButton. Par exemple, l'état de la case à cocher peut être défini à l'aide de la propriété checked.

Outre les états coché et non coché, il existe un troisième état : partiellement coché. L'état partiellement coché peut être activé à l'aide de la propriété tristate. Cet état indique que l'état normal coché/décoché ne peut pas être déterminé, généralement en raison d'autres états qui affectent la case à cocher. Cet état est utile lorsque plusieurs nœuds enfants sont sélectionnés dans une arborescence, par exemple.

ColumnLayout {
    CheckBox {
        checked: true
        text: qsTr("First")
    }
    CheckBox {
        text: qsTr("Second")
    }
    CheckBox {
        checked: true
        text: qsTr("Third")
    }
}

Les groupes de cases à cocher hiérarchiques peuvent être gérés à l'aide d'une adresse non exclusive : ButtonGroup.

L'exemple suivant montre comment l'état de contrôle combiné des enfants peut être lié à l'état de contrôle de la case à cocher parent :

Column {
    ButtonGroup {
        id: childGroup
        exclusive: false
        checkState: parentBox.checkState
    }

    CheckBox {
        id: parentBox
        text: qsTr("Parent")
        checkState: childGroup.checkState
    }

    CheckBox {
        checked: true
        text: qsTr("Child 1")
        leftPadding: indicator.width
        ButtonGroup.group: childGroup
    }

    CheckBox {
        text: qsTr("Child 2")
        leftPadding: indicator.width
        ButtonGroup.group: childGroup
    }
}

Voir également la personnalisation des contrôlesCheckBox, ButtonGroup et Button.

Documentation sur les propriétés

checkState : enumeration

Cette propriété indique l'état de la case à cocher.

États disponibles :

Voir également tristate et checked.

nextCheckState : function [since QtQuick.Controls 2.4 (Qt 5.11)]

Cette propriété contient une fonction de rappel qui est appelée pour déterminer le prochain état de la case à cocher chaque fois que l'utilisateur la fait basculer de manière interactive au moyen du toucher, de la souris ou du clavier.

Par défaut, une case à cocher normale alterne entre les états Qt.Unchecked et Qt.Checked, et une case à cocher à trois états alterne entre les états Qt.Unchecked, Qt.PartiallyChecked et Qt.Checked.

La fonction de rappel nextCheckState peut remplacer le comportement par défaut. L'exemple suivant met en œuvre une case à cocher à trois états qui peut présenter un état partiellement coché en fonction de conditions externes, mais qui ne passe jamais à l'état partiellement coché lorsque l'utilisateur la fait basculer de manière interactive.

CheckBox {
    tristate: true
    checkState: allChildrenChecked ? Qt.Checked :
                   anyChildChecked ? Qt.PartiallyChecked : Qt.Unchecked

    nextCheckState: function() {
        if (checkState === Qt.Checked)
            return Qt.Unchecked
        else
            return Qt.Checked
    }
}

Cette propriété a été introduite dans QtQuick.Controls 2.4 (Qt 5.11).

tristate : bool

Cette propriété indique si la case à cocher est une case à cocher à trois niveaux.

Dans l'animation ci-dessous, la première case à cocher est à trois états :

La valeur par défaut est false, c'est-à-dire que la case à cocher n'a que deux états.