Update javadoc for UiTranslation functions.
1. Provide more detailed information for UiTranslationManager.
2. Clarify the difference for VTC#onClearTranslation and
VTC#onHideTranslation.
Bug: 178044703
Test: n/a. Change javadoc not change code.
Change-Id: I4b2ef1a6c39c3bbbb85d0dcda519d286f10deb25
diff --git a/core/java/android/view/translation/UiTranslationManager.java b/core/java/android/view/translation/UiTranslationManager.java
index b9ed32c..3012e93 100644
--- a/core/java/android/view/translation/UiTranslationManager.java
+++ b/core/java/android/view/translation/UiTranslationManager.java
@@ -33,6 +33,7 @@
import android.util.Log;
import android.view.View;
import android.view.autofill.AutofillId;
+import android.widget.TextView;
import com.android.internal.annotations.GuardedBy;
@@ -42,11 +43,50 @@
import java.util.Map;
import java.util.Objects;
import java.util.concurrent.Executor;
+import java.util.function.Consumer;
-// TODO(b/178044703): Describe what UI Translation is.
/**
- * The {@link UiTranslationManager} class provides ways for apps to use the ui translation
+ * <p>The {@link UiTranslationManager} class provides ways for apps to use the ui translation
* function in framework.
+ *
+ * <p> The UI translation provides ways for apps to support inline translation for the views. For
+ * example the system supports text translation for {@link TextView}. To support UI translation for
+ * your views, you should override the following methods to provide the content to be translated
+ * and deal with the translated result. Here is an example for {@link TextView}-like views:
+ *
+ * <pre><code>
+ * public class MyTextView extends View {
+ * public MyTextView(...) {
+ * // implements how to show the translated result in your View in
+ * // ViewTranslationCallback and set it by setViewTranslationCallback()
+ * setViewTranslationCallback(new MyViewTranslationCallback());
+ * }
+ *
+ * public void onCreateViewTranslationRequest(int[] supportedFormats,
+ * Consumer<ViewTranslationRequest> requestsCollector) {
+ * // collect the information that needs to be translated
+ * ViewTranslationRequest.Builder requestBuilder =
+ * new ViewTranslationRequest.Builder(getAutofillId());
+ * requestBuilder.setValue(ViewTranslationRequest.ID_TEXT,
+ * TranslationRequestValue.forText(etText()));
+ * requestsCollector.accept(requestBuilder.build());
+ * }
+ *
+ * public void onProvideContentCaptureStructure(
+ * ViewStructure structure, int flags) {
+ * // set ViewTranslationResponse
+ * super.onViewTranslationResponse(response);
+ * }
+ * }
+ * </code></pre>
+ *
+ * <p>If your view provides its own virtual hierarchy (for example, if it's a browser that draws the
+ * HTML using {@link android.graphics.Canvas} or native libraries in a different render process),
+ * you must override {@link View#onCreateVirtualViewTranslationRequests(long[], int[], Consumer)} to
+ * provide the content to be translated and implement
+ * {@link View#onVirtualViewTranslationResponses(android.util.LongSparseArray)} for the translated
+ * result. You also need to implement {@link android.view.translation.ViewTranslationCallback} to
+ * handle the translated information show or hide in your {@link View}.
*/
public final class UiTranslationManager {
@@ -248,14 +288,14 @@
}
}
- // TODO(b/178044703): Fix the View API link when it becomes public.
/**
* Register for notifications of UI Translation state changes on the foreground activity. This
* is available to the owning application itself and also the current input method.
* <p>
* The application whose UI is being translated can use this to customize the UI Translation
* behavior in ways that aren't made easy by methods like
- * View#onCreateTranslationRequest().
+ * {@link View#onCreateViewTranslationRequest(int[], Consumer)}.
+ *
* <p>
* Input methods can use this to offer complementary features to UI Translation; for example,
* enabling outgoing message translation when the system is translating incoming messages in a
diff --git a/core/java/android/view/translation/ViewTranslationCallback.java b/core/java/android/view/translation/ViewTranslationCallback.java
index 6efd621..a075662 100644
--- a/core/java/android/view/translation/ViewTranslationCallback.java
+++ b/core/java/android/view/translation/ViewTranslationCallback.java
@@ -19,9 +19,17 @@
import android.annotation.NonNull;
import android.annotation.UiThread;
import android.view.View;
+import android.view.contentcapture.ContentCaptureSession;
/**
- * Callback for handling the translated information show or hide in the {@link View}.
+ * <p> Callback for handling the translated information show or hide in the {@link View}.
+ *
+ * <p> When the platform intelligence starts translation of an app's ui, the system will call
+ * {@link View#dispatchCreateViewTranslationRequest} to collect the {@link ViewTranslationRequest}s
+ * for translation purpose by traversing the hierarchy then send to translation service. After
+ * receiving the {@link ViewTranslationResponse}, the system will call
+ * {@link ViewTranslationCallback#onShowTranslation(View)} to show the translated information for
+ * the {@link View}.
*/
@UiThread
public interface ViewTranslationCallback {
@@ -33,13 +41,19 @@
* method will not be called before {@link View#onViewTranslationResponse} or
* {@link View#onVirtualViewTranslationResponses}.
*
+ * <p> NOTE: For TextView implementation, {@link ContentCaptureSession#notifyViewTextChanged}
+ * shouldn't be called with the translated text, simply calling setText() here will trigger the
+ * method. You should either override {@code View#onProvideContentCaptureStructure()} to report
+ * the original text instead of the translated text or use a different approach to display the
+ * translated text.
+ *
* See {@link View#onViewTranslationResponse} for how to get the translated information.
*
* @return {@code true} if the View handles showing the translation.
*/
boolean onShowTranslation(@NonNull View view);
/**
- * Called when the user wants to show the original text instead of the translated text. This
+ * Called when user wants to view the original content instead of the translated content. This
* method will not be called before {@link View#onViewTranslationResponse} or
* {@link View#onViewTranslationResponse}.
*
@@ -47,7 +61,8 @@
*/
boolean onHideTranslation(@NonNull View view);
/**
- * Called when the user finish the Ui translation and no longer to show the translated text.
+ * Called when the translation state is no longer needed. It should restore the original content
+ * and clear all saved states.
*
* @return {@code true} if the View handles clearing the translation.
*/