Item QML Type

Un type QML visuel de base. Plus d'informations...

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

Propriétés

• activeFocus : bool
• activeFocusOnTab : bool
• anchors
  • anchors.alignWhenCentered : bool
  • anchors.baseline : AnchorLine
  • anchors.baselineOffset : real
  • anchors.bottom : AnchorLine
  • anchors.bottomMargin : real
  • anchors.centerIn : Item
  • anchors.fill : Item
  • anchors.horizontalCenter : AnchorLine
  • anchors.horizontalCenterOffset : real
  • anchors.left : AnchorLine
  • anchors.leftMargin : real
  • anchors.margins : real
  • anchors.right : AnchorLine
  • anchors.rightMargin : real
  • anchors.top : AnchorLine
  • anchors.topMargin : real
  • anchors.verticalCenter : AnchorLine
  • anchors.verticalCenterOffset : real
• antialiasing : bool
• baselineOffset : int
• children : list<Item>
• childrenRect
  • childrenRect.height : real
  • childrenRect.width : real
  • childrenRect.x : real
  • childrenRect.y : real
• clip : bool
• containmentMask : QObject*
• data : list<QtObject>
• enabled : bool
• focus : bool
• focusPolicy : enumeration (since 6.7)
• height : real
• implicitHeight : real
• implicitWidth : real
• layer.effect : Component
• layer.enabled : bool
• layer.format : enumeration
• layer.live : bool (since 6.5)
• layer.mipmap : bool
• layer.samplerName : string
• layer.samples : enumeration
• layer.smooth : bool
• layer.sourceRect : rect
• layer.textureMirroring : enumeration
• layer.textureSize : size
• layer.wrapMode : enumeration
• opacity : real
• palette : Palette (since 6.0)
• parent : Item
• resources : list<QtObject>
• rotation : real
• scale : real
• smooth : bool
• state : string
• states : list<State>
• transform : list<Transform>
• transformOrigin : enumeration
• transitions : list<Transition>
• visible : bool
• visibleChildren : list<Item>
• width : real
• x : real
• y : real
• z : real

Méthodes

• Item childAt(real x, real y)
• bool contains(point point)
• void dumpItemTree() (since 6.3)
• void forceActiveFocus()
• void forceActiveFocus(Qt::FocusReason reason)
• bool grabToImage(callback, targetSize)
• point mapFromGlobal(real x, real y)
• point mapFromItem(Item item, point p)
• rect mapFromItem(Item item, rect r)
• point mapFromItem(Item item, real x, real y)
• rect mapFromItem(Item item, real x, real y, real width, real height)
• point mapToGlobal(real x, real y)
• point mapToItem(Item item, point p)
• rect mapToItem(Item item, rect r)
• point mapToItem(Item item, real x, real y)
• rect mapToItem(Item item, real x, real y, real width, real height)
• Item nextItemInFocusChain(bool forward)

Description détaillée

Le type Item est le type de base pour tous les éléments visuels dans Qt Quick.

Tous les éléments visuels de Qt Quick héritent de Item. Bien qu'un objet Item n'ait pas d'apparence visuelle, il définit tous les attributs communs aux éléments visuels, tels que la position x et y, la largeur et la hauteur, l'ancrage et la gestion des touches.

Le type Item peut être utile pour regrouper plusieurs éléments sous un seul élément visuel racine. C'est le cas, par exemple, de la gestion des événements :

import QtQuick 2.0

Item {
    Image {
        source: "tile.png"
    }
    Image {
        x: 80
        width: 100
        height: 100
        source: "tile.png"
    }
    Image {
        x: 190
        width: 100
        height: 100
        fillMode: Image.Tile
        source: "tile.png"
    }
}

Gestion d'événements

Tous les types visuels basés sur des éléments peuvent utiliser des gestionnaires d'entrée pour gérer les événements d'entrée entrants (sous-classes de QInputEvent), tels que les événements liés à la souris, au toucher et aux touches. Il s'agit de la méthode déclarative préférée pour gérer les événements.

Une autre façon de gérer les événements tactiles est de sous-classer QQuickItem, d'appeler setAcceptTouchEvents() dans le constructeur et de surcharger touchEvent(). Accept l'ensemble de l'événement pour arrêter la livraison aux éléments situés en dessous et pour saisir exclusivement tous les points tactiles de l'événement. Utilisez QPointerEvent::setExclusiveGrabber() pour ne saisir que certains points de contact et permettre à l'événement d'être transmis plus loin.

De même, une sous-classe de QQuickItem peut appeler setAcceptedMouseButtons() pour s'enregistrer afin de recevoir les événements liés aux boutons de la souris, setAcceptHoverEvents() pour recevoir les événements liés au survol (mouvements de la souris alors qu'aucun bouton n'est enfoncé) et surcharger les fonctions virtuelles mousePressEvent(), mouseMoveEvent() et mouseReleaseEvent(). Ceux-ci peuvent également accepter l'événement pour empêcher toute livraison ultérieure et obtenir une saisie implicite en même temps ; ou explicitement grab l'unique QEventPoint que le QMouseEvent transporte.

