native_app_glue

Wrapper of the Android native_app_glue framework to implement app.nit

The framework provides 3 different structures for a single C application under Android. We use all 3 structures in this API to implement app.nit on Android. Each structure is wrapped in a Nit extern class:

  • NativeAppGlue is the lowest level class, it is implemented by the C structure android_app. It offers features on the main Android thread (not on the same thread as Nit). For this reason, prefer to use NdkNativeActivity.

  • NdkNativeActivity is implemented by the C structure ANativeActivity. It is on the same thread as Nit and manages the synchronization with the main Android thread.

  • NativeNativeActivity is implemented in Java by android.app.NativeActivity, which is a subclass of Activity and Context (in Java). It represent main activity of the running application. Use it to get anything related to the Context and as anchor to execute Java UI code.

Dependencies

dep_module_android__native_app_glueloglogdalvikdalvikcardboardcardboardnative_app_gluenative_app_gluecardboard->native_app_gluenative_app_glue->lognative_app_glue->dalvikgamegamegame->native_app_glue

Imports

  • dalvik: Java related services specific to Android and its Dalvik VM
  • log: Advanced Android logging services

Clients

  • cardboard: Services from the Google Cardboard SDK for virtual reality on Android
  • game: Android services and implementation of app.nit for gamnit and mnit

Concerns

  • android: Android platform support and APIs
    • native_app_glue: Wrapper of the Android native_app_glue framework to implement app.nit
  • core: Nit common library of core classes and methods
    • kernel: Most basic classes and methods.
  • app: app.nit, a framework for portable applications
    • app_base: Base of the app.nit framework, defines App

in android::native_app_glue

NativeAppGlue

extern class NativeAppGlue

This is the interface for the standard glue code of a threaded

application. In this model, the application's code is running in its own thread separate from the main thread of the process. It is not required that this thread be associated with the Java VM, although it will need to be in order to make JNI calls any Java objects.

Introduces
  • ndk_native_activity: The ANativeActivity object instance that this app is running in.
  • config: The current configuration the app is running in.
  • saved_state: This is the last instance's saved state, as provided at creation time.
  • saved_state_size
  • looper: The ALooper associated with the app's thread.
  • input_queue: When non-NULL, this is the input queue from which the app will
  • window: When non-NULL, this is the window surface that the app can draw in.
  • activity_state: Current state of the app's activity. May be either APP_CMD_START,
  • detroy_request: This is non-zero when the application's NativeActivity is being
Redefines
  • SELF: Type of this instance, automatically specialized in every class

NdkNativeActivity

extern class NdkNativeActivity

An Android activity implemented in C. This is the C part of NativeActivity

which is the Java part.

The callbacks at this level are synchronous on the UI thread. Thus app.nit do not use them, and instead rely on NativeAppGlue.

Introduces
  • vm: Java VM associated to self
  • env: JNI environmnet associated to self
  • java_native_activity: The NativeActivity, as in the Java object, associated to self
  • internal_data_path: Path to this application's internal data directory.
  • external_data_path: Path to this application's external (removable/mountable) data directory.
  • sdk_version: The platform's SDK version code.
  • instance: This is the native instance of the application. It is not used by
Redefines
  • SELF: Type of this instance, automatically specialized in every class

from core::kernel

Sys

redef class Sys

The main class of the program.

Sys is a singleton class, its only instance is accessible from everywhere with sys.

Because of this, methods that should be accessible from everywhere, like print or exit, are defined in Sys. Moreover, unless there is an ambiguity with self, the receiver of a call to these methods is implicitly sys. Basically it means that the two following instructions are equivalent.

print "Hello World"
sys.print "Hello World"

Methods Implicitly Defined in Sys

Sys is the class where are defined top-level methods, i.e. those defined outside of any class like in a procedural language. Basically it means that

redef class Sys
   fun foo do print "hello"
end

is equivalent with

fun foo print "hello"

As a corollary, in a top-level method, self (the current receiver) is always sys.

Redefines
  • jvm: Default Java Virtual Machine to use

from app::app_base

App

app::App

redef class App

App subclasses are cross-platform applications

This class is refined by platform modules and so App can be specialized directly in the user application code.

Introduces
  • native_app_glue: The underlying implementation using the Android native_app_glue framework
  • save_state: Notification from the Android framework to generate a new saved state
  • init_window: Notification from the native_app glue framework, a new ANativeWindow is ready
  • term_window: Notification from the native_app glue framework, the existing window needs to be terminated
  • gained_focus: Notification from the Android framework, native_activity has gained focus
  • lost_focus: Notification from the Android framework, native_activity has lost focus
  • pause: Notification from the Android framework, your app has been paused
  • stop: Notification from the Android framework, your app has been stopped
  • destroy: Notification from the Android framework, native_activity is being destroyed
  • start: Notification from the Android framework, native_activity has been started
  • resume: Notification from the Android framework, native_activity has been resumed
  • low_memory: Notification from the Android framework, the system is running low on memory
  • config_changed: Notification from the Android framework, the current device configuration has changed
  • input_changed: Notification from the Android framework, native_app_glue.input_queue has changed
  • window_resized: Notification from the Android framework, the window has been resized.
  • window_redraw_needed: Notification from the Android framework, the current ANativeWindow must be redrawn
  • content_rect_changed: Notification from the Android framework, the content area of the window has changed
  • poll_looper: Call the ALooper to retrieve events and callback the application
  • handle_looper_event: Handle an event retrieved by the ALooper and poll_looper without a callback
Redefines
  • setup: Starts the internal setup of graphical and other stuff
  • native_activity: Main Java Activity of this application