Item QML Type

Un type visuel de base en QML. En savoir plus…

• 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
• mutabilityGroup : int (since 6.12)
• 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 de tous les éléments visuels dans Qt Quick.

Tous les éléments visuels d’ Qt Quick héritent de la classe « 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 les positions x et y, la largeur et la hauteur, l’ancrage et la prise en charge de la gestion des touches.

Le type « Item » peut s'avérer utile pour regrouper plusieurs éléments sous un seul élément visuel racine. Par exemple :

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 des événements

Tous les types visuels basés sur Item peuvent utiliser des gestionnaires d’entrée (Input Handlers) pour traiter les événements d’entrée entrants (sous-classes de QInputEvent), tels que les événements de souris, tactiles et de touches. Il s’agit de la méthode déclarative privilégiée pour gérer les événements.

Une autre méthode pour gérer les événements tactiles consiste à créer une sous-classe de ` QQuickItem`, à appeler `setAcceptTouchEvents()` dans le constructeur et à redéfinir la méthode `touchEvent()`. Utilisez ` Accept ` pour intercepter l’intégralité de l’événement afin d’empêcher sa transmission aux éléments situés en dessous et de capturer exclusivement tous les points de contact de l’événement. Utilisez ` QPointerEvent::setExclusiveGrabber()` pour ne capturer que certains points de contact et permettre la transmission de l’événement en aval.

De même, une sous-classe de ` QQuickItem ` peut appeler `setAcceptedMouseButtons()` pour s’enregistrer afin de recevoir les événements de boutons de souris, `setAcceptHoverEvents()` pour recevoir les événements de survol (mouvements de la souris sans qu’aucun bouton ne soit enfoncé), et redéfinir les fonctions virtuelles `mousePressEvent()`, `mouseMoveEvent()` et `mouseReleaseEvent()`. Celles-ci peuvent également accepter l’événement pour empêcher sa transmission ultérieure et obtenir simultanément une capture implicite ; ou intercepter explicitement ( grab ) l’ QEventPoint e unique transporté par l’ QMouseEvent.

La gestion des touches est disponible pour tous les types visuels basés sur des éléments via la propriété associée « Keys ». La propriété associée « Keys » fournit des signaux de base tels que « pressed » et « released », ainsi que des signaux pour des touches spécifiques, comme « 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 Entrée 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");
}

Consultez la propriété attachée ` Keys ` pour obtenir une documentation détaillée.

Mise en miroir de la disposition

La disposition des éléments peut être inversée à l’aide de la propriété attachée LayoutMirroring. Cela entraîne l’inversion horizontale de anchors et provoque également l’inversion horizontale de la direction de la disposition des éléments qui organisent ou positionnent leurs enfants (tels que ListView ou Row).

Voir LayoutMirroring pour plus de détails.

Couches d’éléments

Un élément est normalement affiché 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 l’ensemble de sa sous-arborescence vers une surface hors écran. Seule la surface hors écran, une texture, sera alors dessinée dans la fenêtre.

Si l’on souhaite disposer d’une texture d’une taille différente de celle de l’élément, cela est possible à l’aide de ` layer.textureSize`. Pour afficher uniquement une partie de l’élément dans la texture, utilisez ` layer.sourceRect`. Il est également possible de spécifier ` layer.sourceRect ` afin qu’elle s’étende au-delà des limites de l’élément. Dans ce cas, le pourtour 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 mipmap peut améliorer la qualité visuelle des éléments sous-échantillonnés. Pour le mipmap d’éléments Image uniques, privilégiez Image::mipmap.

Opacité du calque vs opacité de l’élément

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

Opacité sans calques 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 fixée à 1, puis l’opacité de l’élément racine est appliquée à la texture lors de son dessin. Cela signifie qu’un fondu dans une grande hiérarchie d’éléments, de transparent à opaque ou inversement, peut être réalisé sans les artefacts de chevauchement propres au mélange alpha classique élément par élément. Voici le même exemple avec les couches activées :

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ée avec ShaderEffects

