Item QML Type

기본적인 시각적 QML 유형입니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• 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

방법

• 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)

상세 설명

Item 유형은 Qt Quick 의 모든 시각적 항목에 대한 기본 유형입니다.

Qt Quick 의 모든 시각적 항목은 Item을 상속받습니다. Item 객체 자체는 시각적인 형태를 갖지 않지만, x 및 y 위치, 너비와 높이, 고정 위치 지정, 키 처리 지원 등 시각적 항목 전반에 공통적으로 적용되는 모든 속성을 정의합니다.

Item 유형은 여러 항목을 단일 루트 시각적 항목 아래에 그룹화하는 데 유용할 수 있습니다. 예를 들어:

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

이벤트 처리

모든 Item 기반 시각적 유형은 Input Handler를 사용하여 마우스, 터치, 키 이벤트와 같은 입력 이벤트( QInputEvent 의 하위 클래스)를 처리할 수 있습니다. 이는 이벤트를 처리하는 데 권장되는 선언적 방식입니다.

터치 이벤트를 처리하는 또 다른 방법은 ` QQuickItem`을 상속받아 생성자에서 `setAcceptTouchEvents()`를 호출하고 `touchEvent()`를 재정의하는 것입니다. ` Accept `을 호출하면 이벤트 전체를 가로채어 하위 항목으로의 전달을 중지하고, 해당 이벤트의 모든 터치 포인트를 독점적으로 처리할 수 있습니다. ` QPointerEvent::setExclusiveGrabber()`을 사용하면 특정 터치 포인트만 가로채고, 이벤트가 더 아래로 전달되도록 허용할 수 있습니다.

마찬가지로, ` QQuickItem `의 서브클래스는 `setAcceptedMouseButtons()`를 호출하여 마우스 버튼 이벤트를 수신하도록 등록하고, `setAcceptHoverEvents()`를 호출하여 호버 이벤트(버튼이 눌리지 않은 상태에서의 마우스 이동)를 수신하며, 가상 함수인 `mousePressEvent()`, `mouseMoveEvent()` 및 `mouseReleaseEvent()`를 재정의할 수 있습니다. 이들 클래스는 이벤트를 수락하여 추가 전달을 방지하고 동시에 암시적인 그랩을 수행할 수도 있으며, QMouseEvent 가 전달하는 단일 QEventPoint 을 명시적으로 grab 할 수도 있습니다.

키 처리는 Keys 부착 속성을 통해 모든 Item 기반 시각적 유형에서 사용할 수 있습니다. Keys 부착 속성은 pressed 및 released 와 같은 기본 신호뿐만 아니라 spacePressed 와 같은 특정 키에 대한 신호도 제공합니다. 아래 예제는 항목에 키보드 포커스를 할당하고, 일반 onPressed 핸들러를 통해 왼쪽 키를 처리하며, 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");
}

자세한 내용은 Keys 첨부 속성을 참조하십시오.

레이아웃 미러링

LayoutMirroring 부착 속성을 사용하여 항목 레이아웃을 미러링할 수 있습니다. 이렇게 하면 ` anchors `이 수평으로 반전되며, 자식 요소를 레이아웃하거나 위치를 지정하는 항목(예: ` ListView ` 또는 ` Row`)의 레이아웃 방향도 수평으로 반전됩니다.

자세한 내용은 LayoutMirroring 를 참조하십시오.

항목 레이어

항목은 일반적으로 소속된 창에 직접 렌더링됩니다. 그러나 layer.enabled 를 설정하면 해당 항목과 그 전체 하위 트리를 오프스크린 표면으로 위임할 수 있습니다. 그러면 오프스크린 표면, 즉 텍스처만 창에 그려집니다.

아이템의 크기와 다른 텍스처 크기를 원할 경우, ` layer.textureSize`을 사용하여 설정할 수 있습니다. 아이템의 일부만 텍스처에 렌더링하려면 ` layer.sourceRect`을 사용하십시오. 또한 ` layer.sourceRect `을 지정하여 텍스처가 아이템의 경계를 넘어 확장되도록 할 수도 있습니다. 이 경우, 경계 바깥쪽은 투명한 픽셀로 채워집니다.

layer.smooth 가 true 로 설정된 경우, 아이템은 크기 조정에 선형 보간을 사용하며, layer.mipmap 가 true 로 설정된 경우 다운샘플링에 밉맵을 사용합니다. 밉맵핑은 크기가 축소된 아이템의 시각적 품질을 향상시킬 수 있습니다. 단일 이미지 아이템의 밉맵핑에는 Image::mipmap 를 사용하는 것이 좋습니다.

레이어 불투명도와 항목 불투명도의 차이

opacity 를 항목 계층 구조에 적용할 때, 불투명도는 각 항목에 개별적으로 적용됩니다. 이는 불투명도가 하위 트리에 적용될 때 원치 않는 시각적 결과를 초래할 수 있습니다. 다음 예시를 고려해 보십시오:

