Kanzi自定义插件节点属性、自定义消息以及自定义响应

创建自定义节点和属性类型

在自定义插件中可以使用自定义属性类型创建自定义节点，可以设置如何显示以及如何让用户与这些节点交互。

在插件工程.hpp文件中，在元类定义之后声明返回元数据的函数：

...static kanzi::PropertyType<kanzi::string> StringProperty;static kanzi::PropertyType<kanzi::string> NodeStringProperty;KZ_METACLASS_BEGIN(KZPlugin, Node3D, "MyKZPlugin")KZ_METACLASS_PROPERTY_TYPE(StringProperty)KZ_METACLASS_PROPERTY_TYPE(NodeStringProperty)KZ_METACLASS_END()static kanzi::PropertyTypeEditorInfoSharedPtr makeEditorInfo();
...

在插件工程的.cpp文件中，创建函数makeEditorInfo()的定义，创建元数据。

PropertyTypeEditorInfoSharedPtr KZPlugin::makeEditorInfo()
{return PropertyTypeEditorInfoSharedPtr(KZ_PROPERTY_TYPE_EDITOR_INFO([]()->PropertyTypeEditorInfo::AttributeDictionary {PropertyTypeEditorInfo::AttributeDictionary dict;//设置需要在Kanzi Studio中为节点使用的名称dict.displayName = "My Node";//设置要在Kanzi Studio创建菜单中使用的工具提示dict.tooltip = "This example custom node uses custom properties.";//添加水平对齐(Horizontal Alignment)和垂直对齐(Vertical Alignment)dict["AutomaticallyAddedProperties"] = "Node.HorizontalAlignment, Node.VerticalAlignment";//添加状态机(State Manager)属性作为常用属性，可以通过点击旁边的+进行添加dict["FrequentlyAddedProperties"] = "Node.StateManager";//用户使用添加属性(Add Property)上下文菜单或添加属性(Add Properties)窗口的上下文选项卡添加焦点范围(Focus Scope)属性dict["ContextProperties"] = "FocusManager.FocusScope";return dict;}()));
}

添加完上述代码后，重新生成插件，注意在生成插件过程中，要求先暂停Kanzi Studio工程中的Preview。在kanzi插件工程中更新插件：

随后，在Project中的创建列表中添加插件至Project节点下，在插件节点的属性中可以查看到刚才添加的属性。

创建自定义属性类型及其元数据

在插件工程的.hpp头文件中，在元数据声明位置添加如下代码，例如：

...static kanzi::PropertyType<kanzi::string> StringProperty;static kanzi::PropertyType<kanzi::string> NodeRefByStringProperty;KZ_METACLASS_BEGIN(KZPlugin, Node3D, "MyKZPlugin")KZ_METACLASS_PROPERTY_TYPE(StringProperty)KZ_METACLASS_PROPERTY_TYPE(NodeRefByStringProperty)KZ_METACLASS_END()
...

在插件工程的.cpp文件中，为自定义属性类型添加元数据。

使用一行文本编辑器的字符串属性：

//创建字符串属性。不设置编辑器时，使用默认编辑器。
PropertyType<string> KZPlugin::StringProperty(kzMakeFixedString("KZPlugin.String"), "", 0, false,KZ_DECLARE_EDITOR_METADATA(metadata.displayName = "String";
));

应用3D节点的字符串，用户可以从下拉菜单中选择节点：

PropertyType<string> KZPlugin::NodeRefByStringProperty(kzMakeFixedString("KZPlugin.NodeRefByString"), "", 0, false,KZ_DECLARE_EDITOR_METADATA(metadata.displayName = "Node reference by String";metadata.valueProvider = "ProjectObject:Node3D";
));

重新加载插件后，便可以看到自定义属性。

在Project工程节点中可以查看其属性。

默认情况下，Kanzi Studio将自定义属性作为常用属性添加到您为其创建属性类型的节点。要设置Kanzi Studio为属性推荐的节点类型，以及是有Kanzi Studio自动添加该属性，还是用户添加该属性，请设置metadata.host特性。

创建自定义消息类型

您可以创建自定义消息类型，为您的应用程序添加函数。例如，您可以为自定义节点创建一个自定义触发器(trigger)和行为(action) 。

创建自定义触发器

在Kanzi插件中，您可以创建一个自定义消息类型，并在Kanzi Studio中以触发器形式显示出来。例如，可以创建一个名叫“On Fuel Level Changed” 的触发器。

在插件工程的.hpp头文件中，在插件类中嵌套消息类，声明自定义消息类型以及消息名称。

...KZ_METACLASS_MESSAGE_TYPE(OnFuelLevelChangedMessage)KZ_METACLASS_END()
...
//表示FuelIndicator.OnFuelLevelChanged的消息类型class OnFuelLevelChangedMessageArguments : public kanzi::MessageArguments{public:KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(OnFuelLevelChangedMessageArguments, MessageArguments, "On Fuel Level Changed Message Arguments")KZ_METACLASS_END()};//定义其消息类型static kanzi::MessageType<OnFuelLevelChangedMessageArguments> OnFuelLevelChangedMessage;
...

在插件工程头文件中，创建函数，当触发器触发时，发送KZPlugin.OnFuelLevelChanged消息。

 void onFuelLevelChanged(int fuelLevel){OnFuelLevelChangedMessageArguments messageArguments;dispatchMessage(OnFuelLevelChangedMessage, messageArguments);}

最后在插件工程.cpp文件中，声明 KZPlugin.OnFuelLevelChanged消息的元数据。

MessageType<KZPlugin::OnFuelLevelChangedMessageArguments> KZPlugin::OnFuelLevelChangedMessage(kzMakeFixedString("Message.KZPlugin.OnFuelLevelChanged"),KZ_DECLARE_EDITOR_METADATA(metadata.displayName = "On Fuel Level Changed";metadata.tooltip = "Fuel Sets of this trigger when its level changes.";metadata.category = "Custom Controls";metadata["Sendable"] = "False";));

重新编译插件代码，在Kanzi Studio中更新插件信息，在工程节点中添加触发器便可以看见自定义的触发器设置。

创建自定义插件的消息响应

在kanzi插件中，可以为自定义消息创建相应的响应。例如，在上面定义的自定义消息中，为其定义一个名叫“Update Level”的响应。

在插件工程的.hpp头文件中，定义其消息的嵌套类：

...
class FuelUpdateLevelMessageArguments : public kanzi::MessageArguments{public:static kanzi::PropertyType<int> FuelLevelProperty;KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(FuelUpdateLevelMessageArguments, MessageArguments, "Fuel Update Level  Message Arguments")KZ_METACLASS_PROPERTY_TYPE(FuelLevelProperty)KZ_METACLASS_END()int getFuelLevel(){return getArgument(FuelLevelProperty);}};
...

在插件类头文件中定义消息类型：

...static kanzi::MessageType<FuelUpdateLevelMessageArguments> FuelUpdateLevelMessage;
...

并在插件类头文件中元数据声明处，声明自定义的消息类型：

...KZ_METACLASS_MESSAGE_TYPE(FuelUpdateLevelMessage);KZ_METACLASS_END()
...

在插件类头文件中，定义自定义消息的消息响应回调处理函数：

...void fuelUpdateLevelHandler(FuelUpdateLevelMessageArguments& arguments){m_currentLevel += arguments.getFuelLevel();//添加需要处理数据的逻辑}
...

在插件类的.cpp文件中，建立消息与回调函数之间的绑定：

void KZPlugin::initialize()
{// Initialize base class.Node3D::initialize();addMessageHandler(FuelUpdateLevelMessage, this, &KZPlugin::fuelUpdateLevelHandler);
}

在插件类的.cpp文件中，为消息声明对应的元数据：

PropertyType<int> KZPlugin::KZPlugin::FuelUpdateLevelMessageArguments::FuelLevelProperty(kzMakeFixedString("KZPlugin.Fuel.Level"), 0, 0, false,KZ_DECLARE_EDITOR_METADATA(metadata.displayName = "Fuel Level";
));MessageType<KZPlugin::FuelUpdateLevelMessageArguments> KZPlugin::FuelUpdateLevelMessage(kzMakeFixedString("Message.KZPlugin.UpdateLevel"),KZ_DECLARE_EDITOR_METADATA(metadata.displayName = "Update Level";metadata["Listenable"] = "False";
));

重新编译插件代码，并更新Kanzi Studio中的插件信息，在Kanzi Studio中可以看到：

参考：《kanzi手册/Extending the functionality of Kanzi Engine》