导入 | import QtQuick 2.1 |
---|---|
实例 | QQuickItem |
继承 | QtObject |
被继承 | AnimatedSprite, BorderImage, Canvas, Column, ColumnLayout, Flickable, Flipable, Flow, FocusScope, Grid, GridLayout, Image, Loader, MouseArea, MultiPointTouchArea, ParticlePainter, PathView, PinchArea, Rectangle, Repeater, Row, RowLayout, ShaderEffect, ShaderEffectSource, Shape, SpriteSequence, StackLayout, Text, TextEdit, and TextInput |
详细描述
item类是Qt Quick中所有可视项目的基类。尽管Item对象没有可视化外观,但它定义了可视化项目中常见的所有属性,如x和y位置、宽度和高度、锚定(anchoring)和键处理支持。
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 Handlers 来处理传入的输入事件(QInputEvent的子类),如鼠标、触摸和按键事件。这是处理事件的首选声明性方法。
处理触摸事件的另一种方法是子类化QQuickItem,在构造函数中调用setAcceptTouchEvents(),并覆盖touchEvent()。接受整个事件以停止对下面的项目的交付,并独占地抓取所有事件的接触点。使用QPointerEvent::setExclusiveGrabber()只抓取某些接触点,并允许事件进一步传递。
同样,QQuickItem子类可以调用setAcceptedMouseButtons()来注册接收鼠标按钮事件,setAcceptHoverEvents()来接收鼠标悬空事件(没有按钮被按下时鼠标移动),并覆盖虚拟函数mousePressEvent()、mouseMoveEvent()和mouseReleaseEvent()。它们还可以接受事件以防止进一步交付,同时获得一个隐式抓取;或者显式地获取QMouseEvent携带的单个QEventPoint。
按键处理可通过 Keys 附加属性用于所有基于项目的可视类型。Keys attached属性提供了按下和释放等基本信号,以及特定键的信号,如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");
}
布局镜像
可以使用 LayoutMirroring 附加属性镜像项布局。这会导致锚点水平颠倒,也会导致布局或定位其子元素(如ListView或Row)的项水平颠倒其布局方向。
项图层
Item通常会直接呈现到它所属的窗口中。然而,通过设置图层。启用后,可以将项目及其整个子树委托到屏幕外表面。只有屏幕外的表面,一个纹理,将被绘制到窗口。
如果希望有一个不同于item的纹理大小,这可以使用layer.textureSize。要将项目的一部分渲染到纹理中,使用layer.sourceRect。也可以指定层。sourceRect,因此它扩展超出项目的边界。在这种情况下,外部将填充透明像素。
item将使用线性插值缩放,如果layer.smooth设置为true,并将使用mipmap进行下采样。layer.mipmap设置为true。填充映射可以改善缩小项目的视觉质量。对于单个图像项的mipmapping,首选Image::mipmap。
图层不透明度和item不透明度
当将不透明度应用于item层次结构时,不透明度将分别应用于每个item。当不透明度应用于子树时,这会导致不希望的视觉结果。考虑以下例子:
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时,一个图层被渲染,然后根项目的不透明度在纹理被绘制时被应用。这意味着在一个大的项目层次结构中从透明到不透明,或者反之,可以在没有常规项目逐项alpha混合的重叠工件的情况下完成。下面是启用图层的相同例子:
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将会把项目变成一个纹理提供程序,使它可以直接使用项目作为纹理,例如与 ShaderEffect 类型结合使用。
可以在运行时使用layer.effect在图层上应用一个效果:
Item {
id: layerRoot
layer.enabled = true
layer.effect: ShaderEffect {
fragmentShader: "effect.frag.qsb"
}
}
内存和性能
当一个物品的图层被启用时,场景图形将在GPU中分配等于宽×高× 4的内存。在内存受限的配置中,应该小心使用大的层。
在QPainter / QWidget领域中,有时将复杂内容缓存到像素图、图像或纹理中是有利的。在Qt Quick中,由于场景图形渲染器已经应用了一些技术,所以在大多数情况下,这种情况不会发生。由于批量处理,过多的绘制调用已经减少,缓存在大多数情况下将混合比原始内容更多的像素。因此,渲染到屏幕外和绘制结果纹理所涉及的混合开销通常比简单地让项目及其子项目正常绘制要昂贵得多。
另外,在渲染过程中,使用图层的项目不能被批处理。这意味着有许多分层物品的场景可能会有性能问题。
分层对于视觉效果来说是方便和有用的,但是在大多数情况下应该在效果持续期间启用,之后禁用。
属性
implicitHeight : real
implicitWidth : real
设置item的隐式高度和宽度。
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
}
}
注意:使用Text或TextEdit的implicitWidth和显式设置宽度会导致性能损失,因为文本必须布局两次。
height : real
width : real
x : real
y : real
(x,y)位置相对于父节点。
children : list < Item>
resources : list< Object>
children属性包含此项的可视子元素列表。resources属性包含希望按名称引用的非可视资源。
在添加子项目或资源时,通常没有必要引用这些属性,因为默认的数据属性会自动将子对象分配给适当的子项目和资源属性。
activeFocus : bool
此只读属性指示项是否具有活动焦点。
如果activeFocus为true,则该项目要么是当前接收键盘输入的项目,要么是当前接收键盘输入的项目的 FocusScope 祖先。
通常,activeFocus是通过对一个项目及其封装的FocusScope对象设置焦点来获得的。在下面的例子中,输入和focusScope对象将具有活动焦点,而根矩形对象则没有。
也可参考 focus属性 和 Keyboard Focus in Qt Quick.
activeFocusOnTab : bool
此属性保存项是否要位于选项卡焦点链中。默认情况下,它被设置为false。
选项卡焦点链遍历元素,首先访问父元素,然后按元素在children属性中出现的顺序访问其子元素。在选项卡焦点链中的项目上按下选项卡键将把键盘焦点移动到链中的下一个项目。按下BackTab键(通常是Shift+Tab键)将焦点移到上一个项目。
要设置手动选项卡焦点链,请参见键导航( KeyNavigation)。键或键导航使用的Tab键事件优先于焦点链行为;忽略其他键处理程序中的事件以允许其传播。
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
锚点提供了一种通过指定项与其他项的关系来定位项的方法。
Margins 适用于顶部、底部、左侧、右侧和填充锚。anchors.margins可用于一次性将所有不同的页边距设置为相同的值。它不会覆盖先前设定的特定外边距,若要清除显式的边距,请将其值设置为undefined。注意边距是特定于锚点的,如果项目不使用锚点,则不应用边距。
文本锚定在图像上,水平居中和垂直下方,带外边距。
Item {
Image {
id: pic
// ...
}
Text {
id: label
anchors.horizontalCenter: pic.horizontalCenter
anchors.top: pic.bottom
anchors.topMargin: 5
// ...
}
}
文本的左边锚定在图像的右边,带外边距。这两个的y属性默认为0。
Item {
Image {
id: pic
// ...
}
Text {
id: label
anchors.left: pic.right
anchors.leftMargin: 5
// ...
}
}
anchors.fill 提供一种方便的方式使一个项目具有与另一个项目相同的几何形状,相当于连接所有四个定向锚。
若要清除锚定值,请将其设置为undefined。 anchors.left: undefined
anchors.alignWhenCentered (默认为true)以锚点为中心对齐到整个像素的力;如果居中的项的宽度或高度为奇数,则该项将被放置在整个像素上,而不是放置在半像素上。这可以确保物品的颜色清晰。在有些情况下,这是不可取的,例如,当旋转项目抖动可能是明显的中心是圆角。
注意:您只能将一个项目锚定到兄弟或父对象。
antialiasing : bool
由视觉元素来决定项目是否应该使用抗锯齿。在某些情况下,带有抗锯齿的道具需要更多内存,渲染速度可能会更慢(更多细节请参阅抗锯齿( Antialiasing))。
默认值为false,但可以被派生元素覆盖。
baselineOffset : int
指定项的基线在本地坐标中的位置。
文本项的基线是文本所在的假想线。包含文本的控件通常将其基线设置为其文本的基线。
对于非文本项,默认基线偏移量为0。
childrenRect.height : real [read-only]
childrenRect.width : real [read-only]
childrenRect.x : real [read-only]
childrenRect.y : real [read-only]
如果您需要访问项目的子项目的集合几何形状以正确设置项目的大小,则此属性非常有用。
返回的几何图形对于项来说是局部的。例如:
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*
data : list< Object> (默认)
data属性允许您在项目中自由地混合可视子元素和资源。如果您将一个可视化项目分配给数据列表,它将成为一个子项目,如果您分配任何其他对象类型,它将作为资源添加。
所以你可以这样写:
Item {
Text {}
Rectangle {}
Timer {}
}
而不是
Item {
children: [
Text {},
Rectangle {}
]
resources: [
Timer {}
]
}
通常不需要引用data属性,因为它是Item的默认属性,因此所有子项都自动分配给这个属性。
enabled : bool
此属性保存项目是否接收鼠标和键盘事件。默认情况下是true。
设置此属性直接影响子项的enabled。当设置为false时,所有子项的enabled也变为false。当设置为true时,子项的enabled将返回true,除非它们已显式设置为false。
将此属性设置为false会自动将activeFocus设置为false,并且该项目将不再接收键盘事件。
focus : bool
此属性保存项目是否在封闭的 FocusScope 内具有焦点。如果为真,当封闭的FocusScope获得活动焦点时,该项目将获得活动焦点。
在下面的例子中,当scope获得活动焦点时,input将被赋予活动焦点:
Rectangle {
width: 100; height: 100
FocusScope {
id: scope
TextInput {
id: input
focus: true
}
}
}
Rectangle {
width: 100; height: 100
TextInput {
id: input
focus: true //设置为false,则输入不了
}
}
layer.effect : Component
保存应用于此图层的效果。
这个效果通常是一个ShaderEffect组件,尽管任何Item组件都可以被分配。这个效果应该有一个名称匹配layer.samplerName的源纹理属性。
layer.enabled : bool
保存项是否分层。分层默认是禁用的。
一个分层的项目被渲染到一个屏幕外的表面,并被缓存,直到它被改变。为复杂的QML项层次结构启用分层有时是一种优化。
当图层被禁用时,其他的图层属性都没有任何效果。
layer.format : enumeration
layer.mipmap : bool
如果此属性为真,则为纹理生成mipmap。
Note: Some OpenGL ES 2 implementations do not support mipmapping of non-power-of-two textures.
layer.samplerName : string
保存效果的源纹理属性的名称。
此值必须与效果的源纹理属性的名称匹配,以便项目可以正确地将层的屏幕外表面传递到效果。
layer.samples : enumeration
这个属性允许在层中请求多采样渲染。
默认情况下,只要整个窗口启用了multisampling, multisampling就会被启用,假设正在使用的场景渲染器和底层的图形API支持这个功能。
注意:无论层的大小如何,启用多重采样都可能代价高昂,因为它需要依赖于硬件和驱动程序的性能和内存成本。
注意:这个属性只有在支持multisample renderbuffer和framebuffer blit时才有用。否则该值将被静默忽略。
这个属性是在Qt 5.10中引入的。
layer.smooth : bool
保持图层是否平滑转换。当启用时,采样层的纹理使用线性插值,而非平滑的结果使用最近的滤波模式。
默认情况下,此属性设置为false。
layer.textureMirroring : enumeration
layer.textureSize : size
此属性保存层纹理请求的像素大小。如果为空(默认为空),则使用项的大小。
注意:有些平台对framebuffer对象的大小有限制,这意味着实际的纹理大小可能大于请求的大小。
layer.wrapMode : enumeration
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会停止鼠标和键盘事件,还会从项目中移除活动焦点。)
palette : Palette
此属性保存当前为该项设置的调色板。
此属性描述项目请求的调色板。在呈现所有控件时,项目的样式将使用调色板,并可作为确保自定义控件能够与本机平台的本机外观和感觉保持一致的一种方法。不同的平台或不同的风格为应用程序定义不同的调色板是很常见的。
默认选项板取决于系统环境。ApplicationWindow 维护了一个系统/主题调色板,作为所有控件的默认选项。对于某些类型的控件,也可能存在特殊的调色板缺省值。你也可以为控件设置默认的调色板:
不全
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
}
}
scale : real
此属性保存该项的比例因子。
小于1.0的比例将使项目以较小的尺寸呈现,大于1.0的比例将以较大的尺寸呈现项目。负比例会导致项目在渲染时被镜像。
默认值为1.0。
从transformOrigin应用缩放。
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
}
}
smooth : bool
主要用于基于图像的项目,以决定项目是否应该使用平滑采样或不。平滑采样采用线性插值法,非平滑采样采用最近邻法。
在Qt Quick 2.0中,这个属性对性能的影响很小。
默认情况下,该属性被设置为true。
state : string
此属性保存项的当前状态的名称。
如果项处于默认状态,即没有设置显式状态,则此属性保存一个空字符串。同样,您可以通过将此属性设置为空字符串,将项目返回到其默认状态。
参考:Qt Quick States.
states : list
此属性保存此项的可能状态列表。若要更改该项的状态,请将state属性设置为这些状态之一,或将state属性设置为空字符串,以便将该项恢复为其默认状态。
此属性指定为State对象列表。例如,下面是一个带有“red_color”和“blue_color”状态的项目:
Rectangle {
id: root
width: 100; height: 100
states: [
State {
name: "red_color"
PropertyChanges { target: root; color: "red" }
},
State {
name: "blue_color"
PropertyChanges { target: root; color: "blue" }
}
]
}
关于使用状态和转换的更多细节:Qt Quick States 和 Animation and Transitions in Qt Quick
transform : list< Transform>
此属性保存要应用的转换列表。Transform。
transformOrigin : enumeration
这个属性保存了缩放和旋转变换的原点。
有九个变换原点,如下图所示。默认的转换原点是Item.Center。
这个例子将图像旋转到右下角。
transitions : list< Transition>
此属性保存此项目的转换列表。它们定义了当项目改变其状态时应用到它的转换。
此属性指定为转换对象列表。例如:
Item {
transitions: [
Transition {
//...
},
Transition {
//...
}
]
}
关于使用状态和转换的更多细节:Qt Quick States 和 Animation and Transitions in Qt Quick
visible : bool
此属性保存该项是否可见。默认情况下是true。
设置此属性直接影响子项的可见值。当设置为false时,所有子项的可见值也变为false。当设置为true时,子项的可见值将返回true,除非它们被显式设置为false。
(由于这种流上行为,如果属性绑定只响应显式的属性更改,则使用visible属性可能没有预期的效果。在这种情况下,使用不透明度属性可能会更好。)
如果此属性设置为false,则该项将不再接收鼠标事件,但将继续接收按键事件,并将保持键盘焦点(如果已设置)。(相反,将enabled属性设置为false将同时停止鼠标和键盘事件,并从项目中移除焦点。)
注意:此属性的值仅受此属性或父属性的visible属性更改的影响。例如,如果该项目移出屏幕,或者不透明度变为0,它不会改变。
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
}
}
}
方法
object mapToItem(Item item, point p)
object mapToItem(Item item, real x, real y)
将调用该方法的对象( C )的坐标点(x,y),映射到参数item( D )的坐标系统中,并返回一个映射之后的坐标(point)。此时,参数x,y是指的C对象上的坐标点。
object mapToItem(Item item, real x, real y, real width, real height)
object mapToItem(Item item, rect r)
将调用该方法的对象( C )的区域(x,y,width,height),映射到参数item( D )的坐标系统中,并返回一个映射之后的区域(rect)。此时,参数x,y,width,height是指来自的C对象的区域。
如果item是空值,则将点或矩形映射到根QML视图的坐标系统。
object mapFromItem(Item item, point p)
object mapFromItem(Item item, real x, real y)
将参数item( A )的坐标系统的坐标点(x,y)映射到调用该方法的对象( B )坐标系统中,并返回一个映射之后的坐标(point)。此时,参数x,y是指的A对象上的坐标点。
object mapFromItem(Item item, real x, real y, real width, real height)
object mapFromItem(Item item, rect r)
将参数item( A )的坐标系统的区域(x,y,width,height)映射到调用该方法的对象( B )的坐标系统中,并返回一个映射之后的区域(rect)。此时,参数x,y,width,height是指来自的A对象的区域。
如果item是空值,则将点或矩形映射到根QML视图的坐标系统。
参考:https://blog.csdn.net/imtina/article/details/53670528
childAt(real x, real y)
返回在该项的坐标系统内point(x, y)找到的第一个可见的子项。如果没有这样的项,则返回null。
bool contains(point point)
如果该项包含在局部坐标中的point,则返回true;否则返回false。
[since 5.1] forceActiveFocus(Qt::FocusReason reason)
这是一个重载函数。
用给定的理由迫使活动的焦点在项目上。
该方法将焦点设置在项目上,并确保对象层次结构中的所有祖先FocusScope对象也获得焦点。
forceActiveFocus()
迫使活动的焦点在项目上。该方法将焦点设置在项目上,并确保对象层次结构中的所有祖先FocusScope对象也获得焦点。焦点变化的原因是Qt::OtherFocusReason。使用重载方法来指定焦点原因,以便更好地处理焦点变更。
bool grabToImage(callback, targetSize)
将项目抓取到内存映像中。抓取是异步发生的,当抓取完成时将调用JavaScript函数回调。回调函数接受一个参数,它是抓取操作的结果;一个ItemGrabResult对象。
使用targetSize指定目标图像的大小。默认情况下,结果将具有与项目相同的大小。如果抓取不能被初始化,函数将返回false。
下面的代码片段展示了如何获取项并将结果存储到文件中。
Rectangle {
id: source
width: 100
height: 100
gradient: Gradient {
GradientStop { position: 0; color: "steelblue" }
GradientStop { position: 1; color: "black" }
}
}
// ...
source.grabToImage(function(result) {
result.saveToFile("something.png");
});
下面的代码片段展示了如何获取一个项并在另一个图像元素中使用结果。
Image {
id: image
}
// ...
source.grabToImage(function(result) {
image.source = result.url;
},
Qt.size(50, 50));
注意:这个函数将渲染项目到一个屏幕外的表面,并将该表面从GPU的内存复制到CPU的内存,这可能是相当昂贵的。对于“实时”预览,使用图层或ShaderEffectSource。
[since 5.7] object mapFromGlobal(real x, real y)
将全局坐标系统中的点(x, y)映射到项目的坐标系统,并返回与映射坐标匹配的点。
[since 5.7] object mapToGlobal(real x, real y)
将该项目坐标系中的点(x, y)映射到全局坐标系,并返回与映射坐标匹配的点。
[since 5.1] nextItemInFocusChain(bool forward)
返回该项旁边的焦点链中的项。如果forward为真,或者没有提供,则它是forward方向的下一项。如果forward为false,则表示向后方向的下一项。