Developing Kanzi applications for Android

To create Kanzi applications for Android you can use Android Studio, the Clang toolchain, and the Gradle build system.

Requirements

Before you can deploy Kanzi applications to Android, set up your build environment. See Deploying Kanzi applications to Android.

To build and deploy Kanzi applications to Android devices using the Kanzi Android platform package, you need:

• Android Studio 4.1.0 and NDK 21.3.6528147
  You can download and install Android Studio at https://developer.android.com/studio/archive.
• Android Gradle plugin 4.1.3 and Gradle 6.7.1 or lower
• Java Development Environment Kit 1.8 or newer (64-bit version)
  Bundled with the Android Studio installation.
• CMake 3.5.1 or newer
• USB device drivers for your Android device
  See Installing Android USB driver for your Android device.

Kanzi supports Android API level 21 (Android version 5.0) and newer.

This diagram shows the process that Kanzi uses to build an Android package.

Android lifecycle events in a Kanzi application

The Android lifecycle events set how your Kanzi application behaves when the activity state changes. Each event maps to an Android activity callback method. A Kanzi application uses these lifecycle events:

• Lifecycle.Event.ON_CREATE

  // Load the native library that provides Kanzi functionality,
  // initialize the context, and assign the KanziView for rendering.
  // This function calls the KanziNativeLibrary.createApplication() function,
  // which loads the Kanzi project.
  KanziView.createNativeApplication();

• Lifecycle.Event.ON_DESTROY

  // Halt and destroy the Kanzi application.
  // This function calls the KanziNativeLibrary.haltApplication() and
  // KanziNativeLibrary.destroyApplication() functions.
  KanziView.destroyNativeApplication();

• SurfaceHolder.Callback.surfaceCreated

  // When the application surface is created, run the Kanzi application.
  KanziNativeLibrary.runApplication(holder.getSurface());

• SurfaceHolder.Callback.surfaceDestroyed

  // When the Kanzi application surface is destroyed, pause rendering.
  KanziNativeLibrary.haltApplication();

• SurfaceHolder.Callback.surfaceChanged

  // When the format or size of the Kanzi application surface changes,
  // resize the application surface.
  // @param width: The new width of the surface.
  // @param height: The new height of the surface.
  KanziNativeLibrary.resizeEvent(width, height);

Kanzi does not use the LifeCycle.Event.ON_PAUSE and Lifecycle.Event.ON_RESUME events because they do not tell whether the application surface is ready for rendering. To pause and resume rendering, KanziView uses the SurfaceHolder.CallbacksurfaceCreated() and surfaceDestroyed() functions.

See https://developer.android.com/reference/androidx/lifecycle/Lifecycle.Event.html and https://developer.android.com/reference/android/view/SurfaceHolder.Callback.

This diagram shows the initialization sequence of a Kanzi application on the Android platform.

Adding a KanziView to an Android Studio project

To run your Kanzi application in your Android application, you can add a KanziView to an existing Android Studio project.

To add a KanziView to an Android Studio project:

1. In Kanzi Studio open the project which you want to add as a Kanzi View to an Android Studio project, and select File > Export > Export KZB.
   
2. Copy the <KanziWorkspace>/Projects/<ProjectName>/Application/bin directory to your Android Studio project root directory. This way you include the kzb files in the Android package.
   For example, for an Android Studio project called MyProject, copy the Application/bin directory to the MyProject directory.
3. In Android Studio open the project to which you want to add a KanziView.
4. In Android Studio in the app/src/main directory create a directory called cpp and add to that directory the CMake build file and source code for your Kanzi project:
   • From the <KanziWorkspace>/Projects/<ProjectName>/Application directory of your Kanzi project copy the CMakeLists.txt file to the cpp directory.
   • From the <KanziWorkspace>/Projects/<ProjectName>/Application/src directory of your Kanzi project copy the <project_name>.cpp file to the cpp directory.
5. From <KanziWorkspace>/Templates/Basic_application/Application/configs/platforms/android_gradle copy the getkanzi.gradle file to your Android project directory.
   Gradle uses the getkanzi.gradle script to find Kanzi Engine and Kanzi Gradle plugins.
6. In Android Studio add Kanzi to your project:
   1. In the app/build.gradle file add Kanzi to your Android project:

      apply plugin: 'com.rightware.gradle.kanzi'

   2. Import to the Java activity the Configuration and KanziView classes.
      For example, in app/src/main/java/com/rightware/<projectname>/MainActivity.java add:

      import android.content.res.Configuration;
      import com.rightware.kanzi.KanziView;

   3. In the MainActivity.java file add the Kanzi View to the MainActivity class:

      public class MainActivity extends AppCompatActivity {
      
          private KanziView mView = null;
      
          @Override
          protected void onCreate(Bundle savedInstanceState) {
              
              ...
      
              mView = findViewById(R.id.kanzicontent);
              mView.registerLifecycle(getLifecycle());
          }
          ...
      
          @Override
          public void onConfigurationChanged(Configuration newConfig)
          {
              super.onConfigurationChanged(newConfig);
      
              mView.setOrientation(newConfig.orientation);
          }
      }

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

      buildscript {
          apply from: 'getkanzi.gradle'
      
          repositories {
              google()
              jcenter()
      
              flatDir { dirs getKanziPlugins().toString() }
          }
          dependencies {
              classpath 'com.android.tools.build:gradle:4.1.0'
              classpath 'com.rightware.gradle:kanzi:0.6.1'
          }
      ...

   5. Add to your Android application content the KanziView and set its layout.
      For example, in app/src/main/res/layout/content_main.xml, add:

          <com.rightware.kanzi.KanziView
                  android:id="@+id/kanzicontent"
                  android:layout_width="match_parent"
                  android:layout_height="wrap_content"
                  android:layout_marginTop="24dp"
                  app:layout_constraintBottom_toBottomOf="parent"
                  app:layout_constraintEnd_toEndOf="parent"
                  app:layout_constraintStart_toStartOf="parent" />

   6. In the app/build.gradle file set:
      • Asset directory of your Android project to the directory which contains the kzb files
      • Path to the CMake build file

      apply plugin: 'com.android.application'
      apply plugin: 'com.rightware.gradle.kanzi'
      
      android {
      
      ...
      
              sourceSets {
                  main {
                      assets.srcDirs = [new File(rootDir, "bin")]
                  }
              }
          }
      
      ...
      
          externalNativeBuild {
              cmake {
                  path file("$projectDir/src/main/cpp/CMakeLists.txt")
              }
          }
      }

7. In Android Studio in the main menu select Build > Make Project.
   Android Studio builds the application package.
   

See also

Deploying Kanzi applications to Android

Android API reference

Open topic with navigation