레이어가 적용되지 않은 불투명도 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 } }

레이어는 루트 항목의 불투명도가 1로 설정된 상태로 렌더링되며, 이후 루트 항목이 그려질 때 그 불투명도가 텍스처에 적용됩니다. 즉, 대규모 항목 계층 구조에서 투명한 상태에서 불투명한 상태로, 또는 그 반대로 페이드 효과를 적용할 때, 일반적인 항목별 알파 블렌딩에서 발생하는 중첩 아티팩트 없이 처리할 수 있습니다. 다음은 레이어가 활성화된 상태에서 동일한 예시입니다:

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

ShaderEffects와 결합

layer.enabled 를 true로 설정하면 해당 아이템이 레이어드 텍스처( texture provider)로 변환되어, 예를 들어 레이어드 텍스처( ShaderEffect ) 유형과 결합하는 등 아이템을 텍스처로 직접 사용할 수 있게 됩니다.

`layer.effect`를 사용하여 런타임에 레이어에 효과를 적용할 수 있습니다:

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

효과 사용에 대한 자세한 내용은 ShaderEffect 를 참조하십시오.

메모리 및 성능

아이템의 레이어가 활성화되면, 씬 그래프는 width x height x 4 과 동일한 크기의 메모리를 GPU에 할당합니다. 메모리가 부족한 환경에서는 큰 레이어를 사용할 때 주의해야 합니다.

QPainter / QWidget 환경에서는 복잡한 콘텐츠를 픽스맵, 이미지 또는 텍스처에 캐시하는 것이 유리한 경우가 있습니다. Qt Quick 에서는 씬 그래프 렌더러가 이미 적용한 기술 덕분에 대부분의 경우 그렇지 않습니다. 배치 처리 덕분에 과도한 드로우 콜은 이미 줄어든 상태이며, 캐시를 사용할 경우 대부분의 경우 원래 콘텐츠보다 더 많은 픽셀을 블렌딩하게 됩니다. 따라서 오프스크린으로 렌더링하는 데 드는 오버헤드와 결과 텍스처를 그리는 데 수반되는 블렌딩 작업은, 해당 아이템과 그 자식들을 단순히 정상적으로 그리는 것보다 종종 더 많은 비용을 초래합니다.

또한, 레이어를 사용하는 아이템은 렌더링 중에 배치 처리될 수 없습니다. 즉, 레이어 처리된 아이템이 많은 장면에서는 성능 문제가 발생할 수 있습니다.

레이어링은 시각 효과에 편리하고 유용할 수 있지만, 대부분의 경우 효과 적용 기간 동안만 활성화하고 그 후에는 비활성화해야 합니다.

속성 설명서

activeFocus : bool [read-only]

이 읽기 전용 속성은 해당 항목이 활성 포커스를 가지고 있는지 여부를 나타냅니다.

activeFocus가 true인 경우, 이 항목이 현재 키보드 입력을 받고 있거나, 현재 키보드 입력을 받고 있는 항목의 FocusScope 상위 요소 중 하나입니다.

일반적으로 activeFocus는 항목과 이를 감싸고 있는 FocusScope 객체에 focus 를 설정하여 획득합니다. 다음 예제에서 input 및 focusScope 객체는 활성 포커스를 가지지만, 루트 사각형 객체는 그렇지 않습니다.

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: focusScope
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

Qt Quick 의‘ focus ’ 및 ‘Keyboard Focus’항목도 참조하십시오 .

activeFocusOnTab : bool

이 속성은 해당 항목이 탭 포커스 체인에 포함되기를 원하는지 여부를 나타냅니다. 기본적으로 이 속성은 ` false`로 설정되어 있습니다.

탭 포커스 체인은 먼저 부모 요소를 방문한 다음, `children` 속성에 나열된 순서대로 자식 요소들을 순회합니다. 탭 포커스 체인에 포함된 항목에서 탭 키를 누르면 키보드 포커스가 체인의 다음 항목으로 이동합니다. BackTab(일반적으로 Shift+Tab)을 누르면 포커스가 이전 항목으로 이동합니다.

수동 탭 포커스 체인을 설정하려면 KeyNavigation 를 참조하십시오. Keys 또는 KeyNavigation 에서 사용하는 탭 키 이벤트는 포커스 체인 동작보다 우선합니다. 포커스 체인이 정상적으로 전파되도록 하려면 다른 키 핸들러의 이벤트는 무시해야 합니다.

QStyleHints::tabFocusBehavior 및 focusPolicy도 참조하십시오 .

anchors group

앵커는 다른 항목과의 관계를 지정하여 항목의 위치를 설정하는 방법을 제공합니다.

