Java と Kotlin を使用して¶

Kanzi Java API は、Kanzi クラスのプラットフォームに依存しないJavaプロキシを実装し、JavaおよびKotlinで Kanzi 機能への豊富なアクセスを提供します。これにより、Android APIと緊密に統合されたアプリケーションを作成することができます。

Androidでは、Kanzi Java API をAndroid UIスレッドから直接使用でき、ディスパッチャーメカニズムは必要ありません。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コードでは、セッターおよびゲッター関数において、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 メソッドが付属しています。

create メソッドのオブジェクトタイプ、KanziObject から派生したクラスは、新しいオブジェクトへの所有参照である 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 リソースマネージャーが処理します。

デフォルトで、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)
}

ヒント

既存のタイプを上書きするには、registerClass() の代わりに overrideClass を使用できます。

プラグインを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拡張の使用¶

You can implement custom JNI code to access areas of Kanzi Engine C++ API not yet covered by Kanzi Java API. To ease integration with JNI code, all relevant Kanzi Java API classes come with method long getNative(), which returns a pointer to their C++ counterpart. For the exact C++ type of the pointer, see the API reference for respective Kanzi Java API class.

Java と Kotlin を使用して¶

要件¶

プロパティの使用¶

列挙型の使用¶

Kanzi Java API 列挙型を使用する¶

カスタム列挙型の使用¶

メッセージの使用¶

インスタンスの作成¶

インスタンスのライフタイム管理¶

複数のオウニング参照¶

カスタムタイプの作成¶

カスタムリソースローディングの実装¶

データソースの作成¶

バインディングの作成¶

Kanzi Engine Java プラグインの作成¶

プラットフォーム固有のコード¶

例外¶

カスタムJNI拡張の使用¶

関連項目¶