RxImagePicker

English Documentation | 中文文档

(RxJava3) (RxJava2)

Support for RxJava2. Flexible picture selector of Android, provides the support for theme of Zhihu and WeChat.

Zhihu: Famous Online Q&A Community APP in China.
WeChat: Most Used Instant Messaging Social Networking App in China.

Introduction

Purpose of RxImagePicker: Let developers realize the demand of selecting picture in the development of Android in a simple and flexible way.

RxImagePicker is a reactive picture selector for Android, which converts your selection requirements of picture into an interface for configuration and displays any UI theme in Activity or Fragment.

Support

• [x] Android Camera Photograph
• [x] Android photo album picture selection
• [x] Returns data in the format of reactive data stream ( such as Observable/Flowable/Single/Maybe )
• [x] AndroidX support ( after v2.3.0 )

Support of UI

• [x] System Picture Selector
• [x] [Optional] Theme Picture Selector of Zhihu
• [x] [Optional] Theme Picture Selector of WeChat ()
• [x] [Optional] Custom UI Picture Selector

Screenshots

Selection and result display of system picture:

Theme of Zhihu

Theme of WeChat

UI Test

Basic Usage

The following code will show you how to use photo album or camera at the Android system-level :

1.Add the following depending on the file of build.gradle:

// The most basic architecture, only provides the default
// picture selector and photographing function of system.

implementation 'com.github.qingmei2:rximagepicker:${last_version}'

// Provide the basic components of custom UI picture selector
// and this dependency needs to be added to the requirements of the custom UI
implementation 'com.github.qingmei2:rximagepicker_support:${last_version}'


// If you need additional UI support, choose to rely on the corresponding UI extension library

// Zhihu picture selector
implementation 'com.github.qingmei2:rximagepicker_support_zhihu:${last_version}'

// WeChat picture selector
implementation 'com.github.qingmei2:rximagepicker_support_wechat:${last_version}'

If your project not migrate to androidx, please use version 2.2.0.

2.Interface Configuration

Declare an interface and carry out the following configuration:

public interface MyImagePicker {

    @Gallery    // open gallery
    Observable<Result> openGallery(Context context);

    @Camera     // take photos
    Observable<Result> openCamera(Context context);
}

3.Instantiate and use it

Instantiate the interface in your Activity or Fragment to open the default album and camera screen of system:

RxImagePicker
        .create(MyImagePicker.class)
        .openGallery(this)
        .subscribe(new Consumer<Result>() {
            @Override
            public void accept(Result result) throws Exception {
                // do something, ex:
                Uri uri = result.getUri();
                GlideApp.with(this)
                         .load(uri)
                         .into(ivPickedImage);
            }
        });

Support UI theme Usage

1.Add the following depending on the file of build.gradle:

// Zhihu picture selector
implementation 'com.github.qingmei2:rximagepicker_support_zhihu:${last_version}'

2.Interface Configuration

Declare an interface and carry out the following configuration:

interface ZhihuImagePicker {

    // normal style
    @Gallery(componentClazz = ZhihuImagePickerActivity::class,
            openAsFragment = false)
    fun openGalleryAsNormal(context: Context,
                            config: ICustomPickerConfiguration): Observable<Result>

    // dracula style                        
    @Gallery(componentClazz = ZhihuImagePickerActivity::class,
            openAsFragment = false)
    fun openGalleryAsDracula(context: Context,
                             config: ICustomPickerConfiguration): Observable<Result>

    // take photo                         
    @Camera
    fun openCamera(context: Context): Observable<Result>
}

3.Instantiate and use it

val rxImagePicker: ZhihuImagePicker = RxImagePicker
                .create(ZhihuImagePicker::class.java)

rxImagePicker.openGalleryAsNormal(this,
                ZhihuConfigurationBuilder(MimeType.ofImage(), false)
                        .maxSelectable(9)
                        .countable(true)
                        .spanCount(4)
                        .theme(R.style.Zhihu_Normal)
                        .build())
               .subscribe {
                    Glide.with([email protected])
                            .load(it.uri)
                            .into(imageView)
                }

see sample for more informations.

Advanced Usage

1. Action Annotation

RxImagePicker provides two action annovation, respectively @Gallery and @Camera.

@Camera will declare the way annovated by the annovation Open the camera to take a photo.

