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