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