La gestion des touches est disponible pour tous les types visuels basés sur les éléments via la propriété attachée Keys. La propriété Keys attached fournit des signaux de base tels que pressed et released, ainsi que des signaux pour des touches spécifiques, tels que spacePressed. L'exemple ci-dessous attribue le focus clavier à l'élément et gère la touche gauche via le gestionnaire général onPressed et la touche retour via le gestionnaire onReturnPressed:

import QtQuick 2.0

Item {
    focus: true
    Keys.onPressed: (event)=> {
        if (event.key == Qt.Key_Left) {
            console.log("move left");
            event.accepted = true;
        }
    }
    Keys.onReturnPressed: console.log("Pressed return");
}

Voir la propriété Keys attached pour une documentation détaillée.

Miroir de mise en page

Les dispositions des éléments peuvent être mises en miroir à l'aide de la propriété attachée LayoutMirroring. Ainsi, anchors est inversé horizontalement et les éléments qui disposent ou positionnent leurs enfants (tels que ListView ou Row) inversent également horizontalement la direction de leur disposition.

Voir LayoutMirroring pour plus de détails.

Couches d'éléments

Un élément est normalement rendu directement dans la fenêtre à laquelle il appartient. Cependant, en définissant layer.enabled, il est possible de déléguer l'élément et son sous-arbre entier dans une surface hors écran. Seule la surface hors écran, une texture, sera alors dessinée dans la fenêtre.

Si l'on souhaite que la taille de la texture soit différente de celle de l'élément, il est possible de le faire en utilisant layer.textureSize. Pour ne rendre qu'une partie de l'élément dans la texture, utilisez layer.sourceRect. Il est également possible de spécifier layer.sourceRect de manière à ce qu'elle s'étende au-delà des limites de l'élément. Dans ce cas, l'extérieur sera complété par des pixels transparents.

L'élément utilisera l'interpolation linéaire pour la mise à l'échelle si layer.smooth est défini sur true et utilisera le mipmap pour le sous-échantillonnage si layer.mipmap est défini sur true. Le mipmapping peut améliorer la qualité visuelle des éléments mis à l'échelle. Pour le mipmapping d'éléments d'une seule image, préférez Image::mipmap.

Opacité du calque et opacité de l'élément

Lorsque l'on applique opacity à une hiérarchie d'éléments, l'opacité est appliquée à chaque élément individuellement. Cela peut entraîner des résultats visuels indésirables lorsque l'opacité est appliquée à un sous-arbre. Prenons l'exemple suivant :

Opacité sans couche Item { id: nonLayered opacity: 0.5 width: 100 height: 100 Rectangle { width: 80; height: 80; border.width: 1 } Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 } }

Un calque est rendu avec l'opacité de l'élément racine à 1, puis l'opacité de l'élément racine est appliquée à la texture lorsqu'elle est dessinée. Cela signifie qu'un fondu dans une grande hiérarchie d'éléments de transparent à opaque, ou vice versa, peut être effectué sans les artefacts de chevauchement qu'entraîne le mélange alpha normal élément par élément. Voici le même exemple avec le calque activé :

Item {
    id: layered

    opacity: 0.5

    layer.enabled: true

    width: 100
    height: 100

    Rectangle { width: 80; height: 80; border.width: 1 }
    Rectangle { x: 20; y: 20; width: 80; height: 80; border.width: 1 }
}

Combiné avec ShaderEffects

En fixant la valeur de layer.enabled à true, l'élément devient texture provider, ce qui permet de l'utiliser directement comme texture, par exemple en combinaison avec le type ShaderEffect.

Il est possible d'appliquer un effet sur un calque au moment de l'exécution en utilisant layer.effect :

Item {
    id: layerRoot
    layer.enabled: true
    layer.effect: ShaderEffect {
        fragmentShader: "effect.frag.qsb"
    }
}

Voir ShaderEffect pour plus d'informations sur l'utilisation des effets.

Mémoire et performances

Lorsque le calque d'un élément est activé, le graphe de scène alloue au GPU une mémoire égale à width x height x 4. Dans les configurations à mémoire limitée, les calques de grande taille doivent être utilisés avec précaution.

Dans le monde QPainter / QWidget, il est parfois préférable de mettre en cache un contenu complexe dans une pixmap, une image ou une texture. Dans Qt Quick, grâce aux techniques déjà appliquées par le moteur de rendu du graphe de scène, ce ne sera pas le cas dans la plupart des cas. Les appels de dessin excessifs sont déjà réduits grâce à la mise en lots et un cache finira dans la plupart des cas par mélanger plus de pixels que le contenu original. Le surcoût lié au rendu vers un hors-écran et au mélange impliqué dans le dessin de la texture résultante est donc souvent plus élevé que le simple fait de laisser l'élément et ses enfants être dessinés normalement.

