Skip to content
Simple annotation-based API to handle runtime permissions.
Java Kotlin Other
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Resolves #304. Apr 30, 2017
.travis Add gitbook hook on CI(#565) Dec 19, 2018
annotation Rename LICENCE to LICENSE Nov 13, 2018
buildSrc Separate annotations to dedicated module. May 19, 2018
doc Update readme installation. Feb 28, 2019
gradle Update Gradle, AGP, Kotlin and KotlinPoet (#625) Jun 12, 2019
library
lint 602:Improve method identification logic (#627) Jun 18, 2019
processor Rename variables to use camel case. (#639) Sep 15, 2019
sample-kotlin Update Gradle, AGP, Kotlin and KotlinPoet (#625) Jun 12, 2019
sample Update Gradle, AGP, Kotlin and KotlinPoet (#625) Jun 12, 2019
scripts Stop using githubio. (#592) Feb 24, 2019
test Update Gradle, AGP, Kotlin and KotlinPoet (#625) Jun 12, 2019
.gitignore Resolves #304. Apr 30, 2017
.travis.yml Stop using githubio. (#592) Feb 24, 2019
CHANGELOG.md Prepre for 4.5.0 (#631) Jun 30, 2019
LICENSE Rename LICENCE to LICENSE Nov 13, 2018
README.md Update readme installation. Feb 28, 2019
build.gradle Tweak publishing codes. Jul 11, 2018
ext.gradle Tweak bintray plugin settings to work. Jul 9, 2018
gradle.properties Update kotlin version to 1.3.50. (#638) Sep 1, 2019
gradlew Update Gradle, AGP, Kotlin and KotlinPoet (#625) Jun 12, 2019
gradlew.bat Update Gradle, AGP, Kotlin and KotlinPoet (#625) Jun 12, 2019
settings.gradle Remove native Fragment support. Jul 10, 2018

README.md

PermissionsDispatcher Build Status

PermissionsDispatcher provides a simple annotation-based API to handle runtime permissions.

This library lifts the burden that comes with writing a bunch of check statements whether a permission has been granted or not from you, in order to keep your code clean and safe.

Usage(Java)

Here's a minimum example, in which you register a MainActivity which requires Manifest.permission.CAMERA.

0. Prepare AndroidManifest

Add the following line to AndroidManifest.xml:

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

1. Attach annotations

PermissionsDispatcher introduces only a few annotations, keeping its general API concise:

NOTE: Annotated methods must not be private.

Annotation Required Description
@RuntimePermissions Register an Activity, Fragment or Controller to handle permissions
@NeedsPermission Annotate a method which performs the action that requires one or more permissions
@OnShowRationale Annotate a method which explains why the permissions are needed. It passes in a PermissionRequest object which can be used to continue or abort the current permission request upon user input. If you don't specify any argument for the method compiler will generate process${NeedsPermissionMethodName}ProcessRequest and cancel${NeedsPermissionMethodName}ProcessRequest. You can use those methods in place of PermissionRequest(ex: with DialogFragment)
@OnPermissionDenied Annotate a method which is invoked if the user doesn't grant the permissions
@OnNeverAskAgain Annotate a method which is invoked if the user chose to have the device "never ask again" about a permission
@RuntimePermissions
class MainActivity : AppCompatActivity(), View.OnClickListener {

    @NeedsPermission(Manifest.permission.CAMERA)
    fun showCamera() {
        supportFragmentManager.beginTransaction()
                .replace(R.id.sample_content_fragment, CameraPreviewFragment.newInstance())
                .addToBackStack("camera")
                .commitAllowingStateLoss()
    }

    @OnShowRationale(Manifest.permission.CAMERA)
    fun showRationaleForCamera(request: PermissionRequest) {
        showRationaleDialog(R.string.permission_camera_rationale, request)
    }

    @OnPermissionDenied(Manifest.permission.CAMERA)
    fun onCameraDenied() {
        Toast.makeText(this, R.string.permission_camera_denied, Toast.LENGTH_SHORT).show()
    }

    @OnNeverAskAgain(Manifest.permission.CAMERA)
    fun onCameraNeverAskAgain() {
        Toast.makeText(this, R.string.permission_camera_never_askagain, Toast.LENGTH_SHORT).show()
    }
}

2. Delegate to generated functions

Now generated functions become much more concise and intuitive than Java version!

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        findViewById(R.id.button_camera).setOnClickListener {
            // NOTE: delegate the permission handling to generated function
            showCameraWithPermissionCheck()
        }
    }

    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        // NOTE: delegate the permission handling to generated function
        onRequestPermissionsResult(requestCode, grantResults)
    }

Check out the sample for more details.

Other features/plugins

Users

Thankfully we've got hundreds of users around the world!

Installation

NOTE: 4.x only supports Jetpack. If you still use appcompat 3.x is the way to go.

To add PermissionsDispatcher to your project, include the following in your app module build.gradle file:

${latest.version} is Download

dependencies {
  implementation "org.permissionsdispatcher:permissionsdispatcher:${latest.version}"
  annotationProcessor "org.permissionsdispatcher:permissionsdispatcher-processor:${latest.version}"
}

With Kotlin:

apply plugin: 'kotlin-kapt'

dependencies {
  implementation "org.permissionsdispatcher:permissionsdispatcher:${latest.version}"
  kapt "org.permissionsdispatcher:permissionsdispatcher-processor:${latest.version}"
}

Snapshots of the development version are available in JFrog's snapshots repository. Add the repo below to download SNAPSHOT releases.

repositories {
  jcenter()
  maven { url 'http://oss.jfrog.org/artifactory/oss-snapshot-local/' }
}

License

Copyright 2016 Shintaro Katafuchi, Marcel Schnelle, Yoshinori Isogai

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.
You can’t perform that action at this time.