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