diff options
| -rw-r--r-- | core/java/android/view/translation/UiTranslationManager.java | 48 | ||||
| -rw-r--r-- | core/java/android/view/translation/ViewTranslationCallback.java | 21 |
2 files changed, 62 insertions, 7 deletions
diff --git a/core/java/android/view/translation/UiTranslationManager.java b/core/java/android/view/translation/UiTranslationManager.java index b9ed32ce248b..3012e9344a1b 100644 --- a/core/java/android/view/translation/UiTranslationManager.java +++ b/core/java/android/view/translation/UiTranslationManager.java @@ -33,6 +33,7 @@ import android.util.ArrayMap; 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.List; 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 @@ public final class UiTranslationManager { } } - // 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 6efd621c4caa..a0756622ca69 100644 --- a/core/java/android/view/translation/ViewTranslationCallback.java +++ b/core/java/android/view/translation/ViewTranslationCallback.java @@ -19,9 +19,17 @@ package android.view.translation; 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 @@ public interface ViewTranslationCallback { * 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 @@ public interface ViewTranslationCallback { */ 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. */ |