여백은 상단, 하단, 좌측, 우측 및 채우기 앵커에 적용됩니다. anchors.margins 속성을 사용하면 다양한 여백을 한 번에 모두 동일한 값으로 설정할 수 있습니다. 이 속성은 이전에 설정된 특정 여백을 재정의하지 않습니다. 명시적으로 설정된 여백을 지우려면 값을 undefined 로 설정하십시오. 여백은 앵커별로 적용되며, 항목이 앵커를 사용하지 않는 경우에는 적용되지 않습니다.

오프셋은 수평 중앙, 수직 중앙 및 기준선 앵커에 적용됩니다.

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 이는 한 항목이 다른 항목과 동일한 기하학적 구조를 갖도록 하는 편리한 방법을 제공하며, 네 방향의 앵커를 모두 연결하는 것과 동일합니다.

앵커 값을 지우려면 undefined 로 설정하십시오.

anchors.alignWhenCentered (기본값 true)는 중앙 정렬 앵커가 전체 픽셀 단위로 정렬되도록 강제합니다. 중앙 정렬되는 항목의 width 또는 height 값이 홀수인 경우, 해당 항목은 반 픽셀 위치에 배치되지 않고 전체 픽셀 위치에 배치됩니다. 이를 통해 항목이 선명하게 렌더링됩니다. 그러나 이 기능이 바람직하지 않은 경우도 있습니다. 예를 들어, 항목을 회전할 때 중심이 둥글게 처리되어 흔들림 현상이 나타날 수 있습니다.

자세한 내용은 ‘앵커 레이아웃’을 참조하십시오.

antialiasing : bool

시각적 요소가 해당 항목에 앤티앨리어싱을 적용할지 여부를 결정하는 데 사용됩니다. 경우에 따라 앤티앨리어싱이 적용된 항목은 더 많은 메모리를 필요로 하며, 렌더링 속도가 느려질 수 있습니다(자세한 내용은 ‘앤티앨리어싱’ 참조).

기본값은 false이지만, 파생된 요소에서 재정의될 수 있습니다.

baselineOffset : int

항목의 기준선 위치를 로컬 좌표계에서 지정합니다.

Text 항목의 기준선은 텍스트가 배치되는 가상의 선입니다. 텍스트를 포함하는 컨트롤은 일반적으로 기준선을 해당 텍스트의 기준선으로 설정합니다.

텍스트가 아닌 항목의 경우, 기본 기준선 오프셋으로 0이 사용됩니다.

children 속성에는 이 항목의 시각적 자식 요소 목록이 포함됩니다. resources 속성에는 이름으로 참조하려는 비시각적 리소스가 포함됩니다.

자식 항목이나 리소스를 추가할 때 일반적으로 이러한 속성을 참조할 필요는 없습니다. 기본 ' data ' 속성이 자식 객체를 적절하게 ' children ' 및 ' resources ' 속성에 자동으로 할당하기 때문입니다. 자세한 내용은 data 문서를 참조하십시오.

childrenRect group

이 읽기 전용 속성은 항목의 자식 요소들의 총합된 위치와 크기를 저장합니다.

이 속성은 항목의 크기를 올바르게 조정하기 위해 항목의 자식 요소들의 집합적 기하 정보를 참조해야 할 때 유용합니다.

반환되는 지오메트리는 해당 항목에 국한됩니다. 예를 들어:

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

이 속성은 클리핑이 활성화되었는지 여부와 관계없이 적용됩니다. 클리핑의 기본값은 ‘ false ’입니다.

클리핑이 활성화된 경우, 항목은 자체 렌더링 결과뿐만 아니라 하위 항목의 렌더링 결과도 경계 사각형으로 잘라냅니다.

containmentMask : QObject*

이 속성은 ` contains()` 메서드에서 사용될 아이템에 대한 선택적 마스크를 저장합니다. 현재 이 속성의 주요 용도는 pointer event 가 해당 아이템에 착지했는지 여부를 판단하는 것입니다.

기본적으로 ` contains() ` 메서드는 아이템의 바운딩 박스 내의 모든 지점에 대해 `true`를 반환합니다. ` containmentMask `를 사용하면 더 세밀한 제어가 가능합니다. 예를 들어, ` contains()` 메서드가 특화된 사용자 정의 C++ ` QQuickItem ` 서브클래스를 `containmentMask`로 사용하는 경우:

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

이때item의 contains 메서드는 다른 item의 contains() 구현이 true 를 반환하는 경우에만 true 를 반환합니다.

Shape 는 마스크로 사용되어, 항목이 직사각형이 아닌 영역 내에서만 pointer events 에 반응하도록 할 수 있습니다:

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

QML에서 contains 메서드를 정의할 수도 있습니다. 예를 들어, 실제 경계 내의 이벤트에만 반응하는 원형 항목을 만들려면:

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

Qt Quick 예제 - 도형도 참조하십시오 .

data : list<QtObject> [default]

