com.theartofdev.edmodo.cropper

Class CropImage

java.lang.Object

com.theartofdev.edmodo.cropper.CropImage

public final class CropImage
extends java.lang.Object

Helper to simplify crop image work like starting pick-image acitvity and handling camera/gallery intents.
The goal of the helper is to simplify the starting and most-common usage of image cropping and not all porpose all possible scenario one-to-rule-them-all code base. So feel free to use it as is and as a wiki to make your own.
Added value you get out-of-the-box is some edge case handling that you may miss otherwise, like the stupid-ass Android camera result URI that may differ from version to version and from device to device.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CropImage.ActivityBuilder Builder used for creating Image Crop Activity by user request.
static class	CropImage.ActivityResult Result data of Crop Image Activity.

Field Summary

Fields

Modifier and Type	Field and Description
static int	CAMERA_CAPTURE_PERMISSIONS_REQUEST_CODE The request code used to request permission to capture image from camera.
static int	CROP_IMAGE_ACTIVITY_REQUEST_CODE The request code used to start CropImageActivity to be used on result to identify the this specific request.
static int	CROP_IMAGE_ACTIVITY_RESULT_ERROR_CODE The result code used to return error from CropImageActivity.
static java.lang.String	CROP_IMAGE_EXTRA_BUNDLE The key used to pass crop image bundle data to CropImageActivity.
static java.lang.String	CROP_IMAGE_EXTRA_OPTIONS The key used to pass crop image options to CropImageActivity.
static java.lang.String	CROP_IMAGE_EXTRA_RESULT The key used to pass crop image result data back from CropImageActivity.
static java.lang.String	CROP_IMAGE_EXTRA_SOURCE The key used to pass crop image source URI to CropImageActivity.
static int	PICK_IMAGE_CHOOSER_REQUEST_CODE The request code used to start pick image activity to be used on result to identify the this specific request.
static int	PICK_IMAGE_PERMISSIONS_REQUEST_CODE The request code used to request permission to pick image from external storage.

Method Summary

Modifier and Type	Method and Description
static CropImage.ActivityBuilder	activity() Create CropImage.ActivityBuilder instance to open image picker for cropping and then start CropImageActivity to crop the selected image. Result will be received in Activity.onActivityResult(int, int, Intent) and can be retrieved using getActivityResult(Intent).
static CropImage.ActivityBuilder	activity(android.net.Uri uri) Create CropImage.ActivityBuilder instance to start CropImageActivity to crop the given image. Result will be received in Activity.onActivityResult(int, int, Intent) and can be retrieved using getActivityResult(Intent).
static CropImage.ActivityResult	getActivityResult(android.content.Intent data) Get CropImageActivity result data object for crop image activity started using activity(Uri).
static android.content.Intent	getCameraIntent(android.content.Context context, android.net.Uri outputFileUri) Get the main Camera intent for capturing image using device camera app.
static java.util.List<android.content.Intent>	getCameraIntents(android.content.Context context, android.content.pm.PackageManager packageManager) Get all Camera intents for capturing image using device camera apps.
static android.net.Uri	getCaptureImageOutputUri(android.content.Context context) Get URI to image received from capture by camera.
static java.util.List<android.content.Intent>	getGalleryIntents(android.content.pm.PackageManager packageManager, java.lang.String action, boolean includeDocuments) Get all Gallery intents for getting image from one of the apps of the device that handle images.
static android.content.Intent	getPickImageChooserIntent(android.content.Context context) Create a chooser intent to select the source to get image from. The source can be camera's (ACTION_IMAGE_CAPTURE) or gallery's (ACTION_GET_CONTENT). All possible sources are added to the intent chooser. Use "pick_image_intent_chooser_title" string resource to override chooser title.
static android.content.Intent	getPickImageChooserIntent(android.content.Context context, java.lang.CharSequence title, boolean includeDocuments, boolean includeCamera) Create a chooser intent to select the source to get image from. The source can be camera's (ACTION_IMAGE_CAPTURE) or gallery's (ACTION_GET_CONTENT). All possible sources are added to the intent chooser.
static android.net.Uri	getPickImageResultUri(android.content.Context context, android.content.Intent data) Get the URI of the selected image from getPickImageChooserIntent(Context). Will return the correct URI for camera and gallery image.
static boolean	hasPermissionInManifest(android.content.Context context, java.lang.String permissionName) Check if the app requests a specific permission in the manifest.
static boolean	isExplicitCameraPermissionRequired(android.content.Context context) Check if explicetly requesting camera permission is required. It is required in Android Marshmellow and above if "CAMERA" permission is requested in the manifest. See StackOverflow question.
static boolean	isReadExternalStoragePermissionsRequired(android.content.Context context, android.net.Uri uri) Check if the given picked image URI requires READ_EXTERNAL_STORAGE permissions. Only relevant for API version 23 and above and not required for all URI's depends on the implementation of the app that was used for picking the image.
static boolean	isUriRequiresPermissions(android.content.Context context, android.net.Uri uri) Test if we can open the given Android URI to test if permission required error is thrown. Only relevant for API version 23 and above.
static void	startPickImageActivity(android.app.Activity activity) Start an activity to get image for cropping using chooser intent that will have all the available applications for the device like camera (MyCamera), galery (Photos), store apps (Dropbox), etc. Use "pick_image_intent_chooser_title" string resource to override pick chooser title.
static void	startPickImageActivity(android.content.Context context, Fragment fragment) Same as startPickImageActivity method but instead of being called and returning to an Activity, this method can be called and return to a Fragment.
static android.graphics.Bitmap	toOvalBitmap(android.graphics.Bitmap bitmap) Create a new bitmap that has all pixels beyond the oval shape transparent.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CROP_IMAGE_EXTRA_SOURCE

