使用 Java 和 Kotlin¶

Kanzi Java API 为 Kanzi 类实现了平台无关的 Java 代理，提供了对 Java 和 Kotlin 中 Kanzi 功能的丰富访问。这使您能够创建与 Android API 紧密集成的应用程序。

在 Android 上，您可以直接从 Android UI 线程使用 Kanzi Java API，而无需调度机制。请参阅使用 Kanzi Android framework (droidfw) 进行开发时。

本主题概述了 Kanzi Java API 的基础知识。有关完整的 API 参考，请参阅 Kanzi Engine Java API 参考文档。

要求¶

Kanzi Java API 需要 Java 8 (1.8) 或更高版本。

使用属性¶

Kanzi Java API 类包含用于内置属性类型（如 metadata.NodeMetadata.OpacityProperty）的静态成员。要读取和写入这些属性：

Java

// Set property.
node.setProperty(Node.OpacityProperty, 0.5f);

// Get property.
float opacity = node.getProperty(Node.OpacityProperty);

Kotlin

// Set property.
node.setProperty(Node.OpacityProperty, 0.5f)

// Get property.
val opacity = node.getProperty(Node.OpacityProperty)

要通过名称访问属性，请创建 DynamicPropertyType 或 AbstractPropertyType 的实例，并使用属性类型的全名：

Java

// Use DynamicPropertyType to access a property type when the type is known.
DynamicPropertyType<Boolean> dynamicProperty =
    new DynamicPropertyType<>("Node.Visible", Boolean.class);
node.setProperty(dynamicProperty, false);

// Use AbstractPropertyType to access a property type when the type is not known.
AbstractPropertyType abstractProperty = new AbstractPropertyType("Node.Visible");
node.setProperty(abstractProperty, false);

Kotlin

// Use DynamicPropertyType to access a property type when the type is known.
val dynamicProperty = DynamicPropertyType("Node.Visible", Boolean::class.java)
node.setProperty(dynamicProperty, false)

// Use AbstractPropertyType to access a property type when the type is not known.
val abstractProperty = AbstractPropertyType("Node.Visible")
node.setProperty(abstractProperty, false)

要定义新的属性类型，请在您的类中创建一个 PropertyType 的公共静态成员实例，并使用 Metadata 进行注释：

Java

@Metadata
@EditorInfo(displayName = "Custom Property")
public static final PropertyType<String> CustomProperty =
    new PropertyType<>("MyNode2D.Custom", String.class);

// Properties can also have an automatically generated name.
// In this case 'MyNode2D.Other'.
@Metadata
public static final PropertyType<String> OtherProperty = new PropertyType<>(String.class);

Kotlin

// You must place this inside the "companion object".

@Metadata
@EditorInfo(displayName = "Custom Property")
val CustomProperty = PropertyType("MyNode2D.Custom", String::class.java)

// Properties can also have an automatically generated name.
// In this case 'MyNode2D.Other'.
@Metadata
val OtherProperty = PropertyType(String::class.java)

要了解有关可以为您的属性类型设置的元数据的更多信息，请参阅在 Kanzi Studio 中显示 Kanzi Engine 插件自定义类型的参考。。

请参阅属性系统。

使用枚举¶

使用 Kanzi Java API 枚举¶

Kanzi Java API 附带与内置属性相关联的枚举集。

在 Java 代码中，对于 setter 和 getter 函数，像这样访问 Kanzi Java API 枚举值：

textNode.setProperty(TextBlock2D.FontHintingPreferenceProperty, FontHintingPreference.NativeHinting);

Node.HorizontalAlignment value = node.getProperty(Node.HorizontalAlignmentProperty);

由于 Java 和 Kotlin 在接口继承方面的差异，访问 Kanzi Java API 枚举需要使用相应的枚举接口。

例如：使用 metadata.NodeMetadata.HorizontalAlignmentProperty 属性：

这在 Java 和 Kotlin 中都适用：
```
NodeEnums.HorizontalAlignment.Center;
```
这仅在 Java 中有效：
```
Node.HorizontalAlignment.Center;
```

使用自定义枚举¶

如果您声明一个自定义枚举，为了能够将此枚举设置为自定义属性的数据类型，该枚举类型必须继承 Kanzi 枚举：

