1 /*
2  * Copyright (C) 2010 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package androidx.appcompat.view;
18 
19 import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
20 
21 import android.view.Menu;
22 import android.view.MenuInflater;
23 import android.view.MenuItem;
24 import android.view.View;
25 
26 import androidx.annotation.RestrictTo;
27 
28 /**
29  * Represents a contextual mode of the user interface. Action modes can be used to provide
30  * alternative interaction modes and replace parts of the normal UI until finished.
31  * Examples of good action modes include text selection and contextual actions.
32  * <div class="special reference">
33  *
34  * <h3>Developer Guides</h3>
35  * <p>For information about how to provide contextual actions with {@code ActionMode},
36  * read the <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menus</a>
37  * developer guide.</p>
38  *
39  * </div>
40  */
41 public abstract class ActionMode {
42 
43     private Object mTag;
44     private boolean mTitleOptionalHint;
45 
46     /**
47      * Set a tag object associated with this ActionMode.
48      *
49      * <p>Like the tag available to views, this allows applications to associate arbitrary
50      * data with an ActionMode for later reference.
51      *
52      * @param tag Tag to associate with this ActionMode
53      *
54      * @see #getTag()
55      */
setTag(Object tag)56     public void setTag(Object tag) {
57         mTag = tag;
58     }
59 
60     /**
61      * Retrieve the tag object associated with this ActionMode.
62      *
63      * <p>Like the tag available to views, this allows applications to associate arbitrary
64      * data with an ActionMode for later reference.
65      *
66      * @return Tag associated with this ActionMode
67      *
68      * @see #setTag(Object)
69      */
getTag()70     public Object getTag() {
71         return mTag;
72     }
73 
74     /**
75      * Set the title of the action mode. This method will have no visible effect if
76      * a custom view has been set.
77      *
78      * @param title Title string to set
79      *
80      * @see #setTitle(int)
81      * @see #setCustomView(View)
82      */
setTitle(CharSequence title)83     public abstract void setTitle(CharSequence title);
84 
85     /**
86      * Set the title of the action mode. This method will have no visible effect if
87      * a custom view has been set.
88      *
89      * @param resId Resource ID of a string to set as the title
90      *
91      * @see #setTitle(CharSequence)
92      * @see #setCustomView(View)
93      */
setTitle(int resId)94     public abstract void setTitle(int resId);
95 
96     /**
97      * Set the subtitle of the action mode. This method will have no visible effect if
98      * a custom view has been set.
99      *
100      * @param subtitle Subtitle string to set
101      *
102      * @see #setSubtitle(int)
103      * @see #setCustomView(View)
104      */
setSubtitle(CharSequence subtitle)105     public abstract void setSubtitle(CharSequence subtitle);
106 
107     /**
108      * Set the subtitle of the action mode. This method will have no visible effect if
109      * a custom view has been set.
110      *
111      * @param resId Resource ID of a string to set as the subtitle
112      *
113      * @see #setSubtitle(CharSequence)
114      * @see #setCustomView(View)
115      */
setSubtitle(int resId)116     public abstract void setSubtitle(int resId);
117 
118     /**
119      * Set whether or not the title/subtitle display for this action mode
120      * is optional.
121      *
122      * <p>In many cases the supplied title for an action mode is merely
123      * meant to add context and is not strictly required for the action
124      * mode to be useful. If the title is optional, the system may choose
125      * to hide the title entirely rather than truncate it due to a lack
126      * of available space.</p>
127      *
128      * <p>Note that this is merely a hint; the underlying implementation
129      * may choose to ignore this setting under some circumstances.</p>
130      *
131      * @param titleOptional true if the title only presents optional information.
132      */
setTitleOptionalHint(boolean titleOptional)133     public void setTitleOptionalHint(boolean titleOptional) {
134         mTitleOptionalHint = titleOptional;
135     }
136 
137     /**
138      * @return true if this action mode has been given a hint to consider the
139      *         title/subtitle display to be optional.
140      *
141      * @see #setTitleOptionalHint(boolean)
142      * @see #isTitleOptional()
143      */
getTitleOptionalHint()144     public boolean getTitleOptionalHint() {
145         return mTitleOptionalHint;
146     }
147 
148     /**
149      * @return true if this action mode considers the title and subtitle fields
150      *         as optional. Optional titles may not be displayed to the user.
151      */
isTitleOptional()152     public boolean isTitleOptional() {
153         return false;
154     }
155 
156     /**
157      * Set a custom view for this action mode. The custom view will take the place of
158      * the title and subtitle. Useful for things like search boxes.
159      *
160      * @param view Custom view to use in place of the title/subtitle.
161      *
162      * @see #setTitle(CharSequence)
163      * @see #setSubtitle(CharSequence)
164      */
setCustomView(View view)165     public abstract void setCustomView(View view);
166 
167     /**
168      * Invalidate the action mode and refresh menu content. The mode's
169      * {@link ActionMode.Callback} will have its
170      * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called.
171      * If it returns true the menu will be scanned for updated content and any relevant changes
172      * will be reflected to the user.
173      */
invalidate()174     public abstract void invalidate();
175 
176     /**
177      * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will
178      * have its {@link Callback#onDestroyActionMode(ActionMode)} method called.
179      */
finish()180     public abstract void finish();
181 
182     /**
183      * Returns the menu of actions that this action mode presents.
184      *
185      * @return The action mode's menu.
186      */
getMenu()187     public abstract Menu getMenu();
188 
189     /**
190      * Returns the current title of this action mode.
191      *
192      * @return Title text
193      */
getTitle()194     public abstract CharSequence getTitle();
195 
196     /**
197      * Returns the current subtitle of this action mode.
198      *
199      * @return Subtitle text
200      */
getSubtitle()201     public abstract CharSequence getSubtitle();
202 
203     /**
204      * Returns the current custom view for this action mode.
205      *
206      * @return The current custom view
207      */
getCustomView()208     public abstract View getCustomView();
209 
210     /**
211      * Returns a {@link MenuInflater} with the ActionMode's context.
212      */
getMenuInflater()213     public abstract MenuInflater getMenuInflater();
214 
215     /**
216      * Returns whether the UI presenting this action mode can take focus or not.
217      * This is used by internal components within the framework that would otherwise
218      * present an action mode UI that requires focus, such as an EditText as a custom view.
219      *
220      * @return true if the UI used to show this action mode can take focus
221      * @hide Internal use only
222      */
223     @RestrictTo(LIBRARY_GROUP)
isUiFocusable()224     public boolean isUiFocusable() {
225         return true;
226     }
227 
228     /**
229      * Callback interface for action modes. Supplied to
230      * {@link androidx.appcompat.app.AppCompatDelegate#startSupportActionMode(Callback)} (Callback)},
231      * a Callback configures and handles events raised by a user's interaction with an action mode.
232      *
233      * <p>An action mode's lifecycle is as follows:
234      * <ul>
235      * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial
236      * creation</li>
237      * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation
238      * and any time the {@link ActionMode} is invalidated</li>
239      * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a
240      * contextual action button is clicked</li>
241      * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode
242      * is closed</li>
243      * </ul>
244      */
245     public interface Callback {
246 
247         /**
248          * Called when action mode is first created. The menu supplied will be used to
249          * generate action buttons for the action mode.
250          *
251          * @param mode ActionMode being created
252          * @param menu Menu used to populate action buttons
253          * @return true if the action mode should be created, false if entering this
254          *              mode should be aborted.
255          */
onCreateActionMode(ActionMode mode, Menu menu)256         public boolean onCreateActionMode(ActionMode mode, Menu menu);
257 
258         /**
259          * Called to refresh an action mode's action menu whenever it is invalidated.
260          *
261          * @param mode ActionMode being prepared
262          * @param menu Menu used to populate action buttons
263          * @return true if the menu or action mode was updated, false otherwise.
264          */
onPrepareActionMode(ActionMode mode, Menu menu)265         public boolean onPrepareActionMode(ActionMode mode, Menu menu);
266 
267         /**
268          * Called to report a user click on an action button.
269          *
270          * @param mode The current ActionMode
271          * @param item The item that was clicked
272          * @return true if this callback handled the event, false if the standard MenuItem
273          *         invocation should continue.
274          */
onActionItemClicked(ActionMode mode, MenuItem item)275         public boolean onActionItemClicked(ActionMode mode, MenuItem item);
276 
277         /**
278          * Called when an action mode is about to be exited and destroyed.
279          *
280          * @param mode The current ActionMode being destroyed
281          */
onDestroyActionMode(ActionMode mode)282         public void onDestroyActionMode(ActionMode mode);
283     }
284 }
285