Control QML Type

Type de base abstrait offrant des fonctionnalités communes à tous les contrôles. Plus d'informations...

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

Propriétés

• availableHeight : real
• availableWidth : real
• background : Item
• bottomInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• bottomPadding : real
• contentItem : Item
• focusReason : enumeration
• font : font
• horizontalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
• hoverEnabled : bool
• hovered : bool
• implicitBackgroundHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitBackgroundWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitContentHeight : real (since QtQuick.Controls 2.5 (Qt 5.12))
• implicitContentWidth : real (since QtQuick.Controls 2.5 (Qt 5.12))
• leftInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• leftPadding : real
• locale : Locale
• mirrored : bool
• padding : real
• rightInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• rightPadding : real
• spacing : real
• topInset : real (since QtQuick.Controls 2.5 (Qt 5.12))
• topPadding : real
• verticalPadding : real (since QtQuick.Controls 2.5 (Qt 5.12))
• visualFocus : bool
• wheelEnabled : bool

Description détaillée

Le contrôle est le type de base des contrôles d'interface utilisateur. Il reçoit des événements d'entrée du système de fenêtres et peint une représentation de lui-même à l'écran.

Disposition des contrôles

Le diagramme suivant illustre la disposition d'un contrôle typique :

Les pages implicitWidth et implicitHeight d'un contrôle sont généralement basées sur les tailles implicites de l'arrière-plan et de l'élément de contenu, ainsi que sur les encarts et les encadrements éventuels. Ces propriétés déterminent la taille du contrôle lorsqu'aucun width ou height explicite n'est spécifié.

La géométrie du site contentItem est déterminée par l'espacement. L'exemple suivant réserve une marge de 10 px entre les limites du contrôle et son contenu :

Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

L'élément background remplit la totalité de la largeur et de la hauteur du contrôle, à moins que des encarts ou une taille explicite n'aient été spécifiés. Les encarts d'arrière-plan sont utiles pour étendre la zone tactile/interactive d'un contrôle sans affecter sa taille visuelle. Ils sont souvent utilisés sur les appareils tactiles pour s'assurer qu'un contrôle n'est pas trop petit pour que l'utilisateur puisse interagir avec lui. Les encarts affectent la taille du contrôle et, par conséquent, l'espace qu'ils occupent dans une mise en page, par exemple.

Des encarts négatifs peuvent être utilisés pour que l'arrière-plan soit plus grand que le contrôle. L'exemple suivant utilise des encarts négatifs pour placer une ombre en dehors des limites du contrôle :

Control {
    topInset: -2
    leftInset: -2
    rightInset: -6
    bottomInset: -6

    background: BorderImage {
        source: ":/images/shadowed-background.png"
    }
}

Gestion des événements

Tous les contrôles, à l'exception des indicateurs non interactifs, ne laissent pas les clics et les contacts se répercuter sur les éléments situés en dessous d'eux. Par exemple, l'appel à console.log() dans l'exemple ci-dessous ne sera jamais exécuté lorsque l'on clique sur le volet, car le site MouseArea se trouve en dessous de lui dans la scène :

MouseArea {
    anchors.fill: parent
    onClicked: console.log("MouseArea was clicked")

    Pane {
        anchors.fill: parent
    }
}

Les événements de roue sont consommés par les contrôles si wheelEnabled est true.

Voir également ApplicationWindow, Container, et Using Qt Quick Controls types in property declarations.

Documentation sur les propriétés

availableHeight : real [read-only]

Cette propriété indique la hauteur disponible pour contentItem après déduction de l'espacement vertical de height du contrôle.

Voir aussi Control Layout, padding, topPadding, et bottomPadding.

availableWidth : real [read-only]

Cette propriété indique la largeur disponible pour contentItem après déduction de l'espacement horizontal de width du contrôle.

Voir aussi Control Layout, padding, leftPadding, et rightPadding.

background : Item

Cette propriété contient l'élément d'arrière-plan.

Button {
    id: control
    text: qsTr("Button")
    background: Rectangle {
        implicitWidth: 100
        implicitHeight: 40
        opacity: enabled ? 1 : 0.3
        color: control.down ? "#d0d0d0" : "#e0e0e0"
    }
}

Voir également Control Layout.

bottomInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété définit l'encart inférieur de l'arrière-plan.

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir aussi Control Layout et topInset.

bottomPadding : real

Cette propriété définit la marge inférieure. Sauf si elle est explicitement définie, sa valeur est égale à verticalPadding.