public static final java.lang.String CROP_IMAGE_EXTRA_SOURCE

The key used to pass crop image source URI to CropImageActivity.

See Also:

Constant Field Values

CROP_IMAGE_EXTRA_OPTIONS

public static final java.lang.String CROP_IMAGE_EXTRA_OPTIONS

The key used to pass crop image options to CropImageActivity.

See Also:

Constant Field Values

CROP_IMAGE_EXTRA_BUNDLE

public static final java.lang.String CROP_IMAGE_EXTRA_BUNDLE

The key used to pass crop image bundle data to CropImageActivity.

See Also:

Constant Field Values

CROP_IMAGE_EXTRA_RESULT

public static final java.lang.String CROP_IMAGE_EXTRA_RESULT

The key used to pass crop image result data back from CropImageActivity.

See Also:

Constant Field Values

PICK_IMAGE_CHOOSER_REQUEST_CODE

public static final int PICK_IMAGE_CHOOSER_REQUEST_CODE

The request code used to start pick image activity to be used on result to identify the this specific request.

See Also:

Constant Field Values

PICK_IMAGE_PERMISSIONS_REQUEST_CODE

public static final int PICK_IMAGE_PERMISSIONS_REQUEST_CODE

The request code used to request permission to pick image from external storage.

See Also:

Constant Field Values

CAMERA_CAPTURE_PERMISSIONS_REQUEST_CODE

public static final int CAMERA_CAPTURE_PERMISSIONS_REQUEST_CODE

The request code used to request permission to capture image from camera.

See Also:

Constant Field Values

CROP_IMAGE_ACTIVITY_REQUEST_CODE

public static final int CROP_IMAGE_ACTIVITY_REQUEST_CODE

The request code used to start CropImageActivity to be used on result to identify the this specific request.

See Also:

Constant Field Values

CROP_IMAGE_ACTIVITY_RESULT_ERROR_CODE

public static final int CROP_IMAGE_ACTIVITY_RESULT_ERROR_CODE

The result code used to return error from CropImageActivity.

See Also:

Constant Field Values

Method Detail

toOvalBitmap

public static android.graphics.Bitmap toOvalBitmap(android.graphics.Bitmap bitmap)

Create a new bitmap that has all pixels beyond the oval shape transparent. Old bitmap is recycled.

startPickImageActivity

public static void startPickImageActivity(android.app.Activity activity)

Start an activity to get image for cropping using chooser intent that will have all the available applications for the device like camera (MyCamera), galery (Photos), store apps (Dropbox), etc.
Use "pick_image_intent_chooser_title" string resource to override pick chooser title.

Parameters:

activity - the activity to be used to start activity from

startPickImageActivity

public static void startPickImageActivity(android.content.Context context,
                                          Fragment fragment)

Same as startPickImageActivity method but instead of being called and returning to an Activity, this method can be called and return to a Fragment.

Parameters:

context - The Fragments context. Use getContext()

fragment - The calling Fragment to start and return the image to

getPickImageChooserIntent

public static android.content.Intent getPickImageChooserIntent(android.content.Context context)

Create a chooser intent to select the source to get image from.
The source can be camera's (ACTION_IMAGE_CAPTURE) or gallery's (ACTION_GET_CONTENT).
All possible sources are added to the intent chooser.
Use "pick_image_intent_chooser_title" string resource to override chooser title.

Parameters:

context - used to access Android APIs, like content resolve, it is your activity/fragment/widget.

getPickImageChooserIntent

public static android.content.Intent getPickImageChooserIntent(android.content.Context context,
                                                               java.lang.CharSequence title,
                                                               boolean includeDocuments,
                                                               boolean includeCamera)

