Game Activity

#include <GameActivity.h>

The interface to use GameActivity.

Summary

Enumerations
GameActivityHideSoftInputFlags{
  GAMEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001,
  GAMEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002
} 		enum
Flags for GameActivity_hideSoftInput; see the Java InputMethodManager API for documentation.
GameActivitySetWindowFlags{
  GAMEACTIVITY_FLAG_ALLOW_LOCK_WHILE_SCREEN_ON = 0x00000001,
  GAMEACTIVITY_FLAG_DIM_BEHIND = 0x00000002,
  GAMEACTIVITY_FLAG_BLUR_BEHIND = 0x00000004,
  GAMEACTIVITY_FLAG_NOT_FOCUSABLE = 0x00000008,
  GAMEACTIVITY_FLAG_NOT_TOUCHABLE = 0x00000010,
  GAMEACTIVITY_FLAG_NOT_TOUCH_MODAL = 0x00000020,
  GAMEACTIVITY_FLAG_TOUCHABLE_WHEN_WAKING = 0x00000040,
  GAMEACTIVITY_FLAG_KEEP_SCREEN_ON = 0x00000080,
  GAMEACTIVITY_FLAG_LAYOUT_IN_SCREEN = 0x00000100,
  GAMEACTIVITY_FLAG_LAYOUT_NO_LIMITS = 0x00000200,
  GAMEACTIVITY_FLAG_FULLSCREEN = 0x00000400,
  GAMEACTIVITY_FLAG_FORCE_NOT_FULLSCREEN = 0x00000800,
  GAMEACTIVITY_FLAG_DITHER = 0x00001000,
  GAMEACTIVITY_FLAG_SECURE = 0x00002000,
  GAMEACTIVITY_FLAG_SCALED = 0x00004000,
  GAMEACTIVITY_FLAG_IGNORE_CHEEK_PRESSES = 0x00008000,
  GAMEACTIVITY_FLAG_LAYOUT_INSET_DECOR = 0x00010000,
  GAMEACTIVITY_FLAG_ALT_FOCUSABLE_IM = 0x00020000,
  GAMEACTIVITY_FLAG_WATCH_OUTSIDE_TOUCH = 0x00040000,
  GAMEACTIVITY_FLAG_SHOW_WHEN_LOCKED = 0x00080000,
  GAMEACTIVITY_FLAG_SHOW_WALLPAPER = 0x00100000,
  GAMEACTIVITY_FLAG_TURN_SCREEN_ON = 0x00200000,
  GAMEACTIVITY_FLAG_DISMISS_KEYGUARD = 0x00400000
} 		enum
Flags for GameActivity_setWindowFlags, as per the Java API at android.view.WindowManager.LayoutParams.
GameActivityShowSoftInputFlags{
  GAMEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001,
  GAMEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002
} 		enum
Flags for GameActivity_showSoftInput; see the Java InputMethodManager API for documentation.