En définissant ` layer.enabled ` sur `true`, l'élément se transforme en « 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 à un calque lors de l’exécution à l’aide de `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

Lorsqu’un calque d’un élément est activé, l’arbre de scène alloue de la mémoire sur le GPU à hauteur de width x height x 4. Dans les configurations où la mémoire est limitée, l’utilisation de calques volumineux doit être envisagée avec prudence.

Dans l’univers QPainter / QWidget, il est parfois préférable de mettre en cache un contenu complexe dans une carte de pixels (pixmap), une image ou une texture. Dans Qt Quick, en raison des techniques déjà appliquées par le moteur de rendu du graphe de scène, ce ne sera généralement pas le cas. Le nombre excessif d’appels de dessin est déjà réduit grâce au regroupement en lots, et un cache finira dans la plupart des cas par mélanger davantage de pixels que le contenu d’origine. La surcharge liée au rendu hors écran et au mélange nécessaire au dessin de la texture résultante est donc souvent plus coûteuse que de simplement laisser l’élément et ses enfants s’afficher normalement.

De plus, un élément utilisant un calque ne peut pas être regroupé lors du rendu. Cela signifie qu’une scène comportant de nombreux éléments superposés peut présenter des problèmes de performances.

La superposition de couches peut s’avérer pratique et utile pour les effets visuels, mais doit, dans la plupart des cas, être activée pendant la durée de l’effet, puis désactivée par la suite.

Documentation des 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 les entrées clavier, soit il s'agit d'un ancêtre ` FocusScope ` de l'élément qui reçoit actuellement les entrées clavier.

En général, on obtient le focus actif en définissant ` focus ` sur un élément et sur les objets ` FocusScope ` qui l'entourent. Dans l'exemple suivant, les objets ` input ` et ` focusScope ` auront le focus actif, contrairement à l'objet rectangle racine.

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 souhaite faire partie de la chaîne de focus du tab. Par défaut, elle est définie sur « false ».

La chaîne de focus Tab parcourt les éléments en visitant d'abord le parent, puis ses enfants dans l'ordre où ils apparaissent dans la propriété « children ». Appuyer sur la touche Tab sur un élément de la chaîne de focus Tab déplace le focus clavier vers l'élément suivant de la chaîne. Appuyer sur la touche BackTab (généralement Maj+Tab) déplace le focus vers l'élément précédent.

Pour configurer une chaîne de focus manuelle, consultez KeyNavigation. Les événements de la touche Tab utilisés par Keys ou KeyNavigation ont priorité sur le comportement de la chaîne de focus ; ignorez les événements dans les autres gestionnaires de touches pour permettre sa propagation.

Voir également QStyleHints::tabFocusBehavior et focusPolicy.

anchors group

Les ancrages permettent de positionner un élément en précisant sa relation avec d'autres éléments.

Les marges s'appliquent aux ancrages « top », « bottom », « left », « right » et « fill ». La propriété ` anchors.margins ` permet de définir simultanément toutes les marges sur une même valeur. Elle ne remplace pas une marge spécifique déjà définie ; pour effacer une marge explicite, définissez sa valeur sur ` undefined`. Notez que les marges sont spécifiques à chaque ancrage et ne s'appliquent pas si un élément n'utilise pas d'ancrages.

Les décalages s’appliquent aux ancrages « centre horizontal », « centre vertical » et « 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 Cette méthode permet de donner facilement à un élément la même géométrie qu’un autre élément ; elle équivaut à relier les quatre ancrages directionnels.

Pour effacer une valeur d’ancrage, définissez-la sur undefined.

anchors.alignWhenCentered (valeur par défaut : ` true`) force les ancrages centrés à s’aligner sur un pixel entier ; si l’élément à centrer a une valeur ` width ` ou ` height` impaire, il sera positionné sur un pixel entier plutôt que sur un demi-pixel. Cela garantit un rendu net de l’élément. Dans certains cas, ce comportement n’est pas souhaitable ; par exemple, lors de la rotation de l’élément, des tremblements peuvent apparaître car le centre est arrondi.

