From 677df219aa1133996cb7d8b6a29428ae1b5573a1 Mon Sep 17 00:00:00 2001 From: "Philip P. Moltmann" Date: Fri, 29 May 2020 17:15:12 -0700 Subject: [PATCH] Make it clear that checking shouldShowPermissionRationale is recommended Bug: 157779069 Test: Docs change only Change-Id: I288cb852f94ff2e59ede843946d6bee898f0c643 --- core/java/android/app/Activity.java | 18 +++++-------- core/java/android/app/Fragment.java | 41 +++++------------------------ 2 files changed, 12 insertions(+), 47 deletions(-) diff --git a/core/java/android/app/Activity.java b/core/java/android/app/Activity.java index af5fafbc93d4c..5df41340a5a09 100644 --- a/core/java/android/app/Activity.java +++ b/core/java/android/app/Activity.java @@ -5145,6 +5145,10 @@ public class Activity extends ContextThemeWrapper * the signature of the app declaring the permissions. *

*

+ * Call {@link #shouldShowRequestPermissionRationale(String)} before calling this API to + * check if the system recommends to show a rationale UI before asking for a permission. + *

+ *

* If your app does not have the requested permissions the user will be presented * with UI for accepting them. After the user has accepted or rejected the * requested permissions you will receive a callback on {@link @@ -5234,20 +5238,10 @@ public class Activity extends ContextThemeWrapper } /** - * Gets whether you should show UI with rationale for requesting a permission. - * You should do this only if you do not have the permission and the context in - * which the permission is requested does not clearly communicate to the user - * what would be the benefit from granting this permission. - *

- * For example, if you write a camera app, requesting the camera permission - * would be expected by the user and no rationale for why it is requested is - * needed. If however, the app needs location for tagging photos then a non-tech - * savvy user may wonder how location is related to taking photos. In this case - * you may choose to show UI with rationale of requesting this permission. - *

+ * Gets whether you should show UI with rationale before requesting a permission. * * @param permission A permission your app wants to request. - * @return Whether you can show permission rationale UI. + * @return Whether you should show permission rationale UI. * * @see #checkSelfPermission(String) * @see #requestPermissions(String[], int) diff --git a/core/java/android/app/Fragment.java b/core/java/android/app/Fragment.java index c6a0de458df0e..e4e5ba37ddbf9 100644 --- a/core/java/android/app/Fragment.java +++ b/core/java/android/app/Fragment.java @@ -1179,6 +1179,10 @@ public class Fragment implements ComponentCallbacks2, OnCreateContextMenuListene * the signature of the app declaring the permissions. *

*

+ * Call {@link #shouldShowRequestPermissionRationale(String)} before calling this API + * to check if the system recommends to show a rationale UI before asking for a permission. + *

+ *

* If your app does not have the requested permissions the user will be presented * with UI for accepting them. After the user has accepted or rejected the * requested permissions you will receive a callback on {@link @@ -1213,29 +1217,6 @@ public class Fragment implements ComponentCallbacks2, OnCreateContextMenuListene * true because in this case the activity would not receive * result callbacks including {@link #onRequestPermissionsResult(int, String[], int[])}. *

- *

- * A sample permissions request looks like this: - *

- * 

-     * private void showContacts() {
-     *     if (getActivity().checkSelfPermission(Manifest.permission.READ_CONTACTS)
-     *             != PackageManager.PERMISSION_GRANTED) {
-     *         requestPermissions(new String[]{Manifest.permission.READ_CONTACTS},
-     *                 PERMISSIONS_REQUEST_READ_CONTACTS);
-     *     } else {
-     *         doShowContacts();
-     *     }
-     * }
-     *
-     * {@literal @}Override
-     * public void onRequestPermissionsResult(int requestCode, String[] permissions,
-     *         int[] grantResults) {
-     *     if (requestCode == PERMISSIONS_REQUEST_READ_CONTACTS
-     *             && grantResults[0] == PackageManager.PERMISSION_GRANTED) {
-     *         doShowContacts();
-     *     }
-     * }
-     *

* * @param permissions The requested permissions. Must me non-null and not empty. * @param requestCode Application specific request code to match with a result @@ -1275,20 +1256,10 @@ public class Fragment implements ComponentCallbacks2, OnCreateContextMenuListene } /** - * Gets whether you should show UI with rationale for requesting a permission. - * You should do this only if you do not have the permission and the context in - * which the permission is requested does not clearly communicate to the user - * what would be the benefit from granting this permission. - *

- * For example, if you write a camera app, requesting the camera permission - * would be expected by the user and no rationale for why it is requested is - * needed. If however, the app needs location for tagging photos then a non-tech - * savvy user may wonder how location is related to taking photos. In this case - * you may choose to show UI with rationale of requesting this permission. - *

+ * Gets whether you should show UI with rationale before requesting a permission. * * @param permission A permission your app wants to request. - * @return Whether you can show permission rationale UI. + * @return Whether you should show permission rationale UI. * * @see Context#checkSelfPermission(String) * @see #requestPermissions(String[], int)