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