/* * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.view; /** * Represents a contextual mode of the user interface. Action modes can be used to provide * alternative interaction modes and replace parts of the normal UI until finished. * Examples of good action modes include text selection and contextual actions. *
For information about how to provide contextual actions with {@code ActionMode}, * read the Menus * developer guide.
*Like the tag available to views, this allows applications to associate arbitrary * data with an ActionMode for later reference. * * @param tag Tag to associate with this ActionMode * * @see #getTag() */ public void setTag(Object tag) { mTag = tag; } /** * Retrieve the tag object associated with this ActionMode. * *
Like the tag available to views, this allows applications to associate arbitrary * data with an ActionMode for later reference. * * @return Tag associated with this ActionMode * * @see #setTag(Object) */ public Object getTag() { return mTag; } /** * Set the title of the action mode. This method will have no visible effect if * a custom view has been set. * * @param title Title string to set * * @see #setTitle(int) * @see #setCustomView(View) */ public abstract void setTitle(CharSequence title); /** * Set the title of the action mode. This method will have no visible effect if * a custom view has been set. * * @param resId Resource ID of a string to set as the title * * @see #setTitle(CharSequence) * @see #setCustomView(View) */ public abstract void setTitle(int resId); /** * Set the subtitle of the action mode. This method will have no visible effect if * a custom view has been set. * * @param subtitle Subtitle string to set * * @see #setSubtitle(int) * @see #setCustomView(View) */ public abstract void setSubtitle(CharSequence subtitle); /** * Set the subtitle of the action mode. This method will have no visible effect if * a custom view has been set. * * @param resId Resource ID of a string to set as the subtitle * * @see #setSubtitle(CharSequence) * @see #setCustomView(View) */ public abstract void setSubtitle(int resId); /** * Set whether or not the title/subtitle display for this action mode * is optional. * *
In many cases the supplied title for an action mode is merely * meant to add context and is not strictly required for the action * mode to be useful. If the title is optional, the system may choose * to hide the title entirely rather than truncate it due to a lack * of available space.
* *Note that this is merely a hint; the underlying implementation * may choose to ignore this setting under some circumstances.
* * @param titleOptional true if the title only presents optional information. */ public void setTitleOptionalHint(boolean titleOptional) { mTitleOptionalHint = titleOptional; } /** * @return true if this action mode has been given a hint to consider the * title/subtitle display to be optional. * * @see #setTitleOptionalHint(boolean) * @see #isTitleOptional() */ public boolean getTitleOptionalHint() { return mTitleOptionalHint; } /** * @return true if this action mode considers the title and subtitle fields * as optional. Optional titles may not be displayed to the user. */ public boolean isTitleOptional() { return false; } /** * Set a custom view for this action mode. The custom view will take the place of * the title and subtitle. Useful for things like search boxes. * * @param view Custom view to use in place of the title/subtitle. * * @see #setTitle(CharSequence) * @see #setSubtitle(CharSequence) */ public abstract void setCustomView(View view); /** * Invalidate the action mode and refresh menu content. The mode's * {@link ActionMode.Callback} will have its * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called. * If it returns true the menu will be scanned for updated content and any relevant changes * will be reflected to the user. */ public abstract void invalidate(); /** * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will * have its {@link Callback#onDestroyActionMode(ActionMode)} method called. */ public abstract void finish(); /** * Returns the menu of actions that this action mode presents. * @return The action mode's menu. */ public abstract Menu getMenu(); /** * Returns the current title of this action mode. * @return Title text */ public abstract CharSequence getTitle(); /** * Returns the current subtitle of this action mode. * @return Subtitle text */ public abstract CharSequence getSubtitle(); /** * Returns the current custom view for this action mode. * @return The current custom view */ public abstract View getCustomView(); /** * Returns a {@link MenuInflater} with the ActionMode's context. */ public abstract MenuInflater getMenuInflater(); /** * Returns whether the UI presenting this action mode can take focus or not. * This is used by internal components within the framework that would otherwise * present an action mode UI that requires focus, such as an EditText as a custom view. * * @return true if the UI used to show this action mode can take focus * @hide Internal use only */ public boolean isUiFocusable() { return true; } /** * Callback interface for action modes. Supplied to * {@link View#startActionMode(Callback)}, a Callback * configures and handles events raised by a user's interaction with an action mode. * *An action mode's lifecycle is as follows: *