Skip to content

Most visited

Recently visited

navigation

NativeActivity

public class NativeActivity
extends Activity implements SurfaceHolder.Callback2, InputQueue.Callback, ViewTreeObserver.OnGlobalLayoutListener

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.view.ContextThemeWrapper
         ↳ android.app.Activity
           ↳ android.app.NativeActivity


Convenience for implementing an activity that will be implemented purely in native code. That is, a game (or game-like thing). There is no need to derive from this class; you can simply declare it in your manifest, and use the NDK APIs from there.

A sample native activity is available in the NDK samples.

Summary

Constants

String META_DATA_FUNC_NAME

Optional meta-that can be in the manifest for this component, specifying the name of the main entry point for this native activity in the META_DATA_LIB_NAME native code.

String META_DATA_LIB_NAME

Optional meta-that can be in the manifest for this component, specifying the name of the native shared library to load.

Inherited constants

From class android.app.Activity
From class android.content.Context
From interface android.content.ComponentCallbacks2

Inherited fields

From class android.app.Activity

Public constructors

NativeActivity()

Public methods

void onConfigurationChanged(Configuration newConfig)

Called by the system when the device configuration changes while your activity is running.

void onGlobalLayout()

Callback method to be invoked when the global layout state or the visibility of views within the view tree changes

void onInputQueueCreated(InputQueue queue)

Called when the given InputQueue is now associated with the thread making this call, so it can start receiving events from it.

void onInputQueueDestroyed(InputQueue queue)

Called when the given InputQueue is no longer associated with the thread and thus not dispatching events.

void onLowMemory()

This is called when the overall system is running low on memory, and actively running processes should trim their memory usage.

void onWindowFocusChanged(boolean hasFocus)

Called when the current Window of the activity gains or loses focus.

void surfaceChanged(SurfaceHolder holder, int format, int width, int height)

This is called immediately after any structural changes (format or size) have been made to the surface.

void surfaceCreated(SurfaceHolder holder)

This is called immediately after the surface is first created.

void surfaceDestroyed(SurfaceHolder holder)

This is called immediately before a surface is being destroyed.

void surfaceRedrawNeeded(SurfaceHolder holder)

Called when the application needs to redraw the content of its surface, after it is resized or for some other reason.

Protected methods

void onCreate(Bundle savedInstanceState)

Called when the activity is starting.

void onDestroy()

Perform any final cleanup before an activity is destroyed.

void onPause()

Called as part of the activity lifecycle when an activity is going into the background, but has not (yet) been killed.

void onResume()

Called after onRestoreInstanceState(Bundle), onRestart(), or onPause(), for your activity to start interacting with the user.

void onSaveInstanceState(Bundle outState)

Called to retrieve per-instance state from an activity before being killed so that the state can be restored in onCreate(Bundle) or onRestoreInstanceState(Bundle) (the Bundle populated by this method will be passed to both).

void onStart()

Called after onCreate(Bundle) — or after onRestart() when the activity had been stopped, but is now again being displayed to the user.

void onStop()

Called when you are no longer visible to the user.

Inherited methods

From class android.app.Activity
From class android.view.ContextThemeWrapper
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.view.LayoutInflater.Factory2
From interface android.view.Window.Callback
From interface android.view.KeyEvent.Callback
From interface android.view.View.OnCreateContextMenuListener
From interface android.content.ComponentCallbacks2
From interface android.view.SurfaceHolder.Callback2
From interface android.view.InputQueue.Callback
From interface android.view.ViewTreeObserver.OnGlobalLayoutListener
From interface android.view.LayoutInflater.Factory
From interface android.content.ComponentCallbacks
From interface android.view.SurfaceHolder.Callback

Constants

META_DATA_FUNC_NAME

added in API level 9
String META_DATA_FUNC_NAME

Optional meta-that can be in the manifest for this component, specifying the name of the main entry point for this native activity in the META_DATA_LIB_NAME native code. If not specified, "ANativeActivity_onCreate" is used.

Constant Value: "android.app.func_name"

META_DATA_LIB_NAME

added in API level 9
String META_DATA_LIB_NAME

Optional meta-that can be in the manifest for this component, specifying the name of the native shared library to load. If not specified, "main" is used.

Constant Value: "android.app.lib_name"

Public constructors

NativeActivity

added in API level 9
NativeActivity ()

Public methods

onConfigurationChanged

added in API level 9
void onConfigurationChanged (Configuration newConfig)

Called by the system when the device configuration changes while your activity is running. Note that this will only be called if you have selected configurations you would like to handle with the configChanges attribute in your manifest. If any configuration change occurs that is not selected to be reported by that attribute, then instead of reporting it the system will stop and restart the activity (to have it launched with the new configuration).

At the time that this function has been called, your Resources object will have been updated to return resource values matching the new configuration.

