Reference for showing Kanzi Engine plugin custom types in Kanzi Studio

Attribute	Description	Use for property types	Use for message types
displayName	Name of the property or message the way it is shown in Kanzi Studio	x	x
tooltip	Tooltip for the property or message	x	x
category	Property category name the way it is shown in Kanzi Studio	x	x
valueProvider	Source of the possible values for the property that Kanzi Studio lets the user select from	x
host	Node types for which Kanzi Studio suggests the property, and whether Kanzi Studio adds the property automatically or lets the user add it	x
editor	Type of Kanzi Studio editor used to set the value for the property	x
defaultValue	Default value for the property	x
lowerBound	Lowest value the property can have	x
upperBound	Highest value the property can have	x
step	Amount by which the property value changes when a Kanzi Studio user edits it	x
sendable	Whether Kanzi Studio shows the message as an action	x
listenable	Whether Kanzi Studio shows the message as a trigger	x
sortingIndex	Position of the property within its property category in Kanzi Studio	x
studioVisibility	Whether the property or message is available in Kanzi Studio	x	x
legacyName	Name of the property or message in the earlier versions of the plugin	x	x

displayName¶

Sets the name of the property or message the way it is shown in Kanzi Studio.

Syntax

metadata.displayName = "name";

Values

name

Name of the property or message the way you want to see it in Kanzi Studio

Examples

C++

metadata.displayName = "Video Filename";

Java

@EditorInfo(displayName = "Video Filename")

Kotlin

@EditorInfo(displayName = "Video Filename")

../../_images/video-filename-property.png

tooltip¶

Sets the tooltip for the property or message. Kanzi Studio appends to the tooltip text the Kanzi Engine name of the property or message in case the user needs it in application code.

Syntax

metadata.tooltip = "text";

Values

text

Tooltip text

Examples

C++

metadata.displayName = "Video Filename";
metadata.tooltip = "Name of the video file to be played.";

Java

@EditorInfo(
             displayName = "Video Filename",
             tooltip = "Name of the video file to be played."
           )

Kotlin

@EditorInfo(
             displayName = "Video Filename",
             tooltip = "Name of the video file to be played."
           )

category¶

Sets the category name of the property the way it is shown in the Kanzi Studio Properties. Kanzi Studio always lists the General and Description property categories first, followed by other property categories in alphabetical order.

Syntax

metadata.category = "text";

Values

text

valueProvider¶

Sets how Kanzi Studio gets the possible values for the property to let the user select from.

Syntax

metadata.valueProvider = "key:value";

Values

key

ProjectObject provides nodes or resources of specific type set by value.

For example, to show a dropdown with Materials in a project,

use ProjectObject:Material and set editor to MaterialComboBox.
PropertyType lists all available property types in a dropdown.

Do not set value. Do not set the editor type.

Kanzi Studio sets the correct editor automatically.

Use PropertyType with string property types.
StringList provides a list to which the user can add items.

Do not set value. Do not set the editor type.

Kanzi Studio sets the correct editor automatically.

Use StringList with string property types.
Enum provides a dropdown of options set by value.

This is a list of items (string) and values (int) to which Kanzi maps the items.

Use Enum with int and enum property types.

Separate:
- Items and values with pipes
- List of item-value pairs with semicolons
Enum:string1|int1;string2|int2;...;stringN|intN

Examples

C++

// When you set valueProvider to ProjectObject:Node3D,
// Kanzi Studio automatically uses the Node 3D selector editor.
metadata.valueProvider = "ProjectObject:Node3D";

Java

// When you set valueProvider to ProjectObject:Node3D,
// Kanzi Studio automatically uses the Node 3D selector editor.
@EditorInfo(valueProvider = "ProjectObject:Node3D")

Kotlin

// When you set valueProvider to ProjectObject:Node3D,
// Kanzi Studio automatically uses the Node 3D selector editor.
@EditorInfo(valueProvider = "ProjectObject:Node3D")

../../_images/custom-component-node-reference-by-string.png

C++

