From: Jean Privat Date: Wed, 3 Aug 2016 16:38:46 +0000 (-0400) Subject: Merge: app.nit: improve apps life-cycle X-Git-Url: http://nitlanguage.org?hp=0ec26dfafd56c73adfd08a2cdb829f55d72c8018 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 --- diff --git a/contrib/crazy_moles/src/moles.nit b/contrib/crazy_moles/src/moles.nit index 505ce49..514b71f 100644 --- a/contrib/crazy_moles/src/moles.nit +++ b/contrib/crazy_moles/src/moles.nit @@ -308,16 +308,11 @@ redef class App # Elapsed time since program launch var clock = new Clock - redef fun on_start - do - super - assets.load_all self - end - redef fun on_create do super + assets.load_all self maximum_fps = 50.0 end diff --git a/contrib/crazy_moles/src/moles_android.nit b/contrib/crazy_moles/src/moles_android.nit index edf1251..c2c7f58 100644 --- a/contrib/crazy_moles/src/moles_android.nit +++ b/contrib/crazy_moles/src/moles_android.nit @@ -29,7 +29,7 @@ redef class Game end redef class App - redef fun on_start + redef fun on_create do # We use as a reference the Moto X var tw = 720 diff --git a/lib/android/game.nit b/lib/android/game.nit index 2d17054..d04e0f9 100644 --- a/lib/android/game.nit +++ b/lib/android/game.nit @@ -27,7 +27,6 @@ redef class App super on_create on_restore_state - on_start end redef fun term_window @@ -66,6 +65,4 @@ redef class App paused = false super end - - redef fun destroy do on_destroy end diff --git a/lib/android/nit_activity.nit b/lib/android/nit_activity.nit index 1668147..1bdf597 100644 --- a/lib/android/nit_activity.nit +++ b/lib/android/nit_activity.nit @@ -207,6 +207,14 @@ redef class App end end +redef class AppComponent + # The application is starting or restarting, it is visible to the user + fun on_start do end + + # The application is being destroyed + fun on_destroy do end +end + # An Android activity # # You must implement the callbacks (prefixed with `on_`) to follow the @@ -232,7 +240,7 @@ class Activity # Notification from Android, the activity has been restarted # # Followed by `on_start`. - fun on_restart do end + fun on_restart do app.on_restart # Notification from Android, the activity has been started # diff --git a/lib/android/ui/ui.nit b/lib/android/ui/ui.nit index 7e14b19..66791c7 100644 --- a/lib/android/ui/ui.nit +++ b/lib/android/ui/ui.nit @@ -79,6 +79,16 @@ redef class App native_activity.show_fragment(root_layout_id, window.native) super end + + redef fun on_start do window.on_start + + redef fun on_destroy do window.on_destroy +end + +redef class CompositeControl + redef fun on_start do for i in items do i.on_start + + redef fun on_destroy do for i in items do i.on_destroy end redef class Activity diff --git a/lib/app/README.md b/lib/app/README.md index 680c6b9..4baecf4 100644 --- a/lib/app/README.md +++ b/lib/app/README.md @@ -18,25 +18,25 @@ The _app.nit_ application life-cycle is compatible with all target platforms. 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`. diff --git a/lib/app/app_base.nit b/lib/app/app_base.nit index 4e9592c..b2c26f5 100644 --- a/lib/app/app_base.nit +++ b/lib/app/app_base.nit @@ -51,32 +51,57 @@ abstract class AppComponent # 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 diff --git a/lib/app/doc/Makefile b/lib/app/doc/Makefile new file mode 100644 index 0000000..108bb91 --- /dev/null +++ b/lib/app/doc/Makefile @@ -0,0 +1,6 @@ +all: + rubber --pdf app-nit-lifecycle.tex + convert -density 130 app-nit-lifecycle.pdf -quality 90 app-nit-lifecycle.png + +clean: + rm -f *.log *.aux *.pdf diff --git a/lib/app/doc/app-nit-lifecycle.png b/lib/app/doc/app-nit-lifecycle.png new file mode 100644 index 0000000..b241c14 Binary files /dev/null and b/lib/app/doc/app-nit-lifecycle.png differ diff --git a/lib/app/doc/app-nit-lifecycle.tex b/lib/app/doc/app-nit-lifecycle.tex new file mode 100644 index 0000000..c0f2f48 --- /dev/null +++ b/lib/app/doc/app-nit-lifecycle.tex @@ -0,0 +1,19 @@ +\documentclass[tikz]{standalone} + +\usetikzlibrary{automata,positioning} + +\begin{document} +\begin{tikzpicture}[->,shorten >= 1pt,node distance=3cm,auto] + \node[state] (off) {off}; + \node[state] (inact) [right=of off,xshift=-0.5cm] {inactive}; + \node[state] (act) [below=of inact,yshift=2cm] {active}; + \node[state] (back) [right=of inact] {stopped}; + \path[->] + (off) edge [below] node {on\_create} (inact) + (inact) edge [left] node {on\_resume} (act) + edge [below] node {on\_stop} (back) + (back) edge [above] node {on\_restart} (inact) + edge [bend right=20] node {} (off) + (act) edge [right] node {on\_pause} (inact); +\end{tikzpicture} +\end{document} diff --git a/lib/app/ui.nit b/lib/app/ui.nit index 5f66ab4..1fdf801 100644 --- a/lib/app/ui.nit +++ b/lib/app/ui.nit @@ -56,16 +56,12 @@ redef class App redef fun on_create do window.on_create - redef fun on_start do window.on_start - redef fun on_resume do window.on_resume redef fun on_pause do window.on_pause redef fun on_stop do window.on_stop - redef fun on_destroy do window.on_destroy - redef fun on_restore_state do window.on_restore_state redef fun on_save_state do window.on_save_state @@ -165,16 +161,12 @@ class CompositeControl redef fun on_create do for i in items do i.on_create - redef fun on_start do for i in items do i.on_start - redef fun on_resume do for i in items do i.on_resume redef fun on_pause do for i in items do i.on_pause redef fun on_stop do for i in items do i.on_stop - redef fun on_destroy do for i in items do i.on_destroy - redef fun on_restore_state do for i in items do i.on_restore_state redef fun on_save_state do for i in items do i.on_save_state diff --git a/lib/ios/app.nit b/lib/ios/app.nit index b0ffb30..3070868 100644 --- a/lib/ios/app.nit +++ b/lib/ios/app.nit @@ -178,7 +178,7 @@ redef class App # inactive state. # # Redef to undo changes made on entering the background. - fun will_enter_foreground do on_start + fun will_enter_foreground do on_restart # The application just became active # @@ -196,7 +196,6 @@ redef class App on_save_state on_pause on_stop - on_destroy end end diff --git a/lib/linux/linux.nit b/lib/linux/linux.nit index 6b89eb8..e958e2d 100644 --- a/lib/linux/linux.nit +++ b/lib/linux/linux.nit @@ -32,7 +32,6 @@ redef class App on_create on_restore_state - on_start on_resume end @@ -43,7 +42,6 @@ redef class App on_pause on_save_state on_stop - on_destroy end end diff --git a/lib/linux/ui.nit b/lib/linux/ui.nit index 2c0eec1..8a6cc81 100644 --- a/lib/linux/ui.nit +++ b/lib/linux/ui.nit @@ -64,7 +64,6 @@ redef class App do app.on_create app.on_restore_state - app.on_start app.on_resume gtk_main @@ -72,7 +71,6 @@ redef class App app.on_pause app.on_stop app.on_save_state - app.on_destroy end # Spacing between GTK controls, default at 2