Item

The Item element is the basis of all elements that appear on the Zing canvas. Item doesn't paint any content itself, but many of the elements that derive from Item do. The properties on Item define the contents transform, stacking and clipping, which together control where and how painted content appears on the canvas.

property Float x: 0

property Float y: 0

property Float width: 0

property Float height: 0

Define the geometry of the Item.

The x and y values are relative to the transform of the items visual parent.

Item {
    x: 50
    y: 20
    width: 100
    height: 150
}

property Bool clip: false

When set, the visual contents of the item and its children are clipped to the item's shape. By default, the shape of an item is the rectangle defined by its width and height.

Special clipping is applied to Rectangles with rounded corners and Ellipses, where the content is clipped to the curved edges instead.

Item {
    width: 60
    height: 60
    clip: true
}

property Item containerread only

The container property is for situations where the element that holds the current one is not known. Typically the 'parent' keyword is used to refer to the element e.g. width: parent.width. The parents type is known ahead of time e.g. Rectangle and so item specific properties can be accessed e.g. color: parent.color. The root item however does not know what type its parent is ahead of time as it can be used in any element. In this situation the 'container' keyword can be used e.g. width: container.width. Note that the container always has a type of Item so properties that are not of this type cannot be accessed e.g. color: container.color would fail as color is not a property that is part of the Item type.

Note: For type safety and performance reasons it is best to just refer to an items id or as 'parent'. Studio will raise an error when there is no parent and then 'container' can be used instead.

Rectangle as root {
    width: container.width
    height: container.height
    color: #red
    Rectangle {
        width: parent.width / 2
        height: parent.height / 2
        color: #white
    }
}

property Float opacity: 1.0

Sets the opacity for the item, ranging from 0.0 which is completely transparent to 1.0 which is completely opaque. A value of 0.5 corresponds to 50% opacity.

Item {
    width: 50
    height: 50
    opacity: 0.5
}

property Bool visible: true

When false the item and all of its children are no longer drawn.

Item {
    width: 20
    height: 20
    visible: false
}

property Float rotation: 0

property Float scale: 1

property Float scaleX: 1

property Float scaleY: 1

In addition to its x and y translation, items can be rotated and scaled. Scale and rotation are applied around the item's transformOrigin, which is one of 9 predefined grid points, and is the item's center by default.

Rotation is specified in clockwise degrees.

// rotation - item will be rotated 90 degrees about its center
Item {
    rotation: 90
}
// scale - item will be drawn at twice its standard size
Item {
    scale: 2.0
}
// scaleX - item will be drawn mirrored along the x-axis
Item {
    scaleX: -1
}
// scaleY - item will be drawn at twice its height
Item {
    scaleY: 2.0
}

property Item.TransformOrigin transformOrigin: .Center

When items are rotated or scaled they do so about the transform origin. The transform origin can be one of the following 9 options.

Item.TransformOrigin.Center

Item.TransformOrigin.TopLeft

Item.TransformOrigin.Top

Item.TransformOrigin.TopRight

Item.TransformOrigin.Left

Item.TransformOrigin.Right

Item.TransformOrigin.BottomLeft

Item.TransformOrigin.BottomRight

Item.TransformOrigin.Bottom

By selecting the transform origin in the example below you see the effect it has on the transformation.

Item {
    width: 100
    height: 100
    transformOrigin: Item.TransformOrigin.TopLeft 
}

property Int stacking: 0

Items are drawn in the order they are written in a zing file. Each new item will draw on top of the one before it. The stacking property allows this behavior to be overridden. Items with a higher stacking item will be drawn on top of those with a lower one.

Items with the same stacking value will continue to be drawn relative to each other in their definition order, but on top of all items with a lower stacking and below all items with a higher stacking. The ordering functions orderFirst(), orderLast(), orderAfter() and orderBefore() allow the "order" of an item in its container to be changed.

Item as root{
	Rectangle {
		x: 10; y: 10
		width: 100; height: 100
		color: #orange
		stacking: 100
	}
	Rectangle {
		width: 100; height: 100
		color: #blue
	}
}

function takeFocus()

function clearFocus()

function clearFocus(Item.ClearFocusMode mode)

Keyboard focus is an important feature of any application as it controls where keyboard input is directed, and when the keyboard itself is shown.

Item.ClearFocusMode.SingleItem

Item.ClearFocusMode.IncludeChildren

property Bool focusedread only

property Item focusDelegate: null

function mapToItem(Item toItem, Vec2 point) → Vec2

function mapToItem(Item toItem, Float x, Float y) → Vec2

function mapFromItem(Item fromItem, Vec2 point) → Vec2

function mapFromItem(Item fromItem, Float x, Float y) → Vec2

These methods transform a point from one item's coordinate system another.

mapToItem() takes a point in this items coordinate space, and returns the equivalent point in the toItem's coordinates.

mapFromItem() takes a point in fromItem's coordinate space, and returns the equivalent point in this item's coordinates.

function mapToGlobal(Vec2 point) → Vec2

function mapToGlobal(Float x, Float y) → Vec2

function mapFromGlobal(Vec2 point) → Vec2

function mapFromGlobal(Float x, Float y) → Vec2

These methods transform a point to and from the "global" coordinate space. If the item is part of the visual hierarchy, the "global" coordinate space is the screen. If not, it is the outer coordinate space of the item's greatest ancestor.

property Array<Item> childrenread only

The visual children of the Item.

You cannot modify the children array directly. To add or remove children, use the setContainer() method.

function changeContainer(Item targetItem)

function setContainer(Item targetItem)

These methods are used to change the parent of the item, by using another targetItem as the paremeter.

When changeContainer() is used Zing will change the container, but try and preserve the position of the item by automatically adjusting its x and y properties. This is particularly useful for when you want to change container, but don't want the visual item to move.

When setContainer is used the item will change container but keep its original x and y properties. If the new container is in a different position to the old one the visual item will also move relative to its new parent container.

function clearChildren()

Remove all the visual children of this item. This is equivalent to setting the container for each child to null.

function orderFirst()

function orderLast()

function orderBefore(Item targetItem)

function orderAfter(Item targetItem)

These methods alter the order of an item in its container. orderFirst() and orderLast() move the item to the beginning or end in its current container.

orderBefore() and orderAfter() move the item to the same container as targetItem if needed, and then orders it before or after targetItem respectively.

Rectangle {
    width: 200; height: 200
    color: #white
    Rectangle as layer1 {
        x: 50; y:50
        width: 100; height: 100
        color: #green
        with Gesture.Tap {
            on tapped {
                rect.orderBefore(layer1)
            }
        }
    }
    Rectangle as rect {
        width: 100; height: 100
        with Gesture.Tap {
            on tapped {
                rect.orderAfter(layer1)
            }
        }
    }
}