// Provides a dropdown with all available property types.
// Do not set the editor type. Kanzi Studio automatically sets the correct editor.
metadata.valueProvider = "PropertyType";

Java

// Provides a dropdown with all available property types.
// Do not set the editor type. Kanzi Studio automatically sets the correct editor.
@EditorInfo(valueProvider = "PropertyType")

Kotlin

// Provides a dropdown with all available property types.
// Do not set the editor type. Kanzi Studio automatically sets the correct editor.
@EditorInfo(valueProvider = "PropertyType")

../../_images/valueprovider-propertytype.png

C++

// Provides a list to which the user can add items.
// Do not set the editor type. Kanzi Studio automatically sets the correct editor.
metadata.valueProvider = "StringList";

Java

// Provides a list to which the user can add items.
// Do not set the editor type. Kanzi Studio automatically sets the correct editor.
@EditorInfo(valueProvider = "StringList")

Kotlin

// Provides a list to which the user can add items.
// Do not set the editor type. Kanzi Studio automatically sets the correct editor.
@EditorInfo(valueProvider = "StringList")

../../_images/valueprovider-stringlist.png

C++

// Provides a list of directions along different dimensions which Kanzi maps to
// integers from 0 to 5.
metadata.valueProvider =
    "Enum : Left to Right|0;Right to Left|1;Top to Bottom|2;Bottom to Top|3;Near to Far|4;Far to Near|5";

Java

// Provides a list of directions along different dimensions which Kanzi maps to
// integers from 0 to 5.
@EditorInfo(valueProvider =
    "Enum : Left to Right|0;Right to Left|1;Top to Bottom|2;Bottom to Top|3;Near to Far|4;Far to Near|5")

Kotlin

// Provides a list of directions along different dimensions which Kanzi maps to
// integers from 0 to 5.
@EditorInfo(valueProvider =
    "Enum : Left to Right|0;Right to Left|1;Top to Bottom|2;Bottom to Top|3;Near to Far|4;Far to Near|5")

C++

// Creates a string reference to a prefab resource.
PropertyType<string> MyPlugin::PrefabRefByStringProperty(
    kzMakeFixedString("MyPlugin.PrefabRefByString"), "", 0, false,
    KZ_DECLARE_EDITOR_METADATA(
        metadata.displayName = "Prefab Reference by String";
        // When you set valueProvider to ProjectObject:PrefabTemplate,
        // Kanzi Studio automatically uses the Prefab template selector editor.
        metadata.valueProvider = "ProjectObject:PrefabTemplate";
    ));

Java

// Creates a string reference to a prefab resource.
@Metadata
@EditorInfo(
             displayName = "Prefab Reference by String",
             // When you set valueProvider to ProjectObject:PrefabTemplate,
             // Kanzi Studio automatically uses the Prefab template selector editor.
             valueProvider = "ProjectObject:PrefabTemplate"
           )
public static PropertyType<String> PrefabRefByStringProperty =
    new PropertyType("MyPlugin.PrefabRefByString", String.class);

Kotlin

companion object {
    // Creates a string reference to a prefab resource.
    @Metadata
    @EditorInfo(
                 displayName = "Prefab Reference by String",
                 // When you set valueProvider to ProjectObject:PrefabTemplate,
                 // Kanzi Studio automatically uses the Prefab template selector editor.
                 valueProvider = "ProjectObject:PrefabTemplate"
               )
    val PrefabRefByStringProperty =
        PropertyType("MyPlugin.PrefabRefByString", String::class.java);
}

../../_images/custom-component-prefab-reference-by-string.png

C++

// Creates a shared pointer reference to a prefab resource.
PropertyType<ResourceSharedPtr> MyPlugin::PrefabRefBySharedPtrProperty(
    kzMakeFixedString("MyPlugin.PrefabRefBySharedPtr"), ResourceSharedPtr(), 0, false,
    KZ_DECLARE_EDITOR_METADATA(
        metadata.displayName = "Prefab Reference by Shared Pointer";
        // When you set valueProvider to ProjectObject:PrefabTemplate,
        // Kanzi Studio automatically uses the Prefab template selector editor.
        metadata.valueProvider = "ProjectObject:PrefabTemplate";
    ));

