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>
# 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
end
redef class App
- redef fun on_start
+ redef fun on_create
do
# We use as a reference the Moto X
var tw = 720
super
on_create
on_restore_state
- on_start
end
redef fun term_window
paused = false
super
end
-
- redef fun destroy do on_destroy
end
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
# 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
#
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
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.
+
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`.
# 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
--- /dev/null
+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
--- /dev/null
+\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}
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
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
# 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
#
on_save_state
on_pause
on_stop
- on_destroy
end
end
on_create
on_restore_state
- on_start
on_resume
end
on_pause
on_save_state
on_stop
- on_destroy
end
end
do
app.on_create
app.on_restore_state
- app.on_start
app.on_resume
gtk_main
app.on_pause
app.on_stop
app.on_save_state
- app.on_destroy
end
# Spacing between GTK controls, default at 2
nitlanguage / nit.git / commitdiff
