Observing state changes and handling events in Kanzi Android framework (droidfw)¶

Observing state changes¶

You can implement KanziViewListener to listen for state changes in KanziView. Use this to inject custom initialization and un-initialization logic.

For example:

Use the KanziViewListener.onAttachedToWindow callback to access domain, register Kanzi Engine Java plugins or manually setup the view’s node tree.

Java

view.addListener(new KanziViewListener() {
   ...

   @Override
   public void onAttachedToWindow(View view, Domain domain)
   {
         // Register a plugin.
         domain.registerPlugin(new MyPlugin());

         // Manually setup the node tree.
         // Instantiate a node.
         ObjectRef<TextBlock2D> text = TextBlock2D.create(domain, "text");
         // Set as root of the view.
         ((KanziView) view).setRoot(text.get());
         // Set properties on a node.
         text.get().setProperty(TextBox2D.TextProperty, "Hello Kanzi!");

Kotlin

view.addListener(object : KanziViewListener {
   ...

   override fun onAttachedToWindow(view: View, domain: Domain) {
         // Register a plugin.
         domain.registerPlugin(MyPlugin())

         // Manually setup the node tree.
         // Instantiate a node.
         val text = TextBlock2D.create(domain, "text")
         // Set as root of the view.
         (view as KanziView).root = text.get()
         // Set properties on a node.
         text.get().setProperty(TextBox2D.TextProperty, "Hello Kanzi!")

Use the KanziViewListener.onStartupPrefabLoaded callback to access and modify the node tree instantiated from the startup prefab that you have configured.

Java

view.addListener(new KanziViewListener() {
   ...

   @Override
   public void onStartupPrefabLoaded(View view, Domain domain)
   {
         // Look up a child node starting from the root.
         TextBox2D text = ((KanziView)view).getRoot().lookupNode("#Text");
         // Set properties on a node.
         text.setProperty(TextBox2D.TextProperty, "Hello world!");

Kotlin

view.addListener(object : KanziViewListener {
   ...

   override fun onStartupPrefabLoaded(view: View, domain: Domain) {
         // Look up a child node starting from the root.
         val text = (view as KanziView).root.lookupNode<TextBox2D>("#Text")
         // Set properties on a node.
         text.setProperty(TextBox2D.TextProperty, "Hello world!")

To learn more about Kanzi Engine Java plugins, see Creating Kanzi Engine Java plugins.

Handling input¶

While KanziSurfaceView and KanziTextureView handle input events by default, an arbitrary view using KanziViewAdapter must manually forward any input events that it wants Kanzi to process, through the KanziViewAdapter.handleTouchEvent, KanziViewAdapter.handleKeyEvent, and KanziViewAdapter.handleFocusChange interfaces.

All Kanzi views by default set focusableInTouchMode to True, unless otherwise set programmatically or through layout attributes. This makes them gain and keep focus when clicked on. See Android touch mode.

Handling orientation change¶

When the screen orientation changes, an Android application, by default, destroys and recreates the activity. This allows an application to use an alternate layout for portrait and landscape screens, but it also means that you lose all internal Kanzi states.

You can override this by adding the android:configChanges="orientation" property to the AndroidManifest.xml file. With this option, the activity is no longer destroyed on orientation changes, instead onConfigurationChanged() is called on the activity. Forward this event manually to KanziView.handleOrientationChange. This option avoids recreating the Kanzi controls and therefore all internal state is retained. See Android configuration changes.

Handling the Android lifecycle¶

While KanziSurfaceView and KanziTextureView handle window and surface events by default, an arbitrary view using KanziViewAdapter must manually forward the window and surface events it wants Kanzi to process, through the KanziViewAdapter.handleAttachedToWindow, KanziViewAdapter.handleSurfaceCreated, KanziViewAdapter.handleSurfaceChanged, KanziViewAdapter.handleSurfaceDestroyed, and KanziViewAdapter.handleDetachedFromWindow interfaces.

Handling the user-visibility of views¶

Kanzi Android framework (droidfw) automatically and continuously tracks whether each connected view is visible to the user, and does not render the surface of hidden views.

To check whether a view is visible to the user, Kanzi Android framework (droidfw) considers:

The visibility state of the view
The visibility state of all ancestors of the view
The alpha of the view
The effectively visible portion of the view computed through View.getGlobalVisibleRect()

An arbitrary view using KanziViewAdapter must manually forward visibility events that it wants Kanzi to process through the KanziViewAdapter.handleVisibilityChange interface.