frameworks/base/native/include/android/native_activity.h

   1 /*
   2  * Copyright (C) 2010 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17
  18 #ifndef ANDROID_NATIVE_ACTIVITY_H
  19 #define ANDROID_NATIVE_ACTIVITY_H
  20
  21 #include <stdint.h>
  22 #include <sys/types.h>
  23
  24 #include <jni.h>
  25
  26 #include <android/asset_manager.h>
  27 #include <android/input.h>
  28 #include <android/native_window.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 struct ANativeActivityCallbacks;
  35
  36 /**
  37  * This structure defines the native side of an android.app.NativeActivity.
  38  * It is created by the framework, and handed to the application's native
  39  * code as it is being launched.
  40  */
  41 typedef struct ANativeActivity {
  42     /**
  43      * Pointer to the callback function table of the native application.
  44      * You can set the functions here to your own callbacks.  The callbacks
  45      * pointer itself here should not be changed; it is allocated and managed
  46      * for you by the framework.
  47      */
  48     struct ANativeActivityCallbacks* callbacks;
  49
  50     /**
  51      * The global handle on the process's Java VM.
  52      */
  53     JavaVM* vm;
  54
  55     /**
  56      * JNI context for the main thread of the app.  Note that this field
  57      * can ONLY be used from the main thread of the process; that is, the
  58      * thread that calls into the ANativeActivityCallbacks.
  59      */
  60     JNIEnv* env;
  61
  62     /**
  63      * The NativeActivity Java class.
  64      */
  65     jobject clazz;
  66
  67     /**
  68      * Path to this application's internal data directory.
  69      */
  70     const char* internalDataPath;
  71
  72     /**
  73      * Path to this application's external (removable/mountable) data directory.
  74      */
  75     const char* externalDataPath;
  76
  77     /**
  78      * The platform's SDK version code.
  79      */
  80     int32_t sdkVersion;
  81
  82     /**
  83      * This is the native instance of the application.  It is not used by
  84      * the framework, but can be set by the application to its own instance
  85      * state.
  86      */
  87     void* instance;
  88
  89     /**
  90      * Pointer to the Asset Manager instance for the application.  The application
  91      * uses this to access binary assets bundled inside its own .apk file.
  92      */
  93     AAssetManager* assetManager;
  94 } ANativeActivity;
  95
  96 /**
  97  * These are the callbacks the framework makes into a native application.
  98  * All of these callbacks happen on the main thread of the application.
  99  * By default, all callbacks are NULL; set to a pointer to your own function
 100  * to have it called.
 101  */
 102 typedef struct ANativeActivityCallbacks {
 103     /**
 104      * NativeActivity has started.  See Java documentation for Activity.onStart()
 105      * for more information.
 106      */
 107     void (*onStart)(ANativeActivity* activity);
 108
 109     /**
 110      * NativeActivity has resumed.  See Java documentation for Activity.onResume()
 111      * for more information.
 112      */
 113     void (*onResume)(ANativeActivity* activity);
 114
 115     /**
 116      * Framework is asking NativeActivity to save its current instance state.
 117      * See Java documentation for Activity.onSaveInstanceState() for more
 118      * information.  The returned pointer needs to be created with malloc();
 119      * the framework will call free() on it for you.  You also must fill in
 120      * outSize with the number of bytes in the allocation.  Note that the
 121      * saved state will be persisted, so it can not contain any active
 122      * entities (pointers to memory, file descriptors, etc).
 123      */
 124     void* (*onSaveInstanceState)(ANativeActivity* activity, size_t* outSize);
 125
 126     /**
 127      * NativeActivity has paused.  See Java documentation for Activity.onPause()
 128      * for more information.
 129      */
 130     void (*onPause)(ANativeActivity* activity);
 131
 132     /**
 133      * NativeActivity has stopped.  See Java documentation for Activity.onStop()
 134      * for more information.
 135      */
 136     void (*onStop)(ANativeActivity* activity);
 137
 138     /**
 139      * NativeActivity is being destroyed.  See Java documentation for Activity.onDestroy()
 140      * for more information.
 141      */
 142     void (*onDestroy)(ANativeActivity* activity);
 143
 144     /**
 145      * Focus has changed in this NativeActivity's window.  This is often used,
 146      * for example, to pause a game when it loses input focus.
 147      */
 148     void (*onWindowFocusChanged)(ANativeActivity* activity, int hasFocus);
 149
 150     /**
 151      * The drawing window for this native activity has been created.  You
 152      * can use the given native window object to start drawing.
 153      */
 154     void (*onNativeWindowCreated)(ANativeActivity* activity, ANativeWindow* window);
 155
 156     /**
 157      * The drawing window for this native activity has been resized.  You should
 158      * retrieve the new size from the window and ensure that your rendering in
 159      * it now matches.
 160      */
 161     void (*onNativeWindowResized)(ANativeActivity* activity, ANativeWindow* window);
 162
 163     /**
 164      * The drawing window for this native activity needs to be redrawn.  To avoid
 165      * transient artifacts during screen changes (such resizing after rotation),
 166      * applications should not return from this function until they have finished
 167      * drawing their window in its current state.
 168      */
 169     void (*onNativeWindowRedrawNeeded)(ANativeActivity* activity, ANativeWindow* window);
 170
 171     /**
 172      * The drawing window for this native activity is going to be destroyed.
 173      * You MUST ensure that you do not touch the window object after returning
 174      * from this function: in the common case of drawing to the window from
 175      * another thread, that means the implementation of this callback must
 176      * properly synchronize with the other thread to stop its drawing before
 177      * returning from here.
 178      */
 179     void (*onNativeWindowDestroyed)(ANativeActivity* activity, ANativeWindow* window);
 180
 181     /**
 182      * The input queue for this native activity's window has been created.
 183      * You can use the given input queue to start retrieving input events.
 184      */
 185     void (*onInputQueueCreated)(ANativeActivity* activity, AInputQueue* queue);
 186
 187     /**
 188      * The input queue for this native activity's window is being destroyed.
 189      * You should no longer try to reference this object upon returning from this
 190      * function.
 191      */
 192     void (*onInputQueueDestroyed)(ANativeActivity* activity, AInputQueue* queue);
 193
 194     /**
 195      * The rectangle in the window in which content should be placed has changed.
 196      */
 197     void (*onContentRectChanged)(ANativeActivity* activity, const ARect* rect);
 198
 199     /**
 200      * The current device AConfiguration has changed.  The new configuration can
 201      * be retrieved from assetManager.
 202      */
 203     void (*onConfigurationChanged)(ANativeActivity* activity);
 204
 205     /**
 206      * The system is running low on memory.  Use this callback to release
 207      * resources you do not need, to help the system avoid killing more
 208      * important processes.
 209      */
 210     void (*onLowMemory)(ANativeActivity* activity);
 211 } ANativeActivityCallbacks;
 212
 213 /**
 214  * This is the function that must be in the native code to instantiate the
 215  * application's native activity.  It is called with the activity instance (see
 216  * above); if the code is being instantiated from a previously saved instance,
 217  * the savedState will be non-NULL and point to the saved data.  You must make
 218  * any copy of this data you need -- it will be released after you return from
 219  * this function.
 220  */
 221 typedef void ANativeActivity_createFunc(ANativeActivity* activity,
 222         void* savedState, size_t savedStateSize);
 223
 224 /**
 225  * The name of the function that NativeInstance looks for when launching its
 226  * native code.  This is the default function that is used, you can specify
 227  * "android.app.func_name" string meta-data in your manifest to use a different
 228  * function.
 229  */
 230 extern ANativeActivity_createFunc ANativeActivity_onCreate;
 231
 232 /**
 233  * Finish the given activity.  Its finish() method will be called, causing it
 234  * to be stopped and destroyed.  Note that this method can be called from
 235  * *any* thread; it will send a message to the main thread of the process
 236  * where the Java finish call will take place.
 237  */
 238 void ANativeActivity_finish(ANativeActivity* activity);
 239
 240 /**
 241  * Change the window format of the given activity.  Calls getWindow().setFormat()
 242  * of the given activity.  Note that this method can be called from
 243  * *any* thread; it will send a message to the main thread of the process
 244  * where the Java finish call will take place.
 245  */
 246 void ANativeActivity_setWindowFormat(ANativeActivity* activity, int32_t format);
 247
 248 /**
 249  * Change the window flags of the given activity.  Calls getWindow().setFlags()
 250  * of the given activity.  Note that this method can be called from
 251  * *any* thread; it will send a message to the main thread of the process
 252  * where the Java finish call will take place.  See window.h for flag constants.
 253  */
 254 void ANativeActivity_setWindowFlags(ANativeActivity* activity,
 255         uint32_t addFlags, uint32_t removeFlags);
 256
 257 /**
 258  * Flags for ANativeActivity_showSoftInput; see the Java InputMethodManager
 259  * API for documentation.
 260  */
 261 enum {
 262     ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001,
 263     ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002,
 264 };
 265
 266 /**
 267  * Show the IME while in the given activity.  Calls InputMethodManager.showSoftInput()
 268  * for the given activity.  Note that this method can be called from
 269  * *any* thread; it will send a message to the main thread of the process
 270  * where the Java finish call will take place.
 271  */
 272 void ANativeActivity_showSoftInput(ANativeActivity* activity, uint32_t flags);
 273
 274 /**
 275  * Flags for ANativeActivity_hideSoftInput; see the Java InputMethodManager
 276  * API for documentation.
 277  */
 278 enum {
 279     ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001,
 280     ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002,
 281 };
 282
 283 /**
 284  * Hide the IME while in the given activity.  Calls InputMethodManager.hideSoftInput()
 285  * for the given activity.  Note that this method can be called from
 286  * *any* thread; it will send a message to the main thread of the process
 287  * where the Java finish call will take place.
 288  */
 289 void ANativeActivity_hideSoftInput(ANativeActivity* activity, uint32_t flags);
 290
 291 #ifdef __cplusplus
 292 };
 293 #endif
 294
 295 #endif // ANDROID_NATIVE_ACTIVITY_H
 296