De plus, un élément utilisant un calque ne peut pas être mis en lots pendant le rendu. Cela signifie qu'une scène comportant de nombreux éléments en couches peut présenter des problèmes de performance.

Les calques peuvent être pratiques et utiles pour les effets visuels, mais ils doivent dans la plupart des cas être activés pour la durée de l'effet et désactivés par la suite.

Documentation sur les propriétés

activeFocus : bool [read-only]

Cette propriété en lecture seule indique si l'élément a le focus actif.

Si activeFocus est vrai, soit cet élément est celui qui reçoit actuellement la saisie au clavier, soit il est un ancêtre FocusScope de l'élément qui reçoit actuellement la saisie au clavier.

En général, activeFocus est obtenu en définissant focus sur un élément et les objets FocusScope qui l'entourent. Dans l'exemple suivant, les objets input et focusScope auront le focus actif, alors que l'objet rectangle racine ne l'aura pas.

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: focusScope
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

Voir également focus et Keyboard Focus dans Qt Quick.

activeFocusOnTab : bool

Cette propriété indique si l'élément doit faire partie de la chaîne de mise au point de l'onglet. Par défaut, elle est définie sur false.

La chaîne de focalisation sur la tabulation parcourt les éléments en visitant d'abord le parent, puis ses enfants dans l'ordre où ils apparaissent dans la propriété children. En appuyant sur la touche de tabulation d'un élément de la chaîne de tabulation, le focus clavier passe à l'élément suivant de la chaîne. Une pression sur la touche BackTab (normalement Shift+Tab) déplace le focus sur l'élément précédent.

Pour mettre en place une chaîne de tabulation manuelle, voir KeyNavigation. Les événements liés à la touche de tabulation utilisés par Keys ou KeyNavigation ont la priorité sur le comportement de la chaîne de mise au point ; ignorez les événements dans d'autres gestionnaires de touches pour permettre la propagation.

Voir également QStyleHints::tabFocusBehavior et focusPolicy.

anchors group

Les ancres permettent de positionner un élément en spécifiant sa relation avec d'autres éléments.

Les marges s'appliquent aux ancres de haut, de bas, de gauche, de droite et de remplissage. La propriété anchors.margins peut être utilisée pour définir toutes les marges en une seule fois, à la même valeur. Elle ne remplace pas une marge spécifique définie précédemment ; pour supprimer une marge explicite, fixez sa valeur à undefined. Notez que les marges sont spécifiques aux ancres et ne sont pas appliquées si un élément n'utilise pas d'ancres.

Les décalages s'appliquent au centre horizontal, au centre vertical et aux ancres de ligne de base.

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.horizontalCenter: pic.horizontalCenter
        anchors.top: pic.bottom
        anchors.topMargin: 5
        // ...
    }
}

Item {
    Image {
        id: pic
        // ...
    }
    Text {
        id: label
        anchors.left: pic.right
        anchors.leftMargin: 5
        // ...
    }
}

anchors.fill permet à un élément d'avoir la même géométrie qu'un autre élément et équivaut à relier les quatre ancres directionnelles.

Pour effacer une valeur d'ancrage, définissez-la à undefined.

anchors.alignWhenCentered (par défaut true) force les ancres centrées à s'aligner sur un pixel entier ; si l'élément centré a une valeur impaire width ou height, l'élément sera positionné sur un pixel entier au lieu d'être placé sur un demi-pixel. Cela garantit que l'élément est peint avec netteté. Dans certains cas, cela n'est pas souhaitable, par exemple lors de la rotation de l'élément, des vibrations peuvent apparaître lorsque le centre est arrondi.

Pour plus d'informations, voir Dispositions d'ancrage.

antialiasing : bool

Utilisé par les éléments visuels pour décider si l'élément doit utiliser l'anticrénelage ou non. Dans certains cas, les éléments avec anticrénelage nécessitent plus de mémoire et sont potentiellement plus lents à rendre (voir anticrénelage pour plus de détails).

La valeur par défaut est false, mais elle peut être remplacée par des éléments dérivés.

baselineOffset : int

Spécifie la position de la ligne de base de l'article en coordonnées locales.

La ligne de base d'un élément Text est la ligne imaginaire sur laquelle se trouve le texte. Les contrôles contenant du texte définissent généralement leur ligne de base sur la ligne de base de leur texte.

Pour les éléments qui ne contiennent pas de texte, un décalage de la ligne de base de 0 est utilisé par défaut.

La propriété children contient la liste des enfants visuels de cet élément. La propriété resources contient les ressources non visuelles que vous souhaitez référencer par leur nom.

Il n'est généralement pas nécessaire de faire référence à ces propriétés lors de l'ajout d'éléments ou de ressources enfants, car la propriété par défaut data attribue automatiquement les objets enfants aux propriétés children et resources, le cas échéant. Voir la documentation data pour plus de détails.

