# 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
Add Belvedere as a dependency:
```
implementation ‘com.zendesk.belvedere2:belvedere:2.3.0’
```
### How to use Belvedere
#### ImageStream
A simple implementation of the ImageStream looks like this:
```java
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
mediaResults) {
// The user selected attachments
}
@Override
public void onMediaDeselected(List mediaResults) {
// The user deselected attachments
}
}
```
#### Dialog (from 1.x)
```java
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> 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> () {
@Override
public void success(List result) {
// Handle selected files
}
};
Belvedere.from(this).getFilesFromActivityOnResult(requestCode, resultCode, data, callback);
}
}
```
#### API only
Select an image from the camera.
```java
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> 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> () {
@Override
public void success(List 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:
```java
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:
```java
Intent viewIntent = Belvedere.from(this).getViewIntent(mediaResult.getUri(), mediaResult.getMimeType());
startActivity(viewIntent);
```
```java
Intent shareIntent = Belvedere.from(this).getShareIntent(mediaResult.getUri(), mediaResult.getMimeType());
startActivity(shareIntent);
```
### Picasso Compatibility
Belvedere uses [Picasso Compat](https://github.com/schlan/picassocompat) which provides compatibility
between Picasso 2.5.2 and Picasso 2.71828. This allows us to support both versions with needing to release
a `-PCOMP` version to support users of differing versions.
### 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 :+1: 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.
```