Java

// Define a custom enum and inherit from Kanzi Enum. Make sure to import Kanzi Enum.
enum CustomEnum implements Enum
{
    // Add enum values. Make sure to initialize them.
    Value1(0),
    Value2(1);

    // Add a getter function. Make sure that it is public.
    @Override
    public int getValue()
    {
        return mValue;
    }

    // Add a constructor.
    CustomEnum(int value)
    {
        mValue = value;
    }

    // The actual value.
    int mValue;
}

@Metadata
@EditorInfo(displayName = "Custom Enum Property")
public static final PropertyType<CustomEnum> CustomEnumProperty =
    new PropertyType<>("MyNode2D.CustomEnum", CustomEnum.class);

Kotlin

// Define a custom enum and inherit from Kanzi Enum. Make sure to import Kanzi Enum.
// Declare an integer value in the primary constructor.
enum class CustomEnum(private val mValue: Int) : Enum
{
    // Add enum values. Make sure to initialize them.
    Value1(0),
    Value2(1);

    // Add a getter function.
    override fun getValue(): Int
    {
        return mValue;
    }
}

@Metadata
@EditorInfo(displayName = "Custom Enum Property")
val CustomEnumProperty = PropertyType<CustomEnum>("MyNode2D.CustomEnum", CustomEnum::class.java);

使用消息¶

Kanzi Java API 类包含内置消息类型的静态成员，例如 metadata.ButtonConceptMetadata.ToggleStateChangedMessageArguments。

要发送消息：

Java

// Construct message arguments.
ToggleButton2D.ToggleStateChangedMessageArguments args =
    new ToggleButton2D.ToggleStateChangedMessageArguments();

// Set message arguments.
args.setToggleStateProperty(1);

// Dispatch message.
node.dispatchMessage(Button2D.ToggleStateMessage, args);

Kotlin

// Construct message arguments.
val args = ButtonConceptMetadata.ToggleStateChangedMessageArguments()

// Set message arguments.
args.toggleStateProperty = 1

// Dispatch message.
node.dispatchMessage(Button2D.ToggleStateMessage, args)

要在节点接收到消息时作出反应，请向该节点添加消息处理程序：

Java

// Add message subscription.
button.addMessageHandler(Button2D.ToggleStateMessage, messageArguments -> {
    // Extract arguments through accessors..
    Integer toggleState = messageArguments.getToggleStateProperty();
    // .. or through generic accessors
    toggleState = messageArguments.getArgument(
        ButtonConceptMetadata.ToggleStateChangedMessageArguments.ToggleStateProperty);
});

Kotlin

// Add message subscription.
button.addMessageHandler(Button2D.ToggleStateMessage)
{ messageArguments ->
    // Extract arguments.
    val toggleState = messageArguments.toggleStateProperty
}

要使用消息名称，请使用消息类型的全名创建 AbstractMessageType 的实例：

Java

// Get reference to a message type.
AbstractMessageType messageType = new AbstractMessageType("Message.MyMessage");
DynamicPropertyType<Boolean> argumentProperty =
    new DynamicPropertyType<>("MyMessage.Argument", Boolean.class);

// Construct message arguments.
MessageArguments args = new MessageArguments();

// Set message arguments.
args.setArgument(argumentProperty, false);

// Send the message.
node.dispatchMessage(messageType, args);

Kotlin

// Get reference to a message type.
val messageType = AbstractMessageType("Message.MyMessage")
val argumentProperty = DynamicPropertyType("MyMessage.Argument", Boolean::class.java)

// Construct message arguments.
val args = MessageArguments()

// Set message arguments.
args.setArgument(argumentProperty, false)

// Send the message.
node.dispatchMessage(messageType, args)

要定义新消息类型：

（可选）定义一个消息参数类，该类包含您的消息的参数属性类型。

您定义的消息参数类必须从基类 MessageArguments 或另一个消息参数类派生。

您不必定义消息参数类。相反，您可以使用现有的消息参数类，包括基类 MessageArguments。

Java

@Metadata
public static class ExampleMessageArguments extends MessageArguments
{
    // Define metaclass.
    @Metadata
    public static Metaclass metaclass =
        new Metaclass("Example.MyNode2D.ExampleMessageArguments");