childrenRect group

Cette propriété en lecture seule contient la position et la taille collectives des enfants de l'élément.

Cette propriété est utile si vous avez besoin d'accéder à la géométrie collective des enfants d'un élément afin de dimensionner correctement l'élément.

La géométrie renvoyée est locale à l'élément. Par exemple, la géométrie renvoyée est locale à l'élément :

Item {
    x: 50
    y: 100

    // prints: QRectF(-10, -20, 30, 40)
    Component.onCompleted: print(childrenRect)

    Item {
        x: -10
        y: -20
        width: 30
        height: 40
    }
}

clip : bool

Cette propriété indique si l'écrêtage est activé. La valeur par défaut est false.

Si l'écrêtage est activé, un élément écrêtera sa propre peinture, ainsi que celle de ses enfants, sur son rectangle de délimitation.

containmentMask : QObject*

Cette propriété contient un masque facultatif pour l'élément à utiliser dans la méthode contains(). Sa principale utilisation est actuellement de déterminer si un pointer event a atterri dans l'élément ou non.

Par défaut, la méthode contains() renvoie un message vrai pour tout point situé dans la zone de délimitation de l'élément. containmentMask permet un contrôle plus fin. Par exemple, si une sous-classe C++ QQuickItem personnalisée avec une méthode contains() spécialisée est utilisée comme containmentMask :

Item { id: item; containmentMask: AnotherItem { id: anotherItem } }

la méthode contains de l'élément renverrait alors true uniquement si l'implémentation contains() d'un autre élément renvoie true.

Un Shape peut être utilisé comme masque, pour qu'un élément ne réagisse à pointer events que dans une région non rectangulaire :

Rectangle { width: 90; height: 100 color: hoverHandler.hovered ? "wheat" : "lightgray" containmentMask: shape HoverHandler { id: hoverHandler } Shape { id: shape containsMode: Shape.FillContains ShapePath { fillColor: "lightsteelblue" startX: 10; startY: 20 PathArc { x: 10; y: 80 radiusX: 40; radiusY: 40 useLargeArc: true } PathLine { x: 10; y: 20 } } } }

Il est également possible de définir la méthode contains en QML. Par exemple, pour créer un élément circulaire qui ne réagit aux événements qu'à l'intérieur de ses limites réelles :

Rectangle { id: circle width: 100; height: width radius: width / 2 color: tapHandler.pressed ? "tomato" : hoverHandler.hovered ? "darkgray" : "lightgray" TapHandler { id: tapHandler } HoverHandler { id: hoverHandler } containmentMask: QtObject { property alias radius: circle.radius function contains(point: point) : bool { return (Math.pow(point.x - radius, 2) + Math.pow(point.y - radius, 2)) < Math.pow(radius, 2) } } }

Voir également Qt Quick Exemples - Formes.

data : list<QtObject> [default]

La propriété de données vous permet de mélanger librement les enfants visuels et les ressources dans un élément. Si vous assignez un élément visuel à la liste de données, il devient un enfant et si vous assignez un autre type d'objet, il est ajouté en tant que ressource.

Vous pouvez donc écrire :

Item {
    Text {}
    Rectangle {}
    Timer {}
}

au lieu de :

Item {
    children: [
        Text {},
        Rectangle {}
    ]
    resources: [
        Timer {}
    ]
}

Il n'est généralement pas nécessaire de faire référence à la propriété data, puisqu'il s'agit de la propriété par défaut de l'élément et que tous les éléments enfants sont donc automatiquement affectés à cette propriété.

enabled : bool

Cette propriété indique si l'élément reçoit des événements de souris et de clavier. La valeur par défaut est true.

Lorsque la valeur est false, l'élément ne reçoit pas les événements liés au clavier ou au dispositif de pointage, tels que l'appui, le relâchement ou le clic, mais il peut toujours recevoir les événements liés au survol.

La définition de cette propriété affecte directement la valeur enabled des éléments enfants. Lorsque la valeur de cette propriété est false, les valeurs enabled de tous les éléments enfants deviennent également false. Lorsque cette propriété vaut true, les valeurs enabled des éléments enfants sont ramenées à true, à moins qu'elles n'aient été explicitement fixées à false.

La définition de cette propriété à false entraîne automatiquement la définition de activeFocus à false, et cet élément ne recevra plus d'événements clavier.

Voir également visible.

focus : bool

Cette propriété indique si l'élément est au centre de l'attention à l'intérieur du site FocusScope. Si elle est vraie, l'élément obtiendra le focus actif lorsque l'élément englobant FocusScope obtiendra le focus actif.

Dans l'exemple suivant, input obtiendra le focus actif lorsque scope obtiendra le focus actif :

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

Pour les besoins de cette propriété, la scène dans son ensemble est supposée agir comme un champ de focalisation. D'un point de vue pratique, cela signifie que le QML suivant donnera le focus actif à input au démarrage.

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

