X-Git-Url: http://nitlanguage.org?ds=sidebyside diff --git a/lib/app/README.md b/lib/app/README.md index 22f4f77..d69a030 100644 --- a/lib/app/README.md +++ b/lib/app/README.md @@ -1,41 +1,42 @@ -_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. +![_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`. @@ -44,7 +45,7 @@ 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 +# 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`. @@ -65,21 +66,20 @@ So there is two ways to customize the behavior on a given event: * 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: @@ -90,7 +90,7 @@ Pass `null` to clear the value associated to a key. * `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 @@ -123,7 +123,15 @@ redef class App 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. @@ -142,9 +150,20 @@ The _app.nit_ framework defines three annotations to customize the application p 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 + +~~~nitish module my_module is app_name "My App" app_namespace "org.example.my_app" @@ -152,33 +171,38 @@ 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. - ~~~ + ~~~raw # 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 + ~~~nitish + module android_calculator import calculator - import linux::ui + import android + + # ... ~~~