Merge "Update javadoc for UiTranslation functions." into sc-dev am: eba42651

import android.util.Log;

import android.util.Log;

import android.view.View;

import android.view.View;

import android.view.autofill.AutofillId;

import android.view.autofill.AutofillId;

import android.widget.TextView;

import com.android.internal.annotations.GuardedBy;

import com.android.internal.annotations.GuardedBy;

import java.util.Map;

import java.util.Map;

import java.util.Objects;

import java.util.Objects;

import java.util.concurrent.Executor;

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.

 * 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 {

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

     * 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.

     * is available to the owning application itself and also the current input method.

     * <p>

     * <p>

     * The application whose UI is being translated can use this to customize the UI Translation

     * 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

     * behavior in ways that aren't made easy by methods like

     * View#onCreateTranslationRequest().

     * {@link View#onCreateViewTranslationRequest(int[], Consumer)}.

     *

     * <p>

     * <p>

     * Input methods can use this to offer complementary features to UI Translation; for example,

     * 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

     * enabling outgoing message translation when the system is translating incoming messages in a

import android.annotation.NonNull;

import android.annotation.NonNull;

import android.annotation.UiThread;

import android.annotation.UiThread;

import android.view.View;

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

@UiThread

public interface ViewTranslationCallback {

public interface ViewTranslationCallback {

     * method will not be called before {@link View#onViewTranslationResponse} or

     * method will not be called before {@link View#onViewTranslationResponse} or

     * {@link View#onVirtualViewTranslationResponses}.

     * {@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.

     * See {@link View#onViewTranslationResponse} for how to get the translated information.

     *

     *

     * @return {@code true} if the View handles showing the translation.

     * @return {@code true} if the View handles showing the translation.

     */

     */

    boolean onShowTranslation(@NonNull View view);

    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

     * method will not be called before {@link View#onViewTranslationResponse} or

     * {@link View#onViewTranslationResponse}.

     * {@link View#onViewTranslationResponse}.

     *

     *

     */

     */

    boolean onHideTranslation(@NonNull View view);

    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.

     * @return {@code true} if the View handles clearing the translation.

     */

     */