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