Item

The Item element is the base 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 common Item properties define the geometry, transform, stacking and clipping which control 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.

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.

property Item containerread only

The Item's container item.

property Float opacity: 1.0

The Item's opacity, ranging from 0.0 (transparent) to 1.0 (opaque). A value of 0.5 corresponds to 50% opacity.

property Bool visible: true

When false, the item and all of its children are hidden.

property Float rotation: 0

property Float scale: 1

property Float scaleX: 1

property Float scaleY: 1

Define the rotation and scale of the Item.

The scale and rotation are applied around the item's transformOrigin, which is one of 9 predefined grid points. By default, the transform origin is the item's center.

Rotation is specified in degrees clockwise.

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 points.

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

Click the origin point below to see the effect it has on the transformation.

The following example sets the tranform origin point to the top left.

Item {
    transformOrigin: .TopLeft 
}

property Int stacking: 0

The item's stacking value.

The stacking value, along with the item's child order, controls the order in which the item is drawn relative to its siblings. An item with a higher stacking value will be "above" its siblings with lower stacking values.

For a complete explanation of stacking in Zing, see Guide: Children.

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 Item.setContainer() method.

To modify the order of the children list, use the item ordering functions: Item.orderFirst(), Item.orderLast(), Item.orderAfter() and Item.orderBefore().

function setContainer(Item targetItem)

function changeContainer(Item targetItem)

Changes the item's container to the specified target.

changeContainer() will also attempt to update the item's Item.x, Item.y, Item.scale and Item.rotation properties to ensure that the item remains in the same global screen position. That is, such that it doesn't appear to visually "move".

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

function orderAfter(Item afterItem)

These methods modify the position of the item in its container's Item.children list. That is, they modify the item's "child order".

orderFirst() and orderLast() move the item to the beginning or end in its current container.

orderBefore() and orderAfter() move the item to immediately before or after the specified item.

The child order, along with the item's Item.stacking value, controls the order in which the item is drawn relative to its siblings. An item with a higher child order will be "above" its siblings with a lower child order.

For a complete explanation of stacking in Zing, see Guide: Children.

property Float safeAreaInsetLeftread only

property Float safeAreaInsetRightread only

property Float safeAreaInsetTopread only

property Float safeAreaInsetBottomread only

The Item's safe area, expressed as insets from its boundary.

Warning

It is easy to misuse these properties. Whenever possible, use anchors for layout and don't rely on the safe area inset values.

Items should only ever use their container's safe area insets to calculate their position, not their own. Using an item's own inset values tends to create a layout loop.

Consider the following, incorrect, code.

// WRONG
Rectangle {
    x: safeAreaInsetLeft
}

This creates an unstable layout. Each frame the x value cycles back and forth between 0 and 22 as the item moves in and out of the unsafe region and its own safeAreaInsetLeft value updates accordingly.

The correct code uses the container's safe area inset instead

Rectangle {
    x: container.safeAreaInsetLeft
}