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