PermissionsDispatcher README

The project's README from github.com/permissions-dispatcher/PermissionsDispatcher. As one markdown file: README.md.

PermissionsDispatcher CI for pull request PermissionsDispatcher

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

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 or Fragment 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

Installation

NOTE:

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

${latest.version} is Download

dependencies {
  implementation "com.github.permissions-dispatcher:permissionsdispatcher:${latest.version}"
  annotationProcessor "com.github.permissions-dispatcher:permissionsdispatcher-processor:${latest.version}"
}

With Kotlin:

apply plugin: 'kotlin-kapt'

dependencies {
  implementation "com.github.permissions-dispatcher:permissionsdispatcher:${latest.version}"
  kapt "com.github.permissions-dispatcher:permissionsdispatcher-processor:${latest.version}"
}

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.

PermissionsDispatcher (permissions-dispatcher/PermissionsDispatcher)

Searching Database…

11.1K ·GitHub
PermissionsDispatcher
Что это такое?PermissionsDispatcher — это библиотека для Android на основе аннотаций, которая генерирует шаблонный код, необходимый для запроса и проверки разрешений времени выполнения, поэтому не нужно писать проверки разрешений вручную.
Это фреймворк или просто библиотека?Это библиотека для обработки аннотаций: вы добавляете несколько аннотаций к своему Activity или Fragment, и она генерирует за вас код обработки разрешений на этапе компиляции.
Как подключить её к проекту?Добавьте PermissionsDispatcher в файл build.gradle модуля app, затем пометьте свой класс аннотацией @RuntimePermissions, а методы, которым нужны разрешения, — аннотацией @NeedsPermission, и делегируйте вызов сгенерированным функциям.
Нужен ли мне ktx/kapt для Kotlin или apt для Java?Пользователи Kotlin могут выбрать ktx или kapt для обработки аннотаций, а пользователи Java используют apt. Также нужно объявить необходимое разрешение в AndroidManifest.xml.
Есть ли подводные камни при установке, которые мне стоит знать?Если ваш проект всё ещё использует jCenter, нужно перейти на MavenCentral, а версия 4.x поддерживает только Jetpack (AndroidX) — если вы всё ещё используете старую библиотеку appcompat, оставайтесь на 3.x.
Какие аннотации предоставляет PermissionsDispatcher?В основном это @RuntimePermissions, @NeedsPermission, @OnShowRationale, @OnPermissionDenied и @OnNeverAskAgain, которые вместе охватывают запрос разрешения, объяснение, зачем оно нужно, и реакцию на отказ или на «больше не спрашивать».
Используется ли в ней рефлексия?Нет, библиотека описана как на 100% без рефлексии; вместо неё она полагается на обработку аннотаций, которая генерирует код на этапе компиляции.
Могут ли аннотированные методы быть приватными?Нет, методы, помеченные аннотациями PermissionsDispatcher, не должны быть приватными, так как сгенерированному коду нужно их вызывать.
Поддерживает ли она специальные разрешения помимо обычных разрешений времени выполнения?Да, в README упоминается отдельная поддержка «Special Permissions» и опция maxSdkVersion, а также плагин для IntelliJ и плагин для AndroidAnnotations.
What are similar projects?androidannotations, MVPArms, lottie-android, MPAndroidChart, RxPermissions, timber, ARouter, AndroidUtilCode
Which topics is it in?permissions, permission, android-application, annotations, android-library, code-generation, kotlin, mobile-app, sdk, java, mobile, android
Creator
permissions-dispatcher
Size
2.9 MB
Stars
11.1K
Updated
CommitApr 06Release4.8.0Mar 05
Age
11y
Commits · 90 Days