Skip to content

Documentation

Jump to bottom
Halil Kaya edited this page Apr 11, 2016 · 1 revision

Index

Installation

via Gradle

First, define the repository in your build.gradle file:

repositories {
    ...
    maven {
        url "https://jitpack.io"
    }
}

Then, put the dependency string in dependencies:

dependencies {
    ...
    compile 'com.github.halilkaya:golbat:0.0.1'
}

Prerequisite

First of all, you need to require WRITE_EXTERNAL_STORAGE and READ_EXTERNAL_STORAGE permissions in your Manifest file:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

Builder class

To begin to use Golbat, it's needed to build it in your onCreate method of Application class. For example:

new Golbat.Builder()
        .setDirectoryName("MyPhotos")
        .setContentResolver(getContentResolver())
        .setCameraRequestCode(200)
        .setImageQuality(100)
        .build();

Well, what constructor methods am I able to use in Builder class? Let's look at them:

setContentResolver(ContentResolver contentResolver)

It's optional. If you want to get selected photo from gallery as bitmap, you need to use this method.

setDirectoryName(String directoryName)

There will be a directory in Photos directory of sd card. Your captured image(s) will be stored here. It's required.

setCameraRequestCode(int cameraRequestCode)

This value will be used when camera app opens. You will be able to catch captured image on onActivityResult(...) method via this request code. It's optional. Default value is 9420.

setGalleryRequestCode(int galleryRequestCode)

This value will be used when gallery opens to select image from gallery. You will be able to catch selected image on onActivityResult(...) method via this request code. It's optional. Default value is 9421.

setImageQuality(int imageQuality)

You can define image quality of captured images from camera. It's optional. Default value is 100.

setImageType(ImageType imageType)

It's needed for determining compression type of captured image from camera. It's optinal. Default value is ImageType.JPEG.

ImageType enum class:

public enum ImageType {
    JPEG, PNG
}
setImageMaxSize(int maxSizeInPixel)

When you resize your image without giving fixed width and height, it automatically resizes your image according to this maximum size. First, it checks width and height range of your image. If width is greater than height and this maximum size, it reduces width to the determined maximum size and ranges its height. Same situation for resizing height. The value is in pixel. It's optional. Default value is 500px.

Is everything OK? Then let's build Golbat by .build() method!

new Golbat.Builder()
        ...
        ...
        ...
        .build();

Usage

Selecting photo from gallery

You want your users select a photo from gallery and will use it. openGallery method takes an Activity argument. So, if you wanna open gallery in your activity, you can do it in one line:

Golbat.openGallery(this); // 'this' represents the activity class.

Now, gallery opened! Considering you didn't give a custom gallery request code with .setGalleryRequestCode(...) in Builder class, default value request code is 9421. Let's handle data in onActivityResult method:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (resultCode == Activity.RESULT_OK && requestCode == 9421) {
        // Your selected image is in data.getData()
    }
}

Yeah! You can do whatever you want with this image by getting it via data.getData() inside.

Capturing photo from camera

You can capture a photo and save it in the folder that you have determined in your Application class before with openCamera method. It takes an Activity argument and returns the captured and saved image as Uri for you. Let's look at how it works:

Uri imageUri; // We'll store the image Uri in this variable.
imageUri = Golbat.openCamera(this); // 'this' represents the activity class.

Well, with the code above, camera app opened and user captured a photo. Let's handle it in onActivityResult. By the way, if you didn't set a custom camera request code, default is 9420.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (resultCode == Activity.RESULT_OK && requestCode == 9420) {
        // Your selected image uri was stored in 'imageUri' variable.
        // So, you can use it here now!
    }
}

The difference of returning data between camera and gallery is that, as you know, when you open camera, you have to store it in a Uri. Because there is a new file and it will be saved. However, gallery picks an already saved image, so it returns us in data intent.

Converting selected image from gallery to Bitmap

You got the picked image from gallery in data.getData(), but c'mon, it's Uri, so not friendly. Let's convert it to a friendly format, which is Bitmap. We need getSelectedImageAsBitmap(Uri fileUri) method to do that:

Bitmap selectedImage = Golbat.getSelectedImageAsBitmap(data.getData());

Yeah! It's now Bitmap. But wait! If you wanna show this image into an ImageView, Golbat can do it for you. Keep going reading this documentation.

Converting captured image from camera to Bitmap

We have converted selected image to a friendly format but what about captured image from camera? Let's convert it in the same way. We need getCapturedImageAsBitmap(Uri fileUri) method to do that:

Bitmap capturedImage = Golbat.getCapturedImageAsBitmap(fileUri);

Remember that we have stored result of captured image in fileUri variable before.

Generating Base64

As I remember, you said that your API wants it as base64. Talk to Golbat, it will generate it for you. Method we need is getBase64(...). It takes 2 arguments: Bitmap image and boolean resize. If you want to resize it according to the maximum size that you have mentioned in Builder class before, give second parameter true, else false.

String encodedType = Golbat.getBase64(myBitmap, true);

You can send encodedType variable to your API, now!

Resizing image

There are 2 methods to resize an image which are resizing image according to the maximum size (resizeImage method) and resizing image in a fixed size (resizeImageInFixedSize method). First let's see how to use resizeImage method. It returns Bitmap to you.

Bitmap resizedImage = resizeImage(myBitmap);

What happened now? resizeImage method looked at myBitmap's width and height. If width is greater than height and maximum size, it changed myBitmap's width to the maximum size and ranged its height according to the width. If height is greater than width and maximum size, it did the same thing for height.

You want to resize your image to a fixed width and height? Then, use resizeImageInFixedSize(Bitmap image, int width, int height) method. It also returns Bitmap to you.

Bitmap resizedImage = resizeImageInFixedSize(myBitmap, 1024, 768);

By the way, when you generate base64, second parameter boolean resize calls resizeImage method.

Deleting photo

You can delete a photo that stored in your own pictures directory via Golbat. Just use deletePhoto method. It takes a Uri parameter that specifies your file Uri to delete. It returns a boolean value to you if deleting photo is success or not.

boolean isPhotoDeleted = Golbat.deletePhoto(fileUri);

Let's think about another scenario. You have captured an image from camera, converted it to base64 and sent it to API. You don't want the file stay at the local storage. As soon as you send the base64, you want to delete the latest photo in the directory. For that, you can use deleteLatestPhoto() method:

boolean isLatestPhotoDeleted = Golbat.deleteLatestPhoto();

Method looked at the latest photo by its modified date and deleted it and returned the result of deleting photo as boolean to you.

Putting image into an ImageView

Have you waited for this section? OK, then, let's put the image into an ImageView via Golbat. We need showImage(...) to do that. It takes 3 arguments which are CaptureType captureType, ImageView imageView, and Uri fileUri. Here is how it works:

Golbat.showImage(
        Golbat.CaptureType.CAPTURED_FROM_CAMERA,
        myImageView,
        fileUri
);

First argument is used to determine which type of image you want to show in ImageView.

CaptureType enum class:

public enum CaptureType {
    CAPTURED_FROM_CAMERA, SELECTED_FROM_GALLERY
}

License

Golbat is an Android library that helps on working with camera,
gallery and output and its encoded types.
Copyright (C) 2016  Halil Kaya

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
Clone this wiki locally