app -
app.nit, a framework for portable applications
The framework provides services to manage common needs of modern mobile applications:
- Life-cycle
- User interface
- Persistence
- Async HTTP requests
- Package metadata
- Compilation and packaging
The features offered by app.nit are common to all platforms, but may not be available on all devices.
Application Life-Cycle
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:
on_create
: The application is being created. You should build the UI at this time and launch services.on_resume
: The app enters the active state, it is in the foreground and interactive.on_pause
: The app becomes inactive and it leaves the foreground. It may still be visible in the background.on_stop
: The app is completely hidden. It may then be destroyed (without warning) or go back to the active state withon_restart
.on_restart
: The app goes back to the inactive state. You can revert what was done byon_stop
.
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 futureon_restore_state
. There is more on how it can be done in theapp::data_store
section.on_restore_state
: The app is launching, restore its state from a previouson_save_state
.
These events are synchronized to the native platforms applications
The App
instance is the first to be notified of these events.
Other UI elements, from the ui
submodule, are notified of the same events using a simple depth first visit.
So all UI elements can react separately to live-cycle events.
User Interface
The app::ui
module defines an abstract API to build a portable graphical application.
The API is composed of interactive Control
s, visible View
s and an active Window
.
Here is a subset of the most useful controls and views:
The classic pushable
Button
with text (usually rectangular).TextInput
is a field for the user to enter text.HorizontalLayout
andVerticalLayout
organize other controls in order.
Each control is notified of input events by callbacks to on_event
.
All controls have observers that are also notified of the events.
So there is two ways to customize the behavior on a given event:
Create a subclass of the wanted
Control
, let's sayButton
, and specializeon_event
.Add an observer to a
Button
instance, and implementon_event
in the observer.
Usage Example
The example at examples/ui_example.nit
shows off most features of app::ui
in a minimal program.
You can also take a look at the calculator (../../examples/calculator/src/calculator.nit
) which is a concrete usage example.
Platform-specific UI
You can go beyond the portable UI API of app.nit by using the natives services of a platform.
The suggested approach is to use platform specific modules to customize the application on a precise platform. See the calculator example for an adaptation of the UI on Android, the interesting module is in this repository at ../../examples/calculator/src/android_calculator.nit
Persistent State with data_store
app.nit offers the submodule app::data_store
to easily save the application state and user preferences.
The service is accessible by the method App::data_store
. The DataStore
itself defines 2 methods:
[]=
saves and associates any serializable instances to aString
key. Passnull
to clear the value associated to a key.[]
returns the object associated to aString
key. It returnsnull
if nothing is associated to the key.
Usage Example
import app::data_store
redef class App
var user_name: String
redef fun on_save_state
do
app.data_store["first run"] = false
app.data_store["user name"] = user_name
super # call `on_save_state` on all attached instances of `AppComponent`
end
redef fun on_restore_state
do
var first_run = app.data_store["first run"]
if first_run != true then
print "It's the first run of this application"
end
var user_name = app.data_store["user name"]
if user_name isa String then
self.user_name = user_name
else self.user_name = "Undefined"
super
end
end
Async HTTP request
The module app::http_request
provides services to execute asynchronous HTTP request.
The class AsyncHttpRequest
hides the complex parallel logic and
lets the user implement methods acting only on the UI thread.
See the documentation of AsyncHttpRequest
for more information and
the full example at examples/http_request_example.nit
.
Metadata annotations
The app.nit framework defines three annotations to customize the application package.
app_name
takes a single argument, the visible name of the application. This name is used for launchers and window title. By default, the name of the target module.app_namespace
specifies the full namespace (or package name) of the application package. This value usually identify the application uniquely on application stores. It should not change once the application has benn published. By default, the namespace isorg.nitlanguage.{module_name}
.app_version
specifies the version of the application package. This annotation expects at least one argument, usually we use three version numbers: the major, minor and revision. The special functiongit_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 foldersandroid
andios
. Theandroid
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. Theios
folder is searched for icons only.Each argument of
app_files
is a relative path to a folder containing extraandroid
orios
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
module my_module is
app_name "My App"
app_namespace "org.example.my_app"
app_version(1, 0, git_revision)
end
Compiling and Packaging an Application
The Nit compiler detects the target platform from the importations and generates the appropriate application format and package.
Applications using only the portable services of app.nit require some special care at compilation.
Such an application, let's say calculator.nit
, does not depend on a specific platform and use the portable UI.
The target platform must be specified to the compiler for it to produce the correct application package.
There is two main ways to achieve this goal:
The mixin option (
-m module
) imports an additional module before compiling. It can be used to load platform specific implementations of the app.nit portable UI.# GNU/Linux version, using GTK nitc calculator.nit -m linux # Android version nitc calculator.nit -m android # iOS version nitc calculator.nit -m ios
A common alternative for larger projects is to use platform specific modules. Continuing with the calculator example, it is adapted for Android by the module
android_calculator.nit
. This module imports bothcalculator
andandroid
, it can then use Android specific code.module android_calculator import calculator import android
Content
- app: app.nit, a framework for portable applications (lib/app)
- app: app.nit is a framework to create cross-platform applications (lib/app/app.nit)
- app_base: Base of the app.nit framework, defines
App
(lib/app/app_base.nit) - assets: Portable services to load resources from the assets folder (lib/app/assets.nit)
- audio: Services to load and play
Sound
andMusic
from the assets folder (lib/app/audio.nit) - data_store: Key/value storage services (lib/app/data_store.nit)
- examples (lib/app/examples)
- http_request_example: Example for the
app::http_request
main serviceAsyncHttpRequest
(lib/app/examples/http_request_example.nit) - ui_example: User interface example using
app::ui
(lib/app/examples/ui_example.nit)
- http_request_example: Example for the
- http_request: HTTP request services:
AsyncHttpRequest
andText::http_get
(lib/app/http_request.nit) - ui: Portable UI controls for mobiles apps (lib/app/ui.nit)