Create a chooser intent to select the source to get image from.
The source can be camera's (ACTION_IMAGE_CAPTURE) or gallery's (ACTION_GET_CONTENT).
All possible sources are added to the intent chooser.

Parameters:

context - used to access Android APIs, like content resolve, it is your activity/fragment/widget.

title - the title to use for the chooser UI

includeDocuments - if to include KitKat documents activity containing all sources

includeCamera - if to include camera intents

getCameraIntent

public static android.content.Intent getCameraIntent(android.content.Context context,
                                                     android.net.Uri outputFileUri)

Get the main Camera intent for capturing image using device camera app. If the outputFileUri is null, a default Uri will be created with getCaptureImageOutputUri(Context), so then you will be able to get the pictureUri using getPickImageResultUri(Context, Intent). Otherwise, it is just you use the Uri passed to this method.

Parameters:

context - used to access Android APIs, like content resolve, it is your activity/fragment/widget.

outputFileUri - the Uri where the picture will be placed.

getCameraIntents

public static java.util.List<android.content.Intent> getCameraIntents(android.content.Context context,
                                                                      android.content.pm.PackageManager packageManager)

Get all Camera intents for capturing image using device camera apps.

getGalleryIntents

public static java.util.List<android.content.Intent> getGalleryIntents(android.content.pm.PackageManager packageManager,
                                                                       java.lang.String action,
                                                                       boolean includeDocuments)

Get all Gallery intents for getting image from one of the apps of the device that handle images.

isExplicitCameraPermissionRequired

public static boolean isExplicitCameraPermissionRequired(android.content.Context context)

Check if explicetly requesting camera permission is required.
It is required in Android Marshmellow and above if "CAMERA" permission is requested in the manifest.
See StackOverflow question.

hasPermissionInManifest

public static boolean hasPermissionInManifest(android.content.Context context,
                                              java.lang.String permissionName)

Check if the app requests a specific permission in the manifest.

Parameters:

permissionName - the permission to check

Returns:

true - the permission in requested in manifest, false - not.

getCaptureImageOutputUri

public static android.net.Uri getCaptureImageOutputUri(android.content.Context context)

Get URI to image received from capture by camera.

Parameters:

context - used to access Android APIs, like content resolve, it is your activity/fragment/widget.

getPickImageResultUri

public static android.net.Uri getPickImageResultUri(android.content.Context context,
                                                    android.content.Intent data)

Get the URI of the selected image from getPickImageChooserIntent(Context).
Will return the correct URI for camera and gallery image.

Parameters:

context - used to access Android APIs, like content resolve, it is your activity/fragment/widget.

data - the returned data of the activity result

isReadExternalStoragePermissionsRequired

public static boolean isReadExternalStoragePermissionsRequired(android.content.Context context,
                                                               android.net.Uri uri)

Check if the given picked image URI requires READ_EXTERNAL_STORAGE permissions.
Only relevant for API version 23 and above and not required for all URI's depends on the implementation of the app that was used for picking the image. So we just test if we can open the stream or do we get an exception when we try, Android is awesome.

Parameters:

context - used to access Android APIs, like content resolve, it is your activity/fragment/widget.

uri - the result URI of image pick.

Returns:

true - required permission are not granted, false - either no need for permissions or they are granted

isUriRequiresPermissions

public static boolean isUriRequiresPermissions(android.content.Context context,
                                               android.net.Uri uri)

Test if we can open the given Android URI to test if permission required error is thrown.
Only relevant for API version 23 and above.

Parameters:

context - used to access Android APIs, like content resolve, it is your activity/fragment/widget.

uri - the result URI of image pick.

activity

public static CropImage.ActivityBuilder activity()

Create CropImage.ActivityBuilder instance to open image picker for cropping and then start CropImageActivity to crop the selected image.
Result will be received in Activity.onActivityResult(int, int, Intent) and can be retrieved using getActivityResult(Intent).

Returns:

builder for Crop Image Activity

activity

public static CropImage.ActivityBuilder activity(android.net.Uri uri)

Create CropImage.ActivityBuilder instance to start CropImageActivity to crop the given image.
Result will be received in Activity.onActivityResult(int, int, Intent) and can be retrieved using getActivityResult(Intent).

Parameters:

uri - the image Android uri source to crop or null to start a picker

Returns:

builder for Crop Image Activity

getActivityResult

public static CropImage.ActivityResult getActivityResult(android.content.Intent data)

Get CropImageActivity result data object for crop image activity started using activity(Uri).

Parameters:

data - result data intent as received in Activity.onActivityResult(int, int, Intent).

Returns:

Crop Image Activity Result object or null if none exists