diff --git a/core/java/android/app/Notification.java b/core/java/android/app/Notification.java index 0c6c77f8e36b1..d0361b7e1118e 100644 --- a/core/java/android/app/Notification.java +++ b/core/java/android/app/Notification.java @@ -3165,8 +3165,8 @@ public class Notification implements Parcelable /** * Gets the {@link LocusId} associated with this notification. * - *

Used by the device's intelligence services to correlate objects (such as - * {@link ShortcutInfo} and {@link ContentCaptureContext}) that are correlated. + *

Used by the Android system to correlate objects (such as + * {@link ShortcutInfo} and {@link ContentCaptureContext}). */ @Nullable public LocusId getLocusId() { @@ -3534,8 +3534,8 @@ public class Notification implements Parcelable * Sets the {@link LocusId} associated with this notification. * *

This method should be called when the {@link LocusId} is used in other places (such - * as {@link ShortcutInfo} and {@link ContentCaptureContext}) so the device's intelligence - * services can correlate them. + * as {@link ShortcutInfo} and {@link ContentCaptureContext}) so the Android system can + * correlate them. */ @NonNull public Builder setLocusId(@Nullable LocusId locusId) { diff --git a/core/java/android/content/LocusId.java b/core/java/android/content/LocusId.java index 283cea00b1926..613765fd826a3 100644 --- a/core/java/android/content/LocusId.java +++ b/core/java/android/content/LocusId.java @@ -29,9 +29,8 @@ import java.io.PrintWriter; * backup / restore. * *

Locus is a new concept introduced on - * {@link android.os.Build.VERSION_CODES#Q Android Q} and it lets the intelligence service provided - * by the Android System to correlate state between different subsystems such as content capture, - * shortcuts, and notifications. + * {@link android.os.Build.VERSION_CODES#Q Android Q} and it lets the Android system correlate + * state between different subsystems such as content capture, shortcuts, and notifications. * *

For example, if your app provides an activiy representing a chat between 2 users * (say {@code A} and {@code B}, this chat state could be represented by: diff --git a/core/java/android/content/pm/ShortcutInfo.java b/core/java/android/content/pm/ShortcutInfo.java index 1f82fa6b57e38..41be38a6e8dd4 100644 --- a/core/java/android/content/pm/ShortcutInfo.java +++ b/core/java/android/content/pm/ShortcutInfo.java @@ -991,8 +991,8 @@ public final class ShortcutInfo implements Parcelable { * Sets the {@link LocusId} associated with this shortcut. * *

This method should be called when the {@link LocusId} is used in other places (such - * as {@link Notification} and {@link ContentCaptureContext}) so the device's intelligence - * services can correlate them. + * as {@link Notification} and {@link ContentCaptureContext}) so the Android system can + * correlate them. */ @NonNull public Builder setLocusId(@NonNull LocusId locusId) { @@ -1325,8 +1325,8 @@ public final class ShortcutInfo implements Parcelable { /** * Gets the {@link LocusId} associated with this shortcut. * - *

Used by the device's intelligence services to correlate objects (such as - * {@link Notification} and {@link ContentCaptureContext}) that are correlated. + *

Used by the Android system to correlate objects (such as + * {@link Notification} and {@link ContentCaptureContext}). */ @Nullable public LocusId getLocusId() { diff --git a/core/java/android/view/contentcapture/ContentCaptureContext.java b/core/java/android/view/contentcapture/ContentCaptureContext.java index 94e548fa0eebc..1692051924f4b 100644 --- a/core/java/android/view/contentcapture/ContentCaptureContext.java +++ b/core/java/android/view/contentcapture/ContentCaptureContext.java @@ -261,6 +261,7 @@ public final class ContentCaptureContext implements Parcelable { * example). *

  • A unique identifier of the application state (for example, a conversation between * 2 users in a chat app). + * * *

    See {@link ContentCaptureManager} for more info about the content capture context. * diff --git a/core/java/android/view/contentcapture/ContentCaptureManager.java b/core/java/android/view/contentcapture/ContentCaptureManager.java index 26454c055932e..a9770731dbc75 100644 --- a/core/java/android/view/contentcapture/ContentCaptureManager.java +++ b/core/java/android/view/contentcapture/ContentCaptureManager.java @@ -29,7 +29,6 @@ import android.annotation.UiThread; import android.content.ComponentName; import android.content.ContentCaptureOptions; import android.content.Context; -import android.graphics.Canvas; import android.os.Handler; import android.os.IBinder; import android.os.Looper; @@ -51,61 +50,61 @@ import java.util.ArrayList; import java.util.Set; /** - *

    The {@link ContentCaptureManager} provides additional ways for for apps to - * integrate with the content capture subsystem. + * Content capture is mechanism used to let apps notify the Android system of events associated with + * views. * - *

    Content capture provides real-time, continuous capture of application activity, display and - * events to an intelligence service that is provided by the Android system. The intelligence - * service then uses that info to mediate and speed user journey through different apps. For - * example, when the user receives a restaurant address in a chat app and switchs to a map app - * to search for that restaurant, the intelligence service could offer an autofill dialog to - * let the user automatically select its address. - * - *

    Content capture was designed with two major concerns in mind: privacy and performance. - * - *

    - * - *

    In fact, before using this manager, the app developer should check if it's available. Example: - * + *

    Before using this manager, you should check if it's available. Example: + * 

    
  *  ContentCaptureManager mgr = context.getSystemService(ContentCaptureManager.class);
  *  if (mgr != null && mgr.isContentCaptureEnabled()) {
  *    // ...
  *  }
- *  
+ *
    * - *

    App developers usually don't need to explicitly interact with content capture, except when the - * app: + *

    To support content capture, you must notifiy the Android system of the following events: * *

    * + *

    You can get a blank content capture structure using + * {@link ContentCaptureSession#newViewStructure(View)}, then populate its relevant fields. + * Here's an example of the relevant methods for an {@code EditText}-like view: + * + * 

    
+ * public class MyEditText extends View {
+ *
+ * private void populateContentCaptureStructure(@NonNull ViewStructure structure) {
+ *   structure.setText(getText(), getSelectionStart(), getSelectionEnd());
+ *   structure.setHint(getHint());
+ *   structure.setInputType(getInputType());
+ *   // set other properties like setTextIdEntry(), setTextLines(), setTextStyle(),
+ *   // setMinTextEms(), setMaxTextEms(), setMaxTextLength()
+ * }
+ *
+ * private void onTextChanged() {
+ *   if (isLaidOut() && isTextEditable()) {
+ *     ContentCaptureManager mgr = mContext.getSystemService(ContentCaptureManager.class);
+ *     if (cm != null && cm.isContentCaptureEnabled()) {
+ *        ContentCaptureSession session = getContentCaptureSession();
+ *        if (session != null) {
+ *          session.notifyViewTextChanged(getAutofillId(), getText());
+ *        }
+ *   }
+ * }
+ *
    + * *

    The main integration point with content capture is the {@link ContentCaptureSession}. A "main" - * session is automatically created by the Android System when content capture is enabled for the - * activity and its used by the standard Android views to notify the content capture service of - * events such as views being added, views been removed, and text changed by user input. The session - * could have a {@link ContentCaptureContext} to provide more contextual info about it, such as - * the locus associated with the view hierarchy (see {@link android.content.LocusId} for more info - * about locus). By default, the main session doesn't have a {@code ContentCaptureContext}, but you - * can change it after its created. Example: + * session is automatically created by the Android system when content capture is enabled for the + * activity. The session could have a {@link ContentCaptureContext} to provide more contextual info + * about it, such as the locus associated with the view hierarchy + * (see {@link android.content.LocusId} for more info about locus). By default, the main session + * doesn't have a {@code ContentCaptureContext}, but you can change it after its created. Example: * * 

    
  * protected void onCreate(Bundle savedInstanceState) {
@@ -145,54 +144,6 @@ import java.util.Set;
  * }
  *
    * - *

    If your activity has custom views (i.e., views that extend {@link View} directly and provide - * just one logical view, not a virtual tree hiearchy) and it provides content that's relevant for - * content capture (as of {@link android.os.Build.VERSION_CODES#Q Android Q}, the only relevant - * content is text), then your view implementation should: - * - *

    - * - *

    Here's an example of the relevant methods for an {@code EditText}-like view: - * - * 

    
- * public class MyEditText extends View {
- *
- * public MyEditText(...) {
- *   if (getImportantForContentCapture() == IMPORTANT_FOR_CONTENT_CAPTURE_AUTO) {
- *     setImportantForContentCapture(IMPORTANT_FOR_CONTENT_CAPTURE_YES);
- *   }
- * }
- *
- * public void onProvideContentCaptureStructure(@NonNull ViewStructure structure, int flags) {
- *   super.onProvideContentCaptureStructure(structure, flags);
- *
- *   structure.setText(getText(), getSelectionStart(), getSelectionEnd());
- *   structure.setHint(getHint());
- *   structure.setInputType(getInputType());
- *   // set other properties like setTextIdEntry(), setTextLines(), setTextStyle(),
- *   // setMinTextEms(), setMaxTextEms(), setMaxTextLength()
- * }
- *
- * private void onTextChanged() {
- *   if (isLaidOut() && isImportantForContentCapture() && isTextEditable()) {
- *     ContentCaptureManager mgr = mContext.getSystemService(ContentCaptureManager.class);
- *     if (cm != null && cm.isContentCaptureEnabled()) {
- *        ContentCaptureSession session = getContentCaptureSession();
- *        if (session != null) {
- *          session.notifyViewTextChanged(getAutofillId(), getText());
- *        }
- *   }
- * }
- *
    - * - *

    If your view provides its own virtual hierarchy (for example, if it's a browser that draws - * the HTML using {@link Canvas} or native libraries in a different render process), then the view - * is also responsible to notify the session when the virtual elements appear and disappear - - * see {@link ContentCaptureSession#newViewStructure(View)} for more info. */ @SystemService(Context.CONTENT_CAPTURE_MANAGER_SERVICE) public final class ContentCaptureManager { @@ -473,17 +424,6 @@ public final class ContentCaptureManager { /** * Checks whether content capture is enabled for this activity. - * - *

    There are many reasons it could be disabled, such as: - *

    */ public boolean isContentCaptureEnabled() { if (mOptions.lite) return false; @@ -503,9 +443,9 @@ public final class ContentCaptureManager { * Gets the list of conditions for when content capture should be allowed. * *

    This method is typically used by web browsers so they don't generate unnecessary content - * capture events for websites the content capture service is not interested on. + * capture events for some websites. * - * @return list of conditions, or {@code null} if the service didn't set any restriction + * @return list of conditions, or {@code null} if there isn't any restriction * (in which case content capture events should always be generated). If the list is empty, * then it should not generate any event at all. */ diff --git a/core/java/android/view/contentcapture/ContentCaptureSession.java b/core/java/android/view/contentcapture/ContentCaptureSession.java index 17a1fb4053211..210dea1894bf0 100644 --- a/core/java/android/view/contentcapture/ContentCaptureSession.java +++ b/core/java/android/view/contentcapture/ContentCaptureSession.java @@ -41,8 +41,7 @@ import java.util.ArrayList; import java.util.Random; /** - * Session used to notify a system-provided Content Capture service about events associated with - * views. + * Session used to notify the Android system about events associated with views. */ public abstract class ContentCaptureSession implements AutoCloseable { @@ -306,7 +305,7 @@ public abstract class ContentCaptureSession implements AutoCloseable { } /** - * Destroys this session, flushing out all pending notifications to the service. + * Destroys this session, flushing out all pending notifications. * *

    Once destroyed, any new notification will be dropped. */ @@ -354,7 +353,7 @@ public abstract class ContentCaptureSession implements AutoCloseable { } /** - * Notifies the Content Capture Service that a node has been added to the view structure. + * Notifies the Android system that a node has been added to the view structure. * * @param node node that has been added. */ @@ -372,7 +371,7 @@ public abstract class ContentCaptureSession implements AutoCloseable { abstract void internalNotifyViewAppeared(@NonNull ViewNode.ViewStructureImpl node); /** - * Notifies the Content Capture Service that a node has been removed from the view structure. + * Notifies the Android system that a node has been removed from the view structure. * * @param id id of the node that has been removed. */ @@ -386,7 +385,7 @@ public abstract class ContentCaptureSession implements AutoCloseable { abstract void internalNotifyViewDisappeared(@NonNull AutofillId id); /** - * Notifies the Content Capture Service that many nodes has been removed from a virtual view + * Notifies the Android system that many nodes has been removed from a virtual view * structure. * *

    Should only be called by views that handle their own virtual view hierarchy. @@ -412,7 +411,7 @@ public abstract class ContentCaptureSession implements AutoCloseable { } /** - * Notifies the Intelligence Service that the value of a text node has been changed. + * Notifies the Android system that the value of a text node has been changed. * * @param id of the node. * @param text new text.