Voir également activeFocus et Keyboard Focus dans Qt Quick.

focusPolicy : enumeration [since 6.7]

Cette propriété détermine la façon dont l'élément accepte le focus.

Cette propriété a été introduite dans Qt 6.7.

Définit la position et la taille de l'élément. La valeur par défaut est 0.

La position (x,y) est relative à la page parent.

Item { x: 100; y: 100; width: 100; height: 100 }

Définit la largeur ou la hauteur préférée de l'élément.

Si width ou height n'est pas spécifié, la taille effective d'un élément sera déterminée par son implicitWidth ou implicitHeight.

Toutefois, si un élément est l'enfant d'une mise en page, cette dernière déterminera la taille préférée de l'élément à l'aide de sa taille implicite. Dans ce cas, la taille explicite width ou height est ignorée.

La taille implicite par défaut de la plupart des éléments est 0x0, mais certains éléments ont une taille implicite inhérente qui ne peut être modifiée, par exemple Image et Text.

La définition de la taille implicite est utile pour définir des composants qui ont une taille préférée en fonction de leur contenu, par exemple :

// Label.qml
import QtQuick 2.0

Item {
    property alias icon: image.source
    property alias label: text.text
    implicitWidth: text.implicitWidth + image.implicitWidth
    implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
    Image { id: image }
    Text {
        id: text
        wrapMode: Text.Wrap
        anchors.left: image.right; anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
    }
}

layer.effect : Component

Détient l'effet appliqué à ce calque.

Il s'agit généralement d'un composant ShaderEffect, mais n'importe quel composant Item peut être attribué. L'effet doit avoir une propriété de texture source dont le nom correspond à layer.samplerName.

Voir également layer.samplerName et Item Layers.

layer.enabled : bool

Indique si l'élément est superposé ou non. La superposition est désactivée par défaut.

Un élément superposé est rendu dans une surface hors écran et mis en cache jusqu'à ce qu'il soit modifié. L'activation de la superposition pour les hiérarchies d'éléments QML complexes peut parfois constituer une optimisation.

Aucune des autres propriétés du calque n'a d'effet lorsque le calque est désactivé.

Voir également Item Layers.

layer.format : enumeration

Cette propriété définit le format de la texture d'appui. La modification de cette propriété prend tout son sens lorsque l'adresse layer.effect est également spécifiée.

Voir aussi Item Layers.

layer.live : bool [since 6.5]

Lorsque cette propriété est vraie, la texture du calque est mise à jour à chaque fois que l'élément est actualisé. Dans le cas contraire, il s'agira toujours d'une image figée.

Par défaut, cette propriété est définie sur true.

Cette propriété a été introduite dans Qt 6.5.

Voir également Item Layers.

layer.mipmap : bool

Si cette propriété est vraie, des mipmaps sont générés pour la texture.

Voir aussi Item Layers.

layer.samplerName : string

Contient le nom de la propriété de texture source de l'effet.

Cette valeur doit correspondre au nom de la propriété de texture source de l'effet afin que l'élément puisse transmettre correctement la surface hors écran du calque à l'effet.

Voir également layer.effect, ShaderEffect, et Item Layers.

layer.samples : enumeration

Cette propriété permet de demander un rendu multi-échantillonné dans la couche.

Par défaut, le multi-échantillonnage est activé chaque fois que le multi-échantillonnage est activé pour l'ensemble de la fenêtre, à condition que le moteur de rendu de la scène utilisé et l'API graphique sous-jacente le prennent en charge.

En fixant la valeur à 2, 4, etc., il est possible de demander un rendu multi-échantillonné pour une partie de la scène sans activer le multi-échantillonnage pour l'ensemble de la scène. De cette manière, le multi-échantillonnage n'est appliqué qu'à un sous-arbre donné, ce qui peut entraîner des gains de performance significatifs puisque le multi-échantillonnage n'est pas appliqué à d'autres parties de la scène.

layer.smooth : bool

Indique si le calque est transformé de façon régulière. Lorsque cette propriété est activée, l'échantillonnage de la texture de la couche est effectué à l'aide de l'interpolation linear, tandis que si elle n'est pas lisse, le mode de filtrage nearest est utilisé.

Par défaut, cette propriété est définie sur false.

Voir également Item Layers.

layer.sourceRect : rect

Cette propriété définit la zone rectangulaire de l'élément qui doit être rendue dans la texture. Le rectangle source peut être plus grand que l'élément lui-même. Si le rectangle est nul, ce qui est le cas par défaut, l'élément entier est rendu dans la texture.

Voir également Item Layers.

layer.textureMirroring : enumeration

Cette propriété définit la manière dont la texture générée doit être reflétée. La valeur par défaut est ShaderEffectSource.MirrorVertically. La mise en miroir personnalisée peut être utile si la texture générée est directement accessible par des shaders personnalisés, tels que ceux spécifiés par ShaderEffect. Si aucun effet n'est spécifié pour l'élément en couche, la mise en miroir n'a aucun effet sur la représentation de l'élément dans l'interface utilisateur.