Parameters
newConfig Configuration: The new device configuration.

onGlobalLayout

added in API level 9
void onGlobalLayout ()

Callback method to be invoked when the global layout state or the visibility of views within the view tree changes

onInputQueueCreated

added in API level 9
void onInputQueueCreated (InputQueue queue)

Called when the given InputQueue is now associated with the thread making this call, so it can start receiving events from it.

Parameters
queue InputQueue

onInputQueueDestroyed

added in API level 9
void onInputQueueDestroyed (InputQueue queue)

Called when the given InputQueue is no longer associated with the thread and thus not dispatching events.

Parameters
queue InputQueue

onLowMemory

added in API level 9
void onLowMemory ()

This is called when the overall system is running low on memory, and actively running processes should trim their memory usage. While the exact point at which this will be called is not defined, generally it will happen when all background process have been killed. That is, before reaching the point of killing processes hosting service and foreground UI that we would like to avoid killing.

You should implement this method to release any caches or other unnecessary resources you may be holding on to. The system will perform a garbage collection for you after returning from this method.

Preferably, you should implement onTrimMemory(int) from ComponentCallbacks2 to incrementally unload your resources based on various levels of memory demands. That API is available for API level 14 and higher, so you should only use this onLowMemory() method as a fallback for older versions, which can be treated the same as onTrimMemory(int) with the TRIM_MEMORY_COMPLETE level.

onWindowFocusChanged

added in API level 9
void onWindowFocusChanged (boolean hasFocus)

Called when the current Window of the activity gains or loses focus. This is the best indicator of whether this activity is visible to the user. The default implementation clears the key tracking state, so should always be called.

Note that this provides information about global focus state, which is managed independently of activity lifecycles. As such, while focus changes will generally have some relation to lifecycle changes (an activity that is stopped will not generally get window focus), you should not rely on any particular order between the callbacks here and those in the other lifecycle methods such as onResume().

As a general rule, however, a resumed activity will have window focus... unless it has displayed other dialogs or popups that take input focus, in which case the activity itself will not have focus when the other windows have it. Likewise, the system may display system-level windows (such as the status bar notification panel or a system alert) which will temporarily take window input focus without pausing the foreground activity.

Parameters
hasFocus boolean: Whether the window of this activity has focus.

surfaceChanged

added in API level 9
void surfaceChanged (SurfaceHolder holder, 
                int format, 
                int width, 
                int height)

This is called immediately after any structural changes (format or size) have been made to the surface. You should at this point update the imagery in the surface. This method is always called at least once, after surfaceCreated(SurfaceHolder).

Parameters
holder SurfaceHolder: The SurfaceHolder whose surface has changed.

format int: The new PixelFormat of the surface.

width int: The new width of the surface.

height int: The new height of the surface.

surfaceCreated

added in API level 9
void surfaceCreated (SurfaceHolder holder)

This is called immediately after the surface is first created. Implementations of this should start up whatever rendering code they desire. Note that only one thread can ever draw into a Surface, so you should not draw into the Surface here if your normal rendering will be in another thread.

Parameters
holder SurfaceHolder: The SurfaceHolder whose surface is being created.

surfaceDestroyed

added in API level 9
void surfaceDestroyed (SurfaceHolder holder)

This is called immediately before a surface is being destroyed. After returning from this call, you should no longer try to access this surface. If you have a rendering thread that directly accesses the surface, you must ensure that thread is no longer touching the Surface before returning from this function.

Parameters
holder SurfaceHolder: The SurfaceHolder whose surface is being destroyed.

surfaceRedrawNeeded

added in API level 9
void surfaceRedrawNeeded (SurfaceHolder holder)

Called when the application needs to redraw the content of its surface, after it is resized or for some other reason. By not returning from here until the redraw is complete, you can ensure that the user will not see your surface in a bad state (at its new size before it has been correctly drawn that way). This will typically be preceeded by a call to surfaceChanged(SurfaceHolder, int, int, int). As of O, surfaceRedrawNeededAsync(SurfaceHolder, Runnable) may be implemented to provide a non-blocking implementation. If surfaceRedrawNeededAsync(SurfaceHolder, Runnable) is not implemented, then this will be called instead.

Parameters
holder SurfaceHolder: The SurfaceHolder whose surface has changed.

Protected methods

onCreate

added in API level 9
void onCreate (Bundle savedInstanceState)

Called when the activity is starting. This is where most initialization should go: calling setContentView(int) to inflate the activity's UI, using findViewById(int) to programmatically interact with widgets in the UI, calling managedQuery(android.net.Uri, String[], String, String[], String) to retrieve cursors for data being displayed, etc.

You can call finish() from within this function, in which case onDestroy() will be immediately called without any of the rest of the activity lifecycle (onStart(), onResume(), onPause(), etc) executing.

Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.

