Belvedere

A file picker for Android.

Overview

Belvedere gives you the power to easily integrate file selection from third party apps and the camera without the need to take care of permissions, ContentProvider, Intent permissions, and so on.

Download

First add the Zendesk maven repository. This is a new step for versions 3.0.0-RC and newer.

maven {
    url 'https://zendesk.jfrog.io/zendesk/oss-releases-local'
}

Secondly, add Belvedere as a dependency:

implementation ‘com.zendesk.belvedere2:belvedere:3.0.0-RC’

Belvedere 3.0.0-RC and newer uses AndroidX and is recommended for use with Android 11.

How to use Belvedere

ImageStream

A simple implementation of the ImageStream looks like this:

public class TestActivity extends AppCompatActivity implements ImageStream.Listener {

    private ImageStream imageStream;
    private Button selectAttachment;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // ...

        imageStream = BelvedereUi.install(this);
        imageStream.addListener(this);

        selectAttachment.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                BelvedereUi.imageStream(getApplicationContext())
                        .withCameraIntent()
                        .withDocumentIntent("*/*", true)
                        .showPopup(TestActivity.this);
            }
        });
    }

    @Override
    public void onDismissed() {
        // Image Stream was dismissed
    }

    @Override
    public void onVisible() {
        // Image Stream was shown
    }

    @Override
    public void onMediaSelected(List<MediaResult> mediaResults) {
        // The user selected attachments
    }

    @Override
    public void onMediaDeselected(List<MediaResult> mediaResults) {
        // The user deselected attachments
    }
}

Dialog (from 1.x)

public class TestActivity extends AppCompatActivity {

    private ImageStream imageStream;
    private Button selectAttachment;
    
    // Make sure to manage a strong reference to the callback because Belvedere uses
    // a WeakReference to avoid memory leaks
    private Callback<List<MediaResult>> callback; 

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // ...

        selectAttachment.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                Belvedere belvedere = Belvedere.from(this);
                MediaIntent document = belvedere.document().build();
                MediaIntent camera = belvedere.camera().build();

                BelvedereUi.showDialog(getSupportFragmentManager(), document, camera);
            }
        });
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        
        callback = new Callback<List<MediaResult>> () {
            @Override
            public void success(List<MediaResult> result) {
                // Handle selected files                
            }
        };
        
        Belvedere.from(this).getFilesFromActivityOnResult(requestCode, resultCode, data, callback);
    }
}

API only

Select an image from the camera.

public class TestActivity extends AppCompatActivity {

    private ImageStream imageStream;
    private Button selectAttachmentFromCamera;
    private Button selectAttachmentFromDocuments;
    
    // Make sure to manage a strong reference to the callback because Belvedere uses
    // a WeakReference to avoid memory leaks
    private Callback<List<MediaResult>> callback; 

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // ...

        selectAttachmentFromCamera.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                Belvedere.from(TestActivity.this)
                        .camera()
                        .open(TestActivity.this);
            }
        });

        selectAttachmentFromDocuments.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View view) {
                Belvedere.from(TestActivity.this)
                        .document()
                        .open(TestActivity.this);
            }
        });
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        
        callback = new Callback<List<MediaResult>> () {
            @Override
            public void success(List<MediaResult> result) {
                // Handle selected files                
            }
        };
        
        Belvedere.from(this).getFilesFromActivityOnResult(requestCode, resultCode, data, callback);
    }
}

Place a file into Belvedere’s internal storage

Moreover, it’s possible to put your own data into Belvedere’s cache. To get access to an internal file, call:

MediaResult mediaResult = Belvedere.from(this).getFile("dire_name", "file_name.jpg");

Again, you’ll get a file object and a Uri. For example, you can use the file to open a FileOutputStream.

Open or share an internal file

Files that are available through Belvedere could be opened or shared with other apps. To do that, use the Uri you get from a BelvedereResult.

Use the first code snippet to open a file and the second one to share a file:

Intent viewIntent = Belvedere.from(this).getViewIntent(mediaResult.getUri(), mediaResult.getMimeType());
startActivity(viewIntent);

Intent shareIntent = Belvedere.from(this).getShareIntent(mediaResult.getUri(), mediaResult.getMimeType());
startActivity(shareIntent);

Picasso Compatibility

Since version 3.0.0 Belvedere requires Picasso 2.8 or higher because of the migration to AndroidX.

Contributing

Bug reports, feature requests and contributions are very welcome. Please follow these steps to contribute:

• Submit a Pull Request with a detailed explanation of changes and screenshots (if UI is changing). Tests would be great too!
• One of the core team members will review your changes.
• After successful code review, you’ll receive a 👍 and the changes will be merged by one of the core members.

If you’re submitting a bug report, please try to follow these steps:

• Search through the open and closed issues, maybe there is already an issue describing exactly the same problem.
• Describe the issue as detailed as possible. Try to describe the expected and the actual outcome.
• Add reproduction steps. If possible provide sample code that showcases the issue.
• Provide a failing test.

License

Copyright 2018 Zendesk

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.