layer.textureSize : size

Cette propriété indique la taille en pixels de la texture du calque. Si elle est vide, ce qui est le cas par défaut, la taille de l'élément est utilisée.

Voir aussi Item Layers.

layer.wrapMode : enumeration

Cette propriété définit les modes d'enveloppement associés à la texture. La modification de cette propriété prend tout son sens lorsque l'adresse layer.effect est spécifiée.

Voir aussi Item Layers.

opacity : real

Cette propriété définit l'opacité de l'élément. L'opacité est spécifiée sous la forme d'un nombre compris entre 0,0 (totalement transparent) et 1,0 (totalement opaque). La valeur par défaut est 1.0.

Lorsque cette propriété est définie, l'opacité spécifiée est également appliquée individuellement aux éléments enfants. Cela peut avoir un effet inattendu dans certaines circonstances. Par exemple, dans la deuxième série de rectangles ci-dessous, le rectangle rouge a spécifié une opacité de 0,5, ce qui affecte l'opacité de son rectangle enfant bleu, même si l'enfant n'a pas spécifié d'opacité.

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        opacity: 0.5
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

La modification de l'opacité d'un élément n'affecte pas le fait que l'élément reçoive des événements de saisie de l'utilisateur. (En revanche, la définition de la propriété visible sur false arrête les événements de la souris, et la définition de la propriété enabled sur false arrête les événements de la souris et du clavier, et supprime également le focus actif de l'élément).

Voir également visible.

palette : Palette [since 6.0]

Cette propriété contient la palette actuellement définie pour l'élément.

Cette propriété décrit la palette demandée pour l'élément. La palette est utilisée par le style de l'élément lors du rendu de tous les contrôles et permet de 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 plateformes ou différents styles définissent différentes palettes pour une application.

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

• en transmettant une palette personnalisée à QGuiApplication::setPalette(), avant de charger tout QML ; ou
• en spécifiant les couleurs dans le fichier qtquickcontrols2.conf.

Les éléments propagent les propriétés explicites de la palette des parents aux enfants. Si vous modifiez une propriété spécifique de la palette d'un élément, cette propriété se propage à tous les enfants de l'élément, en remplaçant les valeurs par défaut du système pour cette propriété.

Item {
    palette {
        buttonText: "maroon"
        button: "lavender"
    }

    Button {
        text: "Click Me"
    }
}

Cette propriété a été introduite dans Qt 6.0.

Voir aussi Window::palette, Popup::palette, ColorGroup, Palette, et SystemPalette.

parent : Item

Cette propriété contient le parent visuel de l'élément.

rotation : real

Cette propriété indique la rotation de l'élément en degrés dans le sens des aiguilles d'une montre autour de son site transformOrigin.

La valeur par défaut est de 0 degré (c'est-à-dire aucune rotation).

Rectangle {
    color: "blue"
    width: 100; height: 100
    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        rotation: 30
    }
}

Voir également Transform et Rotation.

scale : real

Cette propriété contient le facteur d'échelle de cet élément.

Une échelle inférieure à 1,0 réduit la taille de l'élément et une échelle supérieure à 1,0 augmente la taille de l'élément. Une échelle négative a pour effet de refléter l'élément lors du rendu.

La valeur par défaut est 1,0.

La mise à l'échelle est appliquée à partir du site transformOrigin.

import QtQuick 2.0

Rectangle {
    color: "blue"
    width: 100; height: 100

    Rectangle {
        color: "green"
        width: 25; height: 25
    }

    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        scale: 1.4
        transformOrigin: Item.TopLeft
    }
}

Voir également Transform et Scale.

smooth : bool

Principalement utilisé dans les articles basés sur des images pour décider si l'article doit utiliser un échantillonnage lisse ou non. L'échantillonnage lisse est réalisé à l'aide d'une interpolation linéaire, tandis que l'échantillonnage non lisse est réalisé à l'aide du plus proche voisin.

Dans Qt Quick 2.0, cette propriété a un impact minimal sur les performances.

Par défaut, cette propriété est définie sur true.

state : string

Cette propriété contient le nom de l'état actuel de l'élément.

Si l'élément est dans son état par défaut, c'est-à-dire qu'aucun état explicite n'a été défini, cette propriété contient une chaîne vide. De même, vous pouvez ramener un élément à son état par défaut en définissant cette propriété à une chaîne vide.

Voir également Qt Quick States.

states : list<State>

Cette propriété contient la liste des états possibles pour cet élément. Pour modifier l'état de cet élément, attribuez à la propriété state l'un de ces états ou attribuez à la propriété state la valeur d'une chaîne vide pour rétablir l'état par défaut de l'élément.

Cette propriété est spécifiée sous la forme d'une liste d'objets State. Par exemple, voici un élément avec les états "red_color" et "blue_color" :