‘data’ 속성을 사용하면 항목 내에서 시각적 자식 요소와 리소스를 자유롭게 혼합할 수 있습니다. 데이터 목록에 시각적 항목을 할당하면 해당 항목은 자식 요소가 되고, 다른 유형의 객체를 할당하면 리소스로 추가됩니다.

따라서 다음과 같이 작성할 수 있습니다:

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

다음과 같이 작성할 수 있습니다:

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

data 속성을 직접 참조할 필요는 일반적으로 없습니다. 이는 Item의 기본 속성이므로 모든 자식 항목이 자동으로 이 속성에 할당되기 때문입니다.

enabled : bool

이 속성은 항목이 마우스 및 키보드 이벤트를 수신하는지 여부를 나타냅니다. 기본적으로 이 속성의 값은 ‘ true ’입니다.

false 로 설정된 경우, 해당 항목은 누르기, 놓기, 클릭과 같은 키보드 또는 포인팅 장치 이벤트를 수신하지 않지만, 호버 이벤트는 여전히 수신할 수 있습니다.

이 속성을 설정하면 자식 항목의 enabled 값에 직접적인 영향을 미칩니다. false 로 설정하면 모든 자식 항목의 enabled 값도 false 로 변경됩니다. true 로 설정하면, 자식 항목의 enabled 값이 명시적으로 false 로 설정되지 않은 한 true 로 복원됩니다.

이 속성을 false 로 설정하면 activeFocus 가 자동으로 false 로 설정되며, 이 항목은 더 이상 키보드 이벤트를 수신하지 않게 됩니다.

visible도 참조하십시오 .

focus : bool

이 속성은 해당 항목이 둘러싸고 있는 FocusScope 내에서 포커스를 가지고 있는지 여부와 관계없이 적용됩니다. true인 경우, 둘러싸고 있는 FocusScope 가 활성 포커스를 얻으면 이 항목도 활성 포커스를 얻게 됩니다.

다음 예제에서, scope 가 활성 포커스를 얻으면 input 도 활성 포커스를 받게 됩니다:

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

이 속성의 목적상, 장면 전체가 포커스 범위처럼 작동하는 것으로 간주됩니다. 실질적으로 이는 다음 QML 코드가 시작 시 input 에 활성 포커스를 부여함을 의미합니다.

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

activeFocus 및 Qt Quick 의 키보드 포커스항목도 참조하십시오 .

focusPolicy : enumeration [since 6.7]

이 속성은 항목이 포커스를 받는 방식을 결정합니다.

이 속성은 Qt 6.7에서 도입되었습니다.

항목의 위치와 크기를 정의합니다. 기본값은 0 입니다.

(x, y) 위치는 parent 를 기준으로 합니다.

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

항목의 권장 너비 또는 높이를 정의합니다.

width 또는 height 가 지정되지 않은 경우, 항목의 유효 크기는 implicitWidth 또는 implicitHeight 에 의해 결정됩니다.

그러나 항목이 레이아웃의 자식인 경우, 레이아웃은 암시적 크기를 사용하여 항목의 선호 크기를 결정합니다. 이러한 시나리오에서는 명시적으로 지정된 width 또는 height 값은 무시됩니다.

대부분의 항목에 대한 기본 암시적 크기는 0x0이지만, 일부 항목(예: Image 및 Text)은 재정의할 수 없는 고유한 암시적 크기를 가지고 있습니다.

암시적 크기를 설정하는 것은 콘텐츠에 따라 선호하는 크기가 있는 구성 요소를 정의하는 데 유용합니다. 예를 들면 다음과 같습니다.

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

이 레이어에 적용된 이펙트를 보관합니다.

이 효과는 일반적으로 ‘ ShaderEffect ’ 구성 요소이지만, ‘ Item ’의 모든 구성 요소를 할당할 수 있습니다. 이 효과에는 이름이 layer.samplerName 와 일치하는 소스 텍스처 속성이 있어야 합니다.

layer.samplerName 및 Item Layers항목도 참조하십시오 .

layer.enabled : bool

해당 항목이 레이어링되어 있는지 여부를 나타냅니다. 레이어링은 기본적으로 비활성화되어 있습니다.

레이어링된 항목은 오프스크린 표면에 렌더링되어 변경될 때까지 캐시됩니다. 복잡한 QML 항목 계층 구조에서 레이어링을 활성화하면 성능 최적화에 도움이 될 수 있습니다.

레이어가 비활성화된 상태에서는 다른 레이어 속성들은 아무런 영향을 미치지 않습니다.

Item Layers도 참조하십시오 .

layer.format : enumeration

이 속성은 백킹 텍스처의 형식을 정의합니다. 이 속성을 수정하는 것은 ‘ layer.effect ’도 함께 지정된 경우에 가장 의미가 있습니다.

Item Layers도 참조하십시오 .

layer.live : bool [since 6.5]

이 속성이 true인 경우, 항목이 업데이트될 때마다 레이어 텍스처가 업데이트됩니다. 그렇지 않으면 항상 고정된 이미지로 표시됩니다.

