ContentCaptureSessionCompat


class ContentCaptureSessionCompat


Helper for accessing features in ContentCaptureSession.

Summary

Public functions

Unit

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

AutofillId?
newAutofillId(virtualChildId: Long)

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

ViewStructureCompat?
newVirtualViewStructure(parentId: AutofillId, virtualId: Long)

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

Unit

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

Unit

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

Unit

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

Unit

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

Unit

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

ContentCaptureSession

Provides the ContentCaptureSession represented by this object.

java-static ContentCaptureSessionCompat
@RequiresApi(value = 29)
toContentCaptureSessionCompat(
    contentCaptureSession: ContentCaptureSession,
    host: View
)

Provides a backward-compatible wrapper for ContentCaptureSession.

Public functions

flush

fun flush(): Unit

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
fun newAutofillId(virtualChildId: Long): AutofillId?

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
virtualChildId: Long

id of the virtual child, relative to the parent.

Returns
AutofillId?

AutofillId for the virtual child

newVirtualViewStructure

Added in 1.11.0
fun newVirtualViewStructure(parentId: AutofillId, virtualId: Long): ViewStructureCompat?

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
parentId: AutofillId

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

virtualId: Long

id of the virtual child, relative to the parent.

Returns
ViewStructureCompat?

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

notifyViewAppeared

fun notifyViewAppeared(node: ViewStructure): Unit

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
node: ViewStructure

node that has been added.

notifyViewDisappeared

fun notifyViewDisappeared(id: AutofillId): Unit

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
id: AutofillId

id of the node that has been removed.

notifyViewTextChanged

Added in 1.11.0
fun notifyViewTextChanged(id: AutofillId, text: CharSequence?): Unit

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
id: AutofillId

of the node.

text: CharSequence?

new text.

notifyViewsAppeared

Added in 1.11.0
fun notifyViewsAppeared(appearedNodes: (Mutable)List<ViewStructure!>): Unit

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
appearedNodes: (Mutable)List<ViewStructure!>

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
fun notifyViewsDisappeared(virtualIds: LongArray<Long>): Unit

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
virtualIds: LongArray<Long>

ids of the virtual children.

toContentCaptureSession

Added in 1.11.0
@RequiresApi(value = 29)
fun toContentCaptureSession(): ContentCaptureSession

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
ContentCaptureSession

platform class object

toContentCaptureSessionCompat

Added in 1.11.0
@RequiresApi(value = 29)
java-static fun toContentCaptureSessionCompat(
    contentCaptureSession: ContentCaptureSession,
    host: View
): ContentCaptureSessionCompat

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
contentCaptureSession: ContentCaptureSession

platform class to wrap

host: View

view hosting the session.

Returns
ContentCaptureSessionCompat

wrapped class