    // Define properties.
    @Metadata
    public static PropertyType<Integer> SomeProperty = new PropertyType<>(Integer.class);

    // Optionally, define property accessors. You can instead use the generic argument
    // accessors.
    public Integer getSomeProperty()
    {
        return getArgument(SomeProperty);
    }
    public void setSomeProperty(Integer value)
    {
        setArgument(SomeProperty, value);
    }

    // Define constructors.
    // A constructor with a long argument, which Kanzi uses to wrap native arguments.
    public ExampleMessageArguments(long nativeObject)
    {
        super(nativeObject);
    }
    // Any additional constructors for you to use when dispatching messages.
    public ExampleMessageArguments()
    {
        super();
    }
}

Kotlin

@Metadata
class ExampleMessageArguments : MessageArguments {
    companion object {
        // Define metaclass.
        @Metadata
        var metaclass = Metaclass("Example.MyNode2D.ExampleMessageArguments")

        // Define properties.
        @Metadata
        val SomeProperty = PropertyType(Int::class.java)
    }

    // Optionally, define property accessors. You can instead use the generic argument accessors.

    fun getSomeProperty(): Int? {
        return getArgument(SomeProperty)?.toInt()
    }

    fun setSomeProperty(value: Int) {
        setArgument(SomeProperty, value)
    }

    // Define constructors.

    // A constructor with a long argument, which Kanzi uses to wrap native arguments.
    constructor(nativeObject: Long) : super(nativeObject)

    // Any additional constructors for you to use when dispatching messages.
    constructor() : super()
}

在您的类中创建一个 MessageType 的公共静态成员实例，并使用 Metadata 进行注释：

Java

@Metadata
public static final MessageType<ExampleMessageArguments> ExampleMessage =
    new MessageType<>("Message.MyNode2D.Example", MessageRouting.MessageRoutingBubbling,
        ExampleMessageArguments.class);

Kotlin

// You must place this inside the "companion object".

@Metadata
val ExampleMessage = MessageType(
    "Message.MyNode2D.Example",
    MessageRouting.MessageRoutingBubbling,
    ExampleMessageArguments::class.java
)

要了解有关您可以为消息和消息参数类型设置的元数据的更多信息，请参阅在 Kanzi Studio 中显示 Kanzi Engine 插件自定义类型的参考。。

请参阅使用消息。

创建实例¶

具体的 Kanzi Java API 类型带有 create 方法，您可以使用这些方法来创建实例。

从 KanziObject 派生的对象类型的 create 方法返回一个 ObjectRef 实例，该实例是对新对象的拥有引用。

实现自定义资源加载¶

要在 Java 或 Kotlin 中实现自定义资源加载，定义一个自定义资源管理器协议。

Java

ResourceManager resourceManager = domain.getResourceManager();
resourceManager.registerProtocolHandler(
    "MyProtocol", new ResourceManager.ProtocolHandler() {
        @Override
        public Result handle(ResourceManager resourceManager, String url, String protocol,
            String hostname, String path)
        {
            if (shouldLoadSynchronously)
            {
                // Load a resource synchronously.
                ObjectRef<Resource> resource = loadSynchronousResource();
                return new Result(resource);
            }
            else
            {
                // Use load task for asynchronous loading.
                return new Result(new ResourceManager.LoadTask() {
                    ObjectRef<Resource> mResource = null;
                    @Override
                    public void loadFunction()
                    {
                        // Perform thread-independent loading.
                    }

                    @Override
                    public void finishFunction()
                    {
                        // Create and store the resource.
                        mResource = createResource();
                    }

                    @Override
                    public ObjectRef<? extends Resource> getResult()
                    {
                        // Return the created resource.
                        return mResource.clone();
                    }

                    @Override
                    public void close()
                    {
                        mResource.close();
                    }
                });
            }
        }
    });

Kotlin