Java

// Creates a resource reference to a prefab resource.
@Metadata
@EditorInfo(
             displayName = "Prefab Reference by Reference",
             // When you set valueProvider to ProjectObject:PrefabTemplate,
             // Kanzi Studio automatically uses the Prefab template selector editor.
             valueProvider = "ProjectObject:PrefabTemplate"
           )
public static PropertyType<Resource> PrefabRefByResourceProperty =
    new PropertyType("MyPlugin.PrefabRefBySharedPtr", Resource.class);

Kotlin

companion object {
    // Creates a resource reference to a prefab resource.
    @Metadata
    @EditorInfo(
                 displayName = "Prefab Reference by Reference",
                 // When you set valueProvider to ProjectObject:PrefabTemplate,
                 // Kanzi Studio automatically uses the Prefab template selector editor.
                 valueProvider = "ProjectObject:PrefabTemplate"
               )
    val PrefabRefByResourceProperty =
        PropertyType("MyPlugin.PrefabRefBySharedPtr", Resource::class.java);
}

../../_images/custom-component-prefab-reference-by-shared-pointer.png

C++

// Creates a shared pointer reference to a material resource.
PropertyType<ResourceSharedPtr> MyPlugin::MaterialRefBySharedPtrProperty(
    kzMakeFixedString("MyPlugin.MaterialRefBySharedPtr"), ResourceSharedPtr(), 0, false,
    KZ_DECLARE_EDITOR_METADATA(
        metadata.displayName = "Material Reference by Shared Pointer";
        // When you set valueProvider to ProjectObject:Material,
        // Kanzi Studio automatically uses the Material dropdown editor.
        metadata.valueProvider = "ProjectObject:Material";
    ));

Java

// Creates a resource reference to a material resource.
@Metadata
@EditorInfo(
             displayName = "Material Reference by Reference",
             // When you set valueProvider to ProjectObject:Material,
             // Kanzi Studio automatically uses the Material dropdown editor.
             valueProvider = "ProjectObject:Material"
           )
public static PropertyType<Resource> MaterialRefByResourceProperty =
    new PropertyType("MyPlugin.MaterialRefBySharedPtr", Resource.class);

Kotlin

companion object {
    // Creates a resource reference to a material resource.
    @Metadata
    @EditorInfo(
                 displayName = "Material Reference by Reference",
                 // When you set valueProvider to ProjectObject:Material,
                 // Kanzi Studio automatically uses the Material dropdown editor.
                 valueProvider = "ProjectObject:Material"
                )
    val MaterialRefByResourceProperty =
        PropertyType("MyPlugin.MaterialRefBySharedPtr", Resource::class.java)
}

../../_images/custom-component-material-reference-by-shared-pointer.png

host¶

Sets the node types for which Kanzi Studio suggests the property, and whether Kanzi Studio adds the property automatically or lets the user add it.

If you do not set the host attribute, Kanzi Studio adds the property as a frequently used property to the nodes of the type for which you created the property type and lets the user add the property to any other types of nodes.

Syntax

metadata.host = "nodeType:addition";

Values

nodeType

Type of the node for which you want Kanzi Studio to make the property available.

addition

How Kanzi Studio adds the property or lets the user add it:

user lets the user add the property using the context menu or the Add Properties window.
context lets the user add the property in the same ways as user, and also using the context tab of the Add Properties window.
freq adds the property as a frequently used property, marked with in the Properties. The user can also add the property in the same ways as with context.
auto adds the property automatically.
fixed adds the property automatically and does not let the user remove the property.

You can set multiple nodeType:addition pairs separated with commas.

Examples

C++

// Adds the property as a frequently used property for all 2D nodes.
metadata.host = "Node2D:freq";

// Adds the property automatically for all VideoView2D nodes and
// lets the user add the property for Image nodes.
metadata.host = "VideoView2D:auto,Image2D:user";

