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