lib/core/stream: LineIterator use CachedIterator

[nit.git] / lib / app / README.md

diff --git a/lib/app/README.md b/lib/app/README.md
index 22f4f77..d69a030 100644 (file)
--- 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
 
 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.
 
 * 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.
 
 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 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`.
 
 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`.
 
 
 * `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.
 
 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`.
 
 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.
 
 
 * 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.
 
 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:
 
 _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.
 
 * `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
 
 ~~~
 import app::data_store

@@ -123,7 +123,15 @@ redef class App
 end
 ~~~
 
 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 _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.
 
   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"
 module my_module is
     app_name "My App"
     app_namespace "org.example.my_app"

@@ -152,33 +171,38 @@ module my_module is
 end
 ~~~
 
 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 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:
 
 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.
 
   It can be used to load platform specific implementations of the _app.nit_ portable UI.
 

-  ~~~
+  ~~~raw

   # GNU/Linux version, using GTK
   # GNU/Linux version, using GTK

-  nitc calculator.nit -m NIT_DIR/lib/linux/ui.nit
+  nitc calculator.nit -m linux

 
   # Android version
 
   # 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.
   ~~~
 
 * 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 calculator

-  import linux::ui
+  import android
+
+  # ...

   ~~~
   ~~~