Native UI code cleanup

mobile-sdk/src/main/java/com/github/itwin/mobilesdk/ITMApplication.kt

@@ -499,8 +499,11 @@ open class ITMApplication(
     /**
      * Function that creates an [ITMNativeUI] object for this [ITMApplication]. Override to return a
      * custom [ITMNativeUI] subclass.
+     *
+     * > __Note:__ If you override this function and do not call super, you must call
+     * [registerStandardComponents][ITMNativeUI.registerStandardComponents] on your newly created
+     * native UI object before returning.
      */
-    @CallSuper
     open fun createNativeUI(context: Context) =
         webView?.let {
             ITMNativeUI(context, it, coMessenger).apply { registerStandardComponents() }

mobile-sdk/src/main/java/com/github/itwin/mobilesdk/ITMNativeUI.kt

@@ -2,18 +2,22 @@
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
+@file:Suppress("unused", "MemberVisibilityCanBePrivate")
+
 package com.github.itwin.mobilesdk
 
 import android.content.Context
 import android.content.res.Configuration
 import android.webkit.WebView
+import androidx.annotation.CallSuper
 import kotlin.math.roundToInt
 
 /**
- * Class for converting between JSON dictionary in [WebView] coordinates and Kotlin representing a rectangle
- * in UI coordinates.
+ * Class for converting between a JSON dictionary in [WebView] coordinates and Kotlin representing a
+ * rectangle in UI coordinates.
  *
- * @param value: The JSON value containing the rectangle. This must include `x`, `y`, `width`, and `height` fields.
+ * @param value: The JSON value containing the rectangle. This must include `x`, `y`, `width`, and
+ * `height` fields.
  * @param webView: The [WebView] that the rectangle is in.
  */
 class ITMRect(value: Map<*, *>, webView: WebView) {
@@ -51,8 +55,6 @@ class ITMRect(value: Map<*, *>, webView: WebView) {
 /**
  * Container class for custom [ITMNativeUIComponents][ITMNativeUIComponent].
  *
- * @property components The list of [ITMNativeUIComponent] objects managed by this [ITMNativeUI].
- *
  * @param context The [Context] into which to display the UI.
  * @param webView The [WebView] making use of the native UI.
  * @param coMessenger The [ITMCoMessenger] used to communicate with [webView].
@@ -61,23 +63,25 @@ open class ITMNativeUI(
     val context: Context,
     val webView: WebView,
     val coMessenger: ITMCoMessenger) {
-    @Suppress("MemberVisibilityCanBePrivate")
+    /**
+     * The list of [ITMNativeUIComponent] objects managed by this [ITMNativeUI].
+     */
     val components: MutableList<ITMNativeUIComponent> = mutableListOf()
 
     /**
      * Register the standard [ITMNativeUIComponent] subclasses that are part of mobile-sdk-android.
      *
      * This is called automatically by [ITMApplication.createNativeUI].
      */
-    fun registerStandardComponents() {
+    @CallSuper
+    open fun registerStandardComponents() {
         components.add(ITMActionSheet(this))
         components.add(ITMAlert(this))
     }
 
     /**
-     * Call to detach the receiver from its [Context].
+     * Detach the receiver from its [Context] and remove all components.
      */
-    @Suppress("unused")
     open fun detach() {
         components.forEach { component ->
             component.detach()

mobile-sdk/src/main/java/com/github/itwin/mobilesdk/ITMNativeUIComponent.kt

@@ -2,6 +2,8 @@
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
+@file:Suppress("MemberVisibilityCanBePrivate")
+
 package com.github.itwin.mobilesdk
 
 import android.content.Context
@@ -11,19 +13,34 @@ import android.webkit.WebView
 /**
  * Parent class for native UI components.
  *
- * __Note__: The [nativeUI] passed into the constructor can come from the [ITMNativeUI] constructor itself.
- * When this happens, it is illegal to down-cast to an [ITMNativeUI] subclass that you might implement.
- *
  * @param nativeUI The [ITMNativeUI] in which the component will display.
  */
-open class ITMNativeUIComponent(@Suppress("MemberVisibilityCanBePrivate") protected val nativeUI: ITMNativeUI) {
+open class ITMNativeUIComponent(protected val nativeUI: ITMNativeUI) {
+    /**
+     * Convenience member set to [nativeUI].[ITMNativeUI.context]
+     */
     protected val context: Context = nativeUI.context
+
+    /**
+     * Convenience member set to [nativeUI].[ITMNativeUI.webView]
+     */
     protected val webView: WebView = nativeUI.webView
+
+    /**
+     * Convenience member set to [nativeUI].[ITMNativeUI.coMessenger]
+     */
     protected val coMessenger: ITMCoMessenger = nativeUI.coMessenger
+
+    /**
+     * The handler for this component's messages from [webView].
+     */
     var handler: ITMMessenger.ITMHandler? = null
 
     /**
      * Detach this UI component from the native UI (stop listening for messages).
+     *
+     * > __Note:__ The standard [ITMNativeUIComponents][ITMNativeUIComponent] built into
+     * mobile-sdk-android cannot be reattached; new ones must be created instead.
      */
     open fun detach() {
         coMessenger.removeHandler(handler)
@@ -33,6 +50,8 @@ open class ITMNativeUIComponent(@Suppress("MemberVisibilityCanBePrivate") protec
     /**
      * Called by [nativeUI] when the device configuration changes in the application.
      *
+     * > __Note:__ The default implementation does nothing.
+     *
      * @param newConfig The new device configuration.
      */
     open fun onConfigurationChanged(newConfig: Configuration) {}