domain.resourceManager.registerProtocolHandler("MyProtocol")
{ resourceManager, url, protocol, hostname, path ->
    if (shouldLoadSynchronously) {
        // Load a resource synchronously.
        val resource = loadSynchronousResource()
        ProtocolHandler.Result(resource)
    } else {
        // Use load task for asynchronous loading.
        ProtocolHandler.Result(object : ResourceManager.LoadTask() {
            var mResource: ObjectRef<Resource>? = null
            override fun loadFunction() {
                // Perform thread-independent loading.
            }

            override fun finishFunction() {
                // Create and store the resource.
                mResource = createResource()
            }

            override fun getResult(): ObjectRef<out Resource>? {
                // Return the created resource.
                return mResource!!.clone()
            }

            override fun close() {
                mResource!!.close()
            }
        })
    }
}

如果失败，资源协议 ResourceManager.ProtocolHandler.handle 可能会抛出异常，由 Kanzi Resource Manager 处理。

默认情况下，ResourceManager.LoadTask 会调用 ResourceManager.LoadTask.loadFunction 和 ResourceManager.LoadTask.finishFunction。要设置 ResourceManager.LoadTask 仅调用 ResourceManager.LoadTask.finishFunction，请将 ResourceLoadTaskType.FinishOnly 传递给构造函数。

资源协议可以通过实现 ResourceManager.ReloadProtocolHandler 来支持重新加载操作。Kanzi 调用重新加载处理程序以在 OpenGL 上下文失效时重新初始化现有资源。

Java

ResourceManager resourceManager = domain.getResourceManager();
resourceManager.registerProtocolHandler("MyReloadProtocol",
    new ResourceManager.ProtocolHandler() {
        @Override
        public Result handle(ResourceManager resourceManager, String url, String protocol,
            String hostname, String path)
        {
            TextureBuilder builder = new TextureBuilder()
                                         .setName("Test Empty Texture")
                                         .setWidth(128)
                                         .setHeight(128);

            ObjectRef<Texture> texRef = builder.build(getDomain());
            return new Result(texRef);
        }
    },
    new ResourceManager.ReloadProtocolHandler() {
        @Override
        public void handle(ResourceManager resourceManager, String url, String protocol,
            String hostname, String path, Resource resource)
        {
            if (resource instanceof Texture)
            {
                TextureBuilder builder = new TextureBuilder()
                                             .setName("Reloaded Empty Texture")
                                             .setWidth(128)
                                             .setHeight(128);
                builder.recreate((Texture) resource);
            }
        }
    });

Kotlin

domain.resourceManager.registerProtocolHandler("MyReloadProtocol",
    { resourceManager, url, protocol, hostname, path ->
        val builder = TextureBuilder()
            .setName("Test Empty Texture")
            .setWidth(128)
            .setHeight(128)
        val texRef = builder.build(getDomain())
        ProtocolHandler.Result(texRef)
    },
    { resourceManager, url, protocol, hostname, path, resource ->
        if (resource is Texture) {
            val builder = TextureBuilder()
                .setName("Reloaded Empty Texture")
                .setWidth(128)
                .setHeight(128)
            builder.recreate(resource)
        }
    })

创建数据源¶

数据源使您能够从您的 Kanzi 应用程序访问第三方数据。

要创建数据源：

创建 DataSource 类。

Java

class MyDataSource extends DataSource
{
    @Metadata
    public static final Metaclass metaclass = new Metaclass("MyPlugin.MyDataSource");

    public static ObjectRef<MyDataSource> create(Domain domain, String name)
    {
        return DataSource.createDerived(domain, name, MyDataSource.metaclass);
    }

    private MyDataSource(Domain domain, long nativeHandle, Metaclass metaclass)
    {
        super(domain, nativeHandle, metaclass);
    }

    @Override
    protected void initialize()
    {
        super.initialize();

        createData();
    }

    private void createData() {}
}

Kotlin

class MyKotlinDataSource private constructor(
    domain: Domain,
    nativeHandle: Long,
    metaclass: Metaclass
) :
    DataSource(domain, nativeHandle, metaclass) {
    override fun initialize() {
        super.initialize()
        createData()
    }

    private fun createData() {}

    companion object {
        @Metadata
        val metaclass = Metaclass("MyPlugin.MyDataSource")

        @JvmStatic
        fun create(domain: Domain?, name: String?): ObjectRef<MyKotlinDataSource> {
            return createDerived(domain, name, metaclass)
        }
    }
}

添加所需的成员、访问器和初始化数据的方法。

Java

private ObjectRef<DataObject> mDataRef;
private DataObject mData;
private DataObjectBool mMyBool;

