Merge: app.nit: improve apps life-cycle

Modify the _app.nit_ life-cycle callbacks to add `on_restart`, and to remove `on_start` and `on_destroy`. `on_restart` is called when the app goes comes back from a `on_stop`. `on_start` duplicated other callbacks (`on_create` and the new `on_restart`), plus it didn't have a direct equivalent  in iOS. `on_destroy` also didn't have an iOS equivalent. These changes simplify the life-cycle and use only callbacks existing on both platforms.

This PR also improves the documentation of the _app.nit_ life-cycle with a nice little graph and references to the platform specific triggers.

Pull-Request: #2229
Reviewed-by: Ait younes Mehdi Adel <overpex@gmail.com>

diff --combined lib/app/README.md
index 680c6b9,8847e5d..4baecf4
--- 1/lib/app/README.md
--- 2/lib/app/README.md
+++ b/lib/app/README.md
@@@ -18,25 -18,25 +18,25 @@@ The _app.nit_ application life-cycle i
  It relies on the following sequence of events, represented here by their callback method name:
  
  1. `on_create`: The application is being created.
-    You should build the UI at this time.
+    You should build the UI at this time and launch services.
  
- 2. `on_start`: The app is starting or restarting, background activities may
+ 2. `on_resume`: The app enters the active state, it is in the foreground and interactive.
  
- 3. `on_resume`: The app enters the active state, it is in the foreground.
- 
- 4. `on_pause`: The app leaves the active state and the foreground.
+ 3. `on_pause`: The app becomes inactive and it leaves the foreground.
     It may still be visible in the background.
-    It may then go back to `on_resume` or `on_stop`.
  
- 5. `on_stop`: The app is completely hidden.
-    It may then be destroyed (`on_destroy`) or go back to `on_start`.
+ 4. `on_stop`: The app is completely hidden.
+    It may then be destroyed (without warning) or go back to the active state with `on_restart`.
+ 
+ 5. `on_restart`: The app goes back to the inactive state.
+    You can revert what was done by `on_stop`.
  
- 6. `on_destroy`: The app is being destroyed.
+ ![_app.nit_ life-cycle](doc/app-nit-lifecycle.png)
  
  Life-cycle events related to saving and restoring the application state are provided by two special callback methods:
  
  * `on_save_state`: The app may be destroyed soon, save its state for a future `on_restore_state`.
-   More on how it can be done in the `app::data_store` section.
+   There is more on how it can be done in the `app::data_store` section.
  
  * `on_restore_state`: The app is launching, restore its state from a previous `on_save_state`.
  
@@@ -150,17 -150,6 +150,17 @@@ The _app.nit_ framework defines three a
    The special function `git_revision` will use the prefix of the hash of the latest git commit.
    By default, the version is 0.1.
  
 +* `app_files` tells the compiler where to find platform specific resource files associated to a module.
 +  By default, only the root of the project is searched for the folders `android` and `ios`.
 +  The `android` folder is used as base for the generated Android project,
 +  it can be used to specify the resource files, libs and even Java source files.
 +  The `ios` folder is searched for icons only.
 +
 +  Each argument of `app_files` is a relative path to a folder containing extra `android` or `ios` folders.
 +  If there is no arguments, the parent folder of the annotated module is used.
 +  In case of name conflicts in the resource files, the files from the project root have the lowest priority,
 +  those associated to modules lower in the importation hierarchy have higher priority.
 +
  ## Usage Example
  
  ~~~

diff --combined lib/app/app_base.nit
index 4e9592c,434990c..b2c26f5
--- 1/lib/app/app_base.nit
--- 2/lib/app/app_base.nit
+++ b/lib/app/app_base.nit
@@@ -19,7 -19,6 +19,7 @@@ module app_base i
        new_annotation app_name
        new_annotation app_namespace
        new_annotation app_version
 +      new_annotation app_files
  end
  
  # App subclasses are cross-platform applications
@@@ -51,32 -50,57 +51,57 @@@ abstract class AppComponen
        # The application is being created
        #
        # You should build the UI at this time.
+       #
+       # Triggers are platform specific:
+       # * Android: `Activity.onCreate`
+       # * iOS: `UIApplicationDelegate application:didFinishLaunchingWithOptions`
        fun on_create do end
  
-       # The application is starting or restarting, it is visible to the user
-       fun on_start do end
- 
        # The application enters the active state, it is in the foreground and interactive
+       #
+       # Triggers are platform specific:
+       # * Android: `Activity.onResume`
+       # * iOS: `UIApplicationDelegate applicationDidBecomeActive`
        fun on_resume do end
  
        # The application leaves the active state but is still partially visible
        #
-       # It may still be visible in the background.
        # It may then go back to `on_resume` or `on_stop`.
+       #
+       # Triggers are platform specific:
+       # * Android: `Activity.onPause`
+       # * iOS: `UIApplicationDelegate applicationWillResignActive`
        fun on_pause do end
  
        # The application is completely hidden from the user
        #
-       # It may then be destroyed (`on_destroy`) or go back to `on_start`.
+       # It may then be destroyed or go back to a paused state with `on_restart`.
+       #
+       # Triggers are platform specific:
+       # * Android: `Activity.onStop`
+       # * iOS: `UIApplicationDelegate applicationDidEnterBackground`
        fun on_stop do end
  
-       # The application is being destroyed
-       fun on_destroy do end
+       # The application returns to a visible state from a previous `on_stop`
+       #
+       # Triggers are platform specific:
+       # * Android: `Activity.onRestart`
+       # * iOS: `UIApplicationDelegate applicationWillEnterForeground`
+       fun on_restart do end
  
        # The application may be destroyed soon, save its state for a future `on_restore_state`
+       #
+       # Triggers are platform specific:
+       # * Android: `Activity.onSaveInstanceState`
+       # * iOS: `UIApplicationDelegate applicationDidEnterBackground`
        fun on_save_state do end
  
        # The application is launching, restore its state from a previous `on_save_state`
+       #
+       # Triggers are platform specific:
+       # * Android: `Activity.onCreate`, _not_ `Activity.onRestoreInstanceState`
+       #   as it is trigged only if there is a previous Android specific save state.
+       # * iOS: `UIApplicationDelegate applicationDidEnterBackground`
        fun on_restore_state do end
  end