기본적으로 이 속성은 ` true`로 설정되어 있습니다.

이 속성은 Qt 6.5에서 도입되었습니다.

Item Layers도 참조하십시오 .

layer.mipmap : bool

이 속성이 true인 경우, 해당 텍스처에 대해 밉맵이 생성됩니다.

Item Layers도 참조하십시오 .

layer.samplerName : string

이펙트의 소스 텍스처 속성 이름을 저장합니다.

이 값은 아이템이 레이어의 오프스크린 표면을 효과에 올바르게 전달할 수 있도록, 효과의 소스 텍스처 속성 이름과 일치해야 합니다.

layer.effect, ShaderEffect 및 Item Layers도 참조하십시오 .

layer.samples : enumeration

이 속성을 사용하면 레이어에서 멀티샘플링 렌더링을 요청할 수 있습니다.

기본적으로, 사용 중인 씬그래프 렌더러와 기본 그래픽 API가 이를 지원하는 경우, 전체 창에 대해 멀티샘플링이 활성화되어 있으면 이 레이어에서도 멀티샘플링이 활성화됩니다.

값을 2, 4 등으로 설정하면 전체 씬에 대해 멀티샘플링을 활성화하지 않고도 씬의 일부에 대해 멀티샘플링 렌더링을 요청할 수 있습니다. 이렇게 하면 멀티샘플링이 지정된 하위 트리에만 적용되므로, 씬의 다른 부분에는 멀티샘플링이 적용되지 않아 성능이 크게 향상될 수 있습니다.

layer.smooth : bool

레이어가 부드럽게 변환되는지 여부를 지정합니다. 이 옵션이 활성화되면 레이어의 텍스처 샘플링이 ‘ linear ’ 보간법을 사용하여 수행되며, 비부드럽게 설정하면 ‘ nearest ’ 필터링 모드가 사용됩니다.

기본적으로 이 속성은 false 로 설정되어 있습니다.

Item Layers도 참조하십시오 .

layer.sourceRect : rect

이 속성은 텍스처에 렌더링되어야 하는 아이템의 직사각형 영역을 정의합니다. 소스 직사각형은 아이템 자체보다 클 수 있습니다. 직사각형이 null인 경우(기본값), 아이템 전체가 텍스처에 렌더링됩니다.

Item Layers도 참조하십시오 .

layer.textureMirroring : enumeration

이 속성은 생성된 텍스처가 어떻게 미러링되어야 하는지를 정의합니다. 기본값은 ‘ ShaderEffectSource.MirrorVertically ’입니다. ‘ ShaderEffect ’에서 지정된 것과 같은 사용자 정의 셰이더가 생성된 텍스처에 직접 접근하는 경우, 사용자 정의 미러링이 유용할 수 있습니다. 레이어드 항목에 대한 효과가 지정되지 않은 경우, 미러링은 해당 항목의 UI 표현에 아무런 영향을 미치지 않습니다.

layer.textureSize : size

이 속성은 레이어 텍스처의 요청된 픽셀 크기를 저장합니다. 이 속성이 비어 있는 경우(기본값), 항목의 크기가 사용됩니다.

Item Layers도 참조하십시오 .

layer.wrapMode : enumeration

이 속성은 텍스처와 관련된 래핑 모드를 정의합니다. 이 속성을 수정하는 것은 ‘ layer.effect ’가 지정된 경우에 가장 의미가 있습니다.

Item Layers도 참조하십시오 .

mutabilityGroup : int [since 6.12]

이 속성은 저수준 최적화에 사용할 수 있는 고급 속성입니다. 이 속성은 항목이 얼마나 자주 업데이트될지에 대한 정보를 렌더러에 제공하는 역할을 합니다. 일반적인 사용 사례에서는 이 속성을 기본값(Item.AutoMutabilityGroup (0))으로 두는 것만으로도 충분합니다.

그러나 특정 경우, 성능 분석을 통해 Qt Quick 시네그래프 렌더러의 기본 동작으로는 최적화할 수 없었던 병목 현상이 발견될 수 있습니다. 일반적으로 이는 빠르게 업데이트되는 지오메트리가 정적 지오메트리와 함께 배치 처리될 때 발생할 수 있습니다. 이를 방지하기 위해, 예를 들어 빠르게 업데이트되는 컴포넌트를 Item.DynamicMutabilityGroup에 할당해 볼 수 있습니다. 서로 다른 가변성 그룹에 속한 지오메트리는 함께 배치 처리되지 않습니다.

변경 가능성 그룹은 항목 자체에만 적용되며, 자식 요소로 전파되지 않습니다.

Qt Quick 장면 그래프 렌더러의 내부 작동 방식 및 지오메트리 배치에 대한 자세한 내용은 Qt Quick Scene Graph Default Renderer를 참조하십시오.

사전 정의된 값:

