SurfaceView Maintenance (#1650)

* surfaceView Maintenance

* fixed docs about destruction policy notes

* Javadocs improvements

* Javadocs improvements 2

* Converted the enum class to a regular class

* Constructors and constructors docs

* Constructors docs

* Fixed GameState constructor

jme3-android/build.gradle

@@ -3,6 +3,7 @@ apply plugin: 'java'
 dependencies {
     //added annotations used by JmeSurfaceView.
     compileOnly 'androidx.annotation:annotation:1.2.0'
+    compileOnly 'androidx.lifecycle:lifecycle-common:2.1.0'
     api project(':jme3-core')
     api project(':jme3-plugins')
     compileOnly 'android:android'

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/OnExceptionThrown.java

@@ -32,8 +32,10 @@
 package com.jme3.app.jmeSurfaceView;
 
 /**
- * Embedded interface designed to listen to exceptions and fire when an exception is thrown.
+ * An interface designed to listen for exceptions and fire an event when an exception is thrown.
  * @see JmeSurfaceView#setOnExceptionThrown(OnExceptionThrown)
+ *
+ * @author pavl_g.
  */
 public interface OnExceptionThrown {
     /**

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/OnLayoutDrawn.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2009-2021 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.app.jmeSurfaceView;
+
+import android.view.View;
+import com.jme3.app.LegacyApplication;
+
+/**
+ * An interface used for dispatching an event when the layout holding the {@link android.opengl.GLSurfaceView} is drawn,
+ * the event is dispatched on the user activity context thread.
+ *
+ * @author pavl_g.
+ */
+public interface OnLayoutDrawn {
+    /**
+     * Dispatched when the layout is drawn on the screen.
+     * @param legacyApplication the application instance.
+     * @param layout the current layout.
+     */
+    void onLayoutDrawn(LegacyApplication legacyApplication, View layout);
+}

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/OnRendererCompleted.java

@@ -35,14 +35,16 @@ import com.jme3.app.LegacyApplication;
 import com.jme3.system.AppSettings;
 
 /**
- * Embedded interface class(abstract) to listen for the moment when when the GL thread holding the #{@link JmeSurfaceView}
- * joins the UI thread , after asynchronous rendering.
+ * An interface used for invoking an event when the user delay finishes, on the first update of the game.
  * @see JmeSurfaceView#setOnRendererCompleted(OnRendererCompleted)
+ *
+ * @author pavl_g.
  */
 public interface OnRendererCompleted {
     /**
-     * Listens for the the moment when when the GL thread holding the #{@link JmeSurfaceView}
-     * joins the UI thread , after asynchronous rendering.
+     * Invoked when the user delay finishes, on the first update of the game, the event is dispatched on the
+     * enclosing Activity context thread.
+     * @see JmeSurfaceView#update()
      * @param application the current jme game instance.
      * @param appSettings the current window settings of the running jme game.
      */

jme3-android/src/main/java/com/jme3/app/jmeSurfaceView/OnRendererStarted.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2009-2021 jMonkeyEngine
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * * Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ *
+ * * Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the distribution.
+ *
+ * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
+ *   may be used to endorse or promote products derived from this software
+ *   without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.jme3.app.jmeSurfaceView;
+
+import android.view.View;
+import com.jme3.app.LegacyApplication;
+import com.jme3.system.AppSettings;
+
+/**
+ * An interface used for invoking an event when the application is started explicitly from {@link JmeSurfaceView#startRenderer(int)}.
+ * NB : This listener must be utilized before using {@link JmeSurfaceView#startRenderer(int)}, ie : it would be ignored if you try to use {@link JmeSurfaceView#setOnRendererStarted(OnRendererStarted)} after
+ * {@link JmeSurfaceView#startRenderer(int)}.
+ * @see JmeSurfaceView#setOnRendererStarted(OnRendererStarted)
+ *
+ * @author pavl_g.
+ */
+public interface OnRendererStarted {
+    /**
+     * Invoked when the game application is started by the {@link LegacyApplication#start()}, the event is dispatched on the
+     * holder Activity context thread.
+     * @see JmeSurfaceView#startRenderer(int)
+     * @param application the game instance.
+     * @param layout the enclosing layout.
+     */
+    void onRenderStart(LegacyApplication application, View layout);
+}