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 for
22 * modal interactions with content and replace parts of the normal UI until finished.
23 * Examples of good action modes include selection modes, search, content editing, etc.
24 */
25public abstract class ActionMode {
26    private Object mTag;
27
28    /**
29     * Set a tag object associated with this ActionMode.
30     *
31     * <p>Like the tag available to views, this allows applications to associate arbitrary
32     * data with an ActionMode for later reference.
33     *
34     * @param tag Tag to associate with this ActionMode
35     *
36     * @see #getTag()
37     */
38    public void setTag(Object tag) {
39        mTag = tag;
40    }
41
42    /**
43     * Retrieve the 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     * @return Tag associated with this ActionMode
49     *
50     * @see #setTag(Object)
51     */
52    public Object getTag() {
53        return mTag;
54    }
55
56    /**
57     * Set the title of the action mode. This method will have no visible effect if
58     * a custom view has been set.
59     *
60     * @param title Title string to set
61     *
62     * @see #setTitle(int)
63     * @see #setCustomView(View)
64     */
65    public abstract void setTitle(CharSequence title);
66
67    /**
68     * Set the title of the action mode. This method will have no visible effect if
69     * a custom view has been set.
70     *
71     * @param resId Resource ID of a string to set as the title
72     *
73     * @see #setTitle(CharSequence)
74     * @see #setCustomView(View)
75     */
76    public abstract void setTitle(int resId);
77
78    /**
79     * Set the subtitle of the action mode. This method will have no visible effect if
80     * a custom view has been set.
81     *
82     * @param subtitle Subtitle string to set
83     *
84     * @see #setSubtitle(int)
85     * @see #setCustomView(View)
86     */
87    public abstract void setSubtitle(CharSequence subtitle);
88
89    /**
90     * Set the subtitle of the action mode. This method will have no visible effect if
91     * a custom view has been set.
92     *
93     * @param resId Resource ID of a string to set as the subtitle
94     *
95     * @see #setSubtitle(CharSequence)
96     * @see #setCustomView(View)
97     */
98    public abstract void setSubtitle(int resId);
99
100    /**
101     * Set a custom view for this action mode. The custom view will take the place of
102     * the title and subtitle. Useful for things like search boxes.
103     *
104     * @param view Custom view to use in place of the title/subtitle.
105     *
106     * @see #setTitle(CharSequence)
107     * @see #setSubtitle(CharSequence)
108     */
109    public abstract void setCustomView(View view);
110
111    /**
112     * Invalidate the action mode and refresh menu content. The mode's
113     * {@link ActionMode.Callback} will have its
114     * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called.
115     * If it returns true the menu will be scanned for updated content and any relevant changes
116     * will be reflected to the user.
117     */
118    public abstract void invalidate();
119
120    /**
121     * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will
122     * have its {@link Callback#onDestroyActionMode(ActionMode)} method called.
123     */
124    public abstract void finish();
125
126    /**
127     * Returns the menu of actions that this action mode presents.
128     * @return The action mode's menu.
129     */
130    public abstract Menu getMenu();
131
132    /**
133     * Returns the current title of this action mode.
134     * @return Title text
135     */
136    public abstract CharSequence getTitle();
137
138    /**
139     * Returns the current subtitle of this action mode.
140     * @return Subtitle text
141     */
142    public abstract CharSequence getSubtitle();
143
144    /**
145     * Returns the current custom view for this action mode.
146     * @return The current custom view
147     */
148    public abstract View getCustomView();
149
150    /**
151     * Returns a {@link MenuInflater} with the ActionMode's context.
152     */
153    public abstract MenuInflater getMenuInflater();
154
155    /**
156     * Returns whether the UI presenting this action mode can take focus or not.
157     * This is used by internal components within the framework that would otherwise
158     * present an action mode UI that requires focus, such as an EditText as a custom view.
159     *
160     * @return true if the UI used to show this action mode can take focus
161     * @hide Internal use only
162     */
163    public boolean isUiFocusable() {
164        return true;
165    }
166
167    /**
168     * Callback interface for action modes. Supplied to
169     * {@link View#startActionMode(Callback)}, a Callback
170     * configures and handles events raised by a user's interaction with an action mode.
171     *
172     * <p>An action mode's lifecycle is as follows:
173     * <ul>
174     * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial
175     * creation</li>
176     * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation
177     * and any time the {@link ActionMode} is invalidated</li>
178     * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a
179     * contextual action button is clicked</li>
180     * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode
181     * is closed</li>
182     * </ul>
183     */
184    public interface Callback {
185        /**
186         * Called when action mode is first created. The menu supplied will be used to
187         * generate action buttons for the action mode.
188         *
189         * @param mode ActionMode being created
190         * @param menu Menu used to populate action buttons
191         * @return true if the action mode should be created, false if entering this
192         *              mode should be aborted.
193         */
194        public boolean onCreateActionMode(ActionMode mode, Menu menu);
195
196        /**
197         * Called to refresh an action mode's action menu whenever it is invalidated.
198         *
199         * @param mode ActionMode being prepared
200         * @param menu Menu used to populate action buttons
201         * @return true if the menu or action mode was updated, false otherwise.
202         */
203        public boolean onPrepareActionMode(ActionMode mode, Menu menu);
204
205        /**
206         * Called to report a user click on an action button.
207         *
208         * @param mode The current ActionMode
209         * @param item The item that was clicked
210         * @return true if this callback handled the event, false if the standard MenuItem
211         *          invocation should continue.
212         */
213        public boolean onActionItemClicked(ActionMode mode, MenuItem item);
214
215        /**
216         * Called when an action mode is about to be exited and destroyed.
217         *
218         * @param mode The current ActionMode being destroyed
219         */
220        public void onDestroyActionMode(ActionMode mode);
221    }
222}