public DataObject getData()
{
    return mData;
}

private void createData()
{
    Domain domain = getDomain();
    mDataRef = DataObject.create(domain, "root");
    mData = mDataRef.get();

    // Add the remaining structure of the DataSource.
    try (ObjectRef<DataObjectBool> objRef = DataObjectBool.create(domain, "MyBoolean", true))
    {
        mMyBool = objRef.get();
        mData.addChild(mMyBool);
    }
}

Kotlin

private var mDataRef: ObjectRef<DataObject>? = null
private var mData: DataObject? = null
private var mMyBool: DataObjectBool? = null
override fun getData(): DataObject {
    return mData!!
}

private fun createData() {
    mDataRef = DataObject.create(domain, "root")
    mData = mDataRef?.get()
    DataObjectBool.create(domain, "MyBoolean", true).use { objRef ->
        mMyBool = objRef.get()
        mData?.addChild(mMyBool)
    }
}

要详细了解 Kanzi 中的数据源，请参阅数据源 (Data Sources)。

创建 Kanzi Engine Java 插件¶

您可以将 Java 或 Kotlin 类型分离到 Kanzi Engine Java 插件中。这使您可以从 Kanzi Studio 使用这些类型，并在多个应用程序之间重用它们。

要在 Java 或 Kotlin 中创建 Kanzi Engine 插件：

为插件创建一个类。

Java

class TestPlugin extends Plugin
{
    @Override
    public String getName()
    {
        return "testplugin";
    }
}

Kotlin

class TestPlugin : Plugin() {
    override fun getName(): String {
        return "testplugin"
    }
}

小技巧

从 getName() 返回的字符串必须与 Jar 文件的名称匹配。

使用 Kanzi 注册您的自定义类型。

Java

@Override
public void registerClasses(MetaclassRegistry metaclassRegistry)
{
    metaclassRegistry.registerClass(MyDataSource.class);
}

Kotlin

override fun registerClasses(metaclassRegistry: MetaclassRegistry) {
    metaclassRegistry.registerClass(MyKotlinDataSource::class.java)
}

小技巧

您可以使用 overrideClass 而不是 registerClass() 来覆盖现有类型。

将插件加载到您的 Android 应用程序中。

请参阅使用 Kanzi Engine Java 插件。

要了解有关使用 Java 或 Kotlin 创建 Kanzi Engine 插件的更多信息，请参阅使用模板创建一个 Java Kanzi Engine 插件。和手动创建一个 Java Kanzi Engine 插件。

特定平台代码¶

Java 插件可以在多个平台上运行，例如 Kanzi Android framework (droidfw) 和在 Kanzi Studio Preview。确保将插件仅在兼容的平台上运行平台特定的代码。例如，仅当插件在 Android 环境中运行时调用 Android API。

要检测环境，请使用 Platform 方法：

Java

if (Platform.isAndroid())
{
    // Initialize the code path for when the plugin runs on Android.
    Object context = domain.getPlatformContext();
}
else
{
    // Initialize the code path for when the plugin runs in the Kanzi Studio Preview.
}

Kotlin

if (Platform.isAndroid()) {
    // Initialize the code path for when the plugin runs on Android.
    val context = domain.platformContext
} else {
    // Initialize the code path for when the plugin runs in the Kanzi Studio Preview.
}

异常¶

Kanzi 使用已检查异常来指示可恢复的错误。例如，如果在调用 Node.acquireResource 方法时未找到资源，Kanzi 将抛出 ObjectNotFoundException 异常。

由本机代码抛出的 Kanzi Engine 异常被打包为 NativeException 的实例。Java 代码不需要处理这些异常。相反，应允许异常向上传播，以便 Kanzi 将其重新转换为 Kanzi Engine 可以处理的本机异常。

使用自定义 JNI 扩展¶

您可以实现自定义 JNI 代码来访问 Kanzi Engine C++ API 中尚未被 Kanzi Java API 覆盖的部分。为了简化与 JNI 代码的集成，所有相关的 Kanzi Java API 类都带有方法 long getNative()，该方法返回指向其 C++ 对应部分的指针。有关指针的确切 C++ 类型，请参阅相应 Kanzi Java API 类的 API 参考。