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:

  1. on_create: The application is being created. You should build the UI at this time and launch services.

  2. on_resume: The app enters the active state, it is in the foreground and interactive.

  3. on_pause: The app becomes inactive and it leaves the foreground. It may still be visible in the background.

  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.

_app.nit_ life-cycle

Life-cycle events related to saving and restoring the application state are provided by two special callback methods:

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 ui module defines an abstract API to build a portable graphical application. The API is composed of interactive Controls, visible Views and an active Window.

Here is a subset of the most useful controls and views:

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:

Usage Example

The example at examples/ui_example.nit shows off most features of 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 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 a String key. Pass null to clear the value associated to a key.

  • [] returns the object associated to a String key. It returns null 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 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 is org.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 function git_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 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
    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 both calculator and android, it can then use Android specific code.

    module android_calculator
    
    import calculator
    import android

All groups and modules

module app

app :: app

app.nit is a framework to create cross-platform applications
module app_base

app :: app_base

Base of the app.nit framework, defines App
module assets

app :: assets

Portable services to load resources from the assets folder
module audio

app :: audio

Services to load and play Sound and Music from the assets folder
module data_store

app :: data_store

Key/value storage services
group doc

app > doc

group examples

app > examples

module http_request

app :: http_request

HTTP request services: AsyncHttpRequest and Text::http_get
module ui

app :: ui

Portable UI controls for mobiles apps
package_diagram app app core core app->core serialization serialization app->serialization pthreads pthreads app->pthreads json json app->json android android app->android serialization->json poset poset serialization->poset meta meta serialization->meta pthreads->core android->core android->json java java android->java mnit mnit android->mnit c c android->c gamnit gamnit android->gamnit ...poset ... ...poset->poset ...meta ... ...meta->meta ...json ... ...json->json gamnit->app ios ios gamnit->ios linux linux gamnit->linux ...java ... ...java->java ...mnit ... ...mnit->mnit ...c ... ...c->c ...gamnit ... ...gamnit->gamnit ios->app linux->app egl egl egl->android glesv2 glesv2 glesv2->android egl... ... egl...->egl gamnit... ... gamnit...->gamnit glesv2... ... glesv2...->glesv2

Ancestors

package binary

binary

Read and write binary data with any Reader and Writer
package c

c

Structures and services for compatibility with the C language
package cocoa

cocoa

Cocoa API, the development layer of OS X
package curl

curl

Data transfer powered by the native curl library
package dom

dom

Easy XML DOM parser
package egl

egl

Interface between rendering APIs (OpenGL, OpenGL ES, etc.) and the native windowing system.
package gamnit

gamnit

Portable game and multimedia framework for Nit
package gen_nit

gen_nit

Support to generate and otherwise manipulate Nit code
package geometry

geometry

Basic geometry data structures and services.
package glesv2

glesv2

OpenGL graphics rendering library for embedded systems, version 2.0
package gtk

gtk

GTK+ widgets and services
package ios

ios

iOS support for app.nit
package java

java

Supporting services for the FFI with Java and to access Java libraries
package jvm

jvm

Java Virtual Machine invocation API and others services from the JNI C API
package linux

linux

Implementation of app.nit for the Linux platform
package matrix

matrix

Services for matrices of Float values
package meta

meta

Simple user-defined meta-level to manipulate types of instances as object.
package mnit

mnit

package more_collections

more_collections

Highly specific, but useful, collections-related classes.
package msgpack

msgpack

MessagePack, an efficient binary serialization format
package opts

opts

Management of options on the command line
package parser_base

parser_base

Simple base for hand-made parsers of all kinds
package performance_analysis

performance_analysis

Services to gather information on the performance of events by categories
package pipeline

pipeline

Pipelined filters and operations on iterators.
package poset

poset

Pre order sets and partial order set (ie hierarchies)
package realtime

realtime

Services to keep time of the wall clock time
package sdl2

sdl2

This is a low-level wrapper of the SDL 2.0 library (as sdl2) and SDL_image 2.0 (as sdl2::image).
package socket

socket

Socket services
package sqlite3

sqlite3

Services to manipulate a Sqlite3 database
package template

template

Basic template system
package xdg_basedir

xdg_basedir

Services for using the XDG Base Directory specification

Parents

package android

android

Android platform support and APIs
package core

core

Nit common library of core classes and methods
package json

json

read and write JSON formatted text
package pthreads

pthreads

POSIX Threads support
package serialization

serialization

Abstract serialization services

Children

package android

android

Android platform support and APIs
package gamnit

gamnit

Portable game and multimedia framework for Nit
package ios

ios

iOS support for app.nit
package linux

linux

Implementation of app.nit for the Linux platform

Descendants

package egl

egl

Interface between rendering APIs (OpenGL, OpenGL ES, etc.) and the native windowing system.
package glesv2

glesv2

OpenGL graphics rendering library for embedded systems, version 2.0