ContentCaptureSessionCompat


public class ContentCaptureSessionCompat


Helper for accessing features in ContentCaptureSession.

Summary

Public methods

void

Flushes an internal buffer of UI events and signals System Intelligence (SI) that a semantically meaningful state has been reached.

@Nullable AutofillId
newAutofillId(long virtualChildId)

Creates a new AutofillId for a virtual child, so it can be used to uniquely identify the children in the session.

@Nullable ViewStructureCompat
newVirtualViewStructure(@NonNull AutofillId parentId, long virtualId)

Creates a ViewStructureCompat for a "virtual" view, so it can be passed to notifyViewsAppeared by the view managing the virtual view hierarchy.

void

Notifies the Content Capture Service that a node has been added to the view structure.

void

Notifies the Content Capture Service that a node has been removed from the view structure.

void

Notifies the Intelligence Service that the value of a text node has been changed.

void

Notifies the Content Capture Service that a list of nodes has appeared in the view structure.

void
notifyViewsDisappeared(@NonNull long[] virtualIds)

Notifies the Content Capture Service that many nodes has been removed from a virtual view structure.

@NonNull ContentCaptureSession

Provides the ContentCaptureSession represented by this object.

static @NonNull ContentCaptureSessionCompat
@RequiresApi(value = 29)
toContentCaptureSessionCompat(
    @NonNull ContentCaptureSession contentCaptureSession,
    @NonNull View host
)

Provides a backward-compatible wrapper for ContentCaptureSession.

Public methods

flush

public void flush()

Flushes an internal buffer of UI events and signals System Intelligence (SI) that a semantically meaningful state has been reached. SI uses this signal to potentially rebuild the view hierarchy and understand the current state of the UI.

UI events are often batched together for performance reasons. A semantic batch represents a series of events that, when applied sequentially, result in a meaningful and complete UI state.

It is crucial to call flush() after completing a semantic batch to ensure SI can accurately reconstruct the view hierarchy.

Premature Flushing: Calling flush() within a semantic batch may lead to SI failing to rebuild the view hierarchy correctly. This could manifest as incorrect ordering of sibling nodes.

Delayed Flushing: While not immediately flushing after a semantic batch is generally safe, it's recommended to do so as soon as possible. In the worst-case scenario where a flush() is never called, SI will attempt to process the events after a short delay based on view appearance and disappearance events.

Compatibility behavior:

  • SDK 36 and above, this method matches platform behavior.
  • SDK 29 through 35, this method is a best-effort to match platform behavior, by sending a special notifyViewsDisappeared event.
  • SDK 28 and below, this method does nothing.

newAutofillId

Added in 1.11.0
public @Nullable AutofillId newAutofillId(long virtualChildId)

Creates a new AutofillId for a virtual child, so it can be used to uniquely identify the children in the session.

Compatibility behavior:

  • SDK 29 and above, this method matches platform behavior.
  • SDK 28 and below, this method returns null.
Parameters
long virtualChildId

id of the virtual child, relative to the parent.

Returns
@Nullable AutofillId

AutofillId for the virtual child

newVirtualViewStructure

Added in 1.11.0
public @Nullable ViewStructureCompat newVirtualViewStructure(@NonNull AutofillId parentId, long virtualId)

Creates a ViewStructureCompat for a "virtual" view, so it can be passed to notifyViewsAppeared by the view managing the virtual view hierarchy.

Compatibility behavior:

  • SDK 29 and above, this method matches platform behavior.
  • SDK 28 and below, this method returns null.
Parameters
@NonNull AutofillId parentId

id of the virtual view parent (it can be obtained by calling getAutofillId on the parent).

long virtualId

id of the virtual child, relative to the parent.

Returns
@Nullable ViewStructureCompat

a new ViewStructure that can be used for Content Capture purposes.

notifyViewAppeared

public void notifyViewAppeared(@NonNull ViewStructure node)

Notifies the Content Capture Service that a node has been added to the view structure.

Typically called "manually" by views that handle their own virtual view hierarchy, or automatically by the Android System for views that return true on onProvideContentCaptureStructure.

Consider use notifyViewsAppeared which has a better performance when notifying a list of nodes has appeared.

Compatibility behavior:

  • SDK 29 and above, this method matches platform behavior.
  • SDK 28 and below, this method does nothing.
Parameters
@NonNull ViewStructure node

node that has been added.

notifyViewDisappeared

public void notifyViewDisappeared(@NonNull AutofillId id)

Notifies the Content Capture Service that a node has been removed from the view structure.

Typically called "manually" by views that handle their own virtual view hierarchy, or automatically by the Android System for standard views.

Consider use notifyViewsDisappeared which has a better performance when notifying a list of nodes has disappeared.

Compatibility behavior:

  • SDK 29 and above, this method matches platform behavior.
  • SDK 28 and below, this method does nothing.
Parameters
@NonNull AutofillId id

id of the node that has been removed.

notifyViewTextChanged

Added in 1.11.0
public void notifyViewTextChanged(@NonNull AutofillId id, @Nullable CharSequence text)

Notifies the Intelligence Service that the value of a text node has been changed.

Compatibility behavior:

  • SDK 29 and above, this method matches platform behavior.
  • SDK 28 and below, this method does nothing.
Parameters
@NonNull AutofillId id

of the node.

@Nullable CharSequence text

new text.

notifyViewsAppeared

Added in 1.11.0
public void notifyViewsAppeared(@NonNull List<ViewStructure> appearedNodes)

Notifies the Content Capture Service that a list of nodes has appeared in the view structure.

Typically called manually by views that handle their own virtual view hierarchy.

Compatibility behavior:

  • SDK 34 and above, this method matches platform behavior.
  • SDK 29 through 33, this method is a best-effort to match platform behavior, by wrapping the virtual children with a pair of special view appeared events.
  • SDK 28 and below, this method does nothing.
Parameters
@NonNull List<ViewStructure> appearedNodes

nodes that have appeared. Each element represents a view node that has been added to the view structure. The order of the elements is important, which should be preserved as the attached order of when the node is attached to the virtual view hierarchy.

notifyViewsDisappeared

Added in 1.11.0
public void notifyViewsDisappeared(@NonNull long[] virtualIds)

Notifies the Content Capture Service that many nodes has been removed from a virtual view structure.

Should only be called by views that handle their own virtual view hierarchy.

Compatibility behavior:

  • SDK 34 and above, this method matches platform behavior.
  • SDK 29 through 33, this method is a best-effort to match platform behavior, by wrapping the virtual children with a pair of special view appeared events.
  • SDK 28 and below, this method does nothing.
Parameters
@NonNull long[] virtualIds

ids of the virtual children.

toContentCaptureSession

Added in 1.11.0
@RequiresApi(value = 29)
public @NonNull ContentCaptureSession toContentCaptureSession()

Provides the ContentCaptureSession represented by this object.

This method is not supported on devices running SDK <29 since the platform class will not be available.

Returns
@NonNull ContentCaptureSession

platform class object

toContentCaptureSessionCompat

Added in 1.11.0
@RequiresApi(value = 29)
public static @NonNull ContentCaptureSessionCompat toContentCaptureSessionCompat(
    @NonNull ContentCaptureSession contentCaptureSession,
    @NonNull View host
)

Provides a backward-compatible wrapper for ContentCaptureSession.

This method is not supported on devices running SDK <29 since the platform class will not be available.

Parameters
@NonNull ContentCaptureSession contentCaptureSession

platform class to wrap

@NonNull View host

view hosting the session.

Returns
@NonNull ContentCaptureSessionCompat

wrapped class