2 * Copyright (C) 2010 The Android Open Source Project
\r
4 * Licensed under the Apache License, Version 2.0 (the "License");
\r
5 * you may not use this file except in compliance with the License.
\r
6 * You may obtain a copy of the License at
\r
8 * http://www.apache.org/licenses/LICENSE-2.0
\r
10 * Unless required by applicable law or agreed to in writing, software
\r
11 * distributed under the License is distributed on an "AS IS" BASIS,
\r
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
13 * See the License for the specific language governing permissions and
\r
14 * limitations under the License.
\r
17 package com.actionbarsherlock.view;
\r
19 import android.view.View;
\r
23 * Represents a contextual mode of the user interface. Action modes can be used for
\r
24 * modal interactions with content and replace parts of the normal UI until finished.
\r
25 * Examples of good action modes include selection modes, search, content editing, etc.
\r
27 public abstract class ActionMode {
\r
28 private Object mTag;
\r
31 * Set a tag object associated with this ActionMode.
\r
33 * <p>Like the tag available to views, this allows applications to associate arbitrary
\r
34 * data with an ActionMode for later reference.
\r
36 * @param tag Tag to associate with this ActionMode
\r
40 public void setTag(Object tag) {
\r
45 * Retrieve the tag object associated with this ActionMode.
\r
47 * <p>Like the tag available to views, this allows applications to associate arbitrary
\r
48 * data with an ActionMode for later reference.
\r
50 * @return Tag associated with this ActionMode
\r
52 * @see #setTag(Object)
\r
54 public Object getTag() {
\r
59 * Set the title of the action mode. This method will have no visible effect if
\r
60 * a custom view has been set.
\r
62 * @param title Title string to set
\r
64 * @see #setTitle(int)
\r
65 * @see #setCustomView(View)
\r
67 public abstract void setTitle(CharSequence title);
\r
70 * Set the title of the action mode. This method will have no visible effect if
\r
71 * a custom view has been set.
\r
73 * @param resId Resource ID of a string to set as the title
\r
75 * @see #setTitle(CharSequence)
\r
76 * @see #setCustomView(View)
\r
78 public abstract void setTitle(int resId);
\r
81 * Set the subtitle of the action mode. This method will have no visible effect if
\r
82 * a custom view has been set.
\r
84 * @param subtitle Subtitle string to set
\r
86 * @see #setSubtitle(int)
\r
87 * @see #setCustomView(View)
\r
89 public abstract void setSubtitle(CharSequence subtitle);
\r
92 * Set the subtitle of the action mode. This method will have no visible effect if
\r
93 * a custom view has been set.
\r
95 * @param resId Resource ID of a string to set as the subtitle
\r
97 * @see #setSubtitle(CharSequence)
\r
98 * @see #setCustomView(View)
\r
100 public abstract void setSubtitle(int resId);
\r
103 * Set a custom view for this action mode. The custom view will take the place of
\r
104 * the title and subtitle. Useful for things like search boxes.
\r
106 * @param view Custom view to use in place of the title/subtitle.
\r
108 * @see #setTitle(CharSequence)
\r
109 * @see #setSubtitle(CharSequence)
\r
111 public abstract void setCustomView(View view);
\r
114 * Invalidate the action mode and refresh menu content. The mode's
\r
115 * {@link ActionMode.Callback} will have its
\r
116 * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called.
\r
117 * If it returns true the menu will be scanned for updated content and any relevant changes
\r
118 * will be reflected to the user.
\r
120 public abstract void invalidate();
\r
123 * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will
\r
124 * have its {@link Callback#onDestroyActionMode(ActionMode)} method called.
\r
126 public abstract void finish();
\r
129 * Returns the menu of actions that this action mode presents.
\r
130 * @return The action mode's menu.
\r
132 public abstract Menu getMenu();
\r
135 * Returns the current title of this action mode.
\r
136 * @return Title text
\r
138 public abstract CharSequence getTitle();
\r
141 * Returns the current subtitle of this action mode.
\r
142 * @return Subtitle text
\r
144 public abstract CharSequence getSubtitle();
\r
147 * Returns the current custom view for this action mode.
\r
148 * @return The current custom view
\r
150 public abstract View getCustomView();
\r
153 * Returns a {@link MenuInflater} with the ActionMode's context.
\r
155 public abstract MenuInflater getMenuInflater();
\r
158 * Returns whether the UI presenting this action mode can take focus or not.
\r
159 * This is used by internal components within the framework that would otherwise
\r
160 * present an action mode UI that requires focus, such as an EditText as a custom view.
\r
162 * @return true if the UI used to show this action mode can take focus
\r
163 * @hide Internal use only
\r
165 public boolean isUiFocusable() {
\r
170 * Callback interface for action modes. Supplied to
\r
171 * {@link View#startActionMode(Callback)}, a Callback
\r
172 * configures and handles events raised by a user's interaction with an action mode.
\r
174 * <p>An action mode's lifecycle is as follows:
\r
176 * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial
\r
178 * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation
\r
179 * and any time the {@link ActionMode} is invalidated</li>
\r
180 * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a
\r
181 * contextual action button is clicked</li>
\r
182 * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode
\r
186 public interface Callback {
\r
188 * Called when action mode is first created. The menu supplied will be used to
\r
189 * generate action buttons for the action mode.
\r
191 * @param mode ActionMode being created
\r
192 * @param menu Menu used to populate action buttons
\r
193 * @return true if the action mode should be created, false if entering this
\r
194 * mode should be aborted.
\r
196 public boolean onCreateActionMode(ActionMode mode, Menu menu);
\r
199 * Called to refresh an action mode's action menu whenever it is invalidated.
\r
201 * @param mode ActionMode being prepared
\r
202 * @param menu Menu used to populate action buttons
\r
203 * @return true if the menu or action mode was updated, false otherwise.
\r
205 public boolean onPrepareActionMode(ActionMode mode, Menu menu);
\r
208 * Called to report a user click on an action button.
\r
210 * @param mode The current ActionMode
\r
211 * @param item The item that was clicked
\r
212 * @return true if this callback handled the event, false if the standard MenuItem
\r
213 * invocation should continue.
\r
215 public boolean onActionItemClicked(ActionMode mode, MenuItem item);
\r
218 * Called when an action mode is about to be exited and destroyed.
\r
220 * @param mode The current ActionMode being destroyed
\r
222 public void onDestroyActionMode(ActionMode mode);
\r