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 17 package android.support.v7.view; 18 19 import android.view.Menu; 20 import android.view.MenuInflater; 21 import android.view.MenuItem; 22 import 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 */ 37 public 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
