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
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 */
31public 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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
175    public abstract Menu getMenu();
176
177    /**
178     * Returns the current title of this action mode.
179     * @return Title text
180     */
181    public abstract CharSequence getTitle();
182
183    /**
184     * Returns the current subtitle of this action mode.
185     * @return Subtitle text
186     */
187    public abstract CharSequence getSubtitle();
188
189    /**
190     * Returns the current custom view for this action mode.
191     * @return The current custom view
192     */
193    public abstract View getCustomView();
194
195    /**
196     * Returns a {@link MenuInflater} with the ActionMode's context.
197     */
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     */
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         */
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         */
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         */
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         */
265        public void onDestroyActionMode(ActionMode mode);
266    }
267}