Pour plus d’informations, consultez la section « Mises en page d’ancrage ».

antialiasing : bool

Utilisé par les éléments visuels pour déterminer si l'élément doit ou non utiliser l'anticrénelage. Dans certains cas, les éléments avec anticrénelage nécessitent davantage de mémoire et peuvent être plus lents à afficher (voir la section « Anticrénelage » pour plus de détails).

La valeur par défaut est « false », mais elle peut être redéfinie par des éléments dérivés.

baselineOffset : int

Spécifie la position de la ligne de base de l'élément dans le système de coordonnées local.

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

Pour les éléments non textuels, un décalage par défaut de 0 est utilisé pour la ligne de base.

La propriété « children » contient la liste des éléments 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 enfants ou de ressources, car la propriété par défaut ` data ` attribuera automatiquement les objets enfants aux propriétés ` children ` et ` resources `, selon le cas. Pour plus de détails, consultez la documentation sur ` data `.

childrenRect group

Cette propriété en lecture seule contient la position et la taille cumulées des éléments 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 ce dernier.

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

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é s'applique que le découpage soit activé ou non. La valeur par défaut du découpage est « false ».

Si le rognage est activé, un élément rognera son propre dessin, ainsi que celui de ses éléments enfants, pour les limiter à son rectangle de délimitation.

containmentMask : QObject*

Cette propriété contient un masque facultatif pour l'élément, destiné à être utilisé dans la méthode contains(). Elle sert principalement, à l'heure actuelle, à déterminer si une pointer event a atterri dans l'élément ou non.

Par défaut, la méthode ` contains() ` renvoie `true` pour tout point situé à l’intérieur du cadre de délimitation de l’élément. ` containmentMask ` permet un contrôle plus précis. Par exemple, si une sous-classe C++ personnalisée de ` QQuickItem `, dotée d’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 de ` contains()` de `anotherItem` renvoie ` true`.

Un ` Shape ` peut être utilisé comme masque, pour faire en sorte qu’un élément ne réagisse à ` pointer events ` qu’au sein d’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 qu’aux événements se produisant à 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 Exemples d’Qt Quick s - Formes.

data : list<QtObject> [default]

La propriété « data » vous permet de combiner librement des éléments visuels et des ressources au sein d'un élément. Si vous attribuez un élément visuel à la liste « data », celui-ci devient un élément enfant ; si vous attribuez tout autre type d'objet, celui-ci est ajouté en tant que ressource.

Vous pouvez donc écrire :

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

au lieu de :

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

En règle générale, il ne devrait pas être nécessaire de faire référence à la propriété « data », car il s'agit de la propriété par défaut de l'élément « Item » et, par conséquent, tous les éléments enfants y sont automatiquement affectés.

enabled : bool

Cette propriété indique si l'élément reçoit les événements de souris et de clavier. Par défaut, elle est définie sur « true ».

Lorsqu’elle est définie sur ` false`, l’élément ne reçoit pas les événements de clavier ou de périphérique de pointage, tels que les événements de pression, de relâchement ou de clic, mais peut toujours recevoir les événements de survol.

La configuration de cette propriété affecte directement la valeur de la propriété ` enabled ` des éléments enfants. Lorsqu’elle est définie sur ` false`, les valeurs de la propriété ` enabled ` de tous les éléments enfants deviennent également ` false`. Lorsqu’elle est définie sur ` true`, les valeurs de la propriété ` enabled ` des éléments enfants reviennent à ` true`, sauf si elles ont été explicitement définies sur ` false`.

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

Voir également visible.

focus : bool

Cette propriété s'applique que l'élément ait ou non le focus au sein de l'FocusScope qui l'entoure. Si elle est définie sur « true », cet élément obtiendra le focus actif lorsque l'FocusScope qui l'entoure obtiendra le focus actif.

Dans l’exemple suivant, input recevra le focus actif lorsque scope recevra le focus actif :

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

