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
17package android.view;
18
19
20import android.annotation.StringRes;
21import android.graphics.Rect;
22
23/**
24 * Represents a contextual mode of the user interface. Action modes can be used to provide
25 * alternative interaction modes and replace parts of the normal UI until finished.
26 * Examples of good action modes include text selection and contextual actions.
27 * <div class="special reference">
28 * <h3>Developer Guides</h3>
29 * <p>For information about how to provide contextual actions with {@code ActionMode},
30 * read the <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menus</a>
31 * developer guide.</p>
32 * </div>
33 */
34public abstract class ActionMode {
35
36    /**
37     * The action mode is treated as a Primary mode. This is the default.
38     * Use with {@link #setType}.
39     */
40    public static final int TYPE_PRIMARY = 0;
41    /**
42     * The action mode is treated as a Floating Toolbar.
43     * Use with {@link #setType}.
44     */
45    public static final int TYPE_FLOATING = 1;
46
47    /**
48     * Default value to hide the action mode for
49     * {@link ViewConfiguration#getDefaultActionModeHideDuration()}.
50     */
51    public static final int DEFAULT_HIDE_DURATION = -1;
52
53    private Object mTag;
54    private boolean mTitleOptionalHint;
55    private int mType = TYPE_PRIMARY;
56
57    /**
58     * Set a tag object associated with this ActionMode.
59     *
60     * <p>Like the tag available to views, this allows applications to associate arbitrary
61     * data with an ActionMode for later reference.
62     *
63     * @param tag Tag to associate with this ActionMode
64     *
65     * @see #getTag()
66     */
67    public void setTag(Object tag) {
68        mTag = tag;
69    }
70
71    /**
72     * Retrieve the tag object associated with this ActionMode.
73     *
74     * <p>Like the tag available to views, this allows applications to associate arbitrary
75     * data with an ActionMode for later reference.
76     *
77     * @return Tag associated with this ActionMode
78     *
79     * @see #setTag(Object)
80     */
81    public Object getTag() {
82        return mTag;
83    }
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 title Title string to set
90     *
91     * @see #setTitle(int)
92     * @see #setCustomView(View)
93     */
94    public abstract void setTitle(CharSequence title);
95
96    /**
97     * Set the title 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 title
101     *
102     * @see #setTitle(CharSequence)
103     * @see #setCustomView(View)
104     */
105    public abstract void setTitle(@StringRes int resId);
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 subtitle Subtitle string to set
112     *
113     * @see #setSubtitle(int)
114     * @see #setCustomView(View)
115     */
116    public abstract void setSubtitle(CharSequence subtitle);
117
118    /**
119     * Set the subtitle of the action mode. This method will have no visible effect if
120     * a custom view has been set.
121     *
122     * @param resId Resource ID of a string to set as the subtitle
123     *
124     * @see #setSubtitle(CharSequence)
125     * @see #setCustomView(View)
126     */
127    public abstract void setSubtitle(@StringRes int resId);
128
129    /**
130     * Set whether or not the title/subtitle display for this action mode
131     * is optional.
132     *
133     * <p>In many cases the supplied title for an action mode is merely
134     * meant to add context and is not strictly required for the action
135     * mode to be useful. If the title is optional, the system may choose
136     * to hide the title entirely rather than truncate it due to a lack
137     * of available space.</p>
138     *
139     * <p>Note that this is merely a hint; the underlying implementation
140     * may choose to ignore this setting under some circumstances.</p>
141     *
142     * @param titleOptional true if the title only presents optional information.
143     */
144    public void setTitleOptionalHint(boolean titleOptional) {
145        mTitleOptionalHint = titleOptional;
146    }
147
148    /**
149     * @return true if this action mode has been given a hint to consider the
150     *         title/subtitle display to be optional.
151     *
152     * @see #setTitleOptionalHint(boolean)
153     * @see #isTitleOptional()
154     */
155    public boolean getTitleOptionalHint() {
156        return mTitleOptionalHint;
157    }
158
159    /**
160     * @return true if this action mode considers the title and subtitle fields
161     *         as optional. Optional titles may not be displayed to the user.
162     */
163    public boolean isTitleOptional() {
164        return false;
165    }
166
167    /**
168     * Set a custom view for this action mode. The custom view will take the place of
169     * the title and subtitle. Useful for things like search boxes.
170     *
171     * @param view Custom view to use in place of the title/subtitle.
172     *
173     * @see #setTitle(CharSequence)
174     * @see #setSubtitle(CharSequence)
175     */
176    public abstract void setCustomView(View view);
177
178    /**
179     * Set a type for this action mode. This will affect how the system renders the action mode if
180     * it has to.
181     *
182     * @param type One of {@link #TYPE_PRIMARY} or {@link #TYPE_FLOATING}.
183     */
184    public void setType(int type) {
185        mType = type;
186    }
187
188    /**
189     * Returns the type for this action mode.
190     *
191     * @return One of {@link #TYPE_PRIMARY} or {@link #TYPE_FLOATING}.
192     */
193    public int getType() {
194        return mType;
195    }
196
197    /**
198     * Invalidate the action mode and refresh menu content. The mode's
199     * {@link ActionMode.Callback} will have its
200     * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called.
201     * If it returns true the menu will be scanned for updated content and any relevant changes
202     * will be reflected to the user.
203     */
204    public abstract void invalidate();
205
206    /**
207     * Invalidate the content rect associated to this ActionMode. This only makes sense for
208     * action modes that support dynamic positioning on the screen, and provides a more efficient
209     * way to reposition it without invalidating the whole action mode.
210     *
211     * @see Callback2#onGetContentRect(ActionMode, View, Rect) .
212     */
213    public void invalidateContentRect() {}
214
215    /**
216     * Hide the action mode view from obstructing the content below for a short duration.
217     * This only makes sense for action modes that support dynamic positioning on the screen.
218     * If this method is called again before the hide duration expires, the later hide call will
219     * cancel the former and then take effect.
220     * NOTE that there is an internal limit to how long the mode can be hidden for. It's typically
221     * about a few seconds.
222     *
223     * @param duration The number of milliseconds to hide for.
224     * @see #DEFAULT_HIDE_DURATION
225     */
226    public void hide(long duration) {}
227
228    /**
229     * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will
230     * have its {@link Callback#onDestroyActionMode(ActionMode)} method called.
231     */
232    public abstract void finish();
233
234    /**
235     * Returns the menu of actions that this action mode presents.
236     * @return The action mode's menu.
237     */
238    public abstract Menu getMenu();
239
240    /**
241     * Returns the current title of this action mode.
242     * @return Title text
243     */
244    public abstract CharSequence getTitle();
245
246    /**
247     * Returns the current subtitle of this action mode.
248     * @return Subtitle text
249     */
250    public abstract CharSequence getSubtitle();
251
252    /**
253     * Returns the current custom view for this action mode.
254     * @return The current custom view
255     */
256    public abstract View getCustomView();
257
258    /**
259     * Returns a {@link MenuInflater} with the ActionMode's context.
260     */
261    public abstract MenuInflater getMenuInflater();
262
263    /**
264     * Called when the window containing the view that started this action mode gains or loses
265     * focus.
266     *
267     * @param hasWindowFocus True if the window containing the view that started this action mode
268     *        now has focus, false otherwise.
269     *
270     */
271    public void onWindowFocusChanged(boolean hasWindowFocus) {}
272
273    /**
274     * Returns whether the UI presenting this action mode can take focus or not.
275     * This is used by internal components within the framework that would otherwise
276     * present an action mode UI that requires focus, such as an EditText as a custom view.
277     *
278     * @return true if the UI used to show this action mode can take focus
279     * @hide Internal use only
280     */
281    public boolean isUiFocusable() {
282        return true;
283    }
284
285    /**
286     * Callback interface for action modes. Supplied to
287     * {@link View#startActionMode(Callback)}, a Callback
288     * configures and handles events raised by a user's interaction with an action mode.
289     *
290     * <p>An action mode's lifecycle is as follows:
291     * <ul>
292     * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial
293     * creation</li>
294     * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation
295     * and any time the {@link ActionMode} is invalidated</li>
296     * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a
297     * contextual action button is clicked</li>
298     * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode
299     * is closed</li>
300     * </ul>
301     */
302    public interface Callback {
303        /**
304         * Called when action mode is first created. The menu supplied will be used to
305         * generate action buttons for the action mode.
306         *
307         * @param mode ActionMode being created
308         * @param menu Menu used to populate action buttons
309         * @return true if the action mode should be created, false if entering this
310         *              mode should be aborted.
311         */
312        public boolean onCreateActionMode(ActionMode mode, Menu menu);
313
314        /**
315         * Called to refresh an action mode's action menu whenever it is invalidated.
316         *
317         * @param mode ActionMode being prepared
318         * @param menu Menu used to populate action buttons
319         * @return true if the menu or action mode was updated, false otherwise.
320         */
321        public boolean onPrepareActionMode(ActionMode mode, Menu menu);
322
323        /**
324         * Called to report a user click on an action button.
325         *
326         * @param mode The current ActionMode
327         * @param item The item that was clicked
328         * @return true if this callback handled the event, false if the standard MenuItem
329         *          invocation should continue.
330         */
331        public boolean onActionItemClicked(ActionMode mode, MenuItem item);
332
333        /**
334         * Called when an action mode is about to be exited and destroyed.
335         *
336         * @param mode The current ActionMode being destroyed
337         */
338        public void onDestroyActionMode(ActionMode mode);
339    }
340
341    /**
342     * Extension of {@link ActionMode.Callback} to provide content rect information. This is
343     * required for ActionModes with dynamic positioning such as the ones with type
344     * {@link ActionMode#TYPE_FLOATING} to ensure the positioning doesn't obscure app content. If
345     * an app fails to provide a subclass of this class, a default implementation will be used.
346     */
347    public static abstract class Callback2 implements ActionMode.Callback {
348
349        /**
350         * Called when an ActionMode needs to be positioned on screen, potentially occluding view
351         * content. Note this may be called on a per-frame basis.
352         *
353         * @param mode The ActionMode that requires positioning.
354         * @param view The View that originated the ActionMode, in whose coordinates the Rect should
355         *          be provided.
356         * @param outRect The Rect to be populated with the content position. Use this to specify
357         *          where the content in your app lives within the given view. This will be used
358         *          to avoid occluding the given content Rect with the created ActionMode.
359         */
360        public void onGetContentRect(ActionMode mode, View view, Rect outRect) {
361            if (view != null) {
362                outRect.set(0, 0, view.getWidth(), view.getHeight());
363            } else {
364                outRect.set(0, 0, 0, 0);
365            }
366        }
367
368    }
369}
370