Property system

Properties provide the means to specify and examine the state, appearance, and behavior of nodes. For example, a property can define a color, indicate whether a button is pressed, or specify the alignment of an item.

You can work with properties by setting the property values in Kanzi Studio and accessing them in code without understanding how the property system works. However, to take full advantage of the Kanzi property system features, you have to become familiar with how the property system works.

Properties provide a uniform way to access data of Kanzi nodes, so that many Kanzi subsystems can manipulate the data. That way you can, for example, animate property values, provide bindings between property values, and monitor property value changes.

Any property value can be affected by multiple input sources. The property system defines the rules of how to resolve the property value from all inputs and resolves the current value. For example, you can specify the value of a property directly, some properties can have default values, styles can affect property values, and animations and state manager can modify property values. This allows to minimize the number of places where the values have to be changed manually by offering rules that are applied automatically.

See Creating property types.

Property data type

Each property is described by a property type. The property type uniquely describes the property where it is used, the name and the type of values the property holds. The data type defines the type of the data of the property.

For example, the Node.Visible property type is used in the Node class and derived classes and controls the visibility of nodes. You can use its name (Node.Visible) to find the property type during runtime and since its type is boolean it accepts values true or false.

Note that in Kanzi Studio you can have more specialized property types, but their representation comes only from the data types listed above. For example, enumeration values are represented as integer values even though they limit the range of values to the entries defined in the enumeration.

Property usage

Most Kanzi properties are defined in the classes that use them. Such properties are used to configure appearance, state, or behavior of the object where they are defined. For example, the Text property in the Text Block node defines the text rendered in the node, and the Visible property controls the visibility of a node and all its derived nodes.

However, some Kanzi properties configure the appearance, behavior, or state of other objects. For example, materials can define the Diffuse Color property which you can assign to nodes using that material, Grid Layout defines the Row and Column properties, but they are assigned to the items under the Grid Layout node, and not the Grid Layout node itself. In Kanzi these properties are referred to as attached properties.

Default property value

Each property type defines the default value of that property. When queried, Kanzi returns the default value of the property, if you do not specify a property value either directly or indirectly (through styles, inheritance, and so on). For example, even though the Node.Visible property is not specified for every node to be true, the default value for this property is true. When queried, all nodes are visible by default.

Not specifying the value, but using the default value can save you time when developing the application. Alternatively, not having a property value is a condition for some property types. For example, properties Node.Width and Node.Height let the user control the size of a particular node, for example, but setting Width and Height to 100 pixels, you force the size of the control to be 100 pixels wide and 100 pixels high. By not specifying these values, you let the control itself decide its own size. For example, the Image node can decide its size based on the image that it shows, or a Stack Layout node can determine to be the size of all of its items.

Property precedence

Querying a property value produces one result, but while determining the value the property system evaluates multiple sources that can affect the property value. The property value sources are evaluated in a specific order.

../_images/property-precedence.svg

Kanzi Engine resolves the runtime values based on these precedence rules (the highest first):

  • Animations and state manager. Animations modify and states override the value. See State manager and Animations.

  • Local value. Local values are property values you set directly. In Kanzi Studio all properties in nodes are defined by a local value. You can set the local value using actions, bindings, and Kanzi Engine API. Using the Kanzi Engine API you can set the local property value with the setProperty() function. For example, to set the value of the Visible property to false use

    node.setProperty(Node::VisibleProperty, false)

    Most of the classes offer helper functions to access the properties. For example, you can set the Node.Visible property with the Node::setVisible function. For helper functions, see the reference of the class that defines the property.

    See Using bindings and Triggers.

  • Named style. Kanzi applies a named style to all nodes whose Style property value points to that style. See Using styles.

  • Typed style. Kanzi applies a typed style to all nodes of the type you specify in the style. See Using styles.

  • Inherited value (if property is inheritable). Each property type specifies whether the property is inheritable. Only certain values can be inherited from ancestors. For example, Node.FontFamily is an inheritable property. If you want to use the same font family for all controls that can display text, you can set the value of the Font Family property to a specific font family only once at the top-most level of your node tree and Kanzi applies the same font to all descendant nodes.

  • Default value from the property type metadata. All properties have the default value that Kanzi's systems use if nothing else affects the value. Each class that inherits the property type can override its default value. For example, the default value of the Node.HorizontalAlignment and Node.VerticalAlignment is HorizontalAlignmentCenter and VerticalAlignmentCenter. Node2D overrides the default values of these properties to HorizontalAlignmentLeft and VerticalAlignmentTop. See Default property value.