Typedefs
GameActivity typedef
struct GameActivity
This structure defines the native side of an android.app.GameActivity.
GameActivityCallbacks typedef
These are the callbacks the framework makes into a native application.
GameActivityKeyEvent typedef
Describe a key event that happened on the GameActivity SurfaceView.
GameActivityMotionEvent typedef
Describe a motion event that happened on the GameActivity SurfaceView.
GameActivityPointerAxes typedef
Describe information about a pointer, found in a GameActivityMotionEvent.
GameActivity_createFunc(GameActivity *activity, void *savedState, size_t savedStateSize) typedef
void
This is the function that must be in the native code to instantiate the application's native activity.
SaveInstanceStateRecallback)(const char *bytes, int len, void *context) typedef
void(*
A function the user should call from their callback with the data, its length and the library- supplied context.

Variables
GameActivity_onCreate
The name of the function that NativeInstance looks for when launching its native code.

Functions
GameActivityKeyEvent_fromJava(JNIEnv *env, jobject motionEvent, GameActivityKeyEvent *out_event)
void
Convert a Java KeyEvent to a GameActivityKeyEvent.
GameActivityMotionEvent_fromJava(JNIEnv *env, jobject motionEvent, GameActivityMotionEvent *out_event)
void
Convert a Java MotionEvent to a GameActivityMotionEvent.
GameActivityPointerAxes_disableAxis(int32_t axis)
void
Disable the specified axis.
GameActivityPointerAxes_enableAxis(int32_t axis)
void
Enable the specified axis, so that its value is reported in the GameActivityPointerAxes structures stored in a motion event.
GameActivityPointerAxes_getAxisValue(GameActivityPointerAxes *pointerInfo, int32_t axis)
float
Get the value of the requested axis.
GameActivityPointerAxes_getX(const GameActivityPointerAxes *pointerInfo)
float
Get the current X coordinate of the pointer.
GameActivityPointerAxes_getY(const GameActivityPointerAxes *pointerInfo)
float
Get the current Y coordinate of the pointer.
GameActivity_finish(GameActivity *activity)
void
Finish the given activity.
GameActivity_getTextInput(const GameActivity *activity)
GameTextInput *
Get a pointer to the GameTextInput library instance.
GameActivity_getTextInputState(GameActivity *activity, GameTextInputGetStateCallback callback, void *context)
void
Get the last-received text entry state (see documentation of the GameTextInputState struct in the Game Text Input library reference).
GameActivity_getWindowInsets(GameActivity *activity, GameCommonInsetsType type, ARect *insets)
void
Get the current window insets of the particular component.
GameActivity_hideSoftInput(GameActivity *activity, uint32_t flags)
void
Hide the IME while in the given activity.
GameActivity_setImeEditorInfo(GameActivity *activity, int inputType, int actionId, int imeOptions)
void
Set options on how the IME behaves when it is requested for text input.
GameActivity_setTextInputState(GameActivity *activity, const GameTextInputState *state)
void
Set the text entry state (see documentation of the GameTextInputState struct in the Game Text Input library reference).
GameActivity_setWindowFlags(GameActivity *activity, uint32_t addFlags, uint32_t removeFlags)
void
Change the window flags of the given activity.
GameActivity_showSoftInput(GameActivity *activity, uint32_t flags)
void
Show the IME while in the given activity.

Macros
GAMEACTIVITY_MAX_NUM_POINTERS_IN_MOTION_EVENT 8
The maximum number of pointers returned inside a motion event.
GAME_ACTIVITY_POINTER_INFO_AXIS_COUNT 48
The maximum number of axes supported in an Android MotionEvent.

Structs
GameActivity

This structure defines the native side of an android.app.GameActivity.

GameActivityCallbacks

These are the callbacks the framework makes into a native application.

GameActivityKeyEvent

Describe a key event that happened on the GameActivity SurfaceView.

GameActivityMotionEvent

Describe a motion event that happened on the GameActivity SurfaceView.

GameActivityPointerAxes

Describe information about a pointer, found in a GameActivityMotionEvent.

Enumerations

GameActivityHideSoftInputFlags

 GameActivityHideSoftInputFlags

Flags for GameActivity_hideSoftInput; see the Java InputMethodManager API for documentation.

Properties
GAMEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY

The soft input window should only be hidden if it was not explicitly shown by the user.

GAMEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS

The soft input window should normally be hidden, unless it was originally shown with GAMEACTIVITY_SHOW_SOFT_INPUT_FORCED.

GameActivitySetWindowFlags

 GameActivitySetWindowFlags

Flags for GameActivity_setWindowFlags, as per the Java API at android.view.WindowManager.LayoutParams.

Properties
GAMEACTIVITY_FLAG_ALLOW_LOCK_WHILE_SCREEN_ON

As long as this window is visible to the user, allow the lock screen to activate while the screen is on.

This can be used independently, or in combination with GAMEACTIVITY_FLAG_KEEP_SCREEN_ON and/or GAMEACTIVITY_FLAG_SHOW_WHEN_LOCKED
GAMEACTIVITY_FLAG_ALT_FOCUSABLE_IM

Invert the state of GAMEACTIVITY_FLAG_NOT_FOCUSABLE with respect to how this window interacts with the current method.

That is, if FLAG_NOT_FOCUSABLE is set and this flag is set, then the window will behave as if it needs to interact with the input method and thus be placed behind/away from it; if GAMEACTIVITY_FLAG_NOT_FOCUSABLE is not set and this flag is set, then the window will behave as if it doesn't need to interact with the input method and can be placed to use more space and cover the input method.

GAMEACTIVITY_FLAG_BLUR_BEHIND

Blur everything behind this window.

Deprecated. Blurring is no longer supported.

GAMEACTIVITY_FLAG_DIM_BEHIND

Everything behind this window will be dimmed.

GAMEACTIVITY_FLAG_DISMISS_KEYGUARD

When set the window will cause the keyguard to be dismissed, only if it is not a secure lock keyguard.

Because such a keyguard is not needed for security, it will never re-appear if the user navigates to another window (in contrast to GAMEACTIVITY_FLAG_SHOW_WHEN_LOCKED, which will only temporarily hide both secure and non-secure keyguards but ensure they reappear when the user moves to another UI that doesn't hide them). If the keyguard is currently active and is secure (requires an unlock pattern) than the user will still need to confirm it before seeing this window, unless GAMEACTIVITY_FLAG_SHOW_WHEN_LOCKED has also been set.

GAMEACTIVITY_FLAG_DITHER

Turn on dithering when compositing this window to the screen.

Deprecated. This flag is no longer used.

GAMEACTIVITY_FLAG_FORCE_NOT_FULLSCREEN

Override GAMEACTIVITY_FLAG_FULLSCREEN and force the screen decorations (such as the status bar) to be shown.

GAMEACTIVITY_FLAG_FULLSCREEN

Hide all screen decorations (such as the status bar) while this window is displayed.

This allows the window to use the entire display space for itself the status bar will be hidden when an app window with this flag set is on the top layer. A fullscreen window will ignore a value of GAMEACTIVITY_SOFT_INPUT_ADJUST_RESIZE; the window will stay fullscreen and will not resize.

GAMEACTIVITY_FLAG_IGNORE_CHEEK_PRESSES

Intended for windows that will often be used when the user is holding the screen against their face, it will aggressively filter the event stream to prevent unintended presses in this situation that may not be desired for a particular window, when such an event stream is detected, the application will receive a AMOTION_EVENT_ACTION_CANCEL to indicate this so applications can handle this accordingly by taking no action on the event until the finger is released.

GAMEACTIVITY_FLAG_KEEP_SCREEN_ON

As long as this window is visible to the user, keep the device's screen turned on and bright.

GAMEACTIVITY_FLAG_LAYOUT_INSET_DECOR

A special option only for use in combination with GAMEACTIVITY_FLAG_LAYOUT_IN_SCREEN.

When requesting layout in the screen your window may appear on top of or behind screen decorations such as the status bar. By also including this flag, the window manager will report the inset rectangle needed to ensure your content is not covered by screen decorations.

GAMEACTIVITY_FLAG_LAYOUT_IN_SCREEN

Place the window within the entire screen, ignoring decorations around the border (such as the status bar).

The window must correctly position its contents to take the screen decoration into account.

GAMEACTIVITY_FLAG_LAYOUT_NO_LIMITS

Allows the window to extend outside of the screen.

GAMEACTIVITY_FLAG_NOT_FOCUSABLE

This window won't ever get key input focus, so the user can not send key or other button events to it.

Those will instead go to whatever focusable window is behind it. This flag will also enable GAMEACTIVITY_FLAG_NOT_TOUCH_MODAL whether or not that is explicitly set.

Setting this flag also implies that the window will not need to interact with a soft input method, so it will be Z-ordered and positioned independently of any active input method (typically this means it gets Z-ordered on top of the input method, so it can use the full screen for its content and cover the input method if needed. You can use GAMEACTIVITY_FLAG_ALT_FOCUSABLE_IM to modify this behavior.

GAMEACTIVITY_FLAG_NOT_TOUCHABLE

This window can never receive touch events.

GAMEACTIVITY_FLAG_NOT_TOUCH_MODAL

Even when this window is focusable (its GAMEACTIVITY_FLAG_NOT_FOCUSABLE is not set), allow any pointer events outside of the window to be sent to the windows behind it.

Otherwise it will consume all pointer events itself, regardless of whether they are inside of the window.

GAMEACTIVITY_FLAG_SCALED

A special mode where the layout parameters are used to perform scaling of the surface when it is composited to the screen.

GAMEACTIVITY_FLAG_SECURE

Treat the content of the window as secure, preventing it from appearing in screenshots or from being viewed on non-secure displays.

GAMEACTIVITY_FLAG_SHOW_WALLPAPER

Ask that the system wallpaper be shown behind your window.

The window surface must be translucent to be able to actually see the wallpaper behind it; this flag just ensures that the wallpaper surface will be there if this window actually has translucent regions.

GAMEACTIVITY_FLAG_SHOW_WHEN_LOCKED

Special flag to let windows be shown when the screen is locked.

This will let application windows take precedence over key guard or any other lock screens. Can be used with GAMEACTIVITY_FLAG_KEEP_SCREEN_ON to turn screen on and display windows directly before showing the key guard window. Can be used with GAMEACTIVITY_FLAG_DISMISS_KEYGUARD to automatically fully dismisss non-secure keyguards. This flag only applies to the top-most full-screen window.

GAMEACTIVITY_FLAG_TOUCHABLE_WHEN_WAKING

When set, if the device is asleep when the touch screen is pressed, you will receive this first touch event.

Usually the first touch event is consumed by the system since the user can not see what they are pressing on.

Deprecated. This flag has no effect.

GAMEACTIVITY_FLAG_TURN_SCREEN_ON

When set as a window is being added or made visible, once the window has been shown then the system will poke the power manager's user activity (as if the user had woken up the device) to turn the screen on.

GAMEACTIVITY_FLAG_WATCH_OUTSIDE_TOUCH

If you have set GAMEACTIVITY_FLAG_NOT_TOUCH_MODAL, you can set this flag to receive a single special MotionEvent with the action AMOTION_EVENT_ACTION_OUTSIDE for touches that occur outside of your window.

Note that you will not receive the full down/move/up gesture, only the location of the first down as an AMOTION_EVENT_ACTION_OUTSIDE.

GameActivityShowSoftInputFlags

 GameActivityShowSoftInputFlags

Flags for GameActivity_showSoftInput; see the Java InputMethodManager API for documentation.

Properties
GAMEACTIVITY_SHOW_SOFT_INPUT_FORCED

The user has forced the input method open (such as by long-pressing menu) so it should not be closed until they explicitly do so.

GAMEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT

Implicit request to show the input window, not as the result of a direct request by the user.

Typedefs

GameActivity

struct GameActivity GameActivity

This structure defines the native side of an android.app.GameActivity.

It is created by the framework, and handed to the application's native code as it is being launched.

GameActivityCallbacks

struct GameActivityCallbacks GameActivityCallbacks

These are the callbacks the framework makes into a native application.

All of these callbacks happen on the main thread of the application. By default, all callbacks are NULL; set to a pointer to your own function to have it called.

GameActivityKeyEvent

struct GameActivityKeyEvent GameActivityKeyEvent

Describe a key event that happened on the GameActivity SurfaceView.

This is 1:1 mapping to the information contained in a Java KeyEvent (see https://developer.android.com/reference/android/view/KeyEvent).

GameActivityMotionEvent

struct GameActivityMotionEvent GameActivityMotionEvent

Describe a motion event that happened on the GameActivity SurfaceView.

This is 1:1 mapping to the information contained in a Java MotionEvent (see https://developer.android.com/reference/android/view/MotionEvent).

GameActivityPointerAxes

struct GameActivityPointerAxes GameActivityPointerAxes

Describe information about a pointer, found in a GameActivityMotionEvent.

You can read values directly from this structure, or use helper functions (GameActivityPointerAxes_getX, GameActivityPointerAxes_getY and GameActivityPointerAxes_getAxisValue).

The X axis and Y axis are enabled by default but any other axis that you want to read must be enabled first, using GameActivityPointerAxes_enableAxis.

See also: GameActivityMotionEvent

GameActivity_createFunc

void GameActivity_createFunc(GameActivity *activity, void *savedState, size_t savedStateSize)

This is the function that must be in the native code to instantiate the application's native activity.

It is called with the activity instance (see above); if the code is being instantiated from a previously saved instance, the savedState will be non-NULL and point to the saved data. You must make any copy of this data you need it will be released after you return from this function.

SaveInstanceStateRecallback

void(* SaveInstanceStateRecallback)(const char *bytes, int len, void *context)

A function the user should call from their callback with the data, its length and the library- supplied context.

Variables

GameActivity_onCreate

GameActivity_createFunc GameActivity_onCreate

The name of the function that NativeInstance looks for when launching its native code.

This is the default function that is used, you can specify "android.app.func_name" string meta-data in your manifest to use a different function.

Functions

GameActivityKeyEvent_fromJava

void GameActivityKeyEvent_fromJava(
  JNIEnv *env,
  jobject motionEvent,
  GameActivityKeyEvent *out_event
)

Convert a Java KeyEvent to a GameActivityKeyEvent.

This is done automatically by the GameActivity: see onKeyUp and onKeyDown to set a callback to consume the received events. This function can be used if you re-implement events handling in your own activity. Ownership of out_event is maintained by the caller.

GameActivityMotionEvent_fromJava

void GameActivityMotionEvent_fromJava(
  JNIEnv *env,
  jobject motionEvent,
  GameActivityMotionEvent *out_event
)

Convert a Java MotionEvent to a GameActivityMotionEvent.

This is done automatically by the GameActivity: see onTouchEvent to set a callback to consume the received events. This function can be used if you re-implement events handling in your own activity. Ownership of out_event is maintained by the caller.

GameActivityPointerAxes_disableAxis

void GameActivityPointerAxes_disableAxis(
  int32_t axis
)

Disable the specified axis.

Its value won't be reported in the GameActivityPointerAxes structures stored in a motion event anymore.

Apart from X and Y, any axis that you want to read must be enabled first, using GameActivityPointerAxes_enableAxis.

If the axis index is out of range, nothing is done.

GameActivityPointerAxes_enableAxis

void GameActivityPointerAxes_enableAxis(
  int32_t axis
)

Enable the specified axis, so that its value is reported in the GameActivityPointerAxes structures stored in a motion event.

You must enable any axis that you want to read, apart from AMOTION_EVENT_AXIS_X and AMOTION_EVENT_AXIS_Y that are enabled by default.

If the axis index is out of range, nothing is done.

GameActivityPointerAxes_getAxisValue

float GameActivityPointerAxes_getAxisValue(
  GameActivityPointerAxes *pointerInfo,
  int32_t axis
)

Get the value of the requested axis.

Apart from X and Y, any axis that you want to read must be enabled first, using GameActivityPointerAxes_enableAxis.

Find the valid enums for the axis (AMOTION_EVENT_AXIS_X, AMOTION_EVENT_AXIS_Y, AMOTION_EVENT_AXIS_PRESSURE...) in https://developer.android.com/ndk/reference/group/input.

Details
Parameters
pointerInfo
The structure containing information about the pointer, obtained from GameActivityMotionEvent.
axis
The axis to get the value from
Returns
The value of the axis, or 0 if the axis is invalid or was not enabled.

GameActivityPointerAxes_getX

float GameActivityPointerAxes_getX(
  const GameActivityPointerAxes *pointerInfo
)

Get the current X coordinate of the pointer.

GameActivityPointerAxes_getY

float GameActivityPointerAxes_getY(
  const GameActivityPointerAxes *pointerInfo
)

Get the current Y coordinate of the pointer.

GameActivity_finish

void GameActivity_finish(
  GameActivity *activity
)

Finish the given activity.

Its finish() method will be called, causing it to be stopped and destroyed. Note that this method can be called from any thread; it will send a message to the main thread of the process where the Java finish call will take place.

GameActivity_getTextInput

GameTextInput * GameActivity_getTextInput(
  const GameActivity *activity
)

Get a pointer to the GameTextInput library instance.

GameActivity_getTextInputState

void GameActivity_getTextInputState(
  GameActivity *activity,
  GameTextInputGetStateCallback callback,
  void *context
)

Get the last-received text entry state (see documentation of the GameTextInputState struct in the Game Text Input library reference).

GameActivity_getWindowInsets

void GameActivity_getWindowInsets(
  GameActivity *activity,
  GameCommonInsetsType type,
  ARect *insets
)

Get the current window insets of the particular component.

See https://developer.android.com/reference/androidx/core/view/WindowInsetsCompat.Type for more details. You can use these insets to influence what you show on the screen.

GameActivity_hideSoftInput

void GameActivity_hideSoftInput(
  GameActivity *activity,
  uint32_t flags
)

Hide the IME while in the given activity.

Calls InputMethodManager.hideSoftInput() for the given activity. Note that this method can be called from any thread; it will send a message to the main thread of the process where the Java finish call will take place.

GameActivity_setImeEditorInfo

void GameActivity_setImeEditorInfo(
  GameActivity *activity,
  int inputType,
  int actionId,
  int imeOptions
)

Set options on how the IME behaves when it is requested for text input.

See https://developer.android.com/reference/android/view/inputmethod/EditorInfo for the meaning of inputType, actionId and imeOptions.

Note that this function will attach the current thread to the JVM if it is not already attached, so the caller must detach the thread from the JVM before the thread is destroyed using DetachCurrentThread.

GameActivity_setTextInputState

void GameActivity_setTextInputState(
  GameActivity *activity,
  const GameTextInputState *state
)

Set the text entry state (see documentation of the GameTextInputState struct in the Game Text Input library reference).

Ownership of the state is maintained by the caller.

GameActivity_setWindowFlags

void GameActivity_setWindowFlags(
  GameActivity *activity,
  uint32_t addFlags,
  uint32_t removeFlags
)

Change the window flags of the given activity.

Calls getWindow().setFlags() of the given activity. Note that some flags must be set before the window decoration is created, see https://developer.android.com/reference/android/view/Window#setFlags(int,%20int). Note also that this method can be called from any thread; it will send a message to the main thread of the process where the Java finish call will take place.

GameActivity_showSoftInput

void GameActivity_showSoftInput(
  GameActivity *activity,
  uint32_t flags
)

Show the IME while in the given activity.

Calls InputMethodManager.showSoftInput() for the given activity. Note that this method can be called from any thread; it will send a message to the main thread of the process where the Java call will take place.

Macros

GAMEACTIVITY_MAX_NUM_POINTERS_IN_MOTION_EVENT

 GAMEACTIVITY_MAX_NUM_POINTERS_IN_MOTION_EVENT 8

The maximum number of pointers returned inside a motion event.

GAME_ACTIVITY_POINTER_INFO_AXIS_COUNT

 GAME_ACTIVITY_POINTER_INFO_AXIS_COUNT 48

The maximum number of axes supported in an Android MotionEvent.

See https://developer.android.com/ndk/reference/group/input.