Dans le cadre de cette propriété, la scène dans son ensemble est considérée comme une zone de focus. Concrètement, cela signifie que le code QML suivant attribuera le focus actif à input au démarrage.

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

Voir également activeFocus et « Focus clavier » dans Qt Quick.

focusPolicy : enumeration [since 6.7]

Cette propriété détermine la manière dont l'élément reçoit 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 à parent.

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

Définit la largeur ou la hauteur souhaité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 son ` implicitHeight`.

Toutefois, si un élément est un enfant d’une mise en page, celle-ci déterminera la taille préférée de l’élément à l’aide de sa taille implicite. Dans ce cas, les valeurs explicites width ou height seront ignorées.

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

La définition de la taille implicite est utile pour définir des composants ayant une taille préférentielle 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

Contient l'effet appliqué à ce calque.

L'effet est généralement un composant « ShaderEffect », bien que n'importe quel composant « Item » puisse être attribué. L'effet doit disposer d'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 en mode « layering » ou non. Le mode « layering » est désactivé par défaut.

Un élément en superposition est rendu sur 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 de couche n’a d’effet lorsque la superposition est désactivée.

Voir également Item Layers.

layer.format : enumeration

Cette propriété définit le format de la texture d'arrière-plan. Il est particulièrement judicieux de modifier cette propriété lorsque l'layer.effect t également spécifiée.

Voir également Item Layers.

layer.live : bool [since 6.5]

Lorsque cette propriété est définie sur « true », 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é a la valeur « true », des mipmaps sont générées pour la texture.

Voir également 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 avec échantillonnage multiple dans le calque.

Par défaut, le multisampling est activé dès lors qu’il est activé pour l’ensemble de la fenêtre, à condition que le moteur de rendu de l’arborescence de scène utilisé et l’API graphique sous-jacente prennent en charge cette fonctionnalité.

En définissant la valeur sur 2, 4, etc., le rendu avec échantillonnage multiple peut être demandé pour une partie de la scène sans activer l'échantillonnage multiple pour l'ensemble de la scène. De cette manière, l'échantillonnage multiple n'est appliqué qu'à une sous-arborescence donnée, ce qui peut entraîner des gains de performances significatifs puisque l'échantillonnage multiple n'est pas appliqué aux autres parties de la scène.

layer.smooth : bool

Indique si la couche est transformée de manière lisse. Lorsque cette option est activée, l'échantillonnage de la texture de la couche s'effectue à l'aide d'une interpolation de type « linear », tandis que l'option « non-smooth » entraîne l'utilisation du mode de filtrage « nearest ».

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 la valeur par défaut), alors 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 mise en miroir. La valeur par défaut est « ShaderEffectSource.MirrorVertically ». Une mise en miroir personnalisée peut s’avérer 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 superposé, 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é contient la taille en pixels demandée pour la texture des calques. Si elle est vide (ce qui est le cas par défaut), c'est la taille de l'élément qui est utilisée.

Voir également Item Layers.

layer.wrapMode : enumeration

Cette propriété définit les modes de répétition associés à la texture. La modification de cette propriété est particulièrement utile lorsque l'option « layer.effect » est activée.

Voir également Item Layers.

mutabilityGroup : int [since 6.12]

Il s'agit d'une propriété avancée pouvant être utilisée pour des optimisations de bas niveau. Elle sert d'indication au moteur de rendu quant à la fréquence de mise à jour d'un élément. Dans les cas d'utilisation courants, il suffit de conserver la valeur par défaut de cette propriété (Item.AutoMutabilityGroup (0)).

Cependant, dans certains cas, une analyse des performances peut révéler des goulots d’étranglement que le comportement par défaut du moteur de rendu Qt Quick n’a pas pu optimiser. Cela se produit généralement lorsque des géométries mises à jour rapidement sont regroupées avec des géométries statiques. Pour éviter cela, vous pouvez par exemple essayer d’attribuer les composants mis à jour rapidement à Item.DynamicMutabilityGroup. Les géométries issues de groupes de mutabilité différents ne seront pas regroupées.

Le groupe de mutabilité s’applique uniquement à l’élément lui-même. Il ne se propage pas aux enfants.

