1 /*
2  * Copyright (C) 2015 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  *      http://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.android.permissioncontroller.permission.ui;
18 
19 import static java.lang.annotation.RetentionPolicy.SOURCE;
20 
21 import android.graphics.drawable.Icon;
22 import android.os.Bundle;
23 import android.view.View;
24 import android.view.Window;
25 import android.view.WindowManager;
26 
27 import androidx.annotation.IntDef;
28 
29 import java.lang.annotation.Retention;
30 import java.util.List;
31 
32 /**
33  * Class for managing the presentation and user interaction of the "grant
34  * permissions" user interface.
35  */
36 public interface GrantPermissionsViewHandler {
37     @Retention(SOURCE)
38     @IntDef({CANCELED, GRANTED_ALWAYS, GRANTED_FOREGROUND_ONLY, DENIED, DENIED_DO_NOT_ASK_AGAIN,
39             GRANTED_ONE_TIME, GRANTED_USER_SELECTED, DENIED_MORE})
40     @interface Result {}
41     int LINKED_TO_PERMISSION_RATIONALE = -3;
42     int LINKED_TO_SETTINGS = -2;
43     int CANCELED = -1;
44     int GRANTED_ALWAYS = 0;
45     int GRANTED_FOREGROUND_ONLY = 1;
46     int DENIED = 2;
47     int DENIED_DO_NOT_ASK_AGAIN = 3;
48     int GRANTED_ONE_TIME = 4;
49     int GRANTED_USER_SELECTED = 5; // The user has used a picker to select data to share
50     int DENIED_MORE = 6; // The user has used the picker at least once, but has denied a request
51                          // for more
52 
53     /**
54      * Listener interface for getting notified when the user responds to a
55      * permissions grant request.
56      */
57     interface ResultListener {
onPermissionGrantResult(String groupName, @Result int result)58         void onPermissionGrantResult(String groupName, @Result int result);
59 
onPermissionGrantResult(String groupName, List<String> affectedForegroundPermissions, @Result int result)60         void onPermissionGrantResult(String groupName, List<String> affectedForegroundPermissions,
61                 @Result int result);
62 
onPermissionRationaleClicked(String groupName)63         void onPermissionRationaleClicked(String groupName);
64     }
65 
66     /**
67      * Creates and returns the view hierarchy that is managed by this view
68      * handler. This must be called before {@link #updateUi}.
69      */
createView()70     View createView();
71 
72     /**
73      * Updates the layout attributes of the current window. This is an optional
74      * operation; implementations only need to do work in this method if they
75      * need to alter the default styles provided by the activity's theme.
76      */
updateWindowAttributes(WindowManager.LayoutParams outLayoutParams)77     void updateWindowAttributes(WindowManager.LayoutParams outLayoutParams);
78 
79     /**
80      * Updates the view hierarchy to reflect the specified state.
81      * <p>
82      * Note that this must be called at least once before showing the UI to
83      * the user to properly initialize the UI.
84      *
85      * @param groupName the name of the permission group
86      * @param groupCount the total number of groups that are being requested
87      * @param groupIndex the index of the current group being requested
88      * @param icon the icon representation of the current group
89      * @param message the message to display the user
90      * @param detailMessage another message to display to the user. This clarifies "message" in more
91      *                      detail
92      * @param permissionRationaleMessage another message to display to the user. This message lets
93      *                                   users know developer stated data usages for the requested
94      *                                   permission
95      * @param buttonVisibilities visibilities for each button
96      * @param locationVisibilities visibilities for location options
97      */
updateUi(String groupName, int groupCount, int groupIndex, Icon icon, CharSequence message, CharSequence detailMessage, CharSequence permissionRationaleMessage, boolean[] buttonVisibilities, boolean[] locationVisibilities)98     void updateUi(String groupName, int groupCount, int groupIndex, Icon icon,
99             CharSequence message, CharSequence detailMessage,
100             CharSequence permissionRationaleMessage, boolean[] buttonVisibilities,
101             boolean[] locationVisibilities);
102 
103     /**
104      * Sets the result listener that will be notified when the user responds
105      * to a permissions grant request.
106      */
setResultListener(ResultListener listener)107     GrantPermissionsViewHandler setResultListener(ResultListener listener);
108 
109     /**
110      * Called by {@link GrantPermissionsActivity} to save the state of this
111      * view handler to the specified bundle.
112      */
saveInstanceState(Bundle outState)113     void saveInstanceState(Bundle outState);
114 
115     /**
116      * Called by {@link GrantPermissionsActivity} to load the state of this
117      * view handler from the specified bundle.
118      */
loadInstanceState(Bundle savedInstanceState)119     void loadInstanceState(Bundle savedInstanceState);
120 
121     /**
122      * Gives a chance for handling the back key.
123      */
onBackPressed()124     void onBackPressed();
125 
126     /**
127      * Handles cancel event for the permission dialog.
128      */
onCancelled()129     default void onCancelled() {}
130 
131     /**
132      * Called by {@link GrantPermissionsActivity} to allow the handler to update
133      * the ui when blur is enabled/disabled.
134      */
onBlurEnabledChanged(Window window, boolean enabled)135     default void onBlurEnabledChanged(Window window, boolean enabled) {}
136 }
137