15、Kanzi插件——通过Kanzi Engine插件创建自定义消息类型+代码解析

一、创建trigger中的自定义消息

比如，想创建一个当汽车燃油量发生变化时对应的消息，可以进行如下操作

首先，在插件工程中的头文件中定义一个嵌套类，下面代码中的第23行和29-44行为新添加代码

#ifndef PLUGINDEMO_HPP
#define PLUGINDEMO_HPP

// Use kanzi.hpp only when you are learning to develop Kanzi applications. 
// To improve compilation time in production projects, include only the header files of the Kanzi functionality you are using.
#include <kanzi/kanzi.hpp>

using namespace kanzi;

class Plugindemo;
typedef kanzi::shared_ptr<Plugindemo> PlugindemoSharedPtr;

class PLUGINDEMO_API Plugindemo : public kanzi::Node3D
{
public:

	//字符串属性
	static kanzi::PropertyType<kanzi::string> StringProperty;
	//引用节点的字符串
	static kanzi::PropertyType<kanzi::string> NodeRefByStringProperty;
	//引用预设件的字符串
	static kanzi::PropertyType<kanzi::string> PrefabRefByStringProperty;
	//引用预设件的共享指针
	static kanzi::PropertyType<kanzi::ResourceSharedPtr> PrefabRefBySharedPtrProperty;
	//引用材质的共享指针
	static kanzi::PropertyType<kanzi::ResourceSharedPtr> MaterialRefBySharedPtrProperty;

	KZ_METACLASS_BEGIN(Plugindemo, Node3D, "MyNode")
	//将属性类型添加到类元数据。
	KZ_METACLASS_PROPERTY_TYPE(StringProperty)
	KZ_METACLASS_PROPERTY_TYPE(NodeRefByStringProperty)
	KZ_METACLASS_PROPERTY_TYPE(PrefabRefByStringProperty)
	KZ_METACLASS_PROPERTY_TYPE(PrefabRefBySharedPtrProperty)
	KZ_METACLASS_PROPERTY_TYPE(MaterialRefBySharedPtrProperty)
	KZ_METACLASS_MESSAGE_TYPE(OnFuelLevelChangedMessage)
	KZ_METACLASS_END()

	static kanzi::PropertyTypeEditorInfoSharedPtr makeEditorInfo();


	// Represents message arguments of message type.
	class OnFuelLevelChangedMessageArguments : public MessageArguments
	{
	public:
		KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(OnFuelLevelChangedMessageArguments, MessageArguments, "On Fuel Level Changed Message Arguments")
			KZ_METACLASS_END()
	};

	// Define the message type of the FuelIndicator.OnFuelLevelChanged message.
	static kanzi::MessageType<OnFuelLevelChangedMessageArguments> OnFuelLevelChangedMessage;

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

    // Creates a Plugindemo.
    static PlugindemoSharedPtr create(kanzi::Domain* domain, kanzi::string_view name);

protected:

    // Constructor.
    explicit Plugindemo(kanzi::Domain* domain, kanzi::string_view name):
        kanzi::Node3D(domain, name)
    {
    }

    // Initializes the created Kanzi Engine plugin.
    // Kanzi node classes typically have a static create() member function, which creates the instance of a node,
    // initializes it, and returns a shared pointer to the instance. To initialize the instance, the initialize()
    // function is called on it. You must initialize a node in the initialize() function, not in the constructor.
    void initialize();
};

宏KZ_METACLASS_MESSAGE_TYPE也是向元类的容器成员中添加元数据，因此在更新插件的时候，kanzistudio能检测出插件元数据变化，进而能更新插件

#define KZ_METACLASS_MESSAGE_TYPE(messageType)\
        messageType.attachArgumentsMetaclass();\
        metaclass.addMessageType(messageType);\
        metaclass.addNestedMetaclass(messageType.getArgumentsMetaclass());

类OnFuelLevelChangedMessageArguments是一个嵌套类，表示插件中的一个消息类型，kanzi中的消息类必须要继承MessageArguments，MessageArguments中主要实现了一些对消息的操作以及get和set接口

class OnFuelLevelChangedMessageArguments : public MessageArguments
{
public:
    KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(OnFuelLevelChangedMessageArguments, MessageArguments, "On Fuel Level Changed Message Arguments")
    KZ_METACLASS_END()
};

// Define the message type of the FuelIndicator.OnFuelLevelChanged message.
static kanzi::MessageType<OnFuelLevelChangedMessageArguments> OnFuelLevelChangedMessage;

第4，5两行的宏展开如下

#define KZ_MESSAGE_ARGUMENTS_METACLASS_BEGIN(thisClass, baseClass, name)\
static const ::kanzi::Metaclass* getStaticMetaclass()\
{\
    typedef thisClass ThisClass;\
    typedef baseClass BaseClass;\
    static ::kanzi::MetaclassStaticImpl<ThisClass> metaclass(::kanzi::MessageArgumentsBaseMetaclassWrapper<BaseClass>::getStaticMetaclass(), kzMakeFixedString(name));\
    if (!metaclass.isSealed())\
    {\
        /* Ensure that the base metaclass is initialized in case of metadata system restart.*/\
        ::kanzi::MessageArgumentsBaseMetaclassWrapper<BaseClass>::getStaticMetaclass();

#define KZ_METACLASS_END()\
        metaclass.setEditorInfo(::kanzi::PropertyTypeEditorInfoSharedPtr(makeEditorInfo()));\
        metaclass.seal();\
    }\
    return &metaclass;\
}

这个函数的作用与之前介绍的一组宏类似，作用也是创建一个消息元类并返回

 

消息类型定义完之后，通过MessageType声明了一个消息类型，该消息的定义在cpp文件中

MessageType<Plugindemo::OnFuelLevelChangedMessageArguments> Plugindemo::OnFuelLevelChangedMessage(
	kzMakeFixedString("Message.FuelIndicator.OnFuelLevelChanged"),
	KZ_DECLARE_EDITOR_METADATA
	(
		// Set the name of the message the way you want to show it in Kanzi Studio.
		metadata.displayName = "On Fuel Level Changed";
		// Set the tooltip for the message.
		metadata.tooltip = "Fuel Indicator sets off this trigger when its level changes.";
		// Set the category under which this message is listed in the triggers list.
		metadata.category = "Custom Controls";
		// Do not show the message in the trigger actions dropdown menu.
		metadata["Sendable"] = "False";
	)
);

至此，消息初始化完成

 

最后设置一个成员函数，当油量变化时，将该消息分发出去（40-44行）

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

 

二、效果

编译上述代码并更新插件

随便点击工程目录下的一个节点，然后为节点添加一个触发，就可以看到自定义的消息触发

 

参考

《Kanzi官方文档》