Voir aussi Control Layout, padding, topPadding, verticalPadding, et availableHeight.

contentItem : Item

Cette propriété contient l'élément de contenu visuel.

Button {
    id: control
    text: qsTr("Button")
    contentItem: Label {
        text: control.text
        verticalAlignment: Text.AlignVCenter
    }
}

Voir également Control Layout et padding.

focusReason : enumeration

Cette propriété contient la raison du dernier changement de focus.

La valeur de cette propriété est modifiée par Qt à chaque fois que le focus est transféré, et vous ne devriez jamais avoir à définir cette propriété vous-même.

Voir également Item::activeFocus et visualFocus.

font : font

Cette propriété contient la police de caractères actuellement définie pour le contrôle.

Cette propriété décrit la police demandée pour le contrôle. La police est utilisée par le style du contrôle lors du rendu des composants standard et est disponible pour garantir que les contrôles personnalisés restent cohérents avec l'aspect et la convivialité de la plate-forme native. Il est courant que différentes plates-formes ou différents styles définissent différentes polices pour une application.

La police par défaut dépend de l'environnement du système. ApplicationWindow maintient une police système/thème qui sert de police par défaut pour tous les contrôles. Il peut également y avoir des polices spéciales par défaut pour certains types de contrôles. Vous pouvez également définir la police par défaut pour les contrôles en

• en passant une police personnalisée à QGuiApplication::setFont(), avant de charger le QML ; ou
• en spécifiant les polices dans le fichier qtquickcontrols2.conf.

Enfin, la police est comparée à la base de données de polices de Qt pour trouver la meilleure correspondance.

Control propage les propriétés de police explicites des parents aux enfants. Si vous modifiez une propriété spécifique de la police d'un contrôle, cette propriété se propage à tous les enfants du contrôle, en remplaçant toutes les valeurs par défaut du système pour cette propriété.

Page {
    font.family: "Courier"

    Column {
        Label {
            text: qsTr("This will use Courier...")
        }

        Switch {
            text: qsTr("... and so will this")
        }
    }
}

Pour obtenir la liste complète des propriétés de police disponibles, consultez la documentation font QML Value Type.

horizontalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété définit le remplissage horizontal. Sauf si elle est explicitement définie, sa valeur est égale à padding.

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir aussi Control Layout, padding, leftPadding, rightPadding, et verticalPadding.

hoverEnabled : bool

Cette propriété détermine si le contrôle accepte les événements de survol. La valeur par défaut est Application.styleHints.useHoverEffects.

La définition de cette propriété propage la valeur à tous les contrôles enfants qui n'ont pas explicitement défini hoverEnabled.

Vous pouvez également activer ou désactiver les effets de survol pour toutes les applications Qt Quick Controls en définissant la variable d'environnement QT_QUICK_CONTROLS_HOVER_ENABLED.

Voir également hovered.

hovered : bool [read-only]

Cette propriété indique si le contrôle est survolé.

Voir aussi hoverEnabled.

implicitBackgroundHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété contient la hauteur implicite de l'arrière-plan.

La valeur est égale à background ? background.implicitHeight : 0.

Elle est généralement utilisée, avec implicitContentHeight, pour calculer la hauteur de l'arrière-plan implicitHeight:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir également implicitBackgroundWidth et implicitContentHeight.

implicitBackgroundWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété définit la largeur implicite de l'arrière-plan.

La valeur est égale à background ? background.implicitWidth : 0.

Elle est généralement utilisée, avec implicitContentWidth, pour calculer la largeur de l'arrière-plan implicitWidth:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir également implicitBackgroundHeight et implicitContentWidth.

implicitContentHeight : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété contient la hauteur implicite du contenu.

Pour les contrôles de base, la valeur est égale à contentItem ? contentItem.implicitHeight : 0. Pour les types qui héritent de Container ou Pane, la valeur est calculée en fonction des enfants du contenu.

Cette propriété est généralement utilisée, avec implicitBackgroundHeight, pour calculer la valeur de implicitHeight:

Control {
    implicitHeight: Math.max(implicitBackgroundHeight + topInset + bottomInset,
                             implicitContentHeight + topPadding + bottomPadding)
}

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir également implicitContentWidth et implicitBackgroundHeight.

