Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/qingmei2/rximagepicker
:rocket:RxJava2 and RxJava3 external support. Android flexible picture selector, provides the support for theme of Zhihu and WeChat (灵活的Android图片选择器，提供了知乎和微信主题的支持）.
https://github.com/qingmei2/rximagepicker
android android-image-picker android-image-selector android-library imagepicker picture-selector rximagepicker
Last synced: 6 days ago
JSON representation
:rocket:RxJava2 and RxJava3 external support. Android flexible picture selector, provides the support for theme of Zhihu and WeChat (灵活的Android图片选择器，提供了知乎和微信主题的支持）.
- Host: GitHub
- URL: https://github.com/qingmei2/rximagepicker
- Owner: qingmei2
- License: mit
- Created: 2018-01-08T11:27:25.000Z (almost 7 years ago)
- Default Branch: 2.x
- Last Pushed: 2022-05-13T02:02:52.000Z (over 2 years ago)
- Last Synced: 2023-11-07T13:58:16.543Z (about 1 year ago)
- Topics: android, android-image-picker, android-image-selector, android-library, imagepicker, picture-selector, rximagepicker
- Language: Kotlin
- Homepage:
- Size: 19.9 MB
- Stars: 1,196
- Watchers: 17
- Forks: 156
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# RxImagePicker
#### English Documentation | [中文文档](https://github.com/qingmei2/RxImagePicker/blob/2.x/README_ZH.md)
(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](https://developer.android.com/jetpack/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:
```groovy
// 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:
```java
public interface MyImagePicker {
@Gallery // open gallery
Observable openGallery(Context context);
@Camera // take photos
Observable 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:
```Java
RxImagePicker
.create(MyImagePicker.class)
.openGallery(this)
.subscribe(new Consumer() {
@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:
```groovy
// Zhihu picture selector
implementation 'com.github.qingmei2:rximagepicker_support_zhihu:${last_version}'
```
### 2.Interface Configuration
Declare an interface and carry out the following configuration:
```kotlin
interface ZhihuImagePicker {
// normal style
@Gallery(componentClazz = ZhihuImagePickerActivity::class,
openAsFragment = false)
fun openGalleryAsNormal(context: Context,
config: ICustomPickerConfiguration): Observable
// dracula style
@Gallery(componentClazz = ZhihuImagePickerActivity::class,
openAsFragment = false)
fun openGalleryAsDracula(context: Context,
config: ICustomPickerConfiguration): Observable
// take photo
@Camera
fun openCamera(context: Context): Observable
}
```
### 3.Instantiate and use it
```Kotlin
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(this@ZhihuActivity)
.load(it.uri)
.into(imageView)
}
```
see [sample](https://github.com/qingmei2/RxImagePicker/blob/2.x/sample/src/main/java/com/qingmei2/sample/zhihu/ZhihuActivity.kt) 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:
```kotlin
interface SystemImagePicker {
@Gallery // by default,componentClazz：KClass = SystemGalleryPickerView::class，openAsFragment：Boolean=true
fun openGallery(context: Context): Observable
}
```
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`:
```kotlin
interface ZhihuImagePicker {
@Gallery(componentClazz = ZhihuImagePickerActivity::class,
openAsFragment = false)
fun openGalleryAsNormal(context: Context,
config: ICustomPickerConfiguration): Observable
@Gallery(componentClazz = ZhihuImagePickerActivity::class,
openAsFragment = false)
fun openGalleryAsDracula(context: Context,
config: ICustomPickerConfiguration): Observable
@Camera
fun openCamera(context: Context): Observable
}
```
For more information, please refer to the [ZhihuActivity](https://github.com/qingmei2/RxImagePicker/blob/2.x/sample/src/main/java/com/qingmei2/sample/zhihu/ZhihuActivity.kt) 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
```kotlin
interface ICustomPickerView {
fun display(fragmentActivity: FragmentActivity,
@IdRes viewContainer: Int,
configuration: ICustomPickerConfiguration?)
fun pickImage(): Observable
}
```
It has several classic implementation classes, for example, [ImagePickerDisplayer](https://github.com/qingmei2/RxImagePicker/blob/2.x/rximagepicker/src/main/java/com/qingmei2/rximagepicker/core/ImagePickerDisplayer.kt) 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](https://github.com/qingmei2/RxImagePicker/blob/2.x/rximagepicker_support/src/main/java/com/qingmei2/rximagepicker_extension/entity/SelectionSpec.kt) 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.](https://github.com/qingmei2/RxWeaver)
* [MVVM-Rhine: The MVVM using RxJava and Android databinding.](https://github.com/qingmei2/MVVM-Rhine)
## 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.