이 속성은 Qt 6.12에서 도입되었습니다.

opacity : real

이 속성은 항목의 불투명도를 나타냅니다. 불투명도는 0.0(완전히 투명)에서 1.0(완전히 불투명) 사이의 숫자로 지정됩니다. 기본값은 1.0입니다.

이 속성이 설정되면, 지정된 불투명도가 자식 항목에도 개별적으로 적용됩니다. 이로 인해 일부 상황에서는 의도하지 않은 결과가 발생할 수 있습니다. 예를 들어, 아래의 두 번째 사각형 그룹에서 빨간색 사각형의 불투명도가 0.5로 지정되어 있는데, 자식인 파란색 사각형에는 불투명도가 명시적으로 지정되지 않았음에도 불구하고 이 속성의 영향이 미칩니다.

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

항목의 불투명도를 변경해도 해당 항목이 사용자 입력 이벤트를 수신하는 데는 영향을 미치지 않습니다. (반면, visible 속성을 false 로 설정하면 마우스 이벤트가 중지되고, enabled 속성을 false 로 설정하면 마우스 및 키보드 이벤트가 중지되며, 해당 항목의 활성 포커스도 제거됩니다.)

visible도 참조하십시오 .

palette : Palette [since 6.0]

이 속성은 해당 항목에 현재 설정된 팔레트를 저장합니다.

이 속성은 항목에 요청된 팔레트를 나타냅니다. 이 팔레트는 모든 컨트롤을 렌더링할 때 항목의 스타일에 사용되며, 사용자 정의 컨트롤이 네이티브 플랫폼의 기본 모양과 느낌과 일관성을 유지할 수 있도록 하는 수단으로 활용됩니다. 서로 다른 플랫폼이나 서로 다른 스타일에서 애플리케이션에 대해 서로 다른 팔레트를 정의하는 것이 일반적입니다.

기본 팔레트는 시스템 환경에 따라 달라집니다. ` ApplicationWindow `는 모든 컨트롤의 기본값으로 사용되는 시스템/테마 팔레트를 유지합니다. 특정 유형의 컨트롤에 대해 특별한 기본 팔레트가 지정될 수도 있습니다. 또한 다음 방법 중 하나를 통해 컨트롤의 기본 팔레트를 설정할 수 있습니다.

• QML을 로드하기 전에 ` QGuiApplication::setPalette()`에 사용자 정의 팔레트를 전달하거나; 또는
• qtquickcontrols2.conf 파일에서 색상을 지정하는 방법.

항목은 부모에서 자식으로 명시적인 팔레트 속성을 전파합니다. 항목의 팔레트에서 특정 속성을 변경하면, 해당 속성이 항목의 모든 자식으로 전파되어 해당 속성에 대한 시스템 기본값을 재정의합니다.

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

    Button {
        text: "Click Me"
    }
}

이 속성은 Qt 6.0에서 도입되었습니다.

Window::palette, Popup::palette, ColorGroup, Palette 및 SystemPalette도 참조하십시오 .

parent : Item

이 속성은 항목의 시각적 상위 항목을 나타냅니다.

rotation : real

이 속성은 항목의 중심점( transformOrigin)을 기준으로 시계 방향으로 회전된 각도(도)를 나타냅니다.

기본값은 0도(즉, 회전 없음)입니다.

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

Transform 및 Rotation도 참조하십시오 .

scale : real

이 속성은 해당 항목의 배율 계수를 저장합니다.

스케일이 1.0보다 작으면 항목이 더 작은 크기로 렌더링되고, 1.0보다 크면 더 큰 크기로 렌더링됩니다. 음수 스케일을 지정하면 항목이 렌더링될 때 대칭으로 반전됩니다.

기본값은 1.0입니다.

크기 조정은 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
    }
}

Transform 및 Scale항목도 참조하십시오 .

smooth : bool

주로 이미지 기반 항목에서 해당 항목에 스무스 샘플링을 적용할지 여부를 결정하는 데 사용됩니다. 스무스 샘플링은 선형 보간법을 사용하여 수행되는 반면, 비스무스 샘플링은 최인접 이웃법을 사용하여 수행됩니다.

Qt Quick 2.0에서는 이 속성이 성능에 미치는 영향이 미미합니다.

기본적으로 이 속성은 ` true`로 설정되어 있습니다.

state : string

이 속성은 항목의 현재 상태 이름을 저장합니다.

항목이 기본 상태, 즉 명시적인 상태가 설정되지 않은 상태인 경우, 이 속성은 빈 문자열을 저장합니다. 마찬가지로, 이 속성을 빈 문자열로 설정하여 항목을 기본 상태로 되돌릴 수 있습니다.

Qt Quick 의 ‘States’항목도 참조하십시오 .

states : list<State>

이 속성은 해당 항목의 가능한 상태 목록을 포함합니다. 이 항목의 상태를 변경하려면 ` state ` 속성을 해당 상태 중 하나로 설정하거나, 항목을 기본 상태로 되돌리려면 ` state ` 속성을 빈 문자열로 설정하십시오.