import QtQuick 2.0

Rectangle {
    id: root
    width: 100; height: 100

    states: [
        State {
            name: "red_color"
            PropertyChanges { root.color: "red" }
        },
        State {
            name: "blue_color"
            PropertyChanges { root.color: "blue" }
        }
    ]
}

Voir Qt Quick States et Animation and Transitions dans Qt Quick pour plus de détails sur l'utilisation des états et des transitions.

Voir également transitions.

transform : list<Transform> [read-only]

Cette propriété contient la liste des transformations à appliquer.

Cette propriété est spécifiée sous la forme d'une liste d'objets dérivés de Transform. Par exemple, cette propriété est spécifiée sous la forme d'une liste d'objets dérivés de :

import QtQuick

Image {
    source: "images/qt-logo.png"
    transform: [
        Scale { origin.x: 25; origin.y: 25; xScale: 1.25 },
        Rotation { origin.x: 45; origin.y: 55; angle: 45 }
    ]
}

Pour plus d'informations, voir Transform.

transformOrigin : enumeration

Cette propriété définit le point d'origine autour duquel l'échelle et la rotation sont transformées.

Neuf origines de transformation sont disponibles, comme le montre l'image ci-dessous. L'origine de la transformation par défaut est Item.Center.

Cet exemple fait pivoter une image autour de son coin inférieur droit.

Image {
    source: "myimage.png"
    transformOrigin: Item.BottomRight
    rotation: 45
}

Pour définir un point d'origine de transformation arbitraire, utilisez les types de transformation Scale ou Rotation avec transform.

transitions : list<Transition>

Cette propriété contient la liste des transitions pour cet élément. Celles-ci définissent les transitions à appliquer à l'élément chaque fois qu'il change d'adresse state.

Cette propriété est spécifiée sous la forme d'une liste d'objets Transition. Par exemple, cette propriété est spécifiée sous la forme d'une liste d'objets :

import QtQuick 2.0

Item {
    transitions: [
        Transition {
            //...
        },
        Transition {
            //...
        }
    ]
}

Voir Qt Quick States and Animation and Transitions in Qt Quick pour plus de détails sur l'utilisation des états et des transitions.

Voir également states.

visible : bool

Cette propriété indique si l'élément est visible. Par défaut, elle est égale à true (vrai).

La définition de cette propriété affecte directement la valeur visible des éléments enfants. Lorsque cette propriété vaut false, les valeurs visible de tous les éléments enfants deviennent également false. Lorsque la valeur est fixée à true, les valeurs visible des éléments enfants sont ramenées à true, à moins qu'elles n'aient été explicitement fixées à false.

(En raison de ce comportement de flux, l'utilisation de la propriété visible peut ne pas avoir l'effet escompté si une liaison de propriété ne doit répondre qu'aux changements explicites de propriété. Dans ce cas, il peut être préférable d'utiliser la propriété opacity ).

Si cette propriété est définie sur false, l'élément ne recevra plus d'événements liés à la souris, mais continuera à recevoir des événements liés aux touches et conservera le clavier focus s'il a été défini. (En revanche, si la propriété enabled est définie sur false, les événements souris et clavier sont interrompus et le focus de l'élément est supprimé).

Voir également opacity et enabled.

visibleChildren : list<Item>

Cette propriété en lecture seule répertorie tous les enfants de l'élément qui sont actuellement visibles. Notez que la visibilité d'un enfant peut avoir changé explicitement, ou parce que la visibilité de cet élément (son parent) ou d'un autre grand-parent a changé.

z : real

Définit l'ordre d'empilement des éléments frères. Par défaut, l'ordre d'empilement est de 0.

Les éléments ayant une valeur d'empilement supérieure sont dessinés au-dessus des frères et sœurs ayant un ordre d'empilement inférieur. Les éléments ayant la même valeur d'empilement sont dessinés de bas en haut dans l'ordre où ils apparaissent. Les éléments ayant une valeur d'empilement négative sont dessinés sous le contenu de leur parent.

L'exemple suivant illustre les différents effets de l'ordre d'empilement.

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        z: 1
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            z: -1
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Méthode Documentation

Item childAt(real x, real y)

Renvoie le premier élément enfant visible trouvé au point (x, y) dans le système de coordonnées de cet élément.

Renvoie null s'il n'existe pas d'élément de ce type.

bool contains(point point)

Renvoie true si cet élément contient point, qui est en coordonnées locales ; renvoie false dans le cas contraire. Il s'agit de la même vérification que celle utilisée pour tester la validité de QEventPoint lors de la livraison d'un événement, et elle est affectée par containmentMask s'il est défini.

[since 6.3] void dumpItemTree()

Extrait certains détails de l'arbre visuel des éléments en commençant par cet élément et ses enfants, de manière récursive.

La sortie est similaire à celle de ce code QML :

