Matisse

https://github.com/zhihu/matisse
Admin
:fireworks: A well-designed local image and video selector for Android
Tokens:2,592
Snippets:15
Trust Score:8.2
License:Apache-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Launch Matisse Image/Video Selector (Java)

Source: https://github.com/zhihu/matisse/wiki/Basic-Usage

Initializes and launches the Matisse image and video selection activity from an Android context. This snippet demonstrates configuring various selection options such as mime types, countability, maximum selectable items, grid size, orientation, thumbnail scale, and the image loading engine before starting the activity for a result.

```java
Matisse.from(MainActivity.this)
        .choose(MimeType.ofAll(), false)
        .countable(true)
        .maxSelectable(9)
        .gridExpectedSize(getResources().getDimensionPixelSize(R.dimen.grid_expected_size))
        .restrictOrientation(ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED)
        .thumbnailScale(0.85f)
        .imageEngine(new GlideEngine())
        .forResult(REQUEST_CODE_CHOOSE);
```

--------------------------------

### Start Matisse Image/Video Selector Activity

Source: https://github.com/zhihu/matisse/blob/master/README.md

Initiate the Matisse image and video selection activity from your Android Activity or Fragment. Configure options such as MIME types, selection limits, filters, grid size, orientation, thumbnail scale, image engine, and preview display.

```java
Matisse.from(MainActivity.this)
        .choose(MimeType.allOf())
        .countable(true)
        .maxSelectable(9)
        .addFilter(new GifSizeFilter(320, 320, 5 * Filter.K * Filter.K))
        .gridExpectedSize(getResources().getDimensionPixelSize(R.dimen.grid_expected_size))
        .restrictOrientation(ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED)
        .thumbnailScale(0.85f)
        .imageEngine(new GlideEngine())
        .showPreview(false) // Default is `true`
        .forResult(REQUEST_CODE_CHOOSE);
```

--------------------------------

### Matisse Launch Entry Points (APIDOC)

Source: https://github.com/zhihu/matisse/wiki/Basic-Usage

Explains the valid contexts from which Matisse can be launched and the corresponding callback mechanism for receiving selection results.

```APIDOC
Launch Entry Points:
- Can be launched from: Activity or Fragment.
- Result reception: Results should be received in the corresponding onActivityResult() callback of the launching Activity or Fragment.
```

--------------------------------

### Matisse UI and Behavior Configuration (APIDOC)

Source: https://github.com/zhihu/matisse/wiki/Basic-Usage

Documents various configuration options for Matisse's user interface and behavior. This includes settings for screen orientation, grid layout, thumbnail scaling, original photo selection, custom camera capture directories, and toolbar visibility in preview mode.

```APIDOC
UI and Behavior Configuration:
- restrictOrientation(@ScreenOrientation int orientation):
    - Description: Sets the desired orientation for the image selection and preview activities.
    - Parameter: orientation (int) - Screen orientation constant.
- spanCount(int spanCount):
    - Description: Sets the number of columns in the grid. Can be fixed or flexible based on screen size.
    - Parameter: spanCount (int) - The desired number of columns.
- thumbnailScale(float scale):
    - Description: Sets the scale of the thumbnail bitmap relative to the view's size. Value should be in (0.0, 1.0].
    - Parameter: scale (float) - The scaling factor.
- originalEnable(boolean enable):
    - Description: Enables or disables the 'select original photo' feature, showing a checkbox in the bottom toolbar.
    - Parameter: enable (boolean) - true to enable, false to disable.
- maxOriginalSize(int size):
    - Description: Sets the maximum allowed size for original photos. Unit is MB.
    - Parameter: size (int) - Maximum size in MB.
- CaptureStrategy(boolean isPublic, String authority, String directory):
    - Description: Customizes the sub-directory for photos taken using the camera feature.
    - Parameters:
        - isPublic (boolean): Whether the directory is public.
        - authority (String): FileProvider authority.
        - directory (String): Custom sub-directory name.
- autoHideToolbarOnSingleTap(boolean enable):
    - Description: Enables or disables auto-hiding the toolbar when a photo is tapped in preview mode.
    - Parameter: enable (boolean) - true to enable, false to disable.
```

--------------------------------

### Configure Matisse with Built-in Image Engines (Java)

Source: https://github.com/zhihu/matisse/wiki/Image-Engine

This snippet demonstrates how to integrate either GlideEngine or PicassoEngine with Matisse for image loading. It shows the chaining of the .imageEngine() method with an instance of the desired engine.

```java
Matisse.from(MainActivity.this)
    ...
    .imageEngine(new GlideEngine() | new PicassoEngine());
    .forResult(REQUEST_CODE_CHOOSE);
```

--------------------------------

### Matisse MimeType Configuration (APIDOC)

Source: https://github.com/zhihu/matisse/wiki/Basic-Usage

Details the supported media types and methods for filtering selectable content within Matisse. This API documentation includes a table of supported mime types and functions for specifying media type selection, as well as an option to show only a single media type.

```APIDOC
MimeType Support:
- image/jpeg (jpg, jpeg)
- image/png (png)
- image/gif (gif)
- image/x-ms-bmp (bmp)
- image/webp (webp)
- video/mpeg (mpeg, mpg)
- video/mp4 (mp4, m4v)
- video/quicktime (mov)
- video/3gpp (3gp, 3gpp)
- video/3gpp2 (3g2, 3gpp2)
- video/x-matroska (mkv)
- video/webm (webm)
- video/mp2ts (ts)
- video/avi (avi)

Methods for MimeType Selection:
- MimeType.ofAll(): Select all supported mime types.
- MimeType.of(MimeType type, MimeType... rest): Select specific mime types.
- MimeType.ofImage(): Select only image mime types.
- MimeType.ofVideo(): Select only video mime types.

Single Media Type Display:
- showSingleMediaType(boolean enable):
    - Description: If true, only one media type (images or videos) will be shown.
    - Parameter: enable (boolean)
```

