-_app.nit_ is a framework to create cross-platform applications
+_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
+# 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:
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`.
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
+# 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`.
* Add an observer to a `Button` instance, and implement `on_event` in the observer.
-### Usage Example
+## Usage Example
-The calculator example (at `../../examples/calculator/src/calculator.nit`) is a concrete,
-simple and complete use of the _app.nit_ portable UI.
+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
+## 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.
-This module redefine `Window::on_start` to call the native language of the platform and setup a native UI.
-
-_TODO complete description and add concrete examples_
+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
+# 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:
* `DataStore::[]` returns the object associated to a `String` key.
It returns `null` if nothing is associated to the key.
-### Usage Example
+## Usage Example
~~~
import app::data_store
end
~~~
-## Metadata annotations
+# 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.
The special function `git_revision` will use the prefix of the hash of the latest git commit.
By default, the version is 0.1.
-### Usage Example
+* `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
~~~
module my_module is
end
~~~
-## Compiling and Packaging an Application
+# 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 specifed to the compiler for it to produce the correct application package.
+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 the mixin option (`-m path`) loads an additionnal module before compiling.
+* 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 NIT_DIR/lib/linux/ui.nit
+ nitc calculator.nit -m linux
# Android version
- nitc calculator.nit -m NIT_DIR/lib/android/ui/
+ 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.nit` example, it can be accompagnied by the module `calculator_linux.nit`.
- This module imports both `calculator` and `linux::ui`, and can also use other GNU/Linux specific code.
+ Continuing with the calculator example, it is adapted for Android by the module `android_calculator.nit`.
+ This module imports both `calculator` and `android`, it can then use Android specific code.
~~~
- module calculator_linux
+ module android_calculator
import calculator
- import linux::ui
+ import android
+
+ # ...
~~~
nitlanguage / nit.git / blobdiff