Working with Kanzi Android framework (droidfw) projects¶

Adding Kanzi Android framework (droidfw) to your Android application¶

To add Kanzi Android framework (droidfw) to an Android application that you created using Android Studio templates either:

Integrate Kanzi as a library sub-project. This is the recommended approach to start using Kanzi on Android. See Integrating Kanzi as a library sub-project.
Integrate Kanzi as a pre-built library. Use this approach if the separation meets the requirements of your workflow. For example, if you benefit from not installing Kanzi or required tooling. See Integrating Kanzi as a prebuilt library (AAR).

Integrating Kanzi as a library sub-project¶

Tip

This is the recommended approach to start using Kanzi on Android.

When you integrate Kanzi as a library sub-project, you add Kanzi CMake integration to your application as an Android library sub-project.

To integrate Kanzi as a library sub-project:

From the <KanziWorkspace>/Templates/Android_library directory, copy to the root of your Android project:
- getkanzi.gradle file
- kanzinative directory
In the settings.gradle or settings.gradle.kts file of your project, add:
Groovy
dependencyResolutionManagement { repositories { flatDir { apply from: 'getkanzi.gradle' dirs getKanziAndroidLibrariesPath() } } }
Kotlin-DSL
dependencyResolutionManagement { repositories { flatDir { apply(from ="getkanzi.gradle") dirs(extra.get("getKanziAndroidLibrariesPath")) } } }
This utility helps your project find Kanzi libraries from your local Kanzi installation or platform package.

You can either:
- Keep your project in the Kanzi workspace directory
- Point KANZI_HOME environment variable to your Kanzi workspace
- In your project local.properties, set the kanzi.home property to your Kanzi workspace or platform package
- Include Kanzi libraries from your own location or repository
To include kanzinative as a sub-project, in the settings.gradle or settings.gradle.kts file of your project add:
Groovy
include ':kanzinative'
Kotlin-DSL
include(":kanzinative")

To make your application depend on prebuilt Kanzi Android libraries and kanzinative sub-project, in the app/build.gradle or app/build.gradle.kts file of your project, add:

Groovy

dependencies {
  implementation 'com.rightware.kanzi:kanziruntime-droidfw@aar'
  implementation 'com.rightware.kanzi:kzjava@aar'
  implementation project(':kanzinative')
}

Kotlin-DSL

dependencies {
  implementation("com.rightware.kanzi:kanziruntime-droidfw@aar")
  implementation("com.rightware.kanzi:kzjava@aar")
  implementation(project(":kanzinative"))
}

In the app/build.gradle or app/build.gradle.kts file of your project, ensure that the Java language version is set to 8 (1.8) or higher:

Groovy

android {
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_11
       targetCompatibility JavaVersion.VERSION_1_11
    }
}

Kotlin-DSL

android {
    compileOptions {
       sourceCompatibility = JavaVersion.VERSION_11
       targetCompatibility = JavaVersion.VERSION_11
    }
}

Integrating Kanzi as a prebuilt library (AAR)¶

In this mode, you link the C++ libraries, including the required C++ plugins, into an AAR once, and then reuse it from your application projects.

This means that:

Building your application project does not require access to the Kanzi workspace or platform package, as long as it can reach the prebuilt Kanzi AARs from your package management system or version control.
Building your application project does not perform a C++ build and therefore does not require NDK or CMake. This makes your application build faster.

Use this approach if such separation meets the requirements of your workflow. For example, if you benefit from not installing Kanzi or required tooling, when building your application project.

Instantiating your library project¶

Copy the <KanziWorkspace>/Templates/Android_library directory to the location that you want to use.

Building an AAR from the library¶

To build and install AAR libraries for all build configurations, run:

gradlew installNativeAARs

To build and install an AAR for one build configuration use install<Configuration>NativeAAR task. For example, to build the debug version of AAR, run:

gradlew installDebugNativeAAR

By default, the resulting AAR contains Kanzi C++ libraries for all available architectures. All install tasks support the arch property with which you can specify a comma-separated list of ABIs. For example, to build and install debug AAR library for x86_64 architecture, run:

gradlew installDebugNativeAAR -Parch=x86_64

The default definitions of these tasks install the AAR with kanzinative-<configuration>.aar name to the Kanzi Android libraries directory.

To change the name of the AAR, you can either:

In your project local.properties, set the kanzi.aar.name property.
Set the aarName property when executing the install task.

For example, to build and install AAR libraries with my-kanzi-aar name, run:
```
gradlew installNativeAARa -PaarName=my-kanzi-aar
```

To change where install tasks put AAR libraries, you can either:

In your project local.properties, set the kanzi.aar.destination property.
Set the aarDest property when executing the install task.

For example, to build and install AAR libraries to C:/MyKanziWorkspace, run:
```
gradlew installNativeAARa -PaarDest=C:/MyKanziWorkspace
```

Importing Kanzi into your application project¶

To import Kanzi into your application project:

Make Kanzi prebuilt and native AARs libraries reachable to you Android project with the package management system that you use.

