public class ContextCompat extends Object
Context
introduced after API level 4 in a backwards compatible fashion.Modifier | Constructor and Description |
---|---|
protected |
ContextCompat()
This class should not be instantiated, but the constructor must be
visible for the class to be extended (ex. in ActivityCompat).
|
Modifier and Type | Method and Description |
---|---|
static int |
checkSelfPermission(Context context,
String permission)
Determine whether you have been granted a particular permission.
|
static Context |
createDeviceProtectedStorageContext(Context context)
Return a new Context object for the current Context but whose storage
APIs are backed by device-protected storage.
|
static File |
getCodeCacheDir(Context context)
Returns the absolute path to the application specific cache directory on
the filesystem designed for storing cached code.
|
static int |
getColor(Context context,
int id)
Returns a color associated with a particular resource ID
Starting in
Build.VERSION_CODES.M , the returned
color will be styled for the specified Context's theme. |
static ColorStateList |
getColorStateList(Context context,
int id)
Returns a color state list associated with a particular resource ID.
|
static File |
getDataDir(Context context)
Returns the absolute path to the directory on the filesystem where all
private files belonging to this app are stored.
|
static Drawable |
getDrawable(Context context,
int id)
Returns a drawable object associated with a particular resource ID.
|
static File[] |
getExternalCacheDirs(Context context)
Returns absolute paths to application-specific directories on all
external storage devices where the application can place cache files it
owns.
|
static File[] |
getExternalFilesDirs(Context context,
String type)
Returns absolute paths to application-specific directories on all
external storage devices where the application can place persistent files
it owns.
|
static File |
getNoBackupFilesDir(Context context)
Returns the absolute path to the directory on the filesystem similar to
Context.getFilesDir() . |
static File[] |
getObbDirs(Context context)
Returns absolute paths to application-specific directories on all
external storage devices where the application's OBB files (if there are
any) can be found.
|
static boolean |
isDeviceProtectedStorage(Context context)
Indicates if the storage APIs of this Context are backed by
device-encrypted storage.
|
static boolean |
startActivities(Context context,
Intent[] intents)
Start a set of activities as a synthesized task stack, if able.
|
static boolean |
startActivities(Context context,
Intent[] intents,
Bundle options)
Start a set of activities as a synthesized task stack, if able.
|
static void |
startActivity(Context context,
Intent intent,
Bundle options)
Start an activity with additional launch information, if able.
|
protected ContextCompat()
public static boolean startActivities(Context context, Intent[] intents)
In API level 11 (Android 3.0/Honeycomb) the recommended conventions for app navigation using the back key changed. The back key's behavior is local to the current task and does not capture navigation across different tasks. Navigating across tasks and easily reaching the previous task is accomplished through the "recents" UI, accessible through the software-provided Recents key on the navigation or system bar. On devices with the older hardware button configuration the recents UI can be accessed with a long press on the Home key.
When crossing from one task stack to another post-Android 3.0, the application should synthesize a back stack/history for the new task so that the user may navigate out of the new task and back to the Launcher by repeated presses of the back key. Back key presses should not navigate across task stacks.
startActivities provides a mechanism for constructing a synthetic task stack of multiple activities. If the underlying API is not available on the system this method will return false.
context
- Start activities using this activity as the starting contextintents
- Array of intents defining the activities that will be started. The element
length-1 will correspond to the top activity on the resulting task stack.public static boolean startActivities(Context context, Intent[] intents, Bundle options)
In API level 11 (Android 3.0/Honeycomb) the recommended conventions for app navigation using the back key changed. The back key's behavior is local to the current task and does not capture navigation across different tasks. Navigating across tasks and easily reaching the previous task is accomplished through the "recents" UI, accessible through the software-provided Recents key on the navigation or system bar. On devices with the older hardware button configuration the recents UI can be accessed with a long press on the Home key.
When crossing from one task stack to another post-Android 3.0, the application should synthesize a back stack/history for the new task so that the user may navigate out of the new task and back to the Launcher by repeated presses of the back key. Back key presses should not navigate across task stacks.
startActivities provides a mechanism for constructing a synthetic task stack of multiple activities. If the underlying API is not available on the system this method will return false.
context
- Start activities using this activity as the starting contextintents
- Array of intents defining the activities that will be started. The element
length-1 will correspond to the top activity on the resulting task stack.options
- Additional options for how the Activity should be started.
See Context.startActivity(Intent, android.os.Bundle)
public static void startActivity(Context context, Intent intent, @Nullable Bundle options)
In Android 4.1+ additional options were introduced to allow for more
control on activity launch animations. Applications can use this method
along with ActivityOptionsCompat
to use these animations when
available. When run on versions of the platform where this feature does
not exist the activity will be launched normally.
context
- Context to launch activity from.intent
- The description of the activity to start.options
- Additional options for how the Activity should be started.
May be null if there are no options. See
ActivityOptionsCompat
for how to build the Bundle
supplied here; there are no supported definitions for
building it manually.public static File getDataDir(Context context)
Context.getFilesDir()
,
Context.getCacheDir()
, Context.getDir(String, int)
, or
other storage APIs on Context
.
The returned path may change over time if the calling app is moved to an adopted storage device, so only relative paths should be persisted.
No additional permissions are required for the calling app to read or write files under the returned path.
ApplicationInfo.dataDir
public static File[] getObbDirs(Context context)
This is like Context.getFilesDir()
in that these files will be
deleted when the application is uninstalled, however there are some
important differences:
External storage devices returned here are considered a permanent part of the device, including both emulated external storage and physical media slots, such as SD cards in a battery compartment. The returned paths do not include transient devices, such as USB flash drives.
An application may store data on any or all of the returned devices. For
example, an app may choose to store large files on the device with the
most available space, as measured by StatFs
.
Starting in Build.VERSION_CODES.KITKAT
, no permissions
are required to write to the returned paths; they're always accessible to
the calling app. Before then,
android.Manifest.permission#WRITE_EXTERNAL_STORAGE
is required to
write. Write access outside of these paths on secondary external storage
devices is not available. To request external storage access in a
backwards compatible way, consider using android:maxSdkVersion
like this:
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="18" />
The first path returned is the same as Context.getObbDir()
.
Returned paths may be null
if a storage device is unavailable.
public static File[] getExternalFilesDirs(Context context, String type)
This is like Context.getFilesDir()
in that these files will be
deleted when the application is uninstalled, however there are some
important differences:
External storage devices returned here are considered a permanent part of the device, including both emulated external storage and physical media slots, such as SD cards in a battery compartment. The returned paths do not include transient devices, such as USB flash drives.
An application may store data on any or all of the returned devices. For
example, an app may choose to store large files on the device with the
most available space, as measured by StatFs
.
Starting in Build.VERSION_CODES.KITKAT
, no permissions
are required to write to the returned paths; they're always accessible to
the calling app. Before then,
android.Manifest.permission#WRITE_EXTERNAL_STORAGE
is required to
write. Write access outside of these paths on secondary external storage
devices is not available. To request external storage access in a
backwards compatible way, consider using android:maxSdkVersion
like this:
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="18" />
The first path returned is the same as
Context.getExternalFilesDir(String)
. Returned paths may be
null
if a storage device is unavailable.
public static File[] getExternalCacheDirs(Context context)
This is like Context.getCacheDir()
in that these files will be
deleted when the application is uninstalled, however there are some
important differences:
External storage devices returned here are considered a permanent part of the device, including both emulated external storage and physical media slots, such as SD cards in a battery compartment. The returned paths do not include transient devices, such as USB flash drives.
An application may store data on any or all of the returned devices. For
example, an app may choose to store large files on the device with the
most available space, as measured by StatFs
.
Starting in Build.VERSION_CODES.KITKAT
, no permissions
are required to write to the returned paths; they're always accessible to
the calling app. Before then,
android.Manifest.permission#WRITE_EXTERNAL_STORAGE
is required to
write. Write access outside of these paths on secondary external storage
devices is not available. To request external storage access in a
backwards compatible way, consider using android:maxSdkVersion
like this:
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" android:maxSdkVersion="18" />
The first path returned is the same as
Context.getExternalCacheDir()
. Returned paths may be null
if a storage device is unavailable.
public static final Drawable getDrawable(Context context, @DrawableRes int id)
Starting in Build.VERSION_CODES.LOLLIPOP
, the
returned drawable will be styled for the specified Context's theme.
id
- The desired resource identifier, as generated by the aapt tool.
This integer encodes the package, type, and resource entry.
The value 0 is an invalid identifier.public static final ColorStateList getColorStateList(Context context, @ColorRes int id)
Starting in Build.VERSION_CODES.M
, the returned
color state list will be styled for the specified Context's theme.
id
- The desired resource identifier, as generated by the aapt
tool. This integer encodes the package, type, and resource
entry. The value 0 is an invalid identifier.null
if the resource could not be
resolved.Resources.NotFoundException
- if the given ID
does not exist.public static final int getColor(Context context, @ColorRes int id)
Starting in Build.VERSION_CODES.M
, the returned
color will be styled for the specified Context's theme.
id
- The desired resource identifier, as generated by the aapt
tool. This integer encodes the package, type, and resource
entry. The value 0 is an invalid identifier.Resources.NotFoundException
- if the given ID
does not exist.public static int checkSelfPermission(@NonNull Context context, @NonNull String permission)
permission
- The name of the permission being checked.PackageManager.PERMISSION_GRANTED
if you have the
permission, or PackageManager.PERMISSION_DENIED
if not.PackageManager.checkPermission(String, String)
public static final File getNoBackupFilesDir(Context context)
Context.getFilesDir()
. The difference is that files placed under this
directory will be excluded from automatic backup to remote storage on
devices running Build.VERSION_CODES.LOLLIPOP
or later.
No permissions are required to read or write to the returned path, since this path is internal storage.
Context.getFilesDir()
public static File getCodeCacheDir(Context context)
Build.VERSION_CODES.LOLLIPOP
or later, the system will delete
any files stored in this location both when your specific application is
upgraded, and when the entire platform is upgraded.
This location is optimal for storing compiled or optimized code generated by your application at runtime.
Apps require no extra permissions to read or write to the returned path, since this path lives in their private storage.
public static Context createDeviceProtectedStorageContext(Context context)
On devices with direct boot, data stored in this location is encrypted with a key tied to the physical device, and it can be accessed immediately after the device has booted successfully, both before and after the user has authenticated with their credentials (such as a lock pattern or PIN).
Because device-protected data is available without user authentication, you should carefully limit the data you store using this Context. For example, storing sensitive authentication tokens or passwords in the device-protected area is strongly discouraged.
If the underlying device does not have the ability to store device-protected and credential-protected data using different keys, then both storage areas will become available at the same time. They remain as two distinct storage locations on disk, and only the window of availability changes.
Each call to this method returns a new instance of a Context object; Context objects are not shared, however common state (ClassLoader, other Resources for the same configuration) may be so the Context itself can be fairly lightweight.
Prior to BuildCompat.isAtLeastN()
this method returns
null
, since device-protected storage is not available.
isDeviceProtectedStorage(Context)
public static boolean isDeviceProtectedStorage(Context context)