1 // Copyright 2018 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 package org.chromium.content_public.browser;
6 
7 import android.content.Intent;
8 import android.view.ActionMode;
9 import android.view.textclassifier.TextClassifier;
10 
11 import org.chromium.content.browser.selection.SelectionPopupControllerImpl;
12 import org.chromium.ui.base.WindowAndroid;
13 
14 /**
15  * An interface that handles input-related web content selection UI like action mode
16  * and paste popup view. It wraps an {@link ActionMode} created by the associated view,
17  * providing modified interaction with it.
18  *
19  * Embedders can use {@link ActionModeCallbackHelper} provided by the implementation of
20  * this interface to create {@link ActionMode.Callback} instance and configure the selection
21  * action mode tasks to their requirements.
22  */
23 public interface SelectionPopupController {
24     // User action of clicking on the Share option within the selection UI.
25     static final String UMA_MOBILE_ACTION_MODE_SHARE = "MobileActionMode.Share";
26 
27     /**
28      * @param webContents {@link WebContents} object.
29      * @return {@link SelectionPopupController} object used for the give WebContents.
30      *         {@code null} if not available.
31      */
fromWebContents(WebContents webContents)32     static SelectionPopupController fromWebContents(WebContents webContents) {
33         return SelectionPopupControllerImpl.fromWebContents(webContents);
34     }
35 
36     /**
37      * Makes {@link SelectionPopupcontroller} only use the WebContents context when inflating menus.
38      */
setMustUseWebContentsContext()39     static void setMustUseWebContentsContext() {
40         SelectionPopupControllerImpl.setMustUseWebContentsContext();
41     }
42 
43     /**
44      * Makes {@link SelectionPopupcontroller} to use the readback view from {@link WindowAndroid}
45      */
setShouldGetReadbackViewFromWindowAndroid()46     static void setShouldGetReadbackViewFromWindowAndroid() {
47         SelectionPopupControllerImpl.setShouldGetReadbackViewFromWindowAndroid();
48     }
49 
50     /**
51      * Set {@link ActionMode.Callback} used by {@link SelectionPopupController}.
52      * @param callback ActionMode.Callback instance.
53      */
setActionModeCallback(ActionMode.Callback callback)54     void setActionModeCallback(ActionMode.Callback callback);
55 
56     /**
57      * Set {@link ActionMode.Callback} used by {@link SelectionPopupController} when no text is
58      * selected.
59      * @param callback ActionMode.Callback instance.
60      */
setNonSelectionActionModeCallback(ActionMode.Callback callback)61     void setNonSelectionActionModeCallback(ActionMode.Callback callback);
62 
63     /**
64      * @return {@link SelectionClient.ResultCallback} instance.
65      */
getResultCallback()66     SelectionClient.ResultCallback getResultCallback();
67 
68     /**
69      * @return The selected text (empty if no text selected).
70      */
getSelectedText()71     String getSelectedText();
72 
73     /**
74      * @return Whether the current focused node is editable.
75      */
isFocusedNodeEditable()76     boolean isFocusedNodeEditable();
77 
78     /**
79      * @return Whether the page has an active, touch-controlled selection region.
80      */
hasSelection()81     boolean hasSelection();
82 
83     /**
84      * Hide action mode and put into destroyed state.
85      */
destroySelectActionMode()86     void destroySelectActionMode();
87 
isSelectActionBarShowing()88     boolean isSelectActionBarShowing();
89 
90     /**
91      * @return {@link ActionModeCallbackHelper} object.
92      */
getActionModeCallbackHelper()93     ActionModeCallbackHelper getActionModeCallbackHelper();
94 
95     /**
96      * Clears the current text selection. Note that we will try to move cursor to selection
97      * end if applicable.
98      */
clearSelection()99     void clearSelection();
100 
101     /**
102      * Called when the processed text is replied from an activity that supports
103      * Intent.ACTION_PROCESS_TEXT.
104      * @param resultCode the code that indicates if the activity successfully processed the text
105      * @param data the reply that contains the processed text.
106      */
onReceivedProcessTextResult(int resultCode, Intent data)107     void onReceivedProcessTextResult(int resultCode, Intent data);
108 
109     /** Sets the given {@link SelectionClient} in the selection popup controller. */
setSelectionClient(SelectionClient selectionClient)110     void setSelectionClient(SelectionClient selectionClient);
111 
112     /**
113      * Sets TextClassifier for Smart Text selection.
114      */
setTextClassifier(TextClassifier textClassifier)115     void setTextClassifier(TextClassifier textClassifier);
116 
117     /**
118      * Returns TextClassifier that is used for Smart Text selection. If the custom classifier
119      * has been set with setTextClassifier, returns that object, otherwise returns the system
120      * classifier.
121      */
getTextClassifier()122     TextClassifier getTextClassifier();
123 
124     /**
125      * Returns the TextClassifier which has been set with setTextClassifier(), or null.
126      */
getCustomTextClassifier()127     TextClassifier getCustomTextClassifier();
128 
129     /**
130      * Set the flag indicating where the selection is preserved the next time the view loses focus.
131      * @param preserve {@code true} if the selection needs to be preserved.
132      */
setPreserveSelectionOnNextLossOfFocus(boolean preserve)133     void setPreserveSelectionOnNextLossOfFocus(boolean preserve);
134 
135     /**
136      * Update the text selection UI depending on the focus of the page. This will hide the selection
137      * handles and selection popups if focus is lost.
138      * TODO(mdjones): This was added as a temporary measure to hide text UI while Reader Mode or
139      * Contextual Search are showing. This should be removed in favor of proper focusing of the
140      * panel's WebContents (which is currently not being added to the view hierarchy).
141      * @param focused If the WebContents currently has focus.
142      */
updateTextSelectionUI(boolean focused)143     void updateTextSelectionUI(boolean focused);
144 }
145