이 속성은 ` State ` 객체 목록으로 지정됩니다. 예를 들어, 다음은 "red_color" 및 "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" }
        }
    ]
}

상태 및 전환 사용에 대한 자세한 내용은 Qt Quick 의 '상태'와 Qt Quick 의 '애니메이션 및 전환'을 참조하십시오.

transitions도 참조하십시오 .

transform : list<Transform> [read-only]

이 속성은 적용할 변환 목록을 포함합니다.

이 속성은 ` Transform`에서 파생된 객체들의 목록으로 지정됩니다. 예:

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

자세한 내용은 Transform 을 참조하십시오.

transformOrigin : enumeration

이 속성은 크기 조정 및 회전 변환의 기준점이 되는 원점을 지정합니다.

아래 이미지와 같이 총 9개의 변환 원점이 제공됩니다. 기본 변환 원점은 Item.Center 입니다.

이 예제에서는 이미지의 오른쪽 하단 모서리를 중심으로 이미지를 회전합니다.

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

임의의 변환 원점을 설정하려면 ` Scale ` 또는 ` Rotation ` 변환 유형을 ` transform`와 함께 사용하십시오.

transitions : list<Transition>

이 속성은 해당 항목에 대한 전환 목록을 포함합니다. 이 목록은 항목의 ‘ state ’가 변경될 때마다 해당 항목에 적용될 전환을 정의합니다.

이 속성은 ` Transition ` 객체의 목록으로 지정됩니다. 예를 들면 다음과 같습니다.

import QtQuick 2.0

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

상태 및 전환 사용에 대한 자세한 내용은 Qt Quick 의 ‘Qt Quick States and Animation and Transitions’를 참조하십시오.

states항목도 참조하십시오 .

visible : bool

이 속성은 항목이 표시되는지 여부를 나타냅니다. 기본값은 true입니다.

이 속성을 설정하면 자식 항목의 ` visible ` 값에 직접적인 영향을 미칩니다. ` false`으로 설정하면 모든 자식 항목의 ` visible ` 값도 ` false`이 됩니다. ` true`으로 설정하면, 자식 항목의 ` visible ` 값은 명시적으로 ` false`로 설정되지 않은 한 ` true`으로 복원됩니다.

(이러한 연쇄 동작으로 인해, 속성 바인딩이 명시적인 속성 변경에만 반응해야 하는 경우 visible 속성을 사용하면 의도한 효과를 얻지 못할 수 있습니다. 이러한 경우에는 대신 opacity 속성을 사용하는 것이 더 나을 수 있습니다.)

이 속성이 false 로 설정되면, 해당 항목은 더 이상 마우스 이벤트를 수신하지 않지만 키 이벤트를 계속 수신하며, 설정된 경우 키보드 focus 도 유지됩니다. (반면, enabled 속성을 false 로 설정하면 마우스 및 키보드 이벤트가 모두 중지되고, 항목의 포커스도 제거됩니다.)

opacity 및 enabled항목도 참조하십시오 .

visibleChildren : list<Item>

이 읽기 전용 속성은 현재 표시 중인 항목의 모든 자식 항목을 나열합니다. 자식 항목의 표시 여부는 명시적으로 변경되었을 수도 있고, 이 항목(부모 항목)이나 다른 조부모 항목의 표시 여부가 변경되어 변경되었을 수도 있습니다.

z : real

동급 항목의 중첩 순서를 설정합니다. 기본적으로 중첩 순서는 0입니다.

스태킹 값이 더 큰 항목은 스태킹 순서가 더 낮은 형제 항목 위에 그려집니다. 스태킹 값이 같은 항목은 나타나는 순서대로 아래에서 위로 그려집니다. 스태킹 값이 음수인 항목은 부모 요소의 콘텐츠 아래에 그려집니다.

다음 예제는 중첩 순서에 따른 다양한 효과를 보여줍니다.

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

메서드 문서

Item childAt(real x, real y)

이 항목의 좌표계 내에서 (x, y) 지점에서 발견된 첫 번째 표시된 자식 항목을 반환합니다.

해당 항목이 없는 경우 null 을 반환합니다.

bool contains(point point)

이 항목에 로컬 좌표계의 ` point`가 포함되어 있으면 ` true `를 반환하고, 그렇지 않으면 ` false `를 반환합니다. 이는 이벤트 전달 시 ` QEventPoint `에 대한 히트 테스트에 사용되는 것과 동일한 확인 과정이며, ` containmentMask `가 설정되어 있는 경우 그 영향을 받습니다.

[since 6.3] void dumpItemTree()

이 항목과 그 자식 항목부터 시작하는 항목들의 시각적 트리에 대한 세부 정보를 재귀적으로 출력합니다.