Java

// Adds the property as a frequently used property for all 2D nodes.
@EditorInfo(host = "Node2D:freq")

// Adds the property automatically for all VideoView2D nodes and
// lets the user add the property for Image nodes.
@EditorInfo(host = "VideoView2D:auto,Image2D:user")

Kotlin

// Adds the property as a frequently used property for all 2D nodes.
@EditorInfo(host = "Node2D:freq")

// Adds the property automatically for all VideoView2D nodes and
// lets the user add the property for Image nodes.
@EditorInfo(host = "VideoView2D:auto,Image2D:user")

editor¶

Sets the editor type Kanzi Studio users use to set the value for the property. If you do not set an editor, Kanzi assigns a default editor.

If you set the valueProvider attribute to PropertyType or StringList, do not set the editor type. Kanzi Studio assigns the correct editor automatically.

For a list of Kanzi Studio property editors, see Kanzi Studio property editors for property types declared in Kanzi Engine plugins.

Syntax

metadata.editor = "editor";

Values

editor

Kanzi Studio property editor name. See Kanzi Studio property editors for property types declared in Kanzi Engine plugins.

Examples

C++

// Set editor to BrowseFileTextEditor which contains a text box with
// a Browse button next to it.
metadata.editor = "BrowseFileTextEditor";

Java

// Set editor to BrowseFileTextEditor which contains a text box with
// a Browse button next to it.
@EditorInfo(editor = "BrowseFileTextEditor")

Kotlin

// Set editor to BrowseFileTextEditor which contains a text box with
// a Browse button next to it.
@EditorInfo(editor = "BrowseFileTextEditor")

defaultValue¶

Sets the default value of the property or message the way it is shown in Kanzi Studio.

Syntax

metadata.defaultValue = "value";

Values

value

The default value of the property or message in Kanzi Studio

Examples

C++

// Set the default value of a string property in Kanzi Studio to video.mp4.
metadata.defaultValue = "video.mp4";

Java

// Set the default value of a string property in Kanzi Studio to video.mp4.
@EditorInfo(defaultValue = "video.mp4")

Kotlin

// Set the default value of a string property in Kanzi Studio to video.mp4.
@EditorInfo(defaultValue = "video.mp4")

C++

// Set the default value of a float property in Kanzi Studio to 180.
metadata.defaultValue = "180";

Java

// Set the default value of a float property in Kanzi Studio to 180.
@EditorInfo(defaultValue = "180")

Kotlin

// Set the default value of a float property in Kanzi Studio to 180.
@EditorInfo(defaultValue = "180")

lowerBound¶

Sets the lowest value the property can have in Kanzi Studio. Use lowerBound with int and float property types. See also upperBound and step.

Syntax

metadata.lowerBound = "value";

Values

value

The lowest value the property can have

Examples

C++

// Set the lowest value the property can have to 0.
metadata.lowerBound = "0";

Java

// Set the lowest value the property can have to 0.
@EditorInfo(lowerBound = "0")

Kotlin

// Set the lowest value the property can have to 0.
@EditorInfo(lowerBound = "0")

upperBound¶

Sets the highest value the property can have in Kanzi Studio. Use upperBound with int and float property types. See also lowerBound and step.

Syntax

metadata.upperBound = "value";

Values

value

The highest value the property can have

Examples

C++

// Set the highest value the property can have to 360.
metadata.upperBound = "360";

Java

// Set the highest value the property can have to 360.
@EditorInfo(upperBound = "360")

Kotlin

// Set the highest value the property can have to 360.
@EditorInfo(upperBound = "360")

step¶

Sets the amount by which the property value changes when a Kanzi Studio user edits it. Use step with int and float property types. See also lowerBound and upperBound.

Syntax

metadata.step = "value";

Values

value

The amount by which the property value changes when a Kanzi Studio user edits it

Examples

C++

// Set the amount by which the property value changes when
// a Kanzi Studio user edits it to 10.
metadata.step = "10";