--------------------------------

### Add Matisse Gradle Dependency

Source: https://github.com/zhihu/matisse/blob/master/README.md

Add the Matisse library to your Android project's `build.gradle` file. Ensure `jcenter()` is included in your repositories for dependency resolution.

```groovy
repositories {
    jcenter()
}

dependencies {
    implementation 'com.zhihu.android:matisse:$latest_version'
}
```

--------------------------------

### Apply Built-in Themes in Matisse

Source: https://github.com/zhihu/matisse/wiki/Theme

This Java code demonstrates how to apply one or more built-in themes (Zhihu or Dracula) to the Matisse image picker instance using the `theme()` method. The themes are specified by their resource IDs, combined with a bitwise OR operator, allowing for flexible theme application.

```Java
Matisse.from(MainActivity.this)
    ...
    .theme(R.style.Matisse_Zhihu | R.style.Matisse_Dracula)
    .forResult(REQUEST_CODE_CHOOSE);
```

--------------------------------

### Matisse Selection Count and Limits (APIDOC)

Source: https://github.com/zhihu/matisse/wiki/Basic-Usage

Describes how to configure the selection count behavior in Matisse, including enabling auto-increased numbering for selected items and setting the maximum number of items that can be selected by the user.

```APIDOC
Selection Count Configuration:
- Default: Check mark in top right corner, single image selection.
- countable(boolean enable):
    - Description: Enables auto-increased number check marks (e.g., 1, 2, 3...).
    - Parameter: enable (boolean) - true to enable, false for default.
- maxSelectable(int maxSelectable):
    - Description: Sets the maximum number of items that can be selected.
    - Parameter: maxSelectable (int) - The maximum number of items.
```

--------------------------------

### Handle Matisse Selection Result in onActivityResult (Java)

Source: https://github.com/zhihu/matisse/wiki/Basic-Usage

Processes the result from the Matisse selection activity within the `onActivityResult()` callback of the calling Activity or Fragment. This code snippet shows how to retrieve the selected media URIs and file paths, and also how to check if the original photo state was selected.

```java
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == REQUEST_CODE_CHOOSE && resultCode == RESULT_OK) {
        Log.d("Matisse", "Uris: " + Matisse.obtainResult(data));
        Log.d("Matisse", "Paths: " + Matisse.obtainPathResult(data));
        Log.e("Matisse", "Use the selected photos with original: "+String.valueOf(Matisse.obtainOriginalState(data)));
    }
}
```

--------------------------------

### Applying Filters in Matisse

Source: https://github.com/zhihu/matisse/wiki/Filter

This snippet shows how to add a custom filter to the Matisse image selection process. The `addFilter` method allows for applying specific filtering logic before the image selection result is returned. A `Filter` object needs to be provided.

```Java
Matisse.from(MainActivity.this)
    ...
    .addFilter(Filter filter)
    .forResult(REQUEST_CODE_CHOOSE);
```

--------------------------------

### Handle Matisse Selection Result in onActivityResult

Source: https://github.com/zhihu/matisse/blob/master/README.md

Process the selected images or videos from Matisse in your `onActivityResult` callback. The selected URIs can be obtained using `Matisse.obtainResult(data)`.

```java
List<Uri> mSelected;

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    if (requestCode == REQUEST_CODE_CHOOSE && resultCode == RESULT_OK) {
        mSelected = Matisse.obtainResult(data);
        Log.d("Matisse", "mSelected: " + mSelected);
    }
}
```

--------------------------------

### Matisse ProGuard Rule for Picasso

Source: https://github.com/zhihu/matisse/blob/master/README.md

Add this ProGuard rule if you are using Picasso as your image engine with Matisse. This rule prevents warnings related to Glide, which might be a transitive dependency or an alternative engine.

```pro
-dontwarn com.bumptech.glide.**
```

--------------------------------

### Matisse Custom Theme Attributes Reference

Source: https://github.com/zhihu/matisse/wiki/Theme

This section lists the customizable attributes defined in `attrs.xml` for Matisse themes. These attributes allow developers to modify the appearance of various UI elements within the Matisse image picker, such as colors, styles, and placeholders, by deriving a custom theme from built-in options.

```APIDOC
Attributes for Matisse Custom Themes:
- colorPrimary: branding color for the app bar
- colorPrimaryDark: darker variant for the status bar
- toolbar: toolbar style
- album.dropdown.title.color: album title's color in the album dropdown list
- album.dropdown.count.color: album media file count's color in the album dropdown list
- album.element.color: toolbar elements' color, elements includes navigation icon, selected album title and a dropdown arrow icon to the right of it
- album.thumbnail.placeholder: album thumbnail's placeholder
- album.emptyView: drawable of the empty view for images
- album.emptyView.textColor: text color of the empty view
- item.placeholder: placeholder color or drawable of the media grid
- page.bg: background color or drawable of the Activity or Fragment page
- bottomToolbar.bg: background color or drawable of the bottom toolbar
- bottomToolbar.preview.textColor: preview button text's color on the bottom toolbar
- bottomToolbar.apply.textColor: apply button text's color on the bottom toolbar
- listPopupWindowStyle: style of the album list's dropdown
- capture.textColor: text color of the capture grid which may appear on the top
```

--------------------------------

### Matisse ProGuard Rule for Glide

Source: https://github.com/zhihu/matisse/blob/master/README.md

Add this ProGuard rule if you are using Glide as your image engine with Matisse. This rule prevents warnings related to Picasso, which might be a transitive dependency or an alternative engine.

```pro
-dontwarn com.squareup.picasso.**
```
Tokens:
Raw