출력 결과는 다음 QML 코드의 결과와 유사합니다:

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

dump(myItem, "")

따라서 더 자세한 정보를 원한다면, 사용자 정의 함수를 구현하여 특정 속성의 값과 같은 추가 정보를 console.log에 출력할 수 있습니다.

이 메서드는 Qt 6.3에서 도입되었습니다.

QObject::dumpObjectTree()도 참조하십시오 .

void forceActiveFocus()

해당 항목에 활성 포커스를 설정합니다.

이 메서드는 해당 항목에 포커스를 설정하고, 객체 계층 구조 내의 모든 상위 FocusScope 객체에도 focus 가 적용되도록 보장합니다.

포커스 변경 사유는 ` Qt::OtherFocusReason`가 됩니다. 포커스 변경을 더 효과적으로 처리하려면 오버로드된 메서드를 사용하여 포커스 변경 사유를 지정하십시오.

activeFocus도 참조하십시오 .

void forceActiveFocus(Qt::FocusReason reason)

지정된 reason 를 가진 항목에 포커스를 강제적으로 설정합니다.

이 메서드는 해당 항목에 포커스를 설정하고, 객체 계층 구조 내의 모든 상위 FocusScope 객체에도 focus 가 적용되도록 보장합니다.

activeFocus 및 Qt::FocusReason도 참조하십시오 .

bool grabToImage(callback, targetSize)

항목을 메모리 내 이미지로 가져옵니다.

가져오기 작업은 비동기적으로 수행되며, 작업이 완료되면 JavaScript 함수 ` callback `가 호출됩니다. 이 콜백 함수는 가져오기 작업의 결과인 ` ItemGrabResult ` 객체를 유일한 인수로 받습니다.

targetSize 를 사용하여 대상 이미지의 크기를 지정하십시오. 기본적으로 결과 이미지의 크기는 항목의 크기와 동일합니다.

캡처 작업을 시작할 수 없는 경우, 이 함수는 ` false`를 반환합니다.

다음 코드 조각은 항목을 캡처하고 그 결과를 파일에 저장하는 방법을 보여줍니다:

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

다음 코드 조각은 항목을 캡처하여 다른 이미지 요소에서 결과를 사용하는 방법을 보여줍니다:

Image {
    id: image
}

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

point mapFromGlobal(real x, real y)

글로벌 좌표계에 있는 점(x, y)을 항목의 좌표계로 매핑하고, 매핑된 좌표와 일치하는 point 를 반환합니다.

매핑에는 항목의 다음 속성이 사용됩니다: x, y, scale, rotation, transformOrigin 및 transform.

항목들이 서로 다른 장면에 속해 있는 경우, 매핑 정보에는 두 장면 간의 상대적 위치가 포함됩니다.

item 의 좌표계에 있는 점(x, y) 또는 사각형(x, y, width, height)을 이 항목의 좌표계로 매핑하고, 매핑된 좌표에 해당하는 point 또는 rect 를 반환합니다.

매핑에는 항목의 다음 속성이 사용됩니다: x, y, scale, rotation, transformOrigin 및 transform.

항목들이 서로 다른 씬에 속해 있는 경우, 매핑에는 두 씬 간의 상대적 위치가 포함됩니다.

item 가 null 값인 경우, 이는 해당 장면의 좌표계에서 점 또는 사각형을 매핑합니다.

point 및 rect를 지원하는 버전은 Qt 5.15부터입니다.

point mapToGlobal(real x, real y)

이 항목의 좌표계에 있는 점(x, y)을 전역 좌표계로 매핑하고, 매핑된 좌표와 일치하는 point 를 반환합니다.

매핑에는 항목의 다음 속성이 사용됩니다: x, y, scale, rotation, transformOrigin 및 transform.

항목들이 서로 다른 장면에 속해 있는 경우, 매핑 정보에는 두 장면 간의 상대적 위치가 포함됩니다.

이 항목의 좌표계에 있는 점(x, y) 또는 직사각형(x, y, width, height)을 item 의 좌표계로 매핑하고, 매핑된 좌표와 일치하는 point 또는 rect 를 반환합니다.

매핑에는 항목의 다음 속성이 사용됩니다: x, y, scale, rotation, transformOrigin 및 transform.

항목들이 서로 다른 씬에 속해 있는 경우, 매핑에는 두 씬 간의 상대적 위치가 포함됩니다.

item 가 null 값인 경우, 점이나 사각형을 해당 씬의 좌표계로 매핑합니다.

point 및 rect를 지원하는 버전은 Qt 5.15부터입니다.

Item nextItemInFocusChain(bool forward)

포커스 체인에서 이 항목 바로 옆에 있는 항목을 반환합니다. ` forward `가 ` true`이거나 지정되지 않은 경우, 앞으로 방향의 다음 항목이 반환됩니다. ` forward `가 ` false`인 경우, 뒤로 방향의 다음 항목이 반환됩니다.