RxJava extension for Android to take photos using the camera, select files or photos from the device and optionally crop or rotate any selected images.
What is RX?
Reactive Extensions for the JVM – a library for composing asynchronous and event-based programs using observable sequences for the Java VM.
What is a Paparazzo?
A freelance photographer who aggressively pursues celebrities for the purpose of taking candid photographs.
This library does that (well not really). But it is a cool name.
- Runtime permissions. Not worries about the tricky Android runtime permissions system. RxPaparazzo relies on RxPermissions to deal with that.
- Takes a photo using the built-in camera.
- Access to gallery and other sources of photos.
- Access to files and documents stored locally and on the cloud.
- Crop and rotate images. RxPaparazzo relies on UCrop to perform beautiful cuts to any face, body or place.
- Honors the observable chain (it means you can go crazy chaining operators). RxOnActivityResult allows RxPaparazzo to transform every intent into an observable for a wonderful chaining process.
Add the JitPack repository in your build.gradle (top level module):
allprojects {
repositories {
jcenter()
maven { url "https://jitpack.io" }
}
}
Add dependencies in the build.gradle of the module:
dependencies {
compile "com.github.miguelbcr:RxPaparazzo:0.4.7"
compile 'io.reactivex:rxandroid:1.2.1'
}
Add the JitPack repository in your build.gradle (top level module):
allprojects {
repositories {
jcenter()
maven { url "https://jitpack.io" }
}
}
Add dependencies in the build.gradle of the module:
dependencies {
compile "com.github.miguelbcr:RxPaparazzo:0.5.2-2.x"
compile 'io.reactivex.rxjava2:rxandroid:2.0.1'
}
Because RxPaparazzo uses RxActivityResult to deal with intent calls, all its requirements and features are inherited too.
Before attempting to use RxPaparazzo, you need to call RxPaparazzo.register
in your Android Application's onCreate
supplying the current Application instance.
public class SampleApp extends Application {
@Override public void onCreate() {
super.onCreate();
RxPaparazzo.register(this);
}
}
You will need to also add a FileProvider named android.support.v4.content.FileProvider
to your AndroidManifest.xml
and create a paths xml file in your src/main/res/xml directory.
<provider
android:name="android.support.v4.content.FileProvider"
android:authorities="${applicationId}.file_provider"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/file_provider_paths"/>
</provider>
If you set the provider android:authorities
attribute to a value other than ${applicationId}.file_provider
name you must set the configuration it using RxPaparazzo.Builder.setFileProviderAuthority(String authority)
Example: file_provider_paths.xml
<?xml version="1.0" encoding="utf-8"?>
<paths>
<files-path name="RxPaparazzoImages" path="RxPaparazzo/"/>
</paths>
The file_provider_paths.xml
is where files are exposed in the FileProvider.
If you set the files-path path
attribute to a value other than RxPaparazzo/
you must set the configuration using RxPaparazzo.Builder.setFileProviderPath(String path)
All features RxPaparazzo exposes can be accessed from both, an activity
or a fragment
instance.
Limitation:: Your fragments need to extend from android.support.v4.app.Fragment
instead of android.app.Fragment
, otherwise they won't be notified.
The generic type of the observable
returned by RxPaparazzo when subscribing to any of its features is always an instance of Response class.
This instance holds a reference to the current Activity/Fragment, accessible calling targetUI()
method. Because the original one may be recreated it would be unsafe calling it. Instead, you must call any method/variable of your Activity/Fragment from this instance encapsulated in the response
instance.
Also, this instance holds a reference to the data as the appropriate response, as such as the result code of the specific operation.
By default, the image / file is saved in a directory the same as the app name on the root of the external storage. You can choose to save the images in internal storage by using .useInternalStorage()
The response
in the callback function supplied to the subscribe()
method holds a reference to the path where the image was persisted.
RxPaparazzo.single(activityOrFragment)
.usingCamera()
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(response -> {
// See response.resultCode() doc
if (response.resultCode() != RESULT_OK) {
response.targetUI().showUserCanceled();
return;
}
response.targetUI().loadImage(response.data());
});
RxPaparazzo.single(activityOrFragment)
.usingFile()
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(response -> {
// See response.resultCode() doc
if (response.resultCode() != RESULT_OK) {
response.targetUI().showUserCanceled();
return;
}
response.targetUI().loadImage(response.data());
});
RxPaparazzo.multiple(activityOrFragment)
.usingFiles()
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(response -> {
// See response.resultCode() doc
if (response.resultCode() != RESULT_OK) {
response.targetUI().showUserCanceled();
return;
}
if (response.data().size() == 1) response.targetUI().loadImage(response.data().get(0));
else response.targetUI().loadImages(response.data());
});
RxPaparazzo.single(activityOrFragment)
.usingGallery()
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(response -> {
// See response.resultCode() doc
if (response.resultCode() != RESULT_OK) {
response.targetUI().showUserCanceled();
return;
}
response.targetUI().loadImage(response.data());
});
RxPaparazzo.multiple(activityOrFragment)
.usingGallery()
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(response -> {
// See response.resultCode() doc
if (response.resultCode() != RESULT_OK) {
response.targetUI().showUserCanceled();
return;
}
if (response.data().size() == 1) response.targetUI().loadImage(response.data().get(0));
else response.targetUI().loadImages(response.data());
});
Note: if the level Android api device is minor than 18, only one image will be retrieved.
When asking RxPaparazzo for an photo / image / file it's possible to apply some configurations to the action.
Size values can be used to set the size of the image to retrieve. There are 4 options:
- SmallSize: 1/8 aprox. of the screen resolution
- ScreenSize: The size image matches aprox. the screen resolution.
- OriginalSize: The original size of the image.
- CustomMaxSize: Yot can specify max size you want and image will be scaled proportionally.
ScreenSize value will be set as default.
RxPaparazzo.multiple(activityOrFragment)
.size(new ScreenSize())
.usingGallery()
This feature is available thanks to the amazing library uCrop authored by Yalantis group.
RxPaparazzo.multiple(activityOrFragment)
.crop()
By calling crop()
method when building the observable instance, all they images retrieved will be able to be cropped, regardless if the images were retrieved using the built-in camera or gallery, even if multiple images were requested in a single call using single()
approach.
Because uCrop Yalantis library exposes some configuration in order to customize the crop screen, RxPaparazzo exposes an overloaded method of crop(UCrop.Options)
which allow to pass an instance of UCrop.Options.
If you need to configure the aspect ratio, the max result size or using the source image aspect ratio, you must pass an instance of Options class, which extends from UCrop.Options
and adds the three missing properties.
UCrop.Options options = new UCrop.Options();
options.setToolbarColor(ContextCompat.getColor(getActivity(), R.color.colorPrimaryDark));
RxPaparazzo.single(activityOrFragment).crop(options)
Options options = new Options();
options.setToolbarColor(ContextCompat.getColor(getActivity(), R.color.colorPrimaryDark));
options.setAspectRatio(25, 50);
RxPaparazzo.single(activityOrFragment)
.crop(options)
To send files to the media scanner so that they can be indexed and available in applications such as the Gallery use sendToMediaScanner()
. If you are using useInternalStorage()
then the media scanner will not be able to access the file.
If you wish to limit the type of images or files then use setMimeType(String mimeType)
to specify a specific mime type for the Intent.
By default Intent.ACTION_GET_CONTENT
is used to request images and files. If you wish to edit the original file call useDocumentPicker()
, this will allow greater, possiblty persistent access to the source file.
# Rxjava rules
-dontwarn rx.internal.util.**
-keepclassmembers class rx.internal.util.unsafe.*ArrayQueue*Field* {
long producerIndex;
long consumerIndex;
}
-keepclassmembers class rx.internal.util.unsafe.BaseLinkedQueueProducerNodeRef {
long producerNode;
long consumerNode;
}
Testing has been done using the following Genymotion devices:
- Genymotion - Google Nexus 5 5.0.0 API 21 1080x1920 480dpi
- Genymotion - Google Nexus 7 5.1.0 API 22 800x1280 213dpi
- Runtime permissions: RxPermissions
- Crop: uCrop
Víctor Albertos
- https://twitter.com/_victorAlbertos
- https://www.linkedin.com/in/victoralbertos
- https://github.com/VictorAlbertos
Miguel García
James McIntosh
- RxCache: Reactive caching library for Android and Java.
- RxGcm: RxJava extension for Gcm which acts as an architectural approach to easily satisfy the requirements of an android app when dealing with push notifications.
- RxActivityResult: A tiny reactive library to break with the OnActivityResult implementation as it breaks the observables chain.