Please note, each method of the interface must add an action annotation to declare the corresponding action. If the method is not configured with @Gallery or @Camera, RxImagePicker will throw an Exception at runtime.

@Gallery

@Gallery will open the photo album to choose picture.

It has three parameters:

• componentClazz：KClass<*> The class object of UI component, opens SystemGalleryPickerView::class—— the system Gallery by default.

• openAsFragment：Boolean Whether UI component is displayed as Fragment in some parts of Activity is true by default.

• containerViewId: Int If UI needs to be displayed as Fragment in ViewGroup, the id corresponding to the ViewGroup needs to be assigned to it.

At present UI component only supports two kinds: FragmentActivity or Fragment(support-v4).

Taking turning on the system camera for example, its principle is to instantiate an invisible Fragment in the current Activity, and Fragment opens the system photo album through Intent and processes the returned data through the method of onActivityResult(). The code is as the following:

interface SystemImagePicker {

    @Gallery   // by default,componentClazz：KClass = SystemGalleryPickerView::class，openAsFragment：Boolean=true
    fun openGallery(context: Context): Observable<Result>
}

When need to custom UI, taking Zhihu theme as an example, we will configure ZhihuImagePickerActivity::class to componentClazz and set the value of openAsFragment to false:

interface ZhihuImagePicker {

    @Gallery(componentClazz = ZhihuImagePickerActivity::class,
            openAsFragment = false)
    fun openGalleryAsNormal(context: Context,
                            config: ICustomPickerConfiguration): Observable<Result>

    @Gallery(componentClazz = ZhihuImagePickerActivity::class,
            openAsFragment = false)
    fun openGalleryAsDracula(context: Context,
                             config: ICustomPickerConfiguration): Observable<Result>

    @Camera
    fun openCamera(context: Context): Observable<Result>
}

For more information, please refer to the ZhihuActivity in sample.

At the same time, when UI needs to be displayed as Fragment, RxImagePicker needs to be informed of the id of the ViewGroup control so that RxImagePicker can be correctly displayed in the corresponding ViewGroup.

@Camera

@Camera will declare the way annotated by the annotation open the camera to take photo.

Please note, @Camera only provides the function of calling the system camera to take a photo at present. Although this annotation provides the same API as @Gallery, there is no sense to configure them at present.

2.ICustomPickerView

ICustomPickerView is an underneath interface, it is used for:

• 1. Show the picture selector interface
• 2. Obtain selection results of users

interface ICustomPickerView {

    fun display(fragmentActivity: FragmentActivity,
                @IdRes viewContainer: Int,
                configuration: ICustomPickerConfiguration?)

    fun pickImage(): Observable<Result>
}

It has several classic implementation classes, for example, ImagePickerDisplayer when open the corresponding activity through configuration;

3.Context: necessary parameters.

Each interface method of RxImagePicker must be configured with a Context as parameters. If the method does not have any parameters, it will throw out NullPointerException:

${method.name} requires just one instance of type: Context, but none.

This is understandable. Starting the UI component of a picture selector must depend on the instance of Context.

Note, This Context must be a FragmentActivity, not Application or others, or else throw out the abnormity of IllegalArgumentException!

4.ICustomPickerConfiguration: optional parameters

ICustomPickerConfiguration interface, similar to a tag. RxImagePicker will treat it as the configuration class.

As for opening the system photo album or system camera, it makes no sense to configure, but it must be configured for custom UI ( such as WeChat theme and Zhihu theme ).

The basic components of RxImagePicker do not provide the implementation class, please refer to SelectionSpec if any questions.

2.5 Complete full custom UI

Though RxImagePicker provides the UI style of WeChat picture selector and Zhihu picture selector, two sets of models are still not enough to cover more and more sophisticated UI demands of APP.

RxImagePicker provides enough degree of freedom interface to provide private customized UI for developers. Whether a new Activity is created or displayed in a ViewGroup container at present, it is enough.

The above WeChat theme and Zhihu theme are based on its to implement. Please refer to the source code for detailed implementation.

Another author's libraries using RxJava:

• RxWeaver: A lightweight and flexible error handler tools of RxJava2.

• MVVM-Rhine: The MVVM using RxJava and Android databinding.

License

The RxImagePicker：MIT License

Copyright (c) 2018 qingmei2

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.