frameworks/native: document native types and enums
Change-Id: Id94b610f27b87426abb30e13484cbd16990aa995
diff --git a/include/android/asset_manager.h b/include/android/asset_manager.h
index f5df46b..d654839 100644
--- a/include/android/asset_manager.h
+++ b/include/android/asset_manager.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Asset
+ * @{
+ */
+
+/**
+ * @file asset_manager.h
+ */
#ifndef ANDROID_ASSET_MANAGER_H
#define ANDROID_ASSET_MANAGER_H
@@ -23,19 +31,49 @@
#endif
struct AAssetManager;
+/**
+ * {@link AAssetManager} provides access to an application's raw assets by
+ * creating {@link AAsset} objects.
+ *
+ * AAssetManager is a wrapper to the low-level native implementation
+ * of the java {@link AAssetManager}, a pointer can be obtained using
+ * AAssetManager_fromJava().
+ *
+ * The asset hierarchy may be examined like a filesystem, using
+ * {@link AAssetDir} objects to peruse a single directory.
+ *
+ * A native {@link AAssetManager} pointer may be shared across multiple threads.
+ */
typedef struct AAssetManager AAssetManager;
struct AAssetDir;
+/**
+ * {@link AAssetDir} provides access to a chunk of the asset hierarchy as if
+ * it were a single directory. The contents are populated by the
+ * {@link AAssetManager}.
+ *
+ * The list of files will be sorted in ascending order by ASCII value.
+ */
typedef struct AAssetDir AAssetDir;
struct AAsset;
+/**
+ * {@link AAsset} provides access to a read-only asset.
+ *
+ * {@link AAsset} objects are NOT thread-safe, and should not be shared across
+ * threads.
+ */
typedef struct AAsset AAsset;
-/* Available modes for opening assets */
+/** Available access modes for opening assets with {@link AAssetManager_open} */
enum {
+ /** No specific information about how data will be accessed. **/
AASSET_MODE_UNKNOWN = 0,
+ /** Read chunks, and seek forward and backward. */
AASSET_MODE_RANDOM = 1,
+ /** Read sequentially, with an occasional forward seek. */
AASSET_MODE_STREAMING = 2,
+ /** Caller plans to ask for a read-only buffer with all data. */
AASSET_MODE_BUFFER = 3
};
@@ -173,3 +211,5 @@
#endif
#endif // ANDROID_ASSET_MANAGER_H
+
+/** @} */
diff --git a/include/android/asset_manager_jni.h b/include/android/asset_manager_jni.h
index aec2d3c..dcee17e 100644
--- a/include/android/asset_manager_jni.h
+++ b/include/android/asset_manager_jni.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Asset
+ * @{
+ */
+
+/**
+ * @file asset_manager_jni.h
+ */
#ifndef ANDROID_ASSET_MANAGER_JNI_H
#define ANDROID_ASSET_MANAGER_JNI_H
@@ -38,3 +46,5 @@
#endif
#endif // ANDROID_ASSET_MANAGER_JNI_H
+
+/** @} */
diff --git a/include/android/bitmap.h b/include/android/bitmap.h
index 6e18763..261e64f 100644
--- a/include/android/bitmap.h
+++ b/include/android/bitmap.h
@@ -14,6 +14,15 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Bitmap
+ * @{
+ */
+
+/**
+ * @file bitmap.h
+ */
+
#ifndef ANDROID_BITMAP_H
#define ANDROID_BITMAP_H
@@ -24,33 +33,52 @@
extern "C" {
#endif
-#define ANDROID_BITMAP_RESULT_SUCCESS 0
-#define ANDROID_BITMAP_RESULT_BAD_PARAMETER -1
-#define ANDROID_BITMAP_RESULT_JNI_EXCEPTION -2
-#define ANDROID_BITMAP_RESULT_ALLOCATION_FAILED -3
+/** AndroidBitmap functions result code. */
+enum {
+ /** Operation was successful. */
+ ANDROID_BITMAP_RESULT_SUCCESS = 0,
+ /** Bad parameter. */
+ ANDROID_BITMAP_RESULT_BAD_PARAMETER = -1,
+ /** JNI exception occured. */
+ ANDROID_BITMAP_RESULT_JNI_EXCEPTION = -2,
+ /** Allocation failed. */
+ ANDROID_BITMAP_RESULT_ALLOCATION_FAILED = -3,
+};
-/* Backward compatibility: this macro used to be misspelled. */
+/** Backward compatibility: this macro used to be misspelled. */
#define ANDROID_BITMAP_RESUT_SUCCESS ANDROID_BITMAP_RESULT_SUCCESS
+/** Bitmap pixel format. */
enum AndroidBitmapFormat {
+ /** No format. */
ANDROID_BITMAP_FORMAT_NONE = 0,
+ /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits. **/
ANDROID_BITMAP_FORMAT_RGBA_8888 = 1,
+ /** Red: 5 bits, Green: 6 bits, Blue: 5 bits. **/
ANDROID_BITMAP_FORMAT_RGB_565 = 4,
+ /** Red: 4 bits, Green: 4 bits, Blue: 4 bits, Alpha: 4 bits. **/
ANDROID_BITMAP_FORMAT_RGBA_4444 = 7,
+ /** Deprecated. */
ANDROID_BITMAP_FORMAT_A_8 = 8,
};
+/** Bitmap info, see AndroidBitmap_getInfo(). */
typedef struct {
+ /** The bitmap width in pixels. */
uint32_t width;
+ /** The bitmap height in pixels. */
uint32_t height;
+ /** The number of byte per row. */
uint32_t stride;
+ /** The bitmap pixel format. See {@link AndroidBitmapFormat} */
int32_t format;
+ /** Unused. */
uint32_t flags; // 0 for now
} AndroidBitmapInfo;
/**
- * Given a java bitmap object, fill out the AndroidBitmap struct for it.
- * If the call fails, the info parameter will be ignored
+ * Given a java bitmap object, fill out the AndroidBitmapInfo struct for it.
+ * If the call fails, the info parameter will be ignored.
*/
int AndroidBitmap_getInfo(JNIEnv* env, jobject jbitmap,
AndroidBitmapInfo* info);
@@ -71,7 +99,7 @@
int AndroidBitmap_lockPixels(JNIEnv* env, jobject jbitmap, void** addrPtr);
/**
- * Call this to balanace a successful call to AndroidBitmap_lockPixels
+ * Call this to balance a successful call to AndroidBitmap_lockPixels.
*/
int AndroidBitmap_unlockPixels(JNIEnv* env, jobject jbitmap);
@@ -80,3 +108,5 @@
#endif
#endif
+
+/** @} */
diff --git a/include/android/configuration.h b/include/android/configuration.h
index be00066..287865e 100644
--- a/include/android/configuration.h
+++ b/include/android/configuration.h
@@ -14,6 +14,15 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Configuration
+ * @{
+ */
+
+/**
+ * @file configuration.h
+ */
+
#ifndef ANDROID_CONFIGURATION_H
#define ANDROID_CONFIGURATION_H
@@ -24,98 +33,395 @@
#endif
struct AConfiguration;
+/**
+ * {@link AConfiguration} is an opaque type used to get and set
+ * various subsystem configurations.
+ *
+ * A {@link AConfiguration} pointer can be obtained using:
+ * - AConfiguration_new()
+ * - AConfiguration_fromAssetManager()
+ */
typedef struct AConfiguration AConfiguration;
+
+/**
+ * Define flags and constants for various subsystem configurations.
+ */
enum {
+ /** Orientation: not specified. */
ACONFIGURATION_ORIENTATION_ANY = 0x0000,
+ /**
+ * Orientation: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#OrientationQualifier">port</a>
+ * resource qualifier.
+ */
ACONFIGURATION_ORIENTATION_PORT = 0x0001,
+ /**
+ * Orientation: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#OrientationQualifier">land</a>
+ * resource qualifier.
+ */
ACONFIGURATION_ORIENTATION_LAND = 0x0002,
+ /** @deprecated Not currently supported or used. */
ACONFIGURATION_ORIENTATION_SQUARE = 0x0003,
+ /** Touchscreen: not specified. */
ACONFIGURATION_TOUCHSCREEN_ANY = 0x0000,
+ /**
+ * Touchscreen: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#TouchscreenQualifier">notouch</a>
+ * resource qualifier.
+ */
ACONFIGURATION_TOUCHSCREEN_NOTOUCH = 0x0001,
+ /** @deprecated Not currently supported or used. */
ACONFIGURATION_TOUCHSCREEN_STYLUS = 0x0002,
+ /**
+ * Touchscreen: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#TouchscreenQualifier">finger</a>
+ * resource qualifier.
+ */
ACONFIGURATION_TOUCHSCREEN_FINGER = 0x0003,
+ /** Density: default density. */
ACONFIGURATION_DENSITY_DEFAULT = 0,
+ /**
+ * Density: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#DensityQualifier">ldpi</a>
+ * resource qualifier.
+ */
ACONFIGURATION_DENSITY_LOW = 120,
+ /**
+ * Density: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#DensityQualifier">mdpi</a>
+ * resource qualifier.
+ */
ACONFIGURATION_DENSITY_MEDIUM = 160,
+ /**
+ * Density: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#DensityQualifier">tvdpi</a>
+ * resource qualifier.
+ */
ACONFIGURATION_DENSITY_TV = 213,
+ /**
+ * Density: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#DensityQualifier">hdpi</a>
+ * resource qualifier.
+ */
ACONFIGURATION_DENSITY_HIGH = 240,
+ /**
+ * Density: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#DensityQualifier">xhdpi</a>
+ * resource qualifier.
+ */
ACONFIGURATION_DENSITY_XHIGH = 320,
+ /**
+ * Density: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#DensityQualifier">xxhdpi</a>
+ * resource qualifier.
+ */
ACONFIGURATION_DENSITY_XXHIGH = 480,
+ /**
+ * Density: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#DensityQualifier">xxxhdpi</a>
+ * resource qualifier.
+ */
ACONFIGURATION_DENSITY_XXXHIGH = 640,
+ /** Density: any density. */
ACONFIGURATION_DENSITY_ANY = 0xfffe,
+ /** Density: no density specified. */
ACONFIGURATION_DENSITY_NONE = 0xffff,
+ /** Keyboard: not specified. */
ACONFIGURATION_KEYBOARD_ANY = 0x0000,
+ /**
+ * Keyboard: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ImeQualifier">nokeys</a>
+ * resource qualifier.
+ */
ACONFIGURATION_KEYBOARD_NOKEYS = 0x0001,
+ /**
+ * Keyboard: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ImeQualifier">qwerty</a>
+ * resource qualifier.
+ */
ACONFIGURATION_KEYBOARD_QWERTY = 0x0002,
+ /**
+ * Keyboard: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ImeQualifier">12key</a>
+ * resource qualifier.
+ */
ACONFIGURATION_KEYBOARD_12KEY = 0x0003,
+ /** Navigation: not specified. */
ACONFIGURATION_NAVIGATION_ANY = 0x0000,
+ /**
+ * Navigation: value corresponding to the
+ * <a href="@@dacRoot/guide/topics/resources/providing-resources.html#NavigationQualifier">nonav</a>
+ * resource qualifier.
+ */
ACONFIGURATION_NAVIGATION_NONAV = 0x0001,
+ /**
+ * Navigation: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#NavigationQualifier">dpad</a>
+ * resource qualifier.
+ */
ACONFIGURATION_NAVIGATION_DPAD = 0x0002,
+ /**
+ * Navigation: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#NavigationQualifier">trackball</a>
+ * resource qualifier.
+ */
ACONFIGURATION_NAVIGATION_TRACKBALL = 0x0003,
+ /**
+ * Navigation: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#NavigationQualifier">wheel</a>
+ * resource qualifier.
+ */
ACONFIGURATION_NAVIGATION_WHEEL = 0x0004,
+ /** Keyboard availability: not specified. */
ACONFIGURATION_KEYSHIDDEN_ANY = 0x0000,
+ /**
+ * Keyboard availability: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#KeyboardAvailQualifier">keysexposed</a>
+ * resource qualifier.
+ */
ACONFIGURATION_KEYSHIDDEN_NO = 0x0001,
+ /**
+ * Keyboard availability: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#KeyboardAvailQualifier">keyshidden</a>
+ * resource qualifier.
+ */
ACONFIGURATION_KEYSHIDDEN_YES = 0x0002,
+ /**
+ * Keyboard availability: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#KeyboardAvailQualifier">keyssoft</a>
+ * resource qualifier.
+ */
ACONFIGURATION_KEYSHIDDEN_SOFT = 0x0003,
+ /** Navigation availability: not specified. */
ACONFIGURATION_NAVHIDDEN_ANY = 0x0000,
+ /**
+ * Navigation availability: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#NavAvailQualifier">navexposed</a>
+ * resource qualifier.
+ */
ACONFIGURATION_NAVHIDDEN_NO = 0x0001,
+ /**
+ * Navigation availability: value corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#NavAvailQualifier">navhidden</a>
+ * resource qualifier.
+ */
ACONFIGURATION_NAVHIDDEN_YES = 0x0002,
+ /** Screen size: not specified. */
ACONFIGURATION_SCREENSIZE_ANY = 0x00,
+ /**
+ * Screen size: value indicating the screen is at least
+ * approximately 320x426 dp units, corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ScreenSizeQualifier">small</a>
+ * resource qualifier.
+ */
ACONFIGURATION_SCREENSIZE_SMALL = 0x01,
+ /**
+ * Screen size: value indicating the screen is at least
+ * approximately 320x470 dp units, corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ScreenSizeQualifier">normal</a>
+ * resource qualifier.
+ */
ACONFIGURATION_SCREENSIZE_NORMAL = 0x02,
+ /**
+ * Screen size: value indicating the screen is at least
+ * approximately 480x640 dp units, corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ScreenSizeQualifier">large</a>
+ * resource qualifier.
+ */
ACONFIGURATION_SCREENSIZE_LARGE = 0x03,
+ /**
+ * Screen size: value indicating the screen is at least
+ * approximately 720x960 dp units, corresponding to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ScreenSizeQualifier">xlarge</a>
+ * resource qualifier.
+ */
ACONFIGURATION_SCREENSIZE_XLARGE = 0x04,
+ /** Screen layout: not specified. */
ACONFIGURATION_SCREENLONG_ANY = 0x00,
+ /**
+ * Screen layout: value that corresponds to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ScreenAspectQualifier">notlong</a>
+ * resource qualifier.
+ */
ACONFIGURATION_SCREENLONG_NO = 0x1,
+ /**
+ * Screen layout: value that corresponds to the
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ScreenAspectQualifier">long</a>
+ * resource qualifier.
+ */
ACONFIGURATION_SCREENLONG_YES = 0x2,
+ /** UI mode: not specified. */
ACONFIGURATION_UI_MODE_TYPE_ANY = 0x00,
+ /**
+ * UI mode: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#UiModeQualifier">no
+ * UI mode type</a> resource qualifier specified.
+ */
ACONFIGURATION_UI_MODE_TYPE_NORMAL = 0x01,
+ /**
+ * UI mode: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#UiModeQualifier">desk</a> resource qualifier specified.
+ */
ACONFIGURATION_UI_MODE_TYPE_DESK = 0x02,
+ /**
+ * UI mode: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#UiModeQualifier">car</a> resource qualifier specified.
+ */
ACONFIGURATION_UI_MODE_TYPE_CAR = 0x03,
+ /**
+ * UI mode: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#UiModeQualifier">television</a> resource qualifier specified.
+ */
ACONFIGURATION_UI_MODE_TYPE_TELEVISION = 0x04,
+ /**
+ * UI mode: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#UiModeQualifier">appliance</a> resource qualifier specified.
+ */
ACONFIGURATION_UI_MODE_TYPE_APPLIANCE = 0x05,
+ /**
+ * UI mode: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#UiModeQualifier">watch</a> resource qualifier specified.
+ */
ACONFIGURATION_UI_MODE_TYPE_WATCH = 0x06,
+ /** UI night mode: not specified.*/
ACONFIGURATION_UI_MODE_NIGHT_ANY = 0x00,
+ /**
+ * UI night mode: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#NightQualifier">notnight</a> resource qualifier specified.
+ */
ACONFIGURATION_UI_MODE_NIGHT_NO = 0x1,
+ /**
+ * UI night mode: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#NightQualifier">night</a> resource qualifier specified.
+ */
ACONFIGURATION_UI_MODE_NIGHT_YES = 0x2,
+ /** Screen width DPI: not specified. */
ACONFIGURATION_SCREEN_WIDTH_DP_ANY = 0x0000,
+ /** Screen height DPI: not specified. */
ACONFIGURATION_SCREEN_HEIGHT_DP_ANY = 0x0000,
+ /** Smallest screen width DPI: not specified.*/
ACONFIGURATION_SMALLEST_SCREEN_WIDTH_DP_ANY = 0x0000,
+ /** Layout direction: not specified. */
ACONFIGURATION_LAYOUTDIR_ANY = 0x00,
+ /**
+ * Layout direction: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#LayoutDirectionQualifier">ldltr</a> resource qualifier specified.
+ */
ACONFIGURATION_LAYOUTDIR_LTR = 0x01,
+ /**
+ * Layout direction: value that corresponds to
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#LayoutDirectionQualifier">ldrtl</a> resource qualifier specified.
+ */
ACONFIGURATION_LAYOUTDIR_RTL = 0x02,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#MccQualifier">mcc</a>
+ * configuration.
+ */
ACONFIGURATION_MCC = 0x0001,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#MccQualifier">mnc</a>
+ * configuration.
+ */
ACONFIGURATION_MNC = 0x0002,
+ /**
+ * Bit mask for
+ * <a href="{@docRoot}guide/topics/resources/providing-resources.html#LocaleQualifier">locale</a>
+ * configuration.
+ */
ACONFIGURATION_LOCALE = 0x0004,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#TouchscreenQualifier">touchscreen</a>
+ * configuration.
+ */
ACONFIGURATION_TOUCHSCREEN = 0x0008,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ImeQualifier">keyboard</a>
+ * configuration.
+ */
ACONFIGURATION_KEYBOARD = 0x0010,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#KeyboardAvailQualifier">keyboardHidden</a>
+ * configuration.
+ */
ACONFIGURATION_KEYBOARD_HIDDEN = 0x0020,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#NavigationQualifier">navigation</a>
+ * configuration.
+ */
ACONFIGURATION_NAVIGATION = 0x0040,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#OrientationQualifier">orientation</a>
+ * configuration.
+ */
ACONFIGURATION_ORIENTATION = 0x0080,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#DensityQualifier">density</a>
+ * configuration.
+ */
ACONFIGURATION_DENSITY = 0x0100,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#ScreenSizeQualifier">screen size</a>
+ * configuration.
+ */
ACONFIGURATION_SCREEN_SIZE = 0x0200,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#VersionQualifier">platform version</a>
+ * configuration.
+ */
ACONFIGURATION_VERSION = 0x0400,
+ /**
+ * Bit mask for screen layout configuration.
+ */
ACONFIGURATION_SCREEN_LAYOUT = 0x0800,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#UiModeQualifier">ui mode</a>
+ * configuration.
+ */
ACONFIGURATION_UI_MODE = 0x1000,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#SmallestScreenWidthQualifier">smallest screen width</a>
+ * configuration.
+ */
ACONFIGURATION_SMALLEST_SCREEN_SIZE = 0x2000,
+ /**
+ * Bit mask for
+ * <a href="@dacRoot/guide/topics/resources/providing-resources.html#LayoutDirectionQualifier">layout direction</a>
+ * configuration.
+ */
ACONFIGURATION_LAYOUTDIR = 0x4000,
-
+ /**
+ * Constant used to to represent MNC (Mobile Network Code) zero.
+ * 0 cannot be used, since it is used to represent an undefined MNC.
+ */
ACONFIGURATION_MNC_ZERO = 0xffff,
};
@@ -132,7 +438,7 @@
/**
* Create and return a new AConfiguration based on the current configuration in
- * use in the given AssetManager.
+ * use in the given {@link AAssetManager}.
*/
void AConfiguration_fromAssetManager(AConfiguration* out, AAssetManager* am);
@@ -383,3 +689,5 @@
#endif
#endif // ANDROID_CONFIGURATION_H
+
+/** @} */
diff --git a/include/android/input.h b/include/android/input.h
index a660761..b11af84 100644
--- a/include/android/input.h
+++ b/include/android/input.h
@@ -14,6 +14,15 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Input
+ * @{
+ */
+
+/**
+ * @file input.h
+ */
+
#ifndef _ANDROID_INPUT_H
#define _ANDROID_INPUT_H
@@ -49,247 +58,271 @@
extern "C" {
#endif
-/*
+/**
* Key states (may be returned by queries about the current state of a
* particular key code, scan code or switch).
*/
enum {
- /* The key state is unknown or the requested key itself is not supported. */
+ /** The key state is unknown or the requested key itself is not supported. */
AKEY_STATE_UNKNOWN = -1,
- /* The key is up. */
+ /** The key is up. */
AKEY_STATE_UP = 0,
- /* The key is down. */
+ /** The key is down. */
AKEY_STATE_DOWN = 1,
- /* The key is down but is a virtual key press that is being emulated by the system. */
+ /** The key is down but is a virtual key press that is being emulated by the system. */
AKEY_STATE_VIRTUAL = 2
};
-/*
+/**
* Meta key / modifer state.
*/
enum {
- /* No meta keys are pressed. */
+ /** No meta keys are pressed. */
AMETA_NONE = 0,
- /* This mask is used to check whether one of the ALT meta keys is pressed. */
+ /** This mask is used to check whether one of the ALT meta keys is pressed. */
AMETA_ALT_ON = 0x02,
- /* This mask is used to check whether the left ALT meta key is pressed. */
+ /** This mask is used to check whether the left ALT meta key is pressed. */
AMETA_ALT_LEFT_ON = 0x10,
- /* This mask is used to check whether the right ALT meta key is pressed. */
+ /** This mask is used to check whether the right ALT meta key is pressed. */
AMETA_ALT_RIGHT_ON = 0x20,
- /* This mask is used to check whether one of the SHIFT meta keys is pressed. */
+ /** This mask is used to check whether one of the SHIFT meta keys is pressed. */
AMETA_SHIFT_ON = 0x01,
- /* This mask is used to check whether the left SHIFT meta key is pressed. */
+ /** This mask is used to check whether the left SHIFT meta key is pressed. */
AMETA_SHIFT_LEFT_ON = 0x40,
- /* This mask is used to check whether the right SHIFT meta key is pressed. */
+ /** This mask is used to check whether the right SHIFT meta key is pressed. */
AMETA_SHIFT_RIGHT_ON = 0x80,
- /* This mask is used to check whether the SYM meta key is pressed. */
+ /** This mask is used to check whether the SYM meta key is pressed. */
AMETA_SYM_ON = 0x04,
- /* This mask is used to check whether the FUNCTION meta key is pressed. */
+ /** This mask is used to check whether the FUNCTION meta key is pressed. */
AMETA_FUNCTION_ON = 0x08,
- /* This mask is used to check whether one of the CTRL meta keys is pressed. */
+ /** This mask is used to check whether one of the CTRL meta keys is pressed. */
AMETA_CTRL_ON = 0x1000,
- /* This mask is used to check whether the left CTRL meta key is pressed. */
+ /** This mask is used to check whether the left CTRL meta key is pressed. */
AMETA_CTRL_LEFT_ON = 0x2000,
- /* This mask is used to check whether the right CTRL meta key is pressed. */
+ /** This mask is used to check whether the right CTRL meta key is pressed. */
AMETA_CTRL_RIGHT_ON = 0x4000,
- /* This mask is used to check whether one of the META meta keys is pressed. */
+ /** This mask is used to check whether one of the META meta keys is pressed. */
AMETA_META_ON = 0x10000,
- /* This mask is used to check whether the left META meta key is pressed. */
+ /** This mask is used to check whether the left META meta key is pressed. */
AMETA_META_LEFT_ON = 0x20000,
- /* This mask is used to check whether the right META meta key is pressed. */
+ /** This mask is used to check whether the right META meta key is pressed. */
AMETA_META_RIGHT_ON = 0x40000,
- /* This mask is used to check whether the CAPS LOCK meta key is on. */
+ /** This mask is used to check whether the CAPS LOCK meta key is on. */
AMETA_CAPS_LOCK_ON = 0x100000,
- /* This mask is used to check whether the NUM LOCK meta key is on. */
+ /** This mask is used to check whether the NUM LOCK meta key is on. */
AMETA_NUM_LOCK_ON = 0x200000,
- /* This mask is used to check whether the SCROLL LOCK meta key is on. */
+ /** This mask is used to check whether the SCROLL LOCK meta key is on. */
AMETA_SCROLL_LOCK_ON = 0x400000,
};
-/*
+struct AInputEvent;
+/**
* Input events.
*
* Input events are opaque structures. Use the provided accessors functions to
* read their properties.
*/
-struct AInputEvent;
typedef struct AInputEvent AInputEvent;
-/*
+/**
* Input event types.
*/
enum {
- /* Indicates that the input event is a key event. */
+ /** Indicates that the input event is a key event. */
AINPUT_EVENT_TYPE_KEY = 1,
- /* Indicates that the input event is a motion event. */
+ /** Indicates that the input event is a motion event. */
AINPUT_EVENT_TYPE_MOTION = 2
};
-/*
+/**
* Key event actions.
*/
enum {
- /* The key has been pressed down. */
+ /** The key has been pressed down. */
AKEY_EVENT_ACTION_DOWN = 0,
- /* The key has been released. */
+ /** The key has been released. */
AKEY_EVENT_ACTION_UP = 1,
- /* Multiple duplicate key events have occurred in a row, or a complex string is
- * being delivered. The repeat_count property of the key event contains the number
- * of times the given key code should be executed.
+ /**
+ * Multiple duplicate key events have occurred in a row, or a
+ * complex string is being delivered. The repeat_count property
+ * of the key event contains the number of times the given key
+ * code should be executed.
*/
AKEY_EVENT_ACTION_MULTIPLE = 2
};
-/*
+/**
* Key event flags.
*/
enum {
- /* This mask is set if the device woke because of this key event. */
+ /** This mask is set if the device woke because of this key event. */
AKEY_EVENT_FLAG_WOKE_HERE = 0x1,
- /* This mask is set if the key event was generated by a software keyboard. */
+ /** This mask is set if the key event was generated by a software keyboard. */
AKEY_EVENT_FLAG_SOFT_KEYBOARD = 0x2,
- /* This mask is set if we don't want the key event to cause us to leave touch mode. */
+ /** This mask is set if we don't want the key event to cause us to leave touch mode. */
AKEY_EVENT_FLAG_KEEP_TOUCH_MODE = 0x4,
- /* This mask is set if an event was known to come from a trusted part
- * of the system. That is, the event is known to come from the user,
- * and could not have been spoofed by a third party component. */
+ /**
+ * This mask is set if an event was known to come from a trusted
+ * part of the system. That is, the event is known to come from
+ * the user, and could not have been spoofed by a third party
+ * component.
+ */
AKEY_EVENT_FLAG_FROM_SYSTEM = 0x8,
- /* This mask is used for compatibility, to identify enter keys that are
+ /**
+ * This mask is used for compatibility, to identify enter keys that are
* coming from an IME whose enter key has been auto-labelled "next" or
* "done". This allows TextView to dispatch these as normal enter keys
* for old applications, but still do the appropriate action when
- * receiving them. */
+ * receiving them.
+ */
AKEY_EVENT_FLAG_EDITOR_ACTION = 0x10,
- /* When associated with up key events, this indicates that the key press
+ /**
+ * When associated with up key events, this indicates that the key press
* has been canceled. Typically this is used with virtual touch screen
* keys, where the user can slide from the virtual key area on to the
* display: in that case, the application will receive a canceled up
* event and should not perform the action normally associated with the
* key. Note that for this to work, the application can not perform an
* action for a key until it receives an up or the long press timeout has
- * expired. */
+ * expired.
+ */
AKEY_EVENT_FLAG_CANCELED = 0x20,
- /* This key event was generated by a virtual (on-screen) hard key area.
+ /**
+ * This key event was generated by a virtual (on-screen) hard key area.
* Typically this is an area of the touchscreen, outside of the regular
- * display, dedicated to "hardware" buttons. */
+ * display, dedicated to "hardware" buttons.
+ */
AKEY_EVENT_FLAG_VIRTUAL_HARD_KEY = 0x40,
- /* This flag is set for the first key repeat that occurs after the
- * long press timeout. */
+ /**
+ * This flag is set for the first key repeat that occurs after the
+ * long press timeout.
+ */
AKEY_EVENT_FLAG_LONG_PRESS = 0x80,
- /* Set when a key event has AKEY_EVENT_FLAG_CANCELED set because a long
- * press action was executed while it was down. */
+ /**
+ * Set when a key event has AKEY_EVENT_FLAG_CANCELED set because a long
+ * press action was executed while it was down.
+ */
AKEY_EVENT_FLAG_CANCELED_LONG_PRESS = 0x100,
- /* Set for AKEY_EVENT_ACTION_UP when this event's key code is still being
+ /**
+ * Set for AKEY_EVENT_ACTION_UP when this event's key code is still being
* tracked from its initial down. That is, somebody requested that tracking
* started on the key down and a long press has not caused
- * the tracking to be canceled. */
+ * the tracking to be canceled.
+ */
AKEY_EVENT_FLAG_TRACKING = 0x200,
- /* Set when a key event has been synthesized to implement default behavior
+ /**
+ * Set when a key event has been synthesized to implement default behavior
* for an event that the application did not handle.
* Fallback key events are generated by unhandled trackball motions
* (to emulate a directional keypad) and by certain unhandled key presses
* that are declared in the key map (such as special function numeric keypad
- * keys when numlock is off). */
+ * keys when numlock is off).
+ */
AKEY_EVENT_FLAG_FALLBACK = 0x400,
};
-/*
- * Motion event actions.
- */
-
-/* Bit shift for the action bits holding the pointer index as
+/**
+ * Bit shift for the action bits holding the pointer index as
* defined by AMOTION_EVENT_ACTION_POINTER_INDEX_MASK.
*/
#define AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT 8
+/** Motion event actions */
enum {
- /* Bit mask of the parts of the action code that are the action itself.
- */
+ /** Bit mask of the parts of the action code that are the action itself. */
AMOTION_EVENT_ACTION_MASK = 0xff,
- /* Bits in the action code that represent a pointer index, used with
+ /**
+ * Bits in the action code that represent a pointer index, used with
* AMOTION_EVENT_ACTION_POINTER_DOWN and AMOTION_EVENT_ACTION_POINTER_UP. Shifting
* down by AMOTION_EVENT_ACTION_POINTER_INDEX_SHIFT provides the actual pointer
* index where the data for the pointer going up or down can be found.
*/
AMOTION_EVENT_ACTION_POINTER_INDEX_MASK = 0xff00,
- /* A pressed gesture has started, the motion contains the initial starting location.
- */
+ /** A pressed gesture has started, the motion contains the initial starting location. */
AMOTION_EVENT_ACTION_DOWN = 0,
- /* A pressed gesture has finished, the motion contains the final release location
+ /**
+ * A pressed gesture has finished, the motion contains the final release location
* as well as any intermediate points since the last down or move event.
*/
AMOTION_EVENT_ACTION_UP = 1,
- /* A change has happened during a press gesture (between AMOTION_EVENT_ACTION_DOWN and
+ /**
+ * A change has happened during a press gesture (between AMOTION_EVENT_ACTION_DOWN and
* AMOTION_EVENT_ACTION_UP). The motion contains the most recent point, as well as
* any intermediate points since the last down or move event.
*/
AMOTION_EVENT_ACTION_MOVE = 2,
- /* The current gesture has been aborted.
+ /**
+ * The current gesture has been aborted.
* You will not receive any more points in it. You should treat this as
* an up event, but not perform any action that you normally would.
*/
AMOTION_EVENT_ACTION_CANCEL = 3,
- /* A movement has happened outside of the normal bounds of the UI element.
+ /**
+ * A movement has happened outside of the normal bounds of the UI element.
* This does not provide a full gesture, but only the initial location of the movement/touch.
*/
AMOTION_EVENT_ACTION_OUTSIDE = 4,
- /* A non-primary pointer has gone down.
+ /**
+ * A non-primary pointer has gone down.
* The bits in AMOTION_EVENT_ACTION_POINTER_INDEX_MASK indicate which pointer changed.
*/
AMOTION_EVENT_ACTION_POINTER_DOWN = 5,
- /* A non-primary pointer has gone up.
+ /**
+ * A non-primary pointer has gone up.
* The bits in AMOTION_EVENT_ACTION_POINTER_INDEX_MASK indicate which pointer changed.
*/
AMOTION_EVENT_ACTION_POINTER_UP = 6,
- /* A change happened but the pointer is not down (unlike AMOTION_EVENT_ACTION_MOVE).
+ /**
+ * A change happened but the pointer is not down (unlike AMOTION_EVENT_ACTION_MOVE).
* The motion contains the most recent point, as well as any intermediate points since
* the last hover move event.
*/
AMOTION_EVENT_ACTION_HOVER_MOVE = 7,
- /* The motion event contains relative vertical and/or horizontal scroll offsets.
+ /**
+ * The motion event contains relative vertical and/or horizontal scroll offsets.
* Use getAxisValue to retrieve the information from AMOTION_EVENT_AXIS_VSCROLL
* and AMOTION_EVENT_AXIS_HSCROLL.
* The pointer may or may not be down when this event is dispatched.
@@ -298,20 +331,19 @@
*/
AMOTION_EVENT_ACTION_SCROLL = 8,
- /* The pointer is not down but has entered the boundaries of a window or view.
- */
+ /** The pointer is not down but has entered the boundaries of a window or view. */
AMOTION_EVENT_ACTION_HOVER_ENTER = 9,
- /* The pointer is not down but has exited the boundaries of a window or view.
- */
+ /** The pointer is not down but has exited the boundaries of a window or view. */
AMOTION_EVENT_ACTION_HOVER_EXIT = 10,
};
-/*
+/**
* Motion event flags.
*/
enum {
- /* This flag indicates that the window that received this motion event is partly
+ /**
+ * This flag indicates that the window that received this motion event is partly
* or wholly obscured by another visible window above it. This flag is set to true
* even if the event did not directly pass through the obscured area.
* A security sensitive application can check this flag to identify situations in which
@@ -323,170 +355,509 @@
AMOTION_EVENT_FLAG_WINDOW_IS_OBSCURED = 0x1,
};
-/*
+/**
* Motion event edge touch flags.
*/
enum {
- /* No edges intersected */
+ /** No edges intersected. */
AMOTION_EVENT_EDGE_FLAG_NONE = 0,
- /* Flag indicating the motion event intersected the top edge of the screen. */
+ /** Flag indicating the motion event intersected the top edge of the screen. */
AMOTION_EVENT_EDGE_FLAG_TOP = 0x01,
- /* Flag indicating the motion event intersected the bottom edge of the screen. */
+ /** Flag indicating the motion event intersected the bottom edge of the screen. */
AMOTION_EVENT_EDGE_FLAG_BOTTOM = 0x02,
- /* Flag indicating the motion event intersected the left edge of the screen. */
+ /** Flag indicating the motion event intersected the left edge of the screen. */
AMOTION_EVENT_EDGE_FLAG_LEFT = 0x04,
- /* Flag indicating the motion event intersected the right edge of the screen. */
+ /** Flag indicating the motion event intersected the right edge of the screen. */
AMOTION_EVENT_EDGE_FLAG_RIGHT = 0x08
};
-/*
+/**
* Constants that identify each individual axis of a motion event.
- * Refer to the documentation on the MotionEvent class for descriptions of each axis.
+ * @anchor AMOTION_EVENT_AXIS
*/
enum {
+ /**
+ * Axis constant: X axis of a motion event.
+ *
+ * - For a touch screen, reports the absolute X screen position of the center of
+ * the touch contact area. The units are display pixels.
+ * - For a touch pad, reports the absolute X surface position of the center of the touch
+ * contact area. The units are device-dependent.
+ * - For a mouse, reports the absolute X screen position of the mouse pointer.
+ * The units are display pixels.
+ * - For a trackball, reports the relative horizontal displacement of the trackball.
+ * The value is normalized to a range from -1.0 (left) to 1.0 (right).
+ * - For a joystick, reports the absolute X position of the joystick.
+ * The value is normalized to a range from -1.0 (left) to 1.0 (right).
+ */
AMOTION_EVENT_AXIS_X = 0,
+ /**
+ * Axis constant: Y axis of a motion event.
+ *
+ * - For a touch screen, reports the absolute Y screen position of the center of
+ * the touch contact area. The units are display pixels.
+ * - For a touch pad, reports the absolute Y surface position of the center of the touch
+ * contact area. The units are device-dependent.
+ * - For a mouse, reports the absolute Y screen position of the mouse pointer.
+ * The units are display pixels.
+ * - For a trackball, reports the relative vertical displacement of the trackball.
+ * The value is normalized to a range from -1.0 (up) to 1.0 (down).
+ * - For a joystick, reports the absolute Y position of the joystick.
+ * The value is normalized to a range from -1.0 (up or far) to 1.0 (down or near).
+ */
AMOTION_EVENT_AXIS_Y = 1,
+ /**
+ * Axis constant: Pressure axis of a motion event.
+ *
+ * - For a touch screen or touch pad, reports the approximate pressure applied to the surface
+ * by a finger or other tool. The value is normalized to a range from
+ * 0 (no pressure at all) to 1 (normal pressure), although values higher than 1
+ * may be generated depending on the calibration of the input device.
+ * - For a trackball, the value is set to 1 if the trackball button is pressed
+ * or 0 otherwise.
+ * - For a mouse, the value is set to 1 if the primary mouse button is pressed
+ * or 0 otherwise.
+ */
AMOTION_EVENT_AXIS_PRESSURE = 2,
+ /**
+ * Axis constant: Size axis of a motion event.
+ *
+ * - For a touch screen or touch pad, reports the approximate size of the contact area in
+ * relation to the maximum detectable size for the device. The value is normalized
+ * to a range from 0 (smallest detectable size) to 1 (largest detectable size),
+ * although it is not a linear scale. This value is of limited use.
+ * To obtain calibrated size information, see
+ * {@link AMOTION_EVENT_AXIS_TOUCH_MAJOR} or {@link AMOTION_EVENT_AXIS_TOOL_MAJOR}.
+ */
AMOTION_EVENT_AXIS_SIZE = 3,
+ /**
+ * Axis constant: TouchMajor axis of a motion event.
+ *
+ * - For a touch screen, reports the length of the major axis of an ellipse that
+ * represents the touch area at the point of contact.
+ * The units are display pixels.
+ * - For a touch pad, reports the length of the major axis of an ellipse that
+ * represents the touch area at the point of contact.
+ * The units are device-dependent.
+ */
AMOTION_EVENT_AXIS_TOUCH_MAJOR = 4,
+ /**
+ * Axis constant: TouchMinor axis of a motion event.
+ *
+ * - For a touch screen, reports the length of the minor axis of an ellipse that
+ * represents the touch area at the point of contact.
+ * The units are display pixels.
+ * - For a touch pad, reports the length of the minor axis of an ellipse that
+ * represents the touch area at the point of contact.
+ * The units are device-dependent.
+ *
+ * When the touch is circular, the major and minor axis lengths will be equal to one another.
+ */
AMOTION_EVENT_AXIS_TOUCH_MINOR = 5,
+ /**
+ * Axis constant: ToolMajor axis of a motion event.
+ *
+ * - For a touch screen, reports the length of the major axis of an ellipse that
+ * represents the size of the approaching finger or tool used to make contact.
+ * - For a touch pad, reports the length of the major axis of an ellipse that
+ * represents the size of the approaching finger or tool used to make contact.
+ * The units are device-dependent.
+ *
+ * When the touch is circular, the major and minor axis lengths will be equal to one another.
+ *
+ * The tool size may be larger than the touch size since the tool may not be fully
+ * in contact with the touch sensor.
+ */
AMOTION_EVENT_AXIS_TOOL_MAJOR = 6,
+ /**
+ * Axis constant: ToolMinor axis of a motion event.
+ *
+ * - For a touch screen, reports the length of the minor axis of an ellipse that
+ * represents the size of the approaching finger or tool used to make contact.
+ * - For a touch pad, reports the length of the minor axis of an ellipse that
+ * represents the size of the approaching finger or tool used to make contact.
+ * The units are device-dependent.
+ *
+ * When the touch is circular, the major and minor axis lengths will be equal to one another.
+ *
+ * The tool size may be larger than the touch size since the tool may not be fully
+ * in contact with the touch sensor.
+ */
AMOTION_EVENT_AXIS_TOOL_MINOR = 7,
+ /**
+ * Axis constant: Orientation axis of a motion event.
+ *
+ * - For a touch screen or touch pad, reports the orientation of the finger
+ * or tool in radians relative to the vertical plane of the device.
+ * An angle of 0 radians indicates that the major axis of contact is oriented
+ * upwards, is perfectly circular or is of unknown orientation. A positive angle
+ * indicates that the major axis of contact is oriented to the right. A negative angle
+ * indicates that the major axis of contact is oriented to the left.
+ * The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
+ * (finger pointing fully right).
+ * - For a stylus, the orientation indicates the direction in which the stylus
+ * is pointing in relation to the vertical axis of the current orientation of the screen.
+ * The range is from -PI radians to PI radians, where 0 is pointing up,
+ * -PI/2 radians is pointing left, -PI or PI radians is pointing down, and PI/2 radians
+ * is pointing right. See also {@link AMOTION_EVENT_AXIS_TILT}.
+ */
AMOTION_EVENT_AXIS_ORIENTATION = 8,
+ /**
+ * Axis constant: Vertical Scroll axis of a motion event.
+ *
+ * - For a mouse, reports the relative movement of the vertical scroll wheel.
+ * The value is normalized to a range from -1.0 (down) to 1.0 (up).
+ *
+ * This axis should be used to scroll views vertically.
+ */
AMOTION_EVENT_AXIS_VSCROLL = 9,
+ /**
+ * Axis constant: Horizontal Scroll axis of a motion event.
+ *
+ * - For a mouse, reports the relative movement of the horizontal scroll wheel.
+ * The value is normalized to a range from -1.0 (left) to 1.0 (right).
+ *
+ * This axis should be used to scroll views horizontally.
+ */
AMOTION_EVENT_AXIS_HSCROLL = 10,
+ /**
+ * Axis constant: Z axis of a motion event.
+ *
+ * - For a joystick, reports the absolute Z position of the joystick.
+ * The value is normalized to a range from -1.0 (high) to 1.0 (low).
+ * <em>On game pads with two analog joysticks, this axis is often reinterpreted
+ * to report the absolute X position of the second joystick instead.</em>
+ */
AMOTION_EVENT_AXIS_Z = 11,
+ /**
+ * Axis constant: X Rotation axis of a motion event.
+ *
+ * - For a joystick, reports the absolute rotation angle about the X axis.
+ * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
+ */
AMOTION_EVENT_AXIS_RX = 12,
+ /**
+ * Axis constant: Y Rotation axis of a motion event.
+ *
+ * - For a joystick, reports the absolute rotation angle about the Y axis.
+ * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
+ */
AMOTION_EVENT_AXIS_RY = 13,
+ /**
+ * Axis constant: Z Rotation axis of a motion event.
+ *
+ * - For a joystick, reports the absolute rotation angle about the Z axis.
+ * The value is normalized to a range from -1.0 (counter-clockwise) to 1.0 (clockwise).
+ * On game pads with two analog joysticks, this axis is often reinterpreted
+ * to report the absolute Y position of the second joystick instead.
+ */
AMOTION_EVENT_AXIS_RZ = 14,
+ /**
+ * Axis constant: Hat X axis of a motion event.
+ *
+ * - For a joystick, reports the absolute X position of the directional hat control.
+ * The value is normalized to a range from -1.0 (left) to 1.0 (right).
+ */
AMOTION_EVENT_AXIS_HAT_X = 15,
+ /**
+ * Axis constant: Hat Y axis of a motion event.
+ *
+ * - For a joystick, reports the absolute Y position of the directional hat control.
+ * The value is normalized to a range from -1.0 (up) to 1.0 (down).
+ */
AMOTION_EVENT_AXIS_HAT_Y = 16,
+ /**
+ * Axis constant: Left Trigger axis of a motion event.
+ *
+ * - For a joystick, reports the absolute position of the left trigger control.
+ * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed).
+ */
AMOTION_EVENT_AXIS_LTRIGGER = 17,
+ /**
+ * Axis constant: Right Trigger axis of a motion event.
+ *
+ * - For a joystick, reports the absolute position of the right trigger control.
+ * The value is normalized to a range from 0.0 (released) to 1.0 (fully pressed).
+ */
AMOTION_EVENT_AXIS_RTRIGGER = 18,
+ /**
+ * Axis constant: Throttle axis of a motion event.
+ *
+ * - For a joystick, reports the absolute position of the throttle control.
+ * The value is normalized to a range from 0.0 (fully open) to 1.0 (fully closed).
+ */
AMOTION_EVENT_AXIS_THROTTLE = 19,
+ /**
+ * Axis constant: Rudder axis of a motion event.
+ *
+ * - For a joystick, reports the absolute position of the rudder control.
+ * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right).
+ */
AMOTION_EVENT_AXIS_RUDDER = 20,
+ /**
+ * Axis constant: Wheel axis of a motion event.
+ *
+ * - For a joystick, reports the absolute position of the steering wheel control.
+ * The value is normalized to a range from -1.0 (turn left) to 1.0 (turn right).
+ */
AMOTION_EVENT_AXIS_WHEEL = 21,
+ /**
+ * Axis constant: Gas axis of a motion event.
+ *
+ * - For a joystick, reports the absolute position of the gas (accelerator) control.
+ * The value is normalized to a range from 0.0 (no acceleration)
+ * to 1.0 (maximum acceleration).
+ */
AMOTION_EVENT_AXIS_GAS = 22,
+ /**
+ * Axis constant: Brake axis of a motion event.
+ *
+ * - For a joystick, reports the absolute position of the brake control.
+ * The value is normalized to a range from 0.0 (no braking) to 1.0 (maximum braking).
+ */
AMOTION_EVENT_AXIS_BRAKE = 23,
+ /**
+ * Axis constant: Distance axis of a motion event.
+ *
+ * - For a stylus, reports the distance of the stylus from the screen.
+ * A value of 0.0 indicates direct contact and larger values indicate increasing
+ * distance from the surface.
+ */
AMOTION_EVENT_AXIS_DISTANCE = 24,
+ /**
+ * Axis constant: Tilt axis of a motion event.
+ *
+ * - For a stylus, reports the tilt angle of the stylus in radians where
+ * 0 radians indicates that the stylus is being held perpendicular to the
+ * surface, and PI/2 radians indicates that the stylus is being held flat
+ * against the surface.
+ */
AMOTION_EVENT_AXIS_TILT = 25,
+ /**
+ * Axis constant: Generic 1 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_1 = 32,
+ /**
+ * Axis constant: Generic 2 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_2 = 33,
+ /**
+ * Axis constant: Generic 3 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_3 = 34,
+ /**
+ * Axis constant: Generic 4 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_4 = 35,
+ /**
+ * Axis constant: Generic 5 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_5 = 36,
+ /**
+ * Axis constant: Generic 6 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_6 = 37,
+ /**
+ * Axis constant: Generic 7 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_7 = 38,
+ /**
+ * Axis constant: Generic 8 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_8 = 39,
+ /**
+ * Axis constant: Generic 9 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_9 = 40,
+ /**
+ * Axis constant: Generic 10 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_10 = 41,
+ /**
+ * Axis constant: Generic 11 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_11 = 42,
+ /**
+ * Axis constant: Generic 12 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_12 = 43,
+ /**
+ * Axis constant: Generic 13 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_13 = 44,
+ /**
+ * Axis constant: Generic 14 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_14 = 45,
+ /**
+ * Axis constant: Generic 15 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_15 = 46,
+ /**
+ * Axis constant: Generic 16 axis of a motion event.
+ * The interpretation of a generic axis is device-specific.
+ */
AMOTION_EVENT_AXIS_GENERIC_16 = 47,
// NOTE: If you add a new axis here you must also add it to several other files.
// Refer to frameworks/base/core/java/android/view/MotionEvent.java for the full list.
};
-/*
+/**
* Constants that identify buttons that are associated with motion events.
* Refer to the documentation on the MotionEvent class for descriptions of each button.
*/
enum {
+ /** primary */
AMOTION_EVENT_BUTTON_PRIMARY = 1 << 0,
+ /** secondary */
AMOTION_EVENT_BUTTON_SECONDARY = 1 << 1,
+ /** tertiary */
AMOTION_EVENT_BUTTON_TERTIARY = 1 << 2,
+ /** back */
AMOTION_EVENT_BUTTON_BACK = 1 << 3,
+ /** forward */
AMOTION_EVENT_BUTTON_FORWARD = 1 << 4,
};
-/*
+/**
* Constants that identify tool types.
* Refer to the documentation on the MotionEvent class for descriptions of each tool type.
*/
enum {
+ /** unknown */
AMOTION_EVENT_TOOL_TYPE_UNKNOWN = 0,
+ /** finger */
AMOTION_EVENT_TOOL_TYPE_FINGER = 1,
+ /** stylus */
AMOTION_EVENT_TOOL_TYPE_STYLUS = 2,
+ /** mouse */
AMOTION_EVENT_TOOL_TYPE_MOUSE = 3,
+ /** eraser */
AMOTION_EVENT_TOOL_TYPE_ERASER = 4,
};
-/*
- * Input sources.
+/**
+ * Input source masks.
*
* Refer to the documentation on android.view.InputDevice for more details about input sources
* and their correct interpretation.
*/
enum {
+ /** mask */
AINPUT_SOURCE_CLASS_MASK = 0x000000ff,
+ /** none */
AINPUT_SOURCE_CLASS_NONE = 0x00000000,
+ /** button */
AINPUT_SOURCE_CLASS_BUTTON = 0x00000001,
+ /** pointer */
AINPUT_SOURCE_CLASS_POINTER = 0x00000002,
+ /** navigation */
AINPUT_SOURCE_CLASS_NAVIGATION = 0x00000004,
+ /** position */
AINPUT_SOURCE_CLASS_POSITION = 0x00000008,
+ /** joystick */
AINPUT_SOURCE_CLASS_JOYSTICK = 0x00000010,
};
+/**
+ * Input sources.
+ */
enum {
+ /** unknown */
AINPUT_SOURCE_UNKNOWN = 0x00000000,
+ /** keyboard */
AINPUT_SOURCE_KEYBOARD = 0x00000100 | AINPUT_SOURCE_CLASS_BUTTON,
+ /** dpad */
AINPUT_SOURCE_DPAD = 0x00000200 | AINPUT_SOURCE_CLASS_BUTTON,
+ /** gamepad */
AINPUT_SOURCE_GAMEPAD = 0x00000400 | AINPUT_SOURCE_CLASS_BUTTON,
+ /** touchscreen */
AINPUT_SOURCE_TOUCHSCREEN = 0x00001000 | AINPUT_SOURCE_CLASS_POINTER,
+ /** mouse */
AINPUT_SOURCE_MOUSE = 0x00002000 | AINPUT_SOURCE_CLASS_POINTER,
+ /** stylus */
AINPUT_SOURCE_STYLUS = 0x00004000 | AINPUT_SOURCE_CLASS_POINTER,
+ /** trackball */
AINPUT_SOURCE_TRACKBALL = 0x00010000 | AINPUT_SOURCE_CLASS_NAVIGATION,
+ /** touchpad */
AINPUT_SOURCE_TOUCHPAD = 0x00100000 | AINPUT_SOURCE_CLASS_POSITION,
+ /** navigation */
AINPUT_SOURCE_TOUCH_NAVIGATION = 0x00200000 | AINPUT_SOURCE_CLASS_NONE,
+ /** joystick */
AINPUT_SOURCE_JOYSTICK = 0x01000000 | AINPUT_SOURCE_CLASS_JOYSTICK,
+ /** any */
AINPUT_SOURCE_ANY = 0xffffff00,
};
-/*
+/**
* Keyboard types.
*
* Refer to the documentation on android.view.InputDevice for more details.
*/
enum {
+ /** none */
AINPUT_KEYBOARD_TYPE_NONE = 0,
+ /** non alphabetic */
AINPUT_KEYBOARD_TYPE_NON_ALPHABETIC = 1,
+ /** alphabetic */
AINPUT_KEYBOARD_TYPE_ALPHABETIC = 2,
};
-/*
+/**
* Constants used to retrieve information about the range of motion for a particular
* coordinate of a motion event.
*
* Refer to the documentation on android.view.InputDevice for more details about input sources
* and their correct interpretation.
*
- * DEPRECATION NOTICE: These constants are deprecated. Use AMOTION_EVENT_AXIS_* constants instead.
+ * @deprecated These constants are deprecated. Use {@link AMOTION_EVENT_AXIS AMOTION_EVENT_AXIS_*} constants instead.
*/
enum {
+ /** x */
AINPUT_MOTION_RANGE_X = AMOTION_EVENT_AXIS_X,
+ /** y */
AINPUT_MOTION_RANGE_Y = AMOTION_EVENT_AXIS_Y,
+ /** pressure */
AINPUT_MOTION_RANGE_PRESSURE = AMOTION_EVENT_AXIS_PRESSURE,
+ /** size */
AINPUT_MOTION_RANGE_SIZE = AMOTION_EVENT_AXIS_SIZE,
+ /** touch major */
AINPUT_MOTION_RANGE_TOUCH_MAJOR = AMOTION_EVENT_AXIS_TOUCH_MAJOR,
+ /** touch minor */
AINPUT_MOTION_RANGE_TOUCH_MINOR = AMOTION_EVENT_AXIS_TOUCH_MINOR,
+ /** tool major */
AINPUT_MOTION_RANGE_TOOL_MAJOR = AMOTION_EVENT_AXIS_TOOL_MAJOR,
+ /** tool minor */
AINPUT_MOTION_RANGE_TOOL_MINOR = AMOTION_EVENT_AXIS_TOOL_MINOR,
+ /** orientation */
AINPUT_MOTION_RANGE_ORIENTATION = AMOTION_EVENT_AXIS_ORIENTATION,
-} __attribute__ ((deprecated));
+};
-/*
+/**
* Input event accessors.
*
* Note that most functions can only be used on input events that are of a given type.
@@ -495,10 +866,10 @@
/*** Accessors for all input events. ***/
-/* Get the input event type. */
+/** Get the input event type. */
int32_t AInputEvent_getType(const AInputEvent* event);
-/* Get the id for the device that an input event came from.
+/** Get the id for the device that an input event came from.
*
* Input events can be generated by multiple different input devices.
* Use the input device id to obtain information about the input
@@ -510,272 +881,351 @@
*/
int32_t AInputEvent_getDeviceId(const AInputEvent* event);
-/* Get the input event source. */
+/** Get the input event source. */
int32_t AInputEvent_getSource(const AInputEvent* event);
/*** Accessors for key events only. ***/
-/* Get the key event action. */
+/** Get the key event action. */
int32_t AKeyEvent_getAction(const AInputEvent* key_event);
-/* Get the key event flags. */
+/** Get the key event flags. */
int32_t AKeyEvent_getFlags(const AInputEvent* key_event);
-/* Get the key code of the key event.
- * This is the physical key that was pressed, not the Unicode character. */
+/**
+ * Get the key code of the key event.
+ * This is the physical key that was pressed, not the Unicode character.
+ */
int32_t AKeyEvent_getKeyCode(const AInputEvent* key_event);
-/* Get the hardware key id of this key event.
- * These values are not reliable and vary from device to device. */
+/**
+ * Get the hardware key id of this key event.
+ * These values are not reliable and vary from device to device.
+ */
int32_t AKeyEvent_getScanCode(const AInputEvent* key_event);
-/* Get the meta key state. */
+/** Get the meta key state. */
int32_t AKeyEvent_getMetaState(const AInputEvent* key_event);
-/* Get the repeat count of the event.
+/**
+ * Get the repeat count of the event.
* For both key up an key down events, this is the number of times the key has
* repeated with the first down starting at 0 and counting up from there. For
- * multiple key events, this is the number of down/up pairs that have occurred. */
+ * multiple key events, this is the number of down/up pairs that have occurred.
+ */
int32_t AKeyEvent_getRepeatCount(const AInputEvent* key_event);
-/* Get the time of the most recent key down event, in the
+/**
+ * Get the time of the most recent key down event, in the
* java.lang.System.nanoTime() time base. If this is a down event,
* this will be the same as eventTime.
* Note that when chording keys, this value is the down time of the most recently
- * pressed key, which may not be the same physical key of this event. */
+ * pressed key, which may not be the same physical key of this event.
+ */
int64_t AKeyEvent_getDownTime(const AInputEvent* key_event);
-/* Get the time this event occurred, in the
- * java.lang.System.nanoTime() time base. */
+/**
+ * Get the time this event occurred, in the
+ * java.lang.System.nanoTime() time base.
+ */
int64_t AKeyEvent_getEventTime(const AInputEvent* key_event);
/*** Accessors for motion events only. ***/
-/* Get the combined motion event action code and pointer index. */
+/** Get the combined motion event action code and pointer index. */
int32_t AMotionEvent_getAction(const AInputEvent* motion_event);
-/* Get the motion event flags. */
+/** Get the motion event flags. */
int32_t AMotionEvent_getFlags(const AInputEvent* motion_event);
-/* Get the state of any meta / modifier keys that were in effect when the
- * event was generated. */
+/**
+ * Get the state of any meta / modifier keys that were in effect when the
+ * event was generated.
+ */
int32_t AMotionEvent_getMetaState(const AInputEvent* motion_event);
-/* Get the button state of all buttons that are pressed. */
+/** Get the button state of all buttons that are pressed. */
int32_t AMotionEvent_getButtonState(const AInputEvent* motion_event);
-/* Get a bitfield indicating which edges, if any, were touched by this motion event.
+/**
+ * Get a bitfield indicating which edges, if any, were touched by this motion event.
* For touch events, clients can use this to determine if the user's finger was
- * touching the edge of the display. */
+ * touching the edge of the display.
+ */
int32_t AMotionEvent_getEdgeFlags(const AInputEvent* motion_event);
-/* Get the time when the user originally pressed down to start a stream of
- * position events, in the java.lang.System.nanoTime() time base. */
+/**
+ * Get the time when the user originally pressed down to start a stream of
+ * position events, in the java.lang.System.nanoTime() time base.
+ */
int64_t AMotionEvent_getDownTime(const AInputEvent* motion_event);
-/* Get the time when this specific event was generated,
- * in the java.lang.System.nanoTime() time base. */
+/**
+ * Get the time when this specific event was generated,
+ * in the java.lang.System.nanoTime() time base.
+ */
int64_t AMotionEvent_getEventTime(const AInputEvent* motion_event);
-/* Get the X coordinate offset.
+/**
+ * Get the X coordinate offset.
* For touch events on the screen, this is the delta that was added to the raw
* screen coordinates to adjust for the absolute position of the containing windows
- * and views. */
+ * and views.
+ */
float AMotionEvent_getXOffset(const AInputEvent* motion_event);
-/* Get the Y coordinate offset.
+/**
+ * Get the Y coordinate offset.
* For touch events on the screen, this is the delta that was added to the raw
* screen coordinates to adjust for the absolute position of the containing windows
- * and views. */
+ * and views.
+ */
float AMotionEvent_getYOffset(const AInputEvent* motion_event);
-/* Get the precision of the X coordinates being reported.
+/**
+ * Get the precision of the X coordinates being reported.
* You can multiply this number with an X coordinate sample to find the
- * actual hardware value of the X coordinate. */
+ * actual hardware value of the X coordinate.
+ */
float AMotionEvent_getXPrecision(const AInputEvent* motion_event);
-/* Get the precision of the Y coordinates being reported.
+/**
+ * Get the precision of the Y coordinates being reported.
* You can multiply this number with a Y coordinate sample to find the
- * actual hardware value of the Y coordinate. */
+ * actual hardware value of the Y coordinate.
+ */
float AMotionEvent_getYPrecision(const AInputEvent* motion_event);
-/* Get the number of pointers of data contained in this event.
- * Always >= 1. */
+/**
+ * Get the number of pointers of data contained in this event.
+ * Always >= 1.
+ */
size_t AMotionEvent_getPointerCount(const AInputEvent* motion_event);
-/* Get the pointer identifier associated with a particular pointer
+/**
+ * Get the pointer identifier associated with a particular pointer
* data index in this event. The identifier tells you the actual pointer
* number associated with the data, accounting for individual pointers
- * going up and down since the start of the current gesture. */
+ * going up and down since the start of the current gesture.
+ */
int32_t AMotionEvent_getPointerId(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the tool type of a pointer for the given pointer index.
+/**
+ * Get the tool type of a pointer for the given pointer index.
* The tool type indicates the type of tool used to make contact such as a
- * finger or stylus, if known. */
+ * finger or stylus, if known.
+ */
int32_t AMotionEvent_getToolType(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the original raw X coordinate of this event.
+/**
+ * Get the original raw X coordinate of this event.
* For touch events on the screen, this is the original location of the event
* on the screen, before it had been adjusted for the containing window
- * and views. */
+ * and views.
+ */
float AMotionEvent_getRawX(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the original raw X coordinate of this event.
+/**
+ * Get the original raw X coordinate of this event.
* For touch events on the screen, this is the original location of the event
* on the screen, before it had been adjusted for the containing window
- * and views. */
+ * and views.
+ */
float AMotionEvent_getRawY(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current X coordinate of this event for the given pointer index.
+/**
+ * Get the current X coordinate of this event for the given pointer index.
* Whole numbers are pixels; the value may have a fraction for input devices
- * that are sub-pixel precise. */
+ * that are sub-pixel precise.
+ */
float AMotionEvent_getX(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current Y coordinate of this event for the given pointer index.
+/**
+ * Get the current Y coordinate of this event for the given pointer index.
* Whole numbers are pixels; the value may have a fraction for input devices
- * that are sub-pixel precise. */
+ * that are sub-pixel precise.
+ */
float AMotionEvent_getY(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current pressure of this event for the given pointer index.
+/**
+ * Get the current pressure of this event for the given pointer index.
* The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure),
* although values higher than 1 may be generated depending on the calibration of
- * the input device. */
+ * the input device.
+ */
float AMotionEvent_getPressure(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current scaled value of the approximate size for the given pointer index.
+/**
+ * Get the current scaled value of the approximate size for the given pointer index.
* This represents some approximation of the area of the screen being
* pressed; the actual value in pixels corresponding to the
* touch is normalized with the device specific range of values
* and scaled to a value between 0 and 1. The value of size can be used to
- * determine fat touch events. */
+ * determine fat touch events.
+ */
float AMotionEvent_getSize(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current length of the major axis of an ellipse that describes the touch area
- * at the point of contact for the given pointer index. */
+/**
+ * Get the current length of the major axis of an ellipse that describes the touch area
+ * at the point of contact for the given pointer index.
+ */
float AMotionEvent_getTouchMajor(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current length of the minor axis of an ellipse that describes the touch area
- * at the point of contact for the given pointer index. */
+/**
+ * Get the current length of the minor axis of an ellipse that describes the touch area
+ * at the point of contact for the given pointer index.
+ */
float AMotionEvent_getTouchMinor(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current length of the major axis of an ellipse that describes the size
+/**
+ * Get the current length of the major axis of an ellipse that describes the size
* of the approaching tool for the given pointer index.
* The tool area represents the estimated size of the finger or pen that is
- * touching the device independent of its actual touch area at the point of contact. */
+ * touching the device independent of its actual touch area at the point of contact.
+ */
float AMotionEvent_getToolMajor(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current length of the minor axis of an ellipse that describes the size
+/**
+ * Get the current length of the minor axis of an ellipse that describes the size
* of the approaching tool for the given pointer index.
* The tool area represents the estimated size of the finger or pen that is
- * touching the device independent of its actual touch area at the point of contact. */
+ * touching the device independent of its actual touch area at the point of contact.
+ */
float AMotionEvent_getToolMinor(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the current orientation of the touch area and tool area in radians clockwise from
+/**
+ * Get the current orientation of the touch area and tool area in radians clockwise from
* vertical for the given pointer index.
* An angle of 0 degrees indicates that the major axis of contact is oriented
* upwards, is perfectly circular or is of unknown orientation. A positive angle
* indicates that the major axis of contact is oriented to the right. A negative angle
* indicates that the major axis of contact is oriented to the left.
* The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
- * (finger pointing fully right). */
+ * (finger pointing fully right).
+ */
float AMotionEvent_getOrientation(const AInputEvent* motion_event, size_t pointer_index);
-/* Get the value of the request axis for the given pointer index. */
+/** Get the value of the request axis for the given pointer index. */
float AMotionEvent_getAxisValue(const AInputEvent* motion_event,
int32_t axis, size_t pointer_index);
-/* Get the number of historical points in this event. These are movements that
+/**
+ * Get the number of historical points in this event. These are movements that
* have occurred between this event and the previous event. This only applies
* to AMOTION_EVENT_ACTION_MOVE events -- all other actions will have a size of 0.
- * Historical samples are indexed from oldest to newest. */
+ * Historical samples are indexed from oldest to newest.
+ */
size_t AMotionEvent_getHistorySize(const AInputEvent* motion_event);
-/* Get the time that a historical movement occurred between this event and
- * the previous event, in the java.lang.System.nanoTime() time base. */
+/**
+ * Get the time that a historical movement occurred between this event and
+ * the previous event, in the java.lang.System.nanoTime() time base.
+ */
int64_t AMotionEvent_getHistoricalEventTime(const AInputEvent* motion_event,
size_t history_index);
-/* Get the historical raw X coordinate of this event for the given pointer index that
+/**
+ * Get the historical raw X coordinate of this event for the given pointer index that
* occurred between this event and the previous motion event.
* For touch events on the screen, this is the original location of the event
* on the screen, before it had been adjusted for the containing window
* and views.
* Whole numbers are pixels; the value may have a fraction for input devices
- * that are sub-pixel precise. */
+ * that are sub-pixel precise.
+ */
float AMotionEvent_getHistoricalRawX(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical raw Y coordinate of this event for the given pointer index that
+/**
+ * Get the historical raw Y coordinate of this event for the given pointer index that
* occurred between this event and the previous motion event.
* For touch events on the screen, this is the original location of the event
* on the screen, before it had been adjusted for the containing window
* and views.
* Whole numbers are pixels; the value may have a fraction for input devices
- * that are sub-pixel precise. */
+ * that are sub-pixel precise.
+ */
float AMotionEvent_getHistoricalRawY(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical X coordinate of this event for the given pointer index that
+/**
+ * Get the historical X coordinate of this event for the given pointer index that
* occurred between this event and the previous motion event.
* Whole numbers are pixels; the value may have a fraction for input devices
- * that are sub-pixel precise. */
+ * that are sub-pixel precise.
+ */
float AMotionEvent_getHistoricalX(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical Y coordinate of this event for the given pointer index that
+/**
+ * Get the historical Y coordinate of this event for the given pointer index that
* occurred between this event and the previous motion event.
* Whole numbers are pixels; the value may have a fraction for input devices
- * that are sub-pixel precise. */
+ * that are sub-pixel precise.
+ */
float AMotionEvent_getHistoricalY(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical pressure of this event for the given pointer index that
+/**
+ * Get the historical pressure of this event for the given pointer index that
* occurred between this event and the previous motion event.
* The pressure generally ranges from 0 (no pressure at all) to 1 (normal pressure),
* although values higher than 1 may be generated depending on the calibration of
- * the input device. */
+ * the input device.
+ */
float AMotionEvent_getHistoricalPressure(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the current scaled value of the approximate size for the given pointer index that
+/**
+ * Get the current scaled value of the approximate size for the given pointer index that
* occurred between this event and the previous motion event.
* This represents some approximation of the area of the screen being
* pressed; the actual value in pixels corresponding to the
* touch is normalized with the device specific range of values
* and scaled to a value between 0 and 1. The value of size can be used to
- * determine fat touch events. */
+ * determine fat touch events.
+ */
float AMotionEvent_getHistoricalSize(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical length of the major axis of an ellipse that describes the touch area
+/**
+ * Get the historical length of the major axis of an ellipse that describes the touch area
* at the point of contact for the given pointer index that
- * occurred between this event and the previous motion event. */
+ * occurred between this event and the previous motion event.
+ */
float AMotionEvent_getHistoricalTouchMajor(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical length of the minor axis of an ellipse that describes the touch area
+/**
+ * Get the historical length of the minor axis of an ellipse that describes the touch area
* at the point of contact for the given pointer index that
- * occurred between this event and the previous motion event. */
+ * occurred between this event and the previous motion event.
+ */
float AMotionEvent_getHistoricalTouchMinor(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical length of the major axis of an ellipse that describes the size
+/**
+ * Get the historical length of the major axis of an ellipse that describes the size
* of the approaching tool for the given pointer index that
* occurred between this event and the previous motion event.
* The tool area represents the estimated size of the finger or pen that is
- * touching the device independent of its actual touch area at the point of contact. */
+ * touching the device independent of its actual touch area at the point of contact.
+ */
float AMotionEvent_getHistoricalToolMajor(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical length of the minor axis of an ellipse that describes the size
+/**
+ * Get the historical length of the minor axis of an ellipse that describes the size
* of the approaching tool for the given pointer index that
* occurred between this event and the previous motion event.
* The tool area represents the estimated size of the finger or pen that is
- * touching the device independent of its actual touch area at the point of contact. */
+ * touching the device independent of its actual touch area at the point of contact.
+ */
float AMotionEvent_getHistoricalToolMinor(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical orientation of the touch area and tool area in radians clockwise from
+/**
+ * Get the historical orientation of the touch area and tool area in radians clockwise from
* vertical for the given pointer index that
* occurred between this event and the previous motion event.
* An angle of 0 degrees indicates that the major axis of contact is oriented
@@ -783,51 +1233,54 @@
* indicates that the major axis of contact is oriented to the right. A negative angle
* indicates that the major axis of contact is oriented to the left.
* The full range is from -PI/2 radians (finger pointing fully left) to PI/2 radians
- * (finger pointing fully right). */
+ * (finger pointing fully right).
+ */
float AMotionEvent_getHistoricalOrientation(const AInputEvent* motion_event, size_t pointer_index,
size_t history_index);
-/* Get the historical value of the request axis for the given pointer index
- * that occurred between this event and the previous motion event. */
+/**
+ * Get the historical value of the request axis for the given pointer index
+ * that occurred between this event and the previous motion event.
+ */
float AMotionEvent_getHistoricalAxisValue(const AInputEvent* motion_event,
int32_t axis, size_t pointer_index, size_t history_index);
-/*
+struct AInputQueue;
+/**
* Input queue
*
* An input queue is the facility through which you retrieve input
* events.
*/
-struct AInputQueue;
typedef struct AInputQueue AInputQueue;
-/*
+/**
* Add this input queue to a looper for processing. See
* ALooper_addFd() for information on the ident, callback, and data params.
*/
void AInputQueue_attachLooper(AInputQueue* queue, ALooper* looper,
int ident, ALooper_callbackFunc callback, void* data);
-/*
+/**
* Remove the input queue from the looper it is currently attached to.
*/
void AInputQueue_detachLooper(AInputQueue* queue);
-/*
+/**
* Returns true if there are one or more events available in the
* input queue. Returns 1 if the queue has events; 0 if
* it does not have events; and a negative value if there is an error.
*/
int32_t AInputQueue_hasEvents(AInputQueue* queue);
-/*
+/**
* Returns the next available event from the queue. Returns a negative
* value if no events are available or an error has occurred.
*/
int32_t AInputQueue_getEvent(AInputQueue* queue, AInputEvent** outEvent);
-/*
+/**
* Sends the key for standard pre-dispatching -- that is, possibly deliver
* it to the current IME to be consumed before the app. Returns 0 if it
* was not pre-dispatched, meaning you can process it right now. If non-zero
@@ -837,7 +1290,7 @@
*/
int32_t AInputQueue_preDispatchEvent(AInputQueue* queue, AInputEvent* event);
-/*
+/**
* Report that dispatching has finished with the given event.
* This must be called after receiving an event with AInputQueue_get_event().
*/
@@ -848,3 +1301,5 @@
#endif
#endif // _ANDROID_INPUT_H
+
+/** @} */
diff --git a/include/android/keycodes.h b/include/android/keycodes.h
index 75d0ab6..ec4b0c8 100644
--- a/include/android/keycodes.h
+++ b/include/android/keycodes.h
@@ -14,6 +14,15 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Input
+ * @{
+ */
+
+/**
+ * @file keycodes.h
+ */
+
#ifndef _ANDROID_KEYCODES_H
#define _ANDROID_KEYCODES_H
@@ -39,269 +48,676 @@
extern "C" {
#endif
-/*
+/**
* Key codes.
*/
enum {
+ /** Unknown key code. */
AKEYCODE_UNKNOWN = 0,
+ /** Soft Left key.
+ * Usually situated below the display on phones and used as a multi-function
+ * feature key for selecting a software defined function shown on the bottom left
+ * of the display. */
AKEYCODE_SOFT_LEFT = 1,
+ /** Soft Right key.
+ * Usually situated below the display on phones and used as a multi-function
+ * feature key for selecting a software defined function shown on the bottom right
+ * of the display. */
AKEYCODE_SOFT_RIGHT = 2,
+ /** Home key.
+ * This key is handled by the framework and is never delivered to applications. */
AKEYCODE_HOME = 3,
+ /** Back key. */
AKEYCODE_BACK = 4,
+ /** Call key. */
AKEYCODE_CALL = 5,
+ /** End Call key. */
AKEYCODE_ENDCALL = 6,
+ /** '0' key. */
AKEYCODE_0 = 7,
+ /** '1' key. */
AKEYCODE_1 = 8,
+ /** '2' key. */
AKEYCODE_2 = 9,
+ /** '3' key. */
AKEYCODE_3 = 10,
+ /** '4' key. */
AKEYCODE_4 = 11,
+ /** '5' key. */
AKEYCODE_5 = 12,
+ /** '6' key. */
AKEYCODE_6 = 13,
+ /** '7' key. */
AKEYCODE_7 = 14,
+ /** '8' key. */
AKEYCODE_8 = 15,
+ /** '9' key. */
AKEYCODE_9 = 16,
+ /** '*' key. */
AKEYCODE_STAR = 17,
+ /** '#' key. */
AKEYCODE_POUND = 18,
+ /** Directional Pad Up key.
+ * May also be synthesized from trackball motions. */
AKEYCODE_DPAD_UP = 19,
+ /** Directional Pad Down key.
+ * May also be synthesized from trackball motions. */
AKEYCODE_DPAD_DOWN = 20,
+ /** Directional Pad Left key.
+ * May also be synthesized from trackball motions. */
AKEYCODE_DPAD_LEFT = 21,
+ /** Directional Pad Right key.
+ * May also be synthesized from trackball motions. */
AKEYCODE_DPAD_RIGHT = 22,
+ /** Directional Pad Center key.
+ * May also be synthesized from trackball motions. */
AKEYCODE_DPAD_CENTER = 23,
+ /** Volume Up key.
+ * Adjusts the speaker volume up. */
AKEYCODE_VOLUME_UP = 24,
+ /** Volume Down key.
+ * Adjusts the speaker volume down. */
AKEYCODE_VOLUME_DOWN = 25,
+ /** Power key. */
AKEYCODE_POWER = 26,
+ /** Camera key.
+ * Used to launch a camera application or take pictures. */
AKEYCODE_CAMERA = 27,
+ /** Clear key. */
AKEYCODE_CLEAR = 28,
+ /** 'A' key. */
AKEYCODE_A = 29,
+ /** 'B' key. */
AKEYCODE_B = 30,
+ /** 'C' key. */
AKEYCODE_C = 31,
+ /** 'D' key. */
AKEYCODE_D = 32,
+ /** 'E' key. */
AKEYCODE_E = 33,
+ /** 'F' key. */
AKEYCODE_F = 34,
+ /** 'G' key. */
AKEYCODE_G = 35,
+ /** 'H' key. */
AKEYCODE_H = 36,
+ /** 'I' key. */
AKEYCODE_I = 37,
+ /** 'J' key. */
AKEYCODE_J = 38,
+ /** 'K' key. */
AKEYCODE_K = 39,
+ /** 'L' key. */
AKEYCODE_L = 40,
+ /** 'M' key. */
AKEYCODE_M = 41,
+ /** 'N' key. */
AKEYCODE_N = 42,
+ /** 'O' key. */
AKEYCODE_O = 43,
+ /** 'P' key. */
AKEYCODE_P = 44,
+ /** 'Q' key. */
AKEYCODE_Q = 45,
+ /** 'R' key. */
AKEYCODE_R = 46,
+ /** 'S' key. */
AKEYCODE_S = 47,
+ /** 'T' key. */
AKEYCODE_T = 48,
+ /** 'U' key. */
AKEYCODE_U = 49,
+ /** 'V' key. */
AKEYCODE_V = 50,
+ /** 'W' key. */
AKEYCODE_W = 51,
+ /** 'X' key. */
AKEYCODE_X = 52,
+ /** 'Y' key. */
AKEYCODE_Y = 53,
+ /** 'Z' key. */
AKEYCODE_Z = 54,
+ /** ',' key. */
AKEYCODE_COMMA = 55,
+ /** '.' key. */
AKEYCODE_PERIOD = 56,
+ /** Left Alt modifier key. */
AKEYCODE_ALT_LEFT = 57,
+ /** Right Alt modifier key. */
AKEYCODE_ALT_RIGHT = 58,
+ /** Left Shift modifier key. */
AKEYCODE_SHIFT_LEFT = 59,
+ /** Right Shift modifier key. */
AKEYCODE_SHIFT_RIGHT = 60,
+ /** Tab key. */
AKEYCODE_TAB = 61,
+ /** Space key. */
AKEYCODE_SPACE = 62,
+ /** Symbol modifier key.
+ * Used to enter alternate symbols. */
AKEYCODE_SYM = 63,
+ /** Explorer special function key.
+ * Used to launch a browser application. */
AKEYCODE_EXPLORER = 64,
+ /** Envelope special function key.
+ * Used to launch a mail application. */
AKEYCODE_ENVELOPE = 65,
+ /** Enter key. */
AKEYCODE_ENTER = 66,
+ /** Backspace key.
+ * Deletes characters before the insertion point, unlike {@link AKEYCODE_FORWARD_DEL}. */
AKEYCODE_DEL = 67,
+ /** '`' (backtick) key. */
AKEYCODE_GRAVE = 68,
+ /** '-'. */
AKEYCODE_MINUS = 69,
+ /** '=' key. */
AKEYCODE_EQUALS = 70,
+ /** '[' key. */
AKEYCODE_LEFT_BRACKET = 71,
+ /** ']' key. */
AKEYCODE_RIGHT_BRACKET = 72,
+ /** '\' key. */
AKEYCODE_BACKSLASH = 73,
+ /** ';' key. */
AKEYCODE_SEMICOLON = 74,
+ /** ''' (apostrophe) key. */
AKEYCODE_APOSTROPHE = 75,
+ /** '/' key. */
AKEYCODE_SLASH = 76,
+ /** '@' key. */
AKEYCODE_AT = 77,
+ /** Number modifier key.
+ * Used to enter numeric symbols.
+ * This key is not {@link AKEYCODE_NUM_LOCK}; it is more like {@link AKEYCODE_ALT_LEFT}. */
AKEYCODE_NUM = 78,
+ /** Headset Hook key.
+ * Used to hang up calls and stop media. */
AKEYCODE_HEADSETHOOK = 79,
- AKEYCODE_FOCUS = 80, // *Camera* focus
+ /** Camera Focus key.
+ * Used to focus the camera. */
+ AKEYCODE_FOCUS = 80,
+ /** '+' key. */
AKEYCODE_PLUS = 81,
+ /** Menu key. */
AKEYCODE_MENU = 82,
+ /** Notification key. */
AKEYCODE_NOTIFICATION = 83,
+ /** Search key. */
AKEYCODE_SEARCH = 84,
+ /** Play/Pause media key. */
AKEYCODE_MEDIA_PLAY_PAUSE= 85,
+ /** Stop media key. */
AKEYCODE_MEDIA_STOP = 86,
+ /** Play Next media key. */
AKEYCODE_MEDIA_NEXT = 87,
+ /** Play Previous media key. */
AKEYCODE_MEDIA_PREVIOUS = 88,
+ /** Rewind media key. */
AKEYCODE_MEDIA_REWIND = 89,
+ /** Fast Forward media key. */
AKEYCODE_MEDIA_FAST_FORWARD = 90,
+ /** Mute key.
+ * Mutes the microphone, unlike {@link AKEYCODE_VOLUME_MUTE}. */
AKEYCODE_MUTE = 91,
+ /** Page Up key. */
AKEYCODE_PAGE_UP = 92,
+ /** Page Down key. */
AKEYCODE_PAGE_DOWN = 93,
+ /** Picture Symbols modifier key.
+ * Used to switch symbol sets (Emoji, Kao-moji). */
AKEYCODE_PICTSYMBOLS = 94,
+ /** Switch Charset modifier key.
+ * Used to switch character sets (Kanji, Katakana). */
AKEYCODE_SWITCH_CHARSET = 95,
+ /** A Button key.
+ * On a game controller, the A button should be either the button labeled A
+ * or the first button on the bottom row of controller buttons. */
AKEYCODE_BUTTON_A = 96,
+ /** B Button key.
+ * On a game controller, the B button should be either the button labeled B
+ * or the second button on the bottom row of controller buttons. */
AKEYCODE_BUTTON_B = 97,
+ /** C Button key.
+ * On a game controller, the C button should be either the button labeled C
+ * or the third button on the bottom row of controller buttons. */
AKEYCODE_BUTTON_C = 98,
+ /** X Button key.
+ * On a game controller, the X button should be either the button labeled X
+ * or the first button on the upper row of controller buttons. */
AKEYCODE_BUTTON_X = 99,
+ /** Y Button key.
+ * On a game controller, the Y button should be either the button labeled Y
+ * or the second button on the upper row of controller buttons. */
AKEYCODE_BUTTON_Y = 100,
+ /** Z Button key.
+ * On a game controller, the Z button should be either the button labeled Z
+ * or the third button on the upper row of controller buttons. */
AKEYCODE_BUTTON_Z = 101,
+ /** L1 Button key.
+ * On a game controller, the L1 button should be either the button labeled L1 (or L)
+ * or the top left trigger button. */
AKEYCODE_BUTTON_L1 = 102,
+ /** R1 Button key.
+ * On a game controller, the R1 button should be either the button labeled R1 (or R)
+ * or the top right trigger button. */
AKEYCODE_BUTTON_R1 = 103,
+ /** L2 Button key.
+ * On a game controller, the L2 button should be either the button labeled L2
+ * or the bottom left trigger button. */
AKEYCODE_BUTTON_L2 = 104,
+ /** R2 Button key.
+ * On a game controller, the R2 button should be either the button labeled R2
+ * or the bottom right trigger button. */
AKEYCODE_BUTTON_R2 = 105,
+ /** Left Thumb Button key.
+ * On a game controller, the left thumb button indicates that the left (or only)
+ * joystick is pressed. */
AKEYCODE_BUTTON_THUMBL = 106,
+ /** Right Thumb Button key.
+ * On a game controller, the right thumb button indicates that the right
+ * joystick is pressed. */
AKEYCODE_BUTTON_THUMBR = 107,
+ /** Start Button key.
+ * On a game controller, the button labeled Start. */
AKEYCODE_BUTTON_START = 108,
+ /** Select Button key.
+ * On a game controller, the button labeled Select. */
AKEYCODE_BUTTON_SELECT = 109,
+ /** Mode Button key.
+ * On a game controller, the button labeled Mode. */
AKEYCODE_BUTTON_MODE = 110,
+ /** Escape key. */
AKEYCODE_ESCAPE = 111,
+ /** Forward Delete key.
+ * Deletes characters ahead of the insertion point, unlike {@link AKEYCODE_DEL}. */
AKEYCODE_FORWARD_DEL = 112,
+ /** Left Control modifier key. */
AKEYCODE_CTRL_LEFT = 113,
+ /** Right Control modifier key. */
AKEYCODE_CTRL_RIGHT = 114,
+ /** Caps Lock key. */
AKEYCODE_CAPS_LOCK = 115,
+ /** Scroll Lock key. */
AKEYCODE_SCROLL_LOCK = 116,
+ /** Left Meta modifier key. */
AKEYCODE_META_LEFT = 117,
+ /** Right Meta modifier key. */
AKEYCODE_META_RIGHT = 118,
+ /** Function modifier key. */
AKEYCODE_FUNCTION = 119,
+ /** System Request / Print Screen key. */
AKEYCODE_SYSRQ = 120,
+ /** Break / Pause key. */
AKEYCODE_BREAK = 121,
+ /** Home Movement key.
+ * Used for scrolling or moving the cursor around to the start of a line
+ * or to the top of a list. */
AKEYCODE_MOVE_HOME = 122,
+ /** End Movement key.
+ * Used for scrolling or moving the cursor around to the end of a line
+ * or to the bottom of a list. */
AKEYCODE_MOVE_END = 123,
+ /** Insert key.
+ * Toggles insert / overwrite edit mode. */
AKEYCODE_INSERT = 124,
+ /** Forward key.
+ * Navigates forward in the history stack. Complement of {@link AKEYCODE_BACK}. */
AKEYCODE_FORWARD = 125,
+ /** Play media key. */
AKEYCODE_MEDIA_PLAY = 126,
+ /** Pause media key. */
AKEYCODE_MEDIA_PAUSE = 127,
+ /** Close media key.
+ * May be used to close a CD tray, for example. */
AKEYCODE_MEDIA_CLOSE = 128,
+ /** Eject media key.
+ * May be used to eject a CD tray, for example. */
AKEYCODE_MEDIA_EJECT = 129,
+ /** Record media key. */
AKEYCODE_MEDIA_RECORD = 130,
+ /** F1 key. */
AKEYCODE_F1 = 131,
+ /** F2 key. */
AKEYCODE_F2 = 132,
+ /** F3 key. */
AKEYCODE_F3 = 133,
+ /** F4 key. */
AKEYCODE_F4 = 134,
+ /** F5 key. */
AKEYCODE_F5 = 135,
+ /** F6 key. */
AKEYCODE_F6 = 136,
+ /** F7 key. */
AKEYCODE_F7 = 137,
+ /** F8 key. */
AKEYCODE_F8 = 138,
+ /** F9 key. */
AKEYCODE_F9 = 139,
+ /** F10 key. */
AKEYCODE_F10 = 140,
+ /** F11 key. */
AKEYCODE_F11 = 141,
+ /** F12 key. */
AKEYCODE_F12 = 142,
+ /** Num Lock key.
+ * This is the Num Lock key; it is different from {@link AKEYCODE_NUM}.
+ * This key alters the behavior of other keys on the numeric keypad. */
AKEYCODE_NUM_LOCK = 143,
+ /** Numeric keypad '0' key. */
AKEYCODE_NUMPAD_0 = 144,
+ /** Numeric keypad '1' key. */
AKEYCODE_NUMPAD_1 = 145,
+ /** Numeric keypad '2' key. */
AKEYCODE_NUMPAD_2 = 146,
+ /** Numeric keypad '3' key. */
AKEYCODE_NUMPAD_3 = 147,
+ /** Numeric keypad '4' key. */
AKEYCODE_NUMPAD_4 = 148,
+ /** Numeric keypad '5' key. */
AKEYCODE_NUMPAD_5 = 149,
+ /** Numeric keypad '6' key. */
AKEYCODE_NUMPAD_6 = 150,
+ /** Numeric keypad '7' key. */
AKEYCODE_NUMPAD_7 = 151,
+ /** Numeric keypad '8' key. */
AKEYCODE_NUMPAD_8 = 152,
+ /** Numeric keypad '9' key. */
AKEYCODE_NUMPAD_9 = 153,
+ /** Numeric keypad '/' key (for division). */
AKEYCODE_NUMPAD_DIVIDE = 154,
+ /** Numeric keypad '*' key (for multiplication). */
AKEYCODE_NUMPAD_MULTIPLY = 155,
+ /** Numeric keypad '-' key (for subtraction). */
AKEYCODE_NUMPAD_SUBTRACT = 156,
+ /** Numeric keypad '+' key (for addition). */
AKEYCODE_NUMPAD_ADD = 157,
+ /** Numeric keypad '.' key (for decimals or digit grouping). */
AKEYCODE_NUMPAD_DOT = 158,
+ /** Numeric keypad ',' key (for decimals or digit grouping). */
AKEYCODE_NUMPAD_COMMA = 159,
+ /** Numeric keypad Enter key. */
AKEYCODE_NUMPAD_ENTER = 160,
+ /** Numeric keypad '=' key. */
AKEYCODE_NUMPAD_EQUALS = 161,
+ /** Numeric keypad '(' key. */
AKEYCODE_NUMPAD_LEFT_PAREN = 162,
+ /** Numeric keypad ')' key. */
AKEYCODE_NUMPAD_RIGHT_PAREN = 163,
+ /** Volume Mute key.
+ * Mutes the speaker, unlike {@link AKEYCODE_MUTE}.
+ * This key should normally be implemented as a toggle such that the first press
+ * mutes the speaker and the second press restores the original volume. */
AKEYCODE_VOLUME_MUTE = 164,
+ /** Info key.
+ * Common on TV remotes to show additional information related to what is
+ * currently being viewed. */
AKEYCODE_INFO = 165,
+ /** Channel up key.
+ * On TV remotes, increments the television channel. */
AKEYCODE_CHANNEL_UP = 166,
+ /** Channel down key.
+ * On TV remotes, decrements the television channel. */
AKEYCODE_CHANNEL_DOWN = 167,
+ /** Zoom in key. */
AKEYCODE_ZOOM_IN = 168,
+ /** Zoom out key. */
AKEYCODE_ZOOM_OUT = 169,
+ /** TV key.
+ * On TV remotes, switches to viewing live TV. */
AKEYCODE_TV = 170,
+ /** Window key.
+ * On TV remotes, toggles picture-in-picture mode or other windowing functions. */
AKEYCODE_WINDOW = 171,
+ /** Guide key.
+ * On TV remotes, shows a programming guide. */
AKEYCODE_GUIDE = 172,
+ /** DVR key.
+ * On some TV remotes, switches to a DVR mode for recorded shows. */
AKEYCODE_DVR = 173,
+ /** Bookmark key.
+ * On some TV remotes, bookmarks content or web pages. */
AKEYCODE_BOOKMARK = 174,
+ /** Toggle captions key.
+ * Switches the mode for closed-captioning text, for example during television shows. */
AKEYCODE_CAPTIONS = 175,
+ /** Settings key.
+ * Starts the system settings activity. */
AKEYCODE_SETTINGS = 176,
+ /** TV power key.
+ * On TV remotes, toggles the power on a television screen. */
AKEYCODE_TV_POWER = 177,
+ /** TV input key.
+ * On TV remotes, switches the input on a television screen. */
AKEYCODE_TV_INPUT = 178,
+ /** Set-top-box power key.
+ * On TV remotes, toggles the power on an external Set-top-box. */
AKEYCODE_STB_POWER = 179,
+ /** Set-top-box input key.
+ * On TV remotes, switches the input mode on an external Set-top-box. */
AKEYCODE_STB_INPUT = 180,
+ /** A/V Receiver power key.
+ * On TV remotes, toggles the power on an external A/V Receiver. */
AKEYCODE_AVR_POWER = 181,
+ /** A/V Receiver input key.
+ * On TV remotes, switches the input mode on an external A/V Receiver. */
AKEYCODE_AVR_INPUT = 182,
+ /** Red "programmable" key.
+ * On TV remotes, acts as a contextual/programmable key. */
AKEYCODE_PROG_RED = 183,
+ /** Green "programmable" key.
+ * On TV remotes, actsas a contextual/programmable key. */
AKEYCODE_PROG_GREEN = 184,
+ /** Yellow "programmable" key.
+ * On TV remotes, acts as a contextual/programmable key. */
AKEYCODE_PROG_YELLOW = 185,
+ /** Blue "programmable" key.
+ * On TV remotes, acts as a contextual/programmable key. */
AKEYCODE_PROG_BLUE = 186,
+ /** App switch key.
+ * Should bring up the application switcher dialog. */
AKEYCODE_APP_SWITCH = 187,
+ /** Generic Game Pad Button #1.*/
AKEYCODE_BUTTON_1 = 188,
+ /** Generic Game Pad Button #2.*/
AKEYCODE_BUTTON_2 = 189,
+ /** Generic Game Pad Button #3.*/
AKEYCODE_BUTTON_3 = 190,
+ /** Generic Game Pad Button #4.*/
AKEYCODE_BUTTON_4 = 191,
+ /** Generic Game Pad Button #5.*/
AKEYCODE_BUTTON_5 = 192,
+ /** Generic Game Pad Button #6.*/
AKEYCODE_BUTTON_6 = 193,
+ /** Generic Game Pad Button #7.*/
AKEYCODE_BUTTON_7 = 194,
+ /** Generic Game Pad Button #8.*/
AKEYCODE_BUTTON_8 = 195,
+ /** Generic Game Pad Button #9.*/
AKEYCODE_BUTTON_9 = 196,
+ /** Generic Game Pad Button #10.*/
AKEYCODE_BUTTON_10 = 197,
+ /** Generic Game Pad Button #11.*/
AKEYCODE_BUTTON_11 = 198,
+ /** Generic Game Pad Button #12.*/
AKEYCODE_BUTTON_12 = 199,
+ /** Generic Game Pad Button #13.*/
AKEYCODE_BUTTON_13 = 200,
+ /** Generic Game Pad Button #14.*/
AKEYCODE_BUTTON_14 = 201,
+ /** Generic Game Pad Button #15.*/
AKEYCODE_BUTTON_15 = 202,
+ /** Generic Game Pad Button #16.*/
AKEYCODE_BUTTON_16 = 203,
+ /** Language Switch key.
+ * Toggles the current input language such as switching between English and Japanese on
+ * a QWERTY keyboard. On some devices, the same function may be performed by
+ * pressing Shift+Spacebar. */
AKEYCODE_LANGUAGE_SWITCH = 204,
+ /** Manner Mode key.
+ * Toggles silent or vibrate mode on and off to make the device behave more politely
+ * in certain settings such as on a crowded train. On some devices, the key may only
+ * operate when long-pressed. */
AKEYCODE_MANNER_MODE = 205,
+ /** 3D Mode key.
+ * Toggles the display between 2D and 3D mode. */
AKEYCODE_3D_MODE = 206,
+ /** Contacts special function key.
+ * Used to launch an address book application. */
AKEYCODE_CONTACTS = 207,
+ /** Calendar special function key.
+ * Used to launch a calendar application. */
AKEYCODE_CALENDAR = 208,
+ /** Music special function key.
+ * Used to launch a music player application. */
AKEYCODE_MUSIC = 209,
+ /** Calculator special function key.
+ * Used to launch a calculator application. */
AKEYCODE_CALCULATOR = 210,
+ /** Japanese full-width / half-width key. */
AKEYCODE_ZENKAKU_HANKAKU = 211,
+ /** Japanese alphanumeric key. */
AKEYCODE_EISU = 212,
+ /** Japanese non-conversion key. */
AKEYCODE_MUHENKAN = 213,
+ /** Japanese conversion key. */
AKEYCODE_HENKAN = 214,
+ /** Japanese katakana / hiragana key. */
AKEYCODE_KATAKANA_HIRAGANA = 215,
+ /** Japanese Yen key. */
AKEYCODE_YEN = 216,
+ /** Japanese Ro key. */
AKEYCODE_RO = 217,
+ /** Japanese kana key. */
AKEYCODE_KANA = 218,
+ /** Assist key.
+ * Launches the global assist activity. Not delivered to applications. */
AKEYCODE_ASSIST = 219,
+ /** Brightness Down key.
+ * Adjusts the screen brightness down. */
AKEYCODE_BRIGHTNESS_DOWN = 220,
+ /** Brightness Up key.
+ * Adjusts the screen brightness up. */
AKEYCODE_BRIGHTNESS_UP = 221,
+ /** Audio Track key.
+ * Switches the audio tracks. */
AKEYCODE_MEDIA_AUDIO_TRACK = 222,
+ /** Sleep key.
+ * Puts the device to sleep. Behaves somewhat like {@link AKEYCODE_POWER} but it
+ * has no effect if the device is already asleep. */
AKEYCODE_SLEEP = 223,
+ /** Wakeup key.
+ * Wakes up the device. Behaves somewhat like {@link AKEYCODE_POWER} but it
+ * has no effect if the device is already awake. */
AKEYCODE_WAKEUP = 224,
+ /** Pairing key.
+ * Initiates peripheral pairing mode. Useful for pairing remote control
+ * devices or game controllers, especially if no other input mode is
+ * available. */
AKEYCODE_PAIRING = 225,
+ /** Media Top Menu key.
+ * Goes to the top of media menu. */
AKEYCODE_MEDIA_TOP_MENU = 226,
+ /** '11' key. */
AKEYCODE_11 = 227,
+ /** '12' key. */
AKEYCODE_12 = 228,
+ /** Last Channel key.
+ * Goes to the last viewed channel. */
AKEYCODE_LAST_CHANNEL = 229,
+ /** TV data service key.
+ * Displays data services like weather, sports. */
AKEYCODE_TV_DATA_SERVICE = 230,
+ /** Voice Assist key.
+ * Launches the global voice assist activity. Not delivered to applications. */
AKEYCODE_VOICE_ASSIST = 231,
+ /** Radio key.
+ * Toggles TV service / Radio service. */
AKEYCODE_TV_RADIO_SERVICE = 232,
+ /** Teletext key.
+ * Displays Teletext service. */
AKEYCODE_TV_TELETEXT = 233,
+ /** Number entry key.
+ * Initiates to enter multi-digit channel nubmber when each digit key is assigned
+ * for selecting separate channel. Corresponds to Number Entry Mode (0x1D) of CEC
+ * User Control Code. */
AKEYCODE_TV_NUMBER_ENTRY = 234,
+ /** Analog Terrestrial key.
+ * Switches to analog terrestrial broadcast service. */
AKEYCODE_TV_TERRESTRIAL_ANALOG = 235,
+ /** Digital Terrestrial key.
+ * Switches to digital terrestrial broadcast service. */
AKEYCODE_TV_TERRESTRIAL_DIGITAL = 236,
+ /** Satellite key.
+ * Switches to digital satellite broadcast service. */
AKEYCODE_TV_SATELLITE = 237,
+ /** BS key.
+ * Switches to BS digital satellite broadcasting service available in Japan. */
AKEYCODE_TV_SATELLITE_BS = 238,
+ /** CS key.
+ * Switches to CS digital satellite broadcasting service available in Japan. */
AKEYCODE_TV_SATELLITE_CS = 239,
+ /** BS/CS key.
+ * Toggles between BS and CS digital satellite services. */
AKEYCODE_TV_SATELLITE_SERVICE = 240,
+ /** Toggle Network key.
+ * Toggles selecting broacast services. */
AKEYCODE_TV_NETWORK = 241,
+ /** Antenna/Cable key.
+ * Toggles broadcast input source between antenna and cable. */
AKEYCODE_TV_ANTENNA_CABLE = 242,
+ /** HDMI #1 key.
+ * Switches to HDMI input #1. */
AKEYCODE_TV_INPUT_HDMI_1 = 243,
+ /** HDMI #2 key.
+ * Switches to HDMI input #2. */
AKEYCODE_TV_INPUT_HDMI_2 = 244,
+ /** HDMI #3 key.
+ * Switches to HDMI input #3. */
AKEYCODE_TV_INPUT_HDMI_3 = 245,
+ /** HDMI #4 key.
+ * Switches to HDMI input #4. */
AKEYCODE_TV_INPUT_HDMI_4 = 246,
+ /** Composite #1 key.
+ * Switches to composite video input #1. */
AKEYCODE_TV_INPUT_COMPOSITE_1 = 247,
+ /** Composite #2 key.
+ * Switches to composite video input #2. */
AKEYCODE_TV_INPUT_COMPOSITE_2 = 248,
+ /** Component #1 key.
+ * Switches to component video input #1. */
AKEYCODE_TV_INPUT_COMPONENT_1 = 249,
+ /** Component #2 key.
+ * Switches to component video input #2. */
AKEYCODE_TV_INPUT_COMPONENT_2 = 250,
+ /** VGA #1 key.
+ * Switches to VGA (analog RGB) input #1. */
AKEYCODE_TV_INPUT_VGA_1 = 251,
+ /** Audio description key.
+ * Toggles audio description off / on. */
AKEYCODE_TV_AUDIO_DESCRIPTION = 252,
+ /** Audio description mixing volume up key.
+ * Louden audio description volume as compared with normal audio volume. */
AKEYCODE_TV_AUDIO_DESCRIPTION_MIX_UP = 253,
+ /** Audio description mixing volume down key.
+ * Lessen audio description volume as compared with normal audio volume. */
AKEYCODE_TV_AUDIO_DESCRIPTION_MIX_DOWN = 254,
+ /** Zoom mode key.
+ * Changes Zoom mode (Normal, Full, Zoom, Wide-zoom, etc.) */
AKEYCODE_TV_ZOOM_MODE = 255,
+ /** Contents menu key.
+ * Goes to the title list. Corresponds to Contents Menu (0x0B) of CEC User Control
+ * Code */
AKEYCODE_TV_CONTENTS_MENU = 256,
+ /** Media context menu key.
+ * Goes to the context menu of media contents. Corresponds to Media Context-sensitive
+ * Menu (0x11) of CEC User Control Code. */
AKEYCODE_TV_MEDIA_CONTEXT_MENU = 257,
+ /** Timer programming key.
+ * Goes to the timer recording menu. Corresponds to Timer Programming (0x54) of
+ * CEC User Control Code. */
AKEYCODE_TV_TIMER_PROGRAMMING = 258,
+ /** Help key. */
AKEYCODE_HELP = 259
// NOTE: If you add a new keycode here you must also add it to several other files.
@@ -313,3 +729,5 @@
#endif
#endif // _ANDROID_KEYCODES_H
+
+/** @} */
diff --git a/include/android/looper.h b/include/android/looper.h
index 74c0383..718f703 100644
--- a/include/android/looper.h
+++ b/include/android/looper.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Looper
+ * @{
+ */
+
+/**
+ * @file looper.h
+ */
#ifndef ANDROID_LOOPER_H
#define ANDROID_LOOPER_H
@@ -22,6 +30,7 @@
extern "C" {
#endif
+struct ALooper;
/**
* ALooper
*
@@ -35,7 +44,6 @@
*
* A thread can have only one ALooper associated with it.
*/
-struct ALooper;
typedef struct ALooper ALooper;
/**
@@ -44,13 +52,14 @@
*/
ALooper* ALooper_forThread();
+/** Option for for ALooper_prepare(). */
enum {
/**
- * Option for ALooper_prepare: this looper will accept calls to
- * ALooper_addFd() that do not have a callback (that is provide NULL
- * for the callback). In this case the caller of ALooper_pollOnce()
- * or ALooper_pollAll() MUST check the return from these functions to
- * discover when data is available on such fds and process it.
+ * This looper will accept calls to ALooper_addFd() that do not
+ * have a callback (that is provide NULL for the callback). In
+ * this case the caller of ALooper_pollOnce() or ALooper_pollAll()
+ * MUST check the return from these functions to discover when
+ * data is available on such fds and process it.
*/
ALOOPER_PREPARE_ALLOW_NON_CALLBACKS = 1<<0
};
@@ -64,9 +73,9 @@
*/
ALooper* ALooper_prepare(int opts);
+/** Result from ALooper_pollOnce() and ALooper_pollAll(). */
enum {
/**
- * Result from ALooper_pollOnce() and ALooper_pollAll():
* The poll was awoken using wake() before the timeout expired
* and no callbacks were executed and no other file descriptors were ready.
*/
@@ -176,10 +185,12 @@
*
* Returns ALOOPER_POLL_ERROR if an error occurred.
*
- * Returns a value >= 0 containing an identifier if its file descriptor has data
- * and it has no callback function (requiring the caller here to handle it).
- * In this (and only this) case outFd, outEvents and outData will contain the poll
- * events and data associated with the fd, otherwise they will be set to NULL.
+ * Returns a value >= 0 containing an identifier (the same identifier
+ * `ident` passed to ALooper_addFd()) if its file descriptor has data
+ * and it has no callback function (requiring the caller here to
+ * handle it). In this (and only this) case outFd, outEvents and
+ * outData will contain the poll events and data associated with the
+ * fd, otherwise they will be set to NULL.
*
* This method does not return until it has finished invoking the appropriate callbacks
* for all file descriptors that were signalled.
@@ -254,3 +265,5 @@
#endif
#endif // ANDROID_LOOPER_H
+
+/** @} */
diff --git a/include/android/native_activity.h b/include/android/native_activity.h
index bc70f88..d3d99cf 100644
--- a/include/android/native_activity.h
+++ b/include/android/native_activity.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup NativeActivity Native Activity
+ * @{
+ */
+
+/**
+ * @file native_activity.h
+ */
#ifndef ANDROID_NATIVE_ACTIVITY_H
#define ANDROID_NATIVE_ACTIVITY_H
@@ -31,6 +39,9 @@
extern "C" {
#endif
+/**
+ * {@link ANativeActivityCallbacks}
+ */
struct ANativeActivityCallbacks;
/**
@@ -75,17 +86,17 @@
* Path to this application's internal data directory.
*/
const char* internalDataPath;
-
+
/**
* Path to this application's external (removable/mountable) data directory.
*/
const char* externalDataPath;
-
+
/**
* The platform's SDK version code.
*/
int32_t sdkVersion;
-
+
/**
* This is the native instance of the application. It is not used by
* the framework, but can be set by the application to its own instance
@@ -119,13 +130,13 @@
* for more information.
*/
void (*onStart)(ANativeActivity* activity);
-
+
/**
* NativeActivity has resumed. See Java documentation for Activity.onResume()
* for more information.
*/
void (*onResume)(ANativeActivity* activity);
-
+
/**
* Framework is asking NativeActivity to save its current instance state.
* See Java documentation for Activity.onSaveInstanceState() for more
@@ -136,19 +147,19 @@
* entities (pointers to memory, file descriptors, etc).
*/
void* (*onSaveInstanceState)(ANativeActivity* activity, size_t* outSize);
-
+
/**
* NativeActivity has paused. See Java documentation for Activity.onPause()
* for more information.
*/
void (*onPause)(ANativeActivity* activity);
-
+
/**
* NativeActivity has stopped. See Java documentation for Activity.onStop()
* for more information.
*/
void (*onStop)(ANativeActivity* activity);
-
+
/**
* NativeActivity is being destroyed. See Java documentation for Activity.onDestroy()
* for more information.
@@ -160,7 +171,7 @@
* for example, to pause a game when it loses input focus.
*/
void (*onWindowFocusChanged)(ANativeActivity* activity, int hasFocus);
-
+
/**
* The drawing window for this native activity has been created. You
* can use the given native window object to start drawing.
@@ -191,13 +202,13 @@
* returning from here.
*/
void (*onNativeWindowDestroyed)(ANativeActivity* activity, ANativeWindow* window);
-
+
/**
* The input queue for this native activity's window has been created.
* You can use the given input queue to start retrieving input events.
*/
void (*onInputQueueCreated)(ANativeActivity* activity, AInputQueue* queue);
-
+
/**
* The input queue for this native activity's window is being destroyed.
* You should no longer try to reference this object upon returning from this
@@ -273,7 +284,17 @@
* API for documentation.
*/
enum {
+ /**
+ * Implicit request to show the input window, not as the result
+ * of a direct request by the user.
+ */
ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001,
+
+ /**
+ * 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.
+ */
ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002,
};
@@ -290,7 +311,15 @@
* API for documentation.
*/
enum {
+ /**
+ * The soft input window should only be hidden if it was not
+ * explicitly shown by the user.
+ */
ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001,
+ /**
+ * The soft input window should normally be hidden, unless it was
+ * originally shown with {@link ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED}.
+ */
ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002,
};
@@ -308,3 +337,4 @@
#endif // ANDROID_NATIVE_ACTIVITY_H
+/** @} */
diff --git a/include/android/native_window.h b/include/android/native_window.h
index 2f4f2d3..cf07f1a 100644
--- a/include/android/native_window.h
+++ b/include/android/native_window.h
@@ -14,6 +14,15 @@
* limitations under the License.
*/
+/**
+ * @addtogroup NativeActivity Native Activity
+ * @{
+ */
+
+/**
+ * @file native_window.h
+ */
+
#ifndef ANDROID_NATIVE_WINDOW_H
#define ANDROID_NATIVE_WINDOW_H
@@ -23,18 +32,31 @@
extern "C" {
#endif
-/*
+/**
* Pixel formats that a window can use.
*/
enum {
+ /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits. **/
WINDOW_FORMAT_RGBA_8888 = 1,
+ /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Unused: 8 bits. **/
WINDOW_FORMAT_RGBX_8888 = 2,
+ /** Red: 5 bits, Green: 6 bits, Blue: 5 bits. **/
WINDOW_FORMAT_RGB_565 = 4,
};
struct ANativeWindow;
+/**
+ * {@link ANativeWindow} is opaque type that provides access to a native window.
+ *
+ * A pointer can be obtained using ANativeWindow_fromSurface().
+ */
typedef struct ANativeWindow ANativeWindow;
+/**
+ * {@link ANativeWindow} is a struct that represents a windows buffer.
+ *
+ * A pointer can be obtained using ANativeWindow_lock().
+ */
typedef struct ANativeWindow_Buffer {
// The number of pixels that are show horizontally.
int32_t width;
@@ -51,7 +73,7 @@
// The actual bits.
void* bits;
-
+
// Do not touch.
uint32_t reserved[6];
} ANativeWindow_Buffer;
@@ -67,25 +89,25 @@
*/
void ANativeWindow_release(ANativeWindow* window);
-/*
+/**
* Return the current width in pixels of the window surface. Returns a
* negative value on error.
*/
int32_t ANativeWindow_getWidth(ANativeWindow* window);
-/*
+/**
* Return the current height in pixels of the window surface. Returns a
* negative value on error.
*/
int32_t ANativeWindow_getHeight(ANativeWindow* window);
-/*
+/**
* Return the current pixel format of the window surface. Returns a
* negative value on error.
*/
int32_t ANativeWindow_getFormat(ANativeWindow* window);
-/*
+/**
* Change the format and size of the window buffers.
*
* The width and height control the number of pixels in the buffers, not the
@@ -124,3 +146,5 @@
#endif
#endif // ANDROID_NATIVE_WINDOW_H
+
+/** @} */
diff --git a/include/android/native_window_jni.h b/include/android/native_window_jni.h
index b9e72ef..60a36c3 100644
--- a/include/android/native_window_jni.h
+++ b/include/android/native_window_jni.h
@@ -14,6 +14,15 @@
* limitations under the License.
*/
+/**
+ * @addtogroup NativeActivity Native Activity
+ * @{
+ */
+
+/**
+ * @file native_window_jni.h
+ */
+
#ifndef ANDROID_NATIVE_WINDOW_JNI_H
#define ANDROID_NATIVE_WINDOW_JNI_H
@@ -38,3 +47,5 @@
#endif
#endif // ANDROID_NATIVE_WINDOW_H
+
+/** @} */
diff --git a/include/android/obb.h b/include/android/obb.h
index 65e9b2a..4c6d9d7 100644
--- a/include/android/obb.h
+++ b/include/android/obb.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Storage
+ * @{
+ */
+
+/**
+ * @file obb.h
+ */
#ifndef ANDROID_OBB_H
#define ANDROID_OBB_H
@@ -25,9 +33,12 @@
#endif
struct AObbInfo;
+/** {@link AObbInfo} is an opaque type representing information for obb storage. */
typedef struct AObbInfo AObbInfo;
+/** Flag for an obb file, returned by AObbInfo_getFlags(). */
enum {
+ /** overlay */
AOBBINFO_OVERLAY = 0x0001,
};
@@ -61,3 +72,5 @@
#endif
#endif // ANDROID_OBB_H
+
+/** @} */
diff --git a/include/android/rect.h b/include/android/rect.h
index bcd42a9..80741c0 100644
--- a/include/android/rect.h
+++ b/include/android/rect.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup NativeActivity Native Activity
+ * @{
+ */
+
+/**
+ * @file rect.h
+ */
#ifndef ANDROID_RECT_H
#define ANDROID_RECT_H
@@ -24,13 +32,24 @@
extern "C" {
#endif
+/**
+ * {@link ARect} is a struct that represents a rectangular window area.
+ *
+ * It is used with {@link
+ * ANativeActivityCallbacks::onContentRectChanged} event callback and
+ * ANativeWindow_lock() function.
+ */
typedef struct ARect {
#ifdef __cplusplus
typedef int32_t value_type;
#endif
+ /** left position */
int32_t left;
+ /** top position */
int32_t top;
+ /** left position */
int32_t right;
+ /** bottom position */
int32_t bottom;
} ARect;
@@ -39,3 +58,5 @@
#endif
#endif // ANDROID_RECT_H
+
+/** @} */
diff --git a/include/android/sensor.h b/include/android/sensor.h
index d58c460..4600dad 100644
--- a/include/android/sensor.h
+++ b/include/android/sensor.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Sensor
+ * @{
+ */
+
+/**
+ * @file sensor.h
+ */
#ifndef ANDROID_SENSOR_H
#define ANDROID_SENSOR_H
@@ -34,7 +42,7 @@
* - DO NOT CHANGE THE LAYOUT OR SIZE OF STRUCTURES
*/
-/*
+/**
* Structures and functions to receive and process sensor events in
* native code.
*
@@ -49,37 +57,82 @@
#endif
-/*
- * Sensor types
+/**
+ * Sensor types.
* (keep in sync with hardware/sensor.h)
*/
-
enum {
+ /**
+ * {@link ASENSOR_TYPE_ACCELEROMETER}
+ * reporting-mode: continuous
+ *
+ * All values are in SI units (m/s^2) and measure the acceleration of the
+ * device minus the force of gravity.
+ */
ASENSOR_TYPE_ACCELEROMETER = 1,
+ /**
+ * {@link ASENSOR_TYPE_MAGNETIC_FIELD}
+ * reporting-mode: continuous
+ *
+ * All values are in micro-Tesla (uT) and measure the geomagnetic
+ * field in the X, Y and Z axis.
+ */
ASENSOR_TYPE_MAGNETIC_FIELD = 2,
+ /**
+ * {@link ASENSOR_TYPE_GYROSCOPE}
+ * reporting-mode: continuous
+ *
+ * All values are in radians/second and measure the rate of rotation
+ * around the X, Y and Z axis.
+ */
ASENSOR_TYPE_GYROSCOPE = 4,
+ /**
+ * {@link ASENSOR_TYPE_LIGHT}
+ * reporting-mode: on-change
+ *
+ * The light sensor value is returned in SI lux units.
+ */
ASENSOR_TYPE_LIGHT = 5,
+ /**
+ * {@link ASENSOR_TYPE_PROXIMITY}
+ * reporting-mode: on-change
+ *
+ * The proximity sensor which turns the screen off and back on during calls is the
+ * wake-up proximity sensor. Implement wake-up proximity sensor before implementing
+ * a non wake-up proximity sensor. For the wake-up proximity sensor set the flag
+ * SENSOR_FLAG_WAKE_UP.
+ * The value corresponds to the distance to the nearest object in centimeters.
+ */
ASENSOR_TYPE_PROXIMITY = 8
};
-/*
- * Sensor accuracy measure
+/**
+ * Sensor accuracy measure.
*/
enum {
+ /** no contact */
ASENSOR_STATUS_NO_CONTACT = -1,
+ /** unreliable */
ASENSOR_STATUS_UNRELIABLE = 0,
+ /** low accuracy */
ASENSOR_STATUS_ACCURACY_LOW = 1,
+ /** medium accuracy */
ASENSOR_STATUS_ACCURACY_MEDIUM = 2,
+ /** high accuracy */
ASENSOR_STATUS_ACCURACY_HIGH = 3
};
-/*
+/**
* Sensor Reporting Modes.
*/
enum {
+ /** continuous reporting */
AREPORTING_MODE_CONTINUOUS = 0,
+ /** reporting on change */
AREPORTING_MODE_ON_CHANGE = 1,
+ /** on shot reporting */
AREPORTING_MODE_ONE_SHOT = 2,
+ /** special trigger reporting */
AREPORTING_MODE_SPECIAL_TRIGGER = 3
};
@@ -87,14 +140,14 @@
* A few useful constants
*/
-/* Earth's gravity in m/s^2 */
+/** Earth's gravity in m/s^2 */
#define ASENSOR_STANDARD_GRAVITY (9.80665f)
-/* Maximum magnetic field on Earth's surface in uT */
+/** Maximum magnetic field on Earth's surface in uT */
#define ASENSOR_MAGNETIC_FIELD_EARTH_MAX (60.0f)
-/* Minimum magnetic field on Earth's surface in uT*/
+/** Minimum magnetic field on Earth's surface in uT*/
#define ASENSOR_MAGNETIC_FIELD_EARTH_MIN (30.0f)
-/*
+/**
* A sensor event.
*/
@@ -180,19 +233,82 @@
} ASensorEvent;
struct ASensorManager;
+/**
+ * {@link ASensorManager} is an opaque type to manage sensors and
+ * events queues.
+ *
+ * {@link ASensorManager} is a singleton that can be obtained using
+ * ASensorManager_getInstance().
+ *
+ * This file provides a set of functions that uses {@link
+ * ASensorManager} to access and list hardware sensors, and
+ * create and destroy event queues:
+ * - ASensorManager_getSensorList()
+ * - ASensorManager_getDefaultSensor()
+ * - ASensorManager_getDefaultSensorEx()
+ * - ASensorManager_createEventQueue()
+ * - ASensorManager_destroyEventQueue()
+ */
typedef struct ASensorManager ASensorManager;
+
struct ASensorEventQueue;
+/**
+ * {@link ASensorEventQueue} is an opaque type that provides access to
+ * {@link ASensorEvent} from hardware sensors.
+ *
+ * A new {@link ASensorEventQueue} can be obtained using ASensorManager_createEventQueue().
+ *
+ * This file provides a set of functions to enable and disable
+ * sensors, check and get events, and set event rates on a {@link
+ * ASensorEventQueue}.
+ * - ASensorEventQueue_enableSensor()
+ * - ASensorEventQueue_disableSensor()
+ * - ASensorEventQueue_hasEvents()
+ * - ASensorEventQueue_getEvents()
+ * - ASensorEventQueue_setEventRate()
+ */
typedef struct ASensorEventQueue ASensorEventQueue;
struct ASensor;
+/**
+ * {@link ASensor} is an opaque type that provides information about
+ * an hardware sensors.
+ *
+ * A {@link ASensor} pointer can be obtained using
+ * ASensorManager_getDefaultSensor(),
+ * ASensorManager_getDefaultSensorEx() or from a {@link ASensorList}.
+ *
+ * This file provides a set of functions to access properties of a
+ * {@link ASensor}:
+ * - ASensor_getName()
+ * - ASensor_getVendor()
+ * - ASensor_getType()
+ * - ASensor_getResolution()
+ * - ASensor_getMinDelay()
+ * - ASensor_getFifoMaxEventCount()
+ * - ASensor_getFifoReservedEventCount()
+ * - ASensor_getStringType()
+ * - ASensor_getReportingMode()
+ * - ASensor_isWakeUpSensor()
+ */
typedef struct ASensor ASensor;
+/**
+ * {@link ASensorRef} is a type for constant pointers to {@link ASensor}.
+ *
+ * This is used to define entry in {@link ASensorList} arrays.
+ */
typedef ASensor const* ASensorRef;
+/**
+ * {@link ASensorList} is an array of reference to {@link ASensor}.
+ *
+ * A {@link ASensorList} can be initialized using ASensorManager_getSensorList().
+ */
typedef ASensorRef const* ASensorList;
/*****************************************************************************/
-/*
+/**
* Get a reference to the sensor manager. ASensorManager is a singleton.
*
* Example:
@@ -203,31 +319,35 @@
ASensorManager* ASensorManager_getInstance();
-/*
+/**
* Returns the list of available sensors.
*/
int ASensorManager_getSensorList(ASensorManager* manager, ASensorList* list);
-/*
+/**
* Returns the default sensor for the given type, or NULL if no sensor
* of that type exists.
*/
ASensor const* ASensorManager_getDefaultSensor(ASensorManager* manager, int type);
-/*
+/**
* Returns the default sensor with the given type and wakeUp properties or NULL if no sensor
* of this type and wakeUp properties exists.
*/
ASensor const* ASensorManager_getDefaultSensorEx(ASensorManager* manager, int type,
bool wakeUp);
-/*
+/**
* Creates a new sensor event queue and associate it with a looper.
+ *
+ * "ident" is a identifier for the events that will be returned when
+ * calling ALooper_pollOnce(). The identifier must be >= 0, or
+ * ALOOPER_POLL_CALLBACK if providing a non-NULL callback.
*/
ASensorEventQueue* ASensorManager_createEventQueue(ASensorManager* manager,
ALooper* looper, int ident, ALooper_callbackFunc callback, void* data);
-/*
+/**
* Destroys the event queue and free all resources associated to it.
*/
int ASensorManager_destroyEventQueue(ASensorManager* manager, ASensorEventQueue* queue);
@@ -235,17 +355,17 @@
/*****************************************************************************/
-/*
+/**
* Enable the selected sensor. Returns a negative error code on failure.
*/
int ASensorEventQueue_enableSensor(ASensorEventQueue* queue, ASensor const* sensor);
-/*
+/**
* Disable the selected sensor. Returns a negative error code on failure.
*/
int ASensorEventQueue_disableSensor(ASensorEventQueue* queue, ASensor const* sensor);
-/*
+/**
* Sets the delivery rate of events in microseconds for the given sensor.
* Note that this is a hint only, generally event will arrive at a higher
* rate. It is an error to set a rate inferior to the value returned by
@@ -254,14 +374,14 @@
*/
int ASensorEventQueue_setEventRate(ASensorEventQueue* queue, ASensor const* sensor, int32_t usec);
-/*
+/**
* Returns true if there are one or more events available in the
* sensor queue. Returns 1 if the queue has events; 0 if
* it does not have events; and a negative value if there is an error.
*/
int ASensorEventQueue_hasEvents(ASensorEventQueue* queue);
-/*
+/**
* Returns the next available events from the queue. Returns a negative
* value if no events are available or an error has occurred, otherwise
* the number of events returned.
@@ -280,55 +400,55 @@
/*****************************************************************************/
-/*
+/**
* Returns this sensor's name (non localized)
*/
const char* ASensor_getName(ASensor const* sensor);
-/*
+/**
* Returns this sensor's vendor's name (non localized)
*/
const char* ASensor_getVendor(ASensor const* sensor);
-/*
+/**
* Return this sensor's type
*/
int ASensor_getType(ASensor const* sensor);
-/*
+/**
* Returns this sensors's resolution
*/
float ASensor_getResolution(ASensor const* sensor);
-/*
+/**
* Returns the minimum delay allowed between events in microseconds.
* A value of zero means that this sensor doesn't report events at a
* constant rate, but rather only when a new data is available.
*/
int ASensor_getMinDelay(ASensor const* sensor);
-/*
+/**
* Returns the maximum size of batches for this sensor. Batches will often be
* smaller, as the hardware fifo might be used for other sensors.
*/
int ASensor_getFifoMaxEventCount(ASensor const* sensor);
-/*
+/**
* Returns the hardware batch fifo size reserved to this sensor.
*/
int ASensor_getFifoReservedEventCount(ASensor const* sensor);
-/*
+/**
* Returns this sensor's string type.
*/
const char* ASensor_getStringType(ASensor const* sensor);
-/*
+/**
* Returns the reporting mode for this sensor. One of AREPORTING_MODE_* constants.
*/
int ASensor_getReportingMode(ASensor const* sensor);
-/*
+/**
* Returns true if this is a wake up sensor, false otherwise.
*/
bool ASensor_isWakeUpSensor(ASensor const* sensor);
@@ -338,3 +458,5 @@
#endif
#endif // ANDROID_SENSOR_H
+
+/** @} */
diff --git a/include/android/storage_manager.h b/include/android/storage_manager.h
index bad2491..7f2ee08 100644
--- a/include/android/storage_manager.h
+++ b/include/android/storage_manager.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup Storage
+ * @{
+ */
+
+/**
+ * @file storage_manager.h
+ */
#ifndef ANDROID_STORAGE_MANAGER_H
#define ANDROID_STORAGE_MANAGER_H
@@ -25,55 +33,62 @@
#endif
struct AStorageManager;
+/**
+ * {@link AStorageManager} manages application OBB storage, a pointer
+ * can be obtained with AStorageManager_new().
+ */
typedef struct AStorageManager AStorageManager;
+/**
+ * The different states of a OBB storage passed to AStorageManager_obbCallbackFunc().
+ */
enum {
- /*
+ /**
* The OBB container is now mounted and ready for use. Can be returned
* as the status for callbacks made during asynchronous OBB actions.
*/
AOBB_STATE_MOUNTED = 1,
- /*
+ /**
* The OBB container is now unmounted and not usable. Can be returned
* as the status for callbacks made during asynchronous OBB actions.
*/
AOBB_STATE_UNMOUNTED = 2,
- /*
+ /**
* There was an internal system error encountered while trying to
* mount the OBB. Can be returned as the status for callbacks made
* during asynchronous OBB actions.
*/
AOBB_STATE_ERROR_INTERNAL = 20,
- /*
+ /**
* The OBB could not be mounted by the system. Can be returned as the
* status for callbacks made during asynchronous OBB actions.
*/
AOBB_STATE_ERROR_COULD_NOT_MOUNT = 21,
- /*
+ /**
* The OBB could not be unmounted. This most likely indicates that a
* file is in use on the OBB. Can be returned as the status for
* callbacks made during asynchronous OBB actions.
*/
AOBB_STATE_ERROR_COULD_NOT_UNMOUNT = 22,
- /*
+ /**
* A call was made to unmount the OBB when it was not mounted. Can be
* returned as the status for callbacks made during asynchronous OBB
* actions.
*/
AOBB_STATE_ERROR_NOT_MOUNTED = 23,
- /*
+ /**
* The OBB has already been mounted. Can be returned as the status for
* callbacks made during asynchronous OBB actions.
*/
AOBB_STATE_ERROR_ALREADY_MOUNTED = 24,
- /*
+ /**
* The current application does not have permission to use this OBB.
* This could be because the OBB indicates it's owned by a different
* package. Can be returned as the status for callbacks made during
@@ -94,6 +109,16 @@
/**
* Callback function for asynchronous calls made on OBB files.
+ *
+ * "state" is one of the following constants:
+ * - {@link AOBB_STATE_MOUNTED}
+ * - {@link AOBB_STATE_UNMOUNTED}
+ * - {@link AOBB_STATE_ERROR_INTERNAL}
+ * - {@link AOBB_STATE_ERROR_COULD_NOT_MOUNT}
+ * - {@link AOBB_STATE_ERROR_COULD_NOT_UNMOUNT}
+ * - {@link AOBB_STATE_ERROR_NOT_MOUNTED}
+ * - {@link AOBB_STATE_ERROR_ALREADY_MOUNTED}
+ * - {@link AOBB_STATE_ERROR_PERMISSION_DENIED}
*/
typedef void (*AStorageManager_obbCallbackFunc)(const char* filename, const int32_t state, void* data);
@@ -125,3 +150,5 @@
#endif
#endif // ANDROID_STORAGE_MANAGER_H
+
+/** @} */
diff --git a/include/android/window.h b/include/android/window.h
index 2ab192b..436bf3a 100644
--- a/include/android/window.h
+++ b/include/android/window.h
@@ -14,6 +14,14 @@
* limitations under the License.
*/
+/**
+ * @addtogroup NativeActivity Native Activity
+ * @{
+ */
+
+/**
+ * @file window.h
+ */
#ifndef ANDROID_WINDOW_H
#define ANDROID_WINDOW_H
@@ -26,28 +34,184 @@
* Window flags, as per the Java API at android.view.WindowManager.LayoutParams.
*/
enum {
+ /**
+ * 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 {@link
+ * AWINDOW_FLAG_KEEP_SCREEN_ON} and/or {@link
+ * AWINDOW_FLAG_SHOW_WHEN_LOCKED}
+ */
AWINDOW_FLAG_ALLOW_LOCK_WHILE_SCREEN_ON = 0x00000001,
+ /** Everything behind this window will be dimmed. */
AWINDOW_FLAG_DIM_BEHIND = 0x00000002,
+ /**
+ * Blur everything behind this window.
+ * @deprecated Blurring is no longer supported.
+ */
AWINDOW_FLAG_BLUR_BEHIND = 0x00000004,
+ /**
+ * 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 {@link AWINDOW_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 {@link AWINDOW_FLAG_ALT_FOCUSABLE_IM} to modify this behavior.
+ */
AWINDOW_FLAG_NOT_FOCUSABLE = 0x00000008,
+ /** this window can never receive touch events. */
AWINDOW_FLAG_NOT_TOUCHABLE = 0x00000010,
+ /**
+ * Even when this window is focusable (its
+ * {@link AWINDOW_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.
+ */
AWINDOW_FLAG_NOT_TOUCH_MODAL = 0x00000020,
+ /**
+ * 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.
+ */
AWINDOW_FLAG_TOUCHABLE_WHEN_WAKING = 0x00000040,
+ /**
+ * As long as this window is visible to the user, keep
+ * the device's screen turned on and bright.
+ */
AWINDOW_FLAG_KEEP_SCREEN_ON = 0x00000080,
+ /**
+ * 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.
+ */
AWINDOW_FLAG_LAYOUT_IN_SCREEN = 0x00000100,
+ /** allow window to extend outside of the screen. */
AWINDOW_FLAG_LAYOUT_NO_LIMITS = 0x00000200,
+ /**
+ * 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 {@link
+ * AWINDOW_SOFT_INPUT_ADJUST_RESIZE}; the window will stay
+ * fullscreen and will not resize.
+ */
AWINDOW_FLAG_FULLSCREEN = 0x00000400,
+ /**
+ * Override {@link AWINDOW_FLAG_FULLSCREEN} and force the
+ * screen decorations (such as the status bar) to be shown.
+ */
AWINDOW_FLAG_FORCE_NOT_FULLSCREEN = 0x00000800,
+ /**
+ * Turn on dithering when compositing this window to
+ * the screen.
+ * @deprecated This flag is no longer used.
+ */
AWINDOW_FLAG_DITHER = 0x00001000,
+ /**
+ * Treat the content of the window as secure, preventing
+ * it from appearing in screenshots or from being viewed on non-secure
+ * displays.
+ */
AWINDOW_FLAG_SECURE = 0x00002000,
+ /**
+ * A special mode where the layout parameters are used
+ * to perform scaling of the surface when it is composited to the
+ * screen.
+ */
AWINDOW_FLAG_SCALED = 0x00004000,
+ /**
+ * 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 {@link 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.
+ */
AWINDOW_FLAG_IGNORE_CHEEK_PRESSES = 0x00008000,
+ /**
+ * A special option only for use in combination with
+ * {@link AWINDOW_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.
+ */
AWINDOW_FLAG_LAYOUT_INSET_DECOR = 0x00010000,
+ /**
+ * Invert the state of {@link AWINDOW_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 {@link
+ * AWINDOW_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.
+ */
AWINDOW_FLAG_ALT_FOCUSABLE_IM = 0x00020000,
+ /**
+ * If you have set {@link AWINDOW_FLAG_NOT_TOUCH_MODAL}, you
+ * can set this flag to receive a single special MotionEvent with
+ * the action
+ * {@link 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 {@link AMOTION_EVENT_ACTION_OUTSIDE}.
+ */
AWINDOW_FLAG_WATCH_OUTSIDE_TOUCH = 0x00040000,
+ /**
+ * 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
+ * {@link AWINDOW_FLAG_KEEP_SCREEN_ON} to turn screen on and display windows
+ * directly before showing the key guard window. Can be used with
+ * {@link AWINDOW_FLAG_DISMISS_KEYGUARD} to automatically fully dismisss
+ * non-secure keyguards. This flag only applies to the top-most
+ * full-screen window.
+ */
AWINDOW_FLAG_SHOW_WHEN_LOCKED = 0x00080000,
+ /**
+ * 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.
+ */
AWINDOW_FLAG_SHOW_WALLPAPER = 0x00100000,
+ /**
+ * 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.
+ */
AWINDOW_FLAG_TURN_SCREEN_ON = 0x00200000,
+ /**
+ * 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
+ * {@link AWINDOW_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 {@link AWINDOW_FLAG_SHOW_WHEN_LOCKED} has
+ * also been set.
+ */
AWINDOW_FLAG_DISMISS_KEYGUARD = 0x00400000,
};
@@ -56,3 +220,5 @@
#endif
#endif // ANDROID_WINDOW_H
+
+/** @} */