Control QML Type

Type de base abstrait fournissant des fonctionnalités communes à tous les contrôles. En savoir plus...

• 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 les événements d’entrée provenant du système de fenêtrage et affiche sa propre représentation à l’écran.

Disposition du contrôle

Le schéma suivant illustre la disposition d'un contrôle type :

L'implicitWidth et l'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, auxquelles s'ajoutent les marges intérieures et extérieures. Ces propriétés déterminent la taille du contrôle lorsqu'aucune width ou height explicite n'est spécifiée.

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

Control {
    padding: 10

    contentItem: Text {
        text: "Content"
    }
}

L’élément d’ background occupe toute la largeur et toute la hauteur du contrôle, sauf si des marges intérieures ou une taille explicite lui ont été attribuées. Les marges d'arrière-plan sont utiles pour étendre la zone tactile/interactive d'un contrôle sans affecter sa taille visuelle. Elles sont souvent utilisées sur les appareils tactiles pour s'assurer qu'un contrôle n'est pas trop petit pour permettre à l'utilisateur d'interagir avec lui. Les marges affectent la taille du contrôle et, par conséquent, l'espace qu'il occupe dans une mise en page, par exemple.

Des marges intérieures négatives peuvent être utilisées pour agrandir l’arrière-plan par rapport au contrôle. L’exemple suivant utilise des marges intérieures négatives pour placer une ombre à l’extérieur 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, empêchent les clics et les touches d’atteindre 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 `Pane`, car l’` MouseArea ` se trouve en dessous de celui-ci dans la scène :

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

    Pane {
        anchors.fill: parent
    }
}

Les événements de molette sont interceptés par les contrôles si ` wheelEnabled ` est défini sur ` true`.

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

Documentation des propriétés

availableHeight : real [read-only]

Cette propriété indique la hauteur dont dispose l'contentItem, une fois le remplissage vertical déduit de l'height du contrôle.

Voir également Control Layout, padding, topPadding et bottomPadding.

availableWidth : real [read-only]

Cette propriété indique la largeur dont dispose l'contentItem, une fois le remplissage horizontal déduit de l'width du contrôle.

Voir également 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 le retrait 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 remplissage inférieur. Sauf indication contraire, sa valeur est égale à « verticalPadding ».

Voir également 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 transfert de focus ; vous ne devriez donc jamais avoir à la définir vous-même.

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 par le contrôle. La police est utilisée par le style du contrôle lors du rendu des composants standard, et permet de garantir que les contrôles personnalisés conservent une cohérence avec l'apparence et la convivialité natives de la plateforme. Il est courant que différentes plateformes, ou différents styles, définissent des polices différentes pour une même application.

La police par défaut dépend de l’environnement système. ` ApplicationWindow ` gère une police système/thème qui sert de valeur par défaut pour tous les contrôles. Il peut également exister des polices par défaut spécifiques à certains types de contrôles. Vous pouvez également définir la police par défaut des contrôles de l’une des manières suivantes :

• 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 afin de trouver la meilleure correspondance.

Le contrôle propage les propriétés de police explicites du parent vers les enfants. Si vous modifiez une propriété spécifique de la police d'un contrôle, cette propriété est propagée à tous les enfants du contrôle, remplaçant ainsi toute valeur 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. À moins d'être explicitement définie, sa valeur est égale à « padding ».

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

Voir également 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 la valeur « hoverEnabled » n’est pas explicitement définie.

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 curseur de la souris est positionné sur le contrôle.

Voir également hoverEnabled.

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

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

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

Elle est généralement utilisée, conjointement avec ` implicitContentHeight`, 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 ` 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.

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

Elle est généralement utilisée, conjointement avec ` implicitContentWidth`, pour calculer la propriété ` 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 héritant de Container ou de Pane, la valeur est calculée en fonction des éléments enfants du contenu.

Elle est généralement utilisée, conjointement avec ` implicitBackgroundHeight`, pour calculer la propriété ` 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é contient la largeur implicite du contenu.

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

Elle est généralement utilisée, conjointement avec ` implicitBackgroundWidth`, pour calculer l'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 le retrait 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 remplissage à gauche. Sauf indication contraire, sa valeur est égale à « horizontalPadding ».

Voir également Control Layout, padding, rightPadding, horizontalPadding et availableWidth.

locale : Locale

Cette propriété contient les paramètres régionaux 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 particulière n’ait été définie, il s’agit soit de la locale du contrôle parent, soit de la locale par défaut.

Le contrôle transmet les paramètres régionaux du contrôle parent à ses contrôles enfants. Si vous modifiez les paramètres régionaux du contrôle, ceux-ci sont répercutés sur tous ses contrôles enfants, remplaçant ainsi les paramètres régionaux par défaut du système.

Voir également mirrored.

mirrored : bool [read-only]

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

Cette propriété est fournie à titre pratique. Un contrôle est considéré comme inversé lorsque son sens d'affichage est de droite à gauche ; c'est-à-dire lorsque la propriété ` LayoutMirroring.enabled ` est définie sur ` true`.

À partir de Qt 6.2, la propriété locale n’a plus d’incidence sur 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 également Control Layout, availableWidth, availableHeight, topPadding, leftPadding, rightPadding et bottomPadding.

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

Cette propriété définit le retrait à 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 le remplissage de droite. Sauf indication contraire, sa valeur est égale à « horizontalPadding ».

Voir également Control Layout, padding, leftPadding, horizontalPadding et availableWidth.

spacing : real

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

L'espacement est utile pour les contrôles comportant des éléments constitutifs 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 le contrôle ; chaque style peut donc l'interpréter différemment, et certains peuvent même l'ignorer complètement.

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

Cette propriété définit le décalage vers le haut 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 le remplissage supérieur. À moins d'être explicitement définie, sa valeur est égale à « verticalPadding ».

Voir également Control Layout, padding, bottomPadding, verticalPadding et availableHeight.

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

Cette propriété définit l'espacement vertical. À moins d'être explicitement définie, sa valeur est égale à « padding ».

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

Voir également Control Layout, padding, topPadding, bottomPadding et horizontalPadding.

visualFocus : bool [read-only]

Cette propriété s'applique que le contrôle ait ou non le focus visuel. Elle prend la valeur « true » lorsque le contrôle a le focus actif et que la raison du focus est l'une des suivantes : « Qt.TabFocusReason », « Qt.BacktabFocusReason » ou « Qt.ShortcutFocusReason ».

En général, pour afficher le focus clavier, cette propriété est préférable à Item::activeFocus. Cela garantit que le focus clavier n’est affiché que lors d’une interaction avec le clavier, et non lors d’une interaction tactile 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 molette. La valeur par défaut est false.