implicitContentWidth : real [read-only, since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété indique la largeur implicite du contenu.

Pour les contrôles de base, la valeur est égale à contentItem ? contentItem.implicitWidth : 0. Pour les types qui héritent de Container ou Pane, la valeur est calculée en fonction des enfants du contenu.

Cette propriété est généralement utilisée, avec implicitBackgroundWidth, pour calculer la valeur de implicitWidth:

Control {
    implicitWidth: Math.max(implicitBackgroundWidth + leftInset + rightInset,
                            implicitContentWidth + leftPadding + rightPadding)
}

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir également implicitContentHeight et implicitBackgroundWidth.

leftInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété définit l'encart gauche de l'arrière-plan.

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir aussi Control Layout et rightInset.

leftPadding : real

Cette propriété définit la marge de gauche. Sauf si elle est explicitement définie, sa valeur est égale à horizontalPadding.

Voir aussi Control Layout, padding, rightPadding, horizontalPadding, et availableWidth.

locale : Locale

Cette propriété indique la locale du contrôle.

Elle contient des propriétés spécifiques à la locale pour le formatage des données et des nombres. À moins qu'une locale spéciale n'ait été définie, il s'agit soit de la locale du parent, soit de la locale par défaut.

Le contrôle propage la locale du parent aux enfants. Si vous modifiez la locale du contrôle, cette locale se propage à tous les enfants du contrôle, en remplaçant la locale par défaut du système.

Voir aussi mirrored.

mirrored : bool [read-only]

Cette propriété indique si le contrôle est en miroir.

Cette propriété est fournie pour des raisons de commodité. Un contrôle est considéré comme miroir lorsque son sens de présentation visuelle est de droite à gauche, c'est-à-dire lorsque LayoutMirroring.enabled est true.

Depuis Qt 6.2, la propriété locale n'affecte plus cette propriété.

Voir également LayoutMirroring et Interfaces utilisateur de droite à gauche.

padding : real

Cette propriété définit le remplissage par défaut.

Le remplissage ajoute un espace entre chaque bord de l'élément de contenu et l'élément d'arrière-plan, ce qui permet de contrôler efficacement la taille de l'élément de contenu. Pour spécifier une valeur de remplissage pour un bord spécifique du contrôle, définissez la propriété correspondante :

• leftPadding
• rightPadding
• topPadding
• bottomPadding

padding: 0

définissez plutôt chaque propriété spécifique :

leftPadding: 0
rightPadding: 0
topPadding: 0
bottomPadding: 0

Voir aussi Control Layout, availableWidth, availableHeight, topPadding, leftPadding, rightPadding, et bottomPadding.

rightInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété définit l'insertion droite de l'arrière-plan.

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir aussi Control Layout et leftInset.

rightPadding : real

Cette propriété contient la marge de droite. Sauf si elle est explicitement définie, sa valeur est égale à horizontalPadding.

Voir aussi Control Layout, padding, leftPadding, horizontalPadding, et availableWidth.

spacing : real

Cette propriété définit l'espacement.

L'espacement est utile pour les contrôles dont les blocs de construction sont multiples ou répétitifs. Par exemple, certains styles utilisent l'espacement pour déterminer la distance entre le texte et l'indicateur de CheckBox. L'espacement n'est pas imposé par Control, de sorte que chaque style peut l'interpréter différemment, et certains peuvent l'ignorer complètement.

topInset : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété définit l'encart supérieur de l'arrière-plan.

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir aussi Control Layout et bottomInset.

topPadding : real

Cette propriété définit la marge supérieure. Sauf si elle est explicitement définie, sa valeur est égale à verticalPadding.

Voir aussi Control Layout, padding, bottomPadding, verticalPadding, et availableHeight.

verticalPadding : real [since QtQuick.Controls 2.5 (Qt 5.12)]

Cette propriété définit le remplissage vertical. Sauf si elle est explicitement définie, sa valeur est égale à padding.

Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).

Voir aussi Control Layout, padding, topPadding, bottomPadding, et horizontalPadding.

visualFocus : bool [read-only]

Cette propriété indique si le contrôle a le focus visuel. Cette propriété vaut true lorsque le contrôle a un focus actif et que la raison du focus est soit Qt.TabFocusReason, Qt.BacktabFocusReason, ou Qt.ShortcutFocusReason.

En général, pour la visualisation du focus clé, cette propriété est préférable à Item::activeFocus. Cela permet de s'assurer que la focalisation sur les touches n'est visualisée que lors de l'interaction avec les touches, et non lors de l'interaction avec le toucher ou la souris.

Voir également focusReason et Item::activeFocus.

wheelEnabled : bool

Cette propriété détermine si le contrôle gère les événements de roue. La valeur par défaut est false.