Consultez la section « Qt Quick Scene Graph Default Renderer » pour plus d’informations sur le fonctionnement interne du moteur de rendu du graphe de scène d’ Qt Quick et sur le regroupement des géométries.

Valeurs prédéfinies :

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

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 (entièrement transparent) et 1,0 (entièrement opaque). La valeur par défaut est 1,0.

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

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’a aucune incidence sur sa capacité à recevoir des événements liés aux entrées utilisateur. (En revanche, définir la propriété ` visible ` sur ` false ` bloque les événements de souris, et définir la propriété ` enabled ` sur ` false ` bloque les événements de souris et de clavier, tout en retirant 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 par 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 conservent une cohérence avec l'apparence et le comportement natifs de la plateforme. Il est courant que différentes plateformes, ou différents styles, définissent des palettes différentes pour une même application.

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

• en transmettant une palette personnalisée à ` QGuiApplication::setPalette()` avant de charger tout code 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 éléments parents vers les éléments enfants. Si vous modifiez une propriété spécifique de la palette d’un élément, cette propriété est propagée à tous les éléments enfants de cet élément, remplaçant ainsi 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 également 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 axe d’ transformOrigin.

La valeur par défaut est 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.

Un facteur d'échelle inférieur à 1,0 entraîne l'affichage de l'élément à une taille réduite, tandis qu'un facteur d'échelle supérieur à 1,0 l'affiche à une taille plus grande. Un facteur d'échelle négatif entraîne l'inversion de l'élément lors de son affichage.

La valeur par défaut est 1,0.

La mise à l'échelle est appliquée à partir de l'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 éléments basés sur des images pour déterminer si l'élément doit recourir à un échantillonnage lissé ou non. L'échantillonnage lissé est effectué à l'aide d'une interpolation linéaire, tandis que l'échantillonnage non lissé est effectué à l'aide de la méthode du plus proche voisin.

Dans la version 2.0 d'Qt Quick, cette propriété a un impact minime 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 se trouve dans son état par défaut, c'est-à-dire qu'aucun état explicite n'a été défini, cette propriété contient alors une chaîne vide. De même, vous pouvez rétablir l'état par défaut d'un élément en définissant cette propriété sur une chaîne vide.

Voir également États d’Qt Quick .

states : list<State>

Cette propriété contient la liste des états possibles pour cet élément. Pour modifier l'état de cet élément, définissez la propriété ` state ` sur l'un de ces états, ou définissez la propriété ` state ` sur 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 présentant 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" }
        }
    ]
}

Pour plus d'informations sur l'utilisation des états et des transitions, consultez les sections États d'Qt Quick et Animations et transitions dans Qt Quick.

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 :

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, consultez Transform.

transformOrigin : enumeration

Cette propriété définit le point d'origine autour duquel s'effectuent les transformations d'échelle et de rotation.

Neuf origines de transformation sont disponibles, comme le montre l'image ci-dessous. L'origine de 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 associées à cet élément. Celles-ci définissent les transitions à appliquer à l'élément chaque fois qu'il change d'state.

Cette propriété est spécifiée sous la forme d’une liste d’objets « Transition ». Par exemple :

import QtQuick 2.0

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

Pour plus de détails sur l'utilisation des états et des transitions, consultez les sections « États d'Qt Quick » et « Animation et transitions » dans Qt Quick.

Voir également « states ».

visible : bool

Cette propriété indique si l'élément est visible. Par défaut, sa valeur est « true ».

La définition de cette propriété affecte directement la valeur « visible » des éléments enfants. Lorsqu’elle est définie sur « false », les valeurs « visible » de tous les éléments enfants deviennent également « false ». Lorsqu’elle est définie sur « true », les valeurs « visible » des éléments enfants reviennent à « true », à moins qu’elles n’aient été explicitement définies sur « false ».

(En raison de ce comportement en cascade, l’utilisation de la propriété visible peut ne pas produire l’effet escompté si une liaison de propriété ne doit répondre qu’aux modifications explicites de la propriété. Dans de tels cas, il peut être préférable d’utiliser plutôt la propriété opacity.)