For example, to import Kanzi from the default Kanzi workspace and default install location of native AARs libraries:
1. From the <KanziWorkspace>/Templates/Android_library directory, copy getkanzi.gradle file to the root of your Android project.
2. In the settings.gradle or settings.gradle.kts file of your project, add:
  Groovy
  dependencyResolutionManagement { repositories { flatDir { apply from: 'getkanzi.gradle' dirs getKanziAndroidLibrariesPath() } } }
  Kotlin-DSL
  dependencyResolutionManagement { repositories { flatDir { apply(from ="getkanzi.gradle") dirs(extra.get("getKanziAndroidLibrariesPath")) } } }
This utility helps your project find Kanzi libraries from your local Kanzi installation or platform package.

You can either:
- Keep your project in the Kanzi workspace directory
- Point KANZI_HOME environment variable to your Kanzi workspace
- In your project local.properties, set the kanzi.home property to your Kanzi workspace or platform package
- Include Kanzi libraries from your own location or repository

Import Kanzi prebuilt AARs and native AARs that you built from your library project to the app/build.gradle or app/build.gradle.kts file of your project.

Groovy

dependencies {
  implementation 'com.rightware.kanzi:kanziruntime-droidfw@aar'
  implementation 'com.rightware.kanzi:kzjava@aar'

  debugImplementation 'com.rightware.kanzi:kanzinative-debug@aar'
  releaseImplementation 'com.rightware.kanzi:kanzinative-release@aar'
  "profilingImplementation"('com.rightware.kanzi:kanzinative-profiling@aar')
}

Kotlin-DSL

dependencies {
  implementation("com.rightware.kanzi:kanziruntime-droidfw@aar")
  implementation("com.rightware.kanzi:kzjava@aar")

  debugImplementation("com.rightware.kanzi:kanzinative-debug@aar")
  releaseImplementation("com.rightware.kanzi:kanzinative-release@aar")
  "profilingImplementation("com.rightware.kanzi:kanzinative-profiling@aar")
}

In the app/build.gradle or app/build.gradle.kts file of your project, ensure that the Java language version is set to 8 (1.8) or higher:

Groovy

android {
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_11
       targetCompatibility JavaVersion.VERSION_1_11
    }
}

Kotlin-DSL

android {
    compileOptions {
       sourceCompatibility = JavaVersion.VERSION_11
       targetCompatibility = JavaVersion.VERSION_11
    }
}

Adding Kanzi Studio project assets to your application¶

To add Kanzi Studio assets to your Android application:

Import Kanzi Studio project assets, such as kzb and cfg files, to your Android Studio project, using one of these options:
- In the app/build.gradle or app/build.gradle.kts of your Android Studio project, set the path to the <ProjectName>/Application/bin directory of your Kanzi Studio project:
  Groovy
  android { defaultConfig { sourceSets { main { assets.srcDirs = "<ProjectName>/Application/bin" } } } }
  Kotlin-DSL
  android { defaultConfig { sourceSets.named("main") { assets.srcDirs("<ProjectName>/Application/bin") } } }
- Copy the content of the <ProjectName>/Application/bin directory of your Kanzi Studio project to the app/src/main/assets directory of your Android Studio project.
- In Kanzi Studio, in the Project > Properties set the Binary Export Directory property of your Kanzi Studio project to the app/src/main/assets directory of your Android Studio project.
  
  This way you tell Kanzi Studio where to export your project kzb file.
  
  Note
  
  Kanzi Studio does not export the application.cfg file. Copy the file manually to the app/src/main/assets directory of your Android Studio project.

Disable compression of the assets files that you import, so Kanzi Engine can load them. In the app/build.gradle or app/build.gradle.kts file of your project add:

Groovy

android {
  aaptOptions {
    noCompress "kzb", "cfg", "json"
  }
}

Kotlin-DSL

android {
  androidResources {
    noCompress += listOf("kzb", "cfg", "json")
  }
}

Creating an Android application in Kanzi Studio¶

To create an Android application in Kanzi Studio, in the New tab of the Quick Start window:

Select the project template that you want to use for your Android application:
- Android application template creates a Kanzi Studio project with a Kanzi Android framework-based application.
- Android application with Java plugin template creates a Kanzi Studio project with a Kanzi Android framework-based application that contains a Kanzi Engine Java plugin.
  
  See Creating a Java Kanzi Engine plugin using a template and Using Java and Kotlin.
(Optional) Set Android Package Name to the name of the Android package for the project.
Click Create.

Kanzi Studio creates a project in the project directory that you set in the New tab of the Quick Start window in Location, and an Android application project in the <ProjectName>/Application/configs/platforms/android_gradle directory.

To learn how to build and deploy your application, see Deploying Kanzi applications to Android.

Loading kzb files from a custom location¶

By default, Kanzi reads kzb files from the assets directory of an APK.

To set a different location, call KanziRuntime.setResourceDirectory.

After this call, Kanzi reads kzb files from the specified location across all views of the application.

For example, to load kzb files from the external storage directory:

mRuntimeRef.get().setResourceDirectory(Environment.getExternalStorageDirectory().toPath());

To revert to the default location, call the interface with an empty string.