android.support.v4.content
Class ContextCompat

java.lang.Object
  extended by android.support.v4.content.ContextCompat
Direct Known Subclasses:
ActivityCompat

public class ContextCompat
extends java.lang.Object

Helper for accessing features in Context introduced after API level 4 in a backwards compatible fashion.


Constructor Summary
ContextCompat()
           
 
Method Summary
static java.io.File[] getExternalCacheDirs(android.content.Context context)
          Returns absolute paths to application-specific directories on all external storage devices where the application can place cache files it owns.
static java.io.File[] getExternalFilesDirs(android.content.Context context, java.lang.String type)
          Returns absolute paths to application-specific directories on all external storage devices where the application can place persistent files it owns.
static java.io.File[] getObbDirs(android.content.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 startActivities(android.content.Context context, android.content.Intent[] intents)
          Start a set of activities as a synthesized task stack, if able.
static boolean startActivities(android.content.Context context, android.content.Intent[] intents, android.os.Bundle options)
          Start a set of activities as a synthesized task stack, if able.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ContextCompat

public ContextCompat()
Method Detail

startActivities

public static boolean startActivities(android.content.Context context,
                                      android.content.Intent[] intents)
Start a set of activities as a synthesized task stack, if able.

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.

Parameters:
context - Start activities using this activity as the starting context
intents - 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.
Returns:
true if the underlying API was available and the call was successful, false otherwise

startActivities

public static boolean startActivities(android.content.Context context,
                                      android.content.Intent[] intents,
                                      android.os.Bundle options)
Start a set of activities as a synthesized task stack, if able.

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.

Parameters:
context - Start activities using this activity as the starting context
intents - 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 {@link android.content.Context#startActivity(Intent, Bundle)
Returns:
true if the underlying API was available and the call was successful, false otherwise

getObbDirs

public static java.io.File[] getObbDirs(android.content.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. Note if the application does not have any OBB files, these directories may not exist.

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 android.os.Build.VERSION_CODES#KITKAT, no permissions are required to write to the returned paths; they're always accessible to the calling app. Before then, 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.

See Also:
Context#getObbDir(), EnvironmentCompat.getStorageState(File)

getExternalFilesDirs

public static java.io.File[] getExternalFilesDirs(android.content.Context context,
                                                  java.lang.String type)
Returns absolute paths to application-specific directories on all external storage devices where the application can place persistent files it owns. These files are internal to the application, and not typically visible to the user as media.

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 android.os.Build.VERSION_CODES#KITKAT, no permissions are required to write to the returned paths; they're always accessible to the calling app. Before then, 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.

See Also:
Context#getExternalFilesDir(String), EnvironmentCompat.getStorageState(File)

getExternalCacheDirs

public static java.io.File[] getExternalCacheDirs(android.content.Context context)
Returns absolute paths to application-specific directories on all external storage devices where the application can place cache files it owns. These files are internal to the application, and not typically visible to the user as media.

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 android.os.Build.VERSION_CODES#KITKAT, no permissions are required to write to the returned paths; they're always accessible to the calling app. Before then, 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.

See Also:
Context#getExternalCacheDir(), EnvironmentCompat.getStorageState(File)