Reference for showing Kanzi Engine plugin custom types in Kanzi Studio

You can use Kanzi Engine plugins to create custom property types and messages using the Kanzi Engine API, and use them in Kanzi Studio.

To pass to Kanzi Studio information about the custom property types and messages you create in a Kanzi Engine plugin, you declare metadata that describe these property types and messages.

The metadata enable Kanzi Engine plugin users to interact with the plugin content in Kanzi Studio.

For example, metadata defines the type of Kanzi Studio property editor for setting a value for a property, and the set of values to select from.

Declare only the metadata you need. Kanzi Studio assigns the default values to the attributes that you do not set.

This table lists the metadata attributes you can use.

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

The initial value that the property gets when it is added to a node or resource in Kanzi Studio

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

 
metadata.displayName = "Video Filename";

@EditorInfo(displayName = "Video Filename")

@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

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

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

@EditorInfo(
             displayName = "Video Filename",
             tooltip = "Name of the video file to be played."
           )
../../_images/video-filename-with-category-and-tooltip.png

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

Category

Examples

 
metadata.displayName = "Video Filename";
metadata.category = "Video";

@EditorInfo(
             displayName = "Video Filename",
             category = "Video"
           )

@EditorInfo(
             displayName = "Video Filename",
             category = "Video"
           )
../../_images/video-filename-category.png

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

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

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

// 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 
// Provides a dropdown with all available property types.
// Do not set the editor type. Kanzi Studio automatically sets the correct editor.
metadata.valueProvider = "PropertyType";

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

// 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 
// 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";

// 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")

// 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 
// 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";

// 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")

// 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")
../../_images/valueprovider-enum.png 
// 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";
    ));

// 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);

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 
// 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";
    ));

// 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);

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 
// 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";
    ));

// 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);

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 image0 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

 
// 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";

// 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")

// 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

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

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

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

defaultValue

Sets the value to which Kanzi Studio sets the property when the property is added to a node or resource. Use this attribute to define the value to which the Kanzi Studio user most likely wants to set the property.

For example, for a boolean property type whose default value is true, set metadata.defaultValue = "False";. When the Kanzi Studio user adds that property type to a node, Kanzi Studio sets the property as disabled. This way, the user does not have to perform two actions.

Syntax

metadata.defaultValue = "value";

Values

value

The default value of the property or message in Kanzi Studio

Examples

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

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

// Set the default value of a string property in Kanzi Studio to video.mp4.
@EditorInfo(defaultValue = "video.mp4")
../../_images/video-filename-property.png 
// Set the default value of a float property in Kanzi Studio to 180.
metadata.defaultValue = "180";

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

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

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

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

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

// Set the lowest value the property can have to 0.
@EditorInfo(lowerBound = "0")
../../_images/metadata-lowerbound.png

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

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

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

// Set the highest value the property can have to 360.
@EditorInfo(upperBound = "360")
../../_images/metadata-upperbound.png

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

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

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

// 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

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

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

// 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

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

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

// 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

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

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

// 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

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

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

// 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

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

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

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

See also

Kanzi Engine plugins

Using Kanzi Engine plugins

Creating Kanzi Engine plugins

Kanzi Studio property editors for property types declared in Kanzi Engine plugins

Tutorial: Get application data from a data source

Node2D plugin example

Node3D plugin example