1 /*
2 * Copyright 2021 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package com.google.accompanist.permissions
18
19 import androidx.compose.runtime.Composable
20 import androidx.compose.runtime.Stable
21
22 /**
23 * Creates a [MultiplePermissionsState] that is remembered across compositions.
24 *
25 * It's recommended that apps exercise the permissions workflow as described in the
26 * [documentation](https://developer.android.com/training/permissions/requesting#workflow_for_requesting_permissions).
27 *
28 * @param permissions the permissions to control and observe.
29 * @param onPermissionsResult will be called with whether or not the user granted the permissions
30 * after [MultiplePermissionsState.launchMultiplePermissionRequest] is called.
31 */
32 @ExperimentalPermissionsApi
33 @Composable
rememberMultiplePermissionsStatenull34 public fun rememberMultiplePermissionsState(
35 permissions: List<String>,
36 onPermissionsResult: (Map<String, Boolean>) -> Unit = {}
37 ): MultiplePermissionsState {
38 return rememberMutableMultiplePermissionsState(permissions, onPermissionsResult)
39 }
40
41 /**
42 * A state object that can be hoisted to control and observe multiple [permissions] status changes.
43 *
44 * In most cases, this will be created via [rememberMultiplePermissionsState].
45 *
46 * It's recommended that apps exercise the permissions workflow as described in the
47 * [documentation](https://developer.android.com/training/permissions/requesting#workflow_for_requesting_permissions).
48 */
49 @ExperimentalPermissionsApi
50 @Stable
51 public interface MultiplePermissionsState {
52
53 /**
54 * List of all permissions to request.
55 */
56 public val permissions: List<PermissionState>
57
58 /**
59 * List of permissions revoked by the user.
60 */
61 public val revokedPermissions: List<PermissionState>
62
63 /**
64 * When `true`, the user has granted all [permissions].
65 */
66 public val allPermissionsGranted: Boolean
67
68 /**
69 * When `true`, the user should be presented with a rationale.
70 */
71 public val shouldShowRationale: Boolean
72
73 /**
74 * Request the [permissions] to the user.
75 *
76 * This should always be triggered from non-composable scope, for example, from a side-effect
77 * or a non-composable callback. Otherwise, this will result in an IllegalStateException.
78 *
79 * This triggers a system dialog that asks the user to grant or revoke the permission.
80 * Note that this dialog might not appear on the screen if the user doesn't want to be asked
81 * again or has denied the permission multiple times.
82 * This behavior varies depending on the Android level API.
83 */
launchMultiplePermissionRequestnull84 public fun launchMultiplePermissionRequest(): Unit
85 }
86