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