Si cette propriété est définie sur « false », l’élément ne recevra plus d’événements de souris, mais continuera à recevoir des événements de clavier et conservera la propriété « keyboard focus » si celle-ci a été définie. (En revanche, définir la propriété « enabled » sur « false » interrompt à la fois les événements de souris et de clavier, et retire également le focus de l’élément.)

Voir également opacity et enabled.

visibleChildren : list<Item>

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

z : real

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

Les éléments dont la valeur de superposition est supérieure sont affichés par-dessus les éléments frères dont la valeur de superposition est inférieure. Les éléments ayant la même valeur de superposition sont affichés de bas en haut, dans l'ordre où ils apparaissent. Les éléments dont la valeur de superposition est négative sont affichés sous le contenu de leur parent.

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

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
        }
    }
}

Documentation de la méthode

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 aucun élément de ce type.

bool contains(point point)

Renvoie « true » si cet élément contient « point », qui est exprimé en coordonnées locales ; renvoie « false » dans le cas contraire. Il s’agit de la même vérification que celle utilisée pour le test de collision d’un « QEventPoint » lors de la transmission d’événements, et elle est influencée par « containmentMask » si celui-ci est défini.

[since 6.3] void dumpItemTree()

Affiche certaines informations concernant l'arborescence visuelle des éléments, en commençant par cet élément et ses enfants, de manière récursive.

Le résultat est similaire à celui 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, "")

Ainsi, si vous souhaitez obtenir plus de détails, vous pouvez implémenter votre propre fonction et ajouter des informations supplémentaires dans `console.log`, telles que les valeurs de propriétés spécifiques.

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

Voir également ` QObject::dumpObjectTree()`.

void forceActiveFocus()

Place le focus sur l'élément.

Cette méthode place le focus sur l’élément et garantit que tous les objets ancêtres de type « 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)

Permet de placer le focus sur l'élément dont l'reason est spécifiée.

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

Voir également « activeFocus » et « Qt::FocusReason ».

bool grabToImage(callback, targetSize)

Récupère l'élément dans une image en mémoire.

La capture s'effectue de manière asynchrone et la fonction JavaScript ` callback ` est appelée une fois la capture terminée. La fonction de rappel prend un argument, qui correspond au résultat de l'opération de capture : 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 la capture n’a pas pu être lancée, la fonction renvoie ` false`.

L'extrait de code suivant montre comment capturer un élément et enregistrer 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 de code suivant montre comment capturer 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)

Associe le point (x, y), situé dans le système de coordonnées global, au système de coordonnées de l'élément, et renvoie une instance de ` point ` correspondant à la coordonnée associée.

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, le mappage inclut la position relative des deux scènes.

Effectue la mise en correspondance du point (x, y) ou du rectangle (x, y, width, height), situé 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, le mappage inclut la position relative des deux scènes.

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

Les versions acceptant les types « point » et « rect » sont disponibles depuis Qt 5.15.

point mapToGlobal(real x, real y)

Effectue la mise en correspondance du point (x, y), situé dans le système de coordonnées de cet élément, avec le système de coordonnées global, et renvoie un objet de type « 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.

Mappe 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, vers le système de coordonnées de item, et renvoie un point ou un rect correspondant à la coordonnée mappée.

Les propriétés suivantes de l’élément sont utilisées dans le mappage : x, y, scale, rotation, transformOrigin et transform.

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

Si ` item ` est une valeur de type ` null `, cela mappe le point ou le rectangle au système de coordonnées de la scène.

Les versions acceptant les types `point` et `rect` sont disponibles depuis Qt 5.15.

Item nextItemInFocusChain(bool forward)

Renvoie l'élément de la chaîne de mise au point qui se trouve à côté de cet élément. Si forward est true ou n'est pas fourni, il s'agit de l'élément suivant dans le sens avant. Si forward est false, il s'agit de l'élément suivant dans le sens arrière.