Working with Kanzi Android framework (droidfw) projects

Creating an Android application in Kanzi Studio

In the Kanzi Studio New Project window:

1. Set Template to the 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.

2. (Optional) Set Android Package Name to the name of the Android package for the project.

   

3. Click Create.

   Kanzi Studio creates a project in the project directory that you set in the New Project 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.

Adding the Kanzi Android framework (droidfw) to an existing Android application

This procedure assumes that your Android application project uses the default directory structure.

To add the Kanzi Android framework (droidfw) to an existing Android application:

1. Copy the contents of <ProjectName>/Application/bin directory of your Kanzi Studio project to the app/src/main/assets directory of your Android Studio project.

   This way you import your kzb files into an Android package.

2. Introduce cmake to your project. This way you can link native Kanzi Engine plugins to your application.

   1. Add to the app/src/main/cpp/CMakeLists.txt file:

      cmake_minimum_required(VERSION 3.5.1)
      project(<ProjectName>)
      
      if(NOT KANZI_ENGINE_BUILD)
          find_package(Kanzi REQUIRED CONFIG CMAKE_FIND_ROOT_PATH_BOTH
              HINTS "$ENV{KANZI_HOME}/Engine/lib/cmake")
      endif()
      
      include(kanzi-common)
      
      add_executable(<ProjectName>
                            # This file is only needed because cmake does not allow an executable without any sources.
                            <ProjectName>.cpp)
      
      target_link_libraries(<ProjectName> -Wl,--whole-archive Kanzi::kzdroidfw -Wl,--no-whole-archive)
      
      target_link_libraries(<ProjectName> Kanzi::kzui Kanzi::kzcoreui Kanzi::kzjava Kanzi::kzinterop)
      
      target_link_font_engine_backends(<ProjectName>)
      
      set_target_properties(<ProjectName> PROPERTIES VS_DEBUGGER_WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}/bin")
      set_target_properties(<ProjectName> PROPERTIES VS_DEBUGGER_ENVIRONMENT "${KANZI_VS_DEBUGGER_ENVIRONMENT}")
      
      install_kanzi_libs_to_output_directory()
      install_kzbs_to_output_directory(${CMAKE_SOURCE_DIR}/bin)
      install_target_to_output_directory(<ProjectName>)
      

   2. Add to the app/src/main/cpp directory an empty <ProjectName>.cpp file.

3. Copy the getkanzi.gradle file from the <KanziWorkspace>/Templates/Android_application_template/Application/configs/platforms/android_gradle directory to your Android project root directory.

   Gradle uses the getkanzi.gradle file to find Kanzi Engine and Kanzi Gradle plugins.

4. In the build.gradle file in the Android project root directory, get the Kanzi Gradle plugins and add Kanzi as a dependency:

   buildscript {
       apply from: 'getkanzi.gradle'
   
       repositories {
           google()
           mavenCentral()
           flatDir { dirs getKanziPlugins().toString() }
       }
   
       dependencies {
             classpath "com.android.tools.build:gradle:7.4.2"
             classpath "com.rightware.gradle:kanzi:0.8.1"
       }
   

5. In the app/build.gradle file of your Android Studio project, add the Kanzi Gradle plugin, and import the Kanzi Android framework (droidfw) and its dependencies:

   apply plugin: 'com.rightware.gradle.kanzi'
   ...
   
   android {
       ...
   
       defaultConfig {
         ...
   
           externalNativeBuild {
               cmake {
                   arguments "-DKANZI_LINK_FREETYPE=ON"
                   arguments "-DKANZI_LINK_ITYPE=OFF"
               }
           }
       }
       ...
   
       externalNativeBuild {
           cmake {
               path file('src/main/cpp/CMakeLists.txt')
           }
       }
   }
   ...
   
   kanzi {
       appFramework 'kanziruntime-droidfw'
   }
   
   dependencies {
       ...
       implementation 'com.rightware.kanzi:kzjava@aar'
   }
   

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

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

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.