function dump(object, indent) {
    console.log(indent + object)
    for (const i in object.children)
        dump(object.children[i], indent + "    ")
}

dump(myItem, "")

Si vous voulez plus de détails, vous pouvez implémenter votre propre fonction et ajouter une sortie supplémentaire à la console.log, comme les valeurs de propriétés spécifiques.

Cette méthode a été introduite dans Qt 6.3.

Voir aussi QObject::dumpObjectTree().

void forceActiveFocus()

Force la focalisation active sur l'élément.

Cette méthode place le focus sur l'élément et garantit que tous les objets ancêtres FocusScope dans la hiérarchie des objets reçoivent également le focus focus.

La raison du changement de focus sera Qt::OtherFocusReason. Utilisez la méthode surchargée pour spécifier la raison du focus afin de permettre une meilleure gestion du changement de focus.

Voir également activeFocus.

void forceActiveFocus(Qt::FocusReason reason)

Force la focalisation active sur l'élément avec l'adresse reason.

Cette méthode place le focus sur l'élément et garantit que tous les objets ancêtres FocusScope dans la hiérarchie des objets reçoivent également focus.

Voir aussi activeFocus et Qt::FocusReason.

bool grabToImage(callback, targetSize)

Saisit l'élément dans une image en mémoire.

L'acquisition se fait de manière asynchrone et la fonction JavaScript callback est invoquée lorsque l'acquisition est terminée. Le rappel prend un argument, qui est le résultat de l'opération d'acquisition, un objet ItemGrabResult.

Utilisez targetSize pour spécifier la taille de l'image cible. Par défaut, le résultat aura la même taille que l'élément.

Si l'opération n'a pas pu être lancée, la fonction renvoie false.

L'extrait suivant montre comment saisir un élément et stocker les résultats dans un fichier :

Rectangle {
    id: sourceRectangle
    width: 100
    height: 100
    focus: true
    gradient: Gradient {
        GradientStop { position: 0; color: "steelblue" }
        GradientStop { position: 1; color: "black" }
    }

    Keys.onSpacePressed: {
        sourceRectangle.grabToImage(function(result) {
           result.saveToFile("something.png")
        })
    }
}

L'extrait suivant montre comment saisir un élément et utiliser les résultats dans un autre élément d'image :

Image {
    id: image
}

Keys.onSpacePressed: {
    sourceRectangle.grabToImage(function(result) {
        image.source = result.url
    }, Qt.size(50, 50))
}

point mapFromGlobal(real x, real y)

Met en correspondance le point (x, y), qui se trouve dans le système de coordonnées global, avec le système de coordonnées de l'élément, et renvoie un point correspondant à la coordonnée mise en correspondance.

Les propriétés suivantes de l'élément sont utilisées dans la mise en correspondance : x, y, scale, rotation, transformOrigin, et transform.

Si les éléments font partie de scènes différentes, la correspondance inclut la position relative des deux scènes.

Met en correspondance le point (x, y) ou le rectangle (x, y, width, height), qui se trouve dans le système de coordonnées de item, avec le système de coordonnées de cet élément, et renvoie un point ou un rect correspondant à la coordonnée mise en correspondance.

Les propriétés suivantes de l'élément sont utilisées dans la mise en correspondance : x, y, scale, rotation, transformOrigin, et transform.

Si les éléments font partie de scènes différentes, la correspondance inclut la position relative des deux scènes.

Si item est une valeur null, le point ou le rectangle est mappé à partir du système de coordonnées de la scène.

Les versions acceptant le point et le rect sont depuis Qt 5.15.

point mapToGlobal(real x, real y)

Met en correspondance le point (x, y), qui se trouve dans le système de coordonnées de cet élément, avec le système de coordonnées global, et renvoie un point correspondant à la coordonnée mise en correspondance.

Les propriétés suivantes de l'élément sont utilisées dans la mise en correspondance : x, y, scale, rotation, transformOrigin, et transform.

Si les éléments font partie de scènes différentes, la correspondance inclut la position relative des deux scènes.

Met en correspondance le point (x, y) ou le rectangle (x, y, width, height), qui se trouve dans le système de coordonnées de cet élément, avec le système de coordonnées de item, et renvoie un point ou un rect correspondant à la coordonnée mise en correspondance.

Les propriétés suivantes de l'élément sont utilisées dans la mise en correspondance : x, y, scale, rotation, transformOrigin, et transform.

Si les éléments font partie de scènes différentes, la correspondance inclut la position relative des deux scènes.

Si item est une valeur null, le point ou le rect correspond au système de coordonnées de la scène.

Les versions acceptant le point et le rect sont depuis Qt 5.15.

Item nextItemInFocusChain(bool forward)

Renvoie l'élément de la chaîne de mise au point qui est le plus proche de cet élément. Si forward est true ou n'est pas fourni, il s'agit de l'élément suivant dans la direction avant. Si forward est false, il s'agit de l'élément suivant dans le sens inverse.