Parameters
savedInstanceState Bundle: If the activity is being re-initialized after previously being shut down then this Bundle contains the data it most recently supplied in onSaveInstanceState(Bundle). Note: Otherwise it is null.

onDestroy

added in API level 9
void onDestroy ()

Perform any final cleanup before an activity is destroyed. This can happen either because the activity is finishing (someone called finish() on it, or because the system is temporarily destroying this instance of the activity to save space. You can distinguish between these two scenarios with the isFinishing() method.

Note: do not count on this method being called as a place for saving data! For example, if an activity is editing data in a content provider, those edits should be committed in either onPause() or onSaveInstanceState(Bundle), not here. This method is usually implemented to free resources like threads that are associated with an activity, so that a destroyed activity does not leave such things around while the rest of its application is still running. There are situations where the system will simply kill the activity's hosting process without calling this method (or any others) in it, so it should not be used to do things that are intended to remain around after the process goes away.

Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.

onPause

added in API level 9
void onPause ()

Called as part of the activity lifecycle when an activity is going into the background, but has not (yet) been killed. The counterpart to onResume().

When activity B is launched in front of activity A, this callback will be invoked on A. B will not be created until A's onPause() returns, so be sure to not do anything lengthy here.

This callback is mostly used for saving any persistent state the activity is editing, to present a "edit in place" model to the user and making sure nothing is lost if there are not enough resources to start the new activity without first killing this one. This is also a good place to do things like stop animations and other things that consume a noticeable amount of CPU in order to make the switch to the next activity as fast as possible, or to close resources that are exclusive access such as the camera.

In situations where the system needs more memory it may kill paused processes to reclaim resources. Because of this, you should be sure that all of your state is saved by the time you return from this function. In general onSaveInstanceState(Bundle) is used to save per-instance state in the activity and this method is used to store global persistent data (in content providers, files, etc.)

After receiving this call you will usually receive a following call to onStop() (after the next activity has been resumed and displayed), however in some cases there will be a direct call back to onResume() without going through the stopped state.

Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.

onResume

added in API level 9
void onResume ()

Called after onRestoreInstanceState(Bundle), onRestart(), or onPause(), for your activity to start interacting with the user. This is a good place to begin animations, open exclusive-access devices (such as the camera), etc.

Keep in mind that onResume is not the best indicator that your activity is visible to the user; a system window such as the keyguard may be in front. Use onWindowFocusChanged(boolean) to know for certain that your activity is visible to the user (for example, to resume a game).

Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.

onSaveInstanceState

added in API level 9
void onSaveInstanceState (Bundle outState)

Called to retrieve per-instance state from an activity before being killed so that the state can be restored in onCreate(Bundle) or onRestoreInstanceState(Bundle) (the Bundle populated by this method will be passed to both).

This method is called before an activity may be killed so that when it comes back some time in the future it can restore its state. For example, if activity B is launched in front of activity A, and at some point activity A is killed to reclaim resources, activity A will have a chance to save the current state of its user interface via this method so that when the user returns to activity A, the state of the user interface can be restored via onCreate(Bundle) or onRestoreInstanceState(Bundle).

Do not confuse this method with activity lifecycle callbacks such as onPause(), which is always called when an activity is being placed in the background or on its way to destruction, or onStop() which is called before destruction. One example of when onPause() and onStop() is called and not this method is when a user navigates back from activity B to activity A: there is no need to call onSaveInstanceState(Bundle) on B because that particular instance will never be restored, so the system avoids calling it. An example when onPause() is called and not onSaveInstanceState(Bundle) is when activity B is launched in front of activity A: the system may avoid calling onSaveInstanceState(Bundle) on activity A if it isn't killed during the lifetime of B since the state of the user interface of A will stay intact.

The default implementation takes care of most of the UI per-instance state for you by calling onSaveInstanceState() on each view in the hierarchy that has an id, and by saving the id of the currently focused view (all of which is restored by the default implementation of onRestoreInstanceState(Bundle)). If you override this method to save additional information not captured by each individual view, you will likely want to call through to the default implementation, otherwise be prepared to save all of the state of each view yourself.

If called, this method will occur before onStop(). There are no guarantees about whether it will occur before or after onPause().

Parameters
outState Bundle: Bundle in which to place your saved state.

onStart

added in API level 9
void onStart ()

Called after onCreate(Bundle) — or after onRestart() when the activity had been stopped, but is now again being displayed to the user. It will be followed by onResume().

Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.

onStop

added in API level 9
void onStop ()

Called when you are no longer visible to the user. You will next receive either onRestart(), onDestroy(), or nothing, depending on later user activity.

Derived classes must call through to the super class's implementation of this method. If they do not, an exception will be thrown.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience. (Dec 2017 Android Platform & Tools Survey)