Java

// Set the amount by which the property value changes when
// a Kanzi Studio user edits it to 10.
@EditorInfo(step = "10")

Kotlin

// Set the amount by which the property value changes when
// a Kanzi Studio user edits it to 10.
@EditorInfo(step = "10")

sendable¶

Sets whether Kanzi Studio shows the message as an action in the trigger actions dropdown menu.

Syntax

metadata.sendable = "value"

Values

True

Show the message as an action. Default value.

False

Do not show the message as an action.

Examples

C++

// Do not show the message as an action.
metadata.sendable = "False";

Java

// Do not show the message as an action.
@EditorInfo(sendable = "False")

Kotlin

// Do not show the message as an action.
@EditorInfo(sendable = "False")

listenable¶

Sets whether Kanzi Studio shows the message as a trigger in the Add Triggers window and Add Trigger context menu.

Syntax

metadata.listenable = "value"

Values

True

Show the message as a trigger. Default value.

False

Do not show the message as a trigger.

Examples

C++

// Do not show the message as a trigger.
metadata.listenable = "False";

Java

// Do not show the message as a trigger.
@EditorInfo(listenable = "False")

Kotlin

// Do not show the message as a trigger.
@EditorInfo(listenable = "False")

sortingIndex¶

Sets the position of the property in its property category shown in the Kanzi Studio Properties window. By default Kanzi Studio orders property types within a property category according to their order in the metaclass definition. See category.

Syntax

metadata.sortingIndex = "index"

Values

index

Position of the property in its property category shown in Kanzi Studio

Examples

C++

// Show the property as the first property in its property category.
metadata.sortingIndex = "1";

Java

// Show the property as the first property in its property category.
@EditorInfo(sortingIndex = "1")

Kotlin

// Show the property as the first property in its property category.
@EditorInfo(sortingIndex = "1")

studioVisibility¶

Sets whether the property or message is available in Kanzi Studio.

Syntax

metadata.studioVisibility = "value"

Values

Visible

Show the property or message in Kanzi Studio. Default value.

UserHidden

Hide the property or message from the Kanzi Studio user, but keep Kanzi Studio aware of the property or message.

Hidden

Make Kanzi Studio unaware of the property or message and do not include the property or message in the kzb file.

You can use this value for properties and messages that implement internal functionality of the plugin and do not need to be set in Kanzi Studio.

Examples

C++

// Make Kanzi Studio unaware of the property.
metadata.studioVisibility = "Hidden";

Java

// Make Kanzi Studio unaware of the property.
@EditorInfo(studioVisibility = "Hidden")

Kotlin

// Make Kanzi Studio unaware of the property.
@EditorInfo(studioVisibility = "Hidden")

legacyName¶

Sets the name of the property type or message in earlier versions of the Kanzi Engine plugin.

When you rename a property type or message, use legacyName to inform Kanzi Studio about the change. When a Kanzi Studio user updates the Kanzi Engine plugin in a Kanzi Studio project, Kanzi Studio renames all instances of the property type or message in that project.

Syntax

metadata.legacyName = "name"

Values

name

Name of the property type or message in earlier versions of the plugin. Separate legacy names with semicolons.

Examples

C++

// Give Kanzi Studio the name of the property type or message in
// the earlier versions of the plugin.
metadata.legacyName = "MyOldPropertyName";

Java

// Give Kanzi Studio the name of the property type or message in
// the earlier versions of the plugin.
@EditorInfo(legacyName = "MyOldPropertyName")

Kotlin

// Give Kanzi Studio the name of the property type or message in
// the earlier versions of the plugin.
@EditorInfo(legacyName = "MyOldPropertyName")

Reference for showing Kanzi Engine plugin custom types in Kanzi Studio¶

displayName¶

tooltip¶

category¶

valueProvider¶

host¶

editor¶

defaultValue¶

lowerBound¶

upperBound¶

step¶

sendable¶

listenable¶

sortingIndex¶

studioVisibility¶

legacyName¶

See also¶