Control QML Type
Type de base abstrait offrant des fonctionnalités communes à tous les contrôles. Plus d'informations...
| Import Statement: | import QtQuick.Controls |
| Inherits: | |
| Inherited By: |
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.
Propriété Documentation
availableHeight : real |
Cette propriété indique la hauteur disponible pour contentItem après déduction de l'espacement vertical de height du contrôle.
Voir également Control Layout, padding, topPadding, et bottomPadding.
availableWidth : real |
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" } }
Remarque : si l'élément d'arrière-plan n'a pas de taille explicite spécifiée, il suit automatiquement la taille du contrôle. Dans la plupart des cas, il n'est pas nécessaire de spécifier la largeur ou la hauteur d'un élément d'arrière-plan.
Remarque : la plupart des contrôles utilisent la taille implicite de l'élément d'arrière-plan pour calculer la taille implicite du contrôle lui-même. Si vous remplacez l'élément d'arrière-plan par un élément personnalisé, vous devez également envisager de lui fournir une taille implicite raisonnable (à moins qu'il ne s'agisse d'un élément tel que Image, qui possède sa propre taille implicite).
Voir également Control Layout.
bottomInset : real |
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 également Control Layout et topInset.
bottomPadding : real |
Cette propriété définit le padding du bas. 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 } }
Remarque : l'élément de contenu est automatiquement positionné et redimensionné pour s'adapter à l'intérieur de padding du contrôle. Les liaisons avec les propriétés x, y, width, et height de l'élément de contenu ne sont pas respectées.
Remarque : la plupart des contrôles utilisent la taille implicite de l'élément de contenu pour calculer la taille implicite du contrôle lui-même. Si vous remplacez l'élément de contenu par un élément personnalisé, vous devez également envisager de lui fournir une taille implicite raisonnable (à moins qu'il ne s'agisse d'un élément tel que Text, qui possède sa propre taille implicite).
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.
Remarque : Cette propriété n'indique pas si l'élément a active focus, mais la raison pour laquelle l'élément a gagné ou perdu le focus.
| Constante | Description |
|---|---|
Qt.MouseFocusReason | Une action de la souris s'est produite. |
Qt.TabFocusReason | La touche Tab a été enfoncée. |
Qt.BacktabFocusReason | Un retour de tabulation s'est produit. L'entrée pour cela peut inclure les touches Shift ou Control ; par exemple Shift+Tab. |
Qt.ActiveWindowFocusReason | Le système de fenêtres a rendu cette fenêtre active ou inactive. |
Qt.PopupFocusReason | L'application a ouvert/fermé une fenêtre contextuelle qui a pris/retiré le focus du clavier. |
Qt.ShortcutFocusReason | L'utilisateur a tapé le raccourci d'un copain de l'étiquette. |
Qt.MenuBarFocusReason | La barre de menu a pris le focus. |
Qt.OtherFocusReason | Autre raison, généralement propre à l'application. |
Voir également Item::activeFocus et visualFocus.
font : font |
Cette propriété contient la police 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 peuvent maintenir la cohérence 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 transmettant 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 |
Cette propriété définit l'espacement 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 pour lesquels hoverEnabled n'est pas explicitement défini.
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 |
Cette propriété indique si le contrôle est survolé.
Voir également hoverEnabled.
implicitBackgroundHeight : real |
Cette propriété indique 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 |
Cette propriété indique 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 |
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 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 |
Cette propriété contient 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 |
Cette propriété définit l'insertion gauche de l'arrière-plan.
Cette propriété a été introduite dans QtQuick.Controls 2.5 (Qt 5.12).
Voir également Control Layout et rightInset.
leftPadding : real |
Cette propriété définit le padding 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 |
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 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 :
Remarque : différents styles peuvent spécifier le remplissage par défaut de certains contrôles de différentes manières, et ces manières peuvent changer au fil du temps en fonction de l'évolution des directives de conception sur lesquelles le style est basé. Pour s'assurer que ces changements n'affectent pas les valeurs de remplissage que vous avez spécifiées, il est préférable d'utiliser les propriétés les plus spécifiques disponibles. Par exemple, au lieu de définir la propriété padding :
padding: 0dé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 |
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 également Control Layout et leftInset.
rightPadding : real |
Cette propriété définit l'espacement à 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 éléments constitutifs 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 |
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 également Control Layout et bottomInset.
topPadding : real |
Cette propriété définit l'espacement supérieur. Sauf si elle est explicitement définie, sa valeur est égale à verticalPadding.
Voir aussi Control Layout, padding, bottomPadding, verticalPadding, et availableHeight.
verticalPadding : real |
Cette propriété définit le remplissage vertical. Sauf si elle est explicitement définie, la 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 |
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 visualiser le 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.
Remarque : il convient d'être prudent lors de l'activation des événements de roue pour les contrôles situés dans des éléments déroulants tels que Flickable, car le contrôle consommera les événements et interrompra donc le défilement du Flickable.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. 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.