Java tutorial
/* * 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; import android.annotation.StringRes; import android.annotation.TestApi; import android.graphics.Rect; /** * 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. * <div class="special reference"> * <h3>Developer Guides</h3> * <p>For information about how to provide contextual actions with {@code ActionMode}, * read the <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menus</a> * developer guide.</p> * </div> */ public abstract class ActionMode { /** * The action mode is treated as a Primary mode. This is the default. * Use with {@link #setType}. */ public static final int TYPE_PRIMARY = 0; /** * The action mode is treated as a Floating Toolbar. * Use with {@link #setType}. */ public static final int TYPE_FLOATING = 1; /** * Default value to hide the action mode for * {@link ViewConfiguration#getDefaultActionModeHideDuration()}. */ public static final int DEFAULT_HIDE_DURATION = -1; private Object mTag; private boolean mTitleOptionalHint; private int mType = TYPE_PRIMARY; /** * Set a tag object associated with this ActionMode. * * <p>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. * * <p>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(@StringRes 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(@StringRes int resId); /** * Set whether or not the title/subtitle display for this action mode * is optional. * * <p>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.</p> * * <p>Note that this is merely a hint; the underlying implementation * may choose to ignore this setting under some circumstances.</p> * * @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); /** * Set a type for this action mode. This will affect how the system renders the action mode if * it has to. * * @param type One of {@link #TYPE_PRIMARY} or {@link #TYPE_FLOATING}. */ public void setType(int type) { mType = type; } /** * Returns the type for this action mode. * * @return One of {@link #TYPE_PRIMARY} or {@link #TYPE_FLOATING}. */ public int getType() { return mType; } /** * 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(); /** * Invalidate the content rect associated to this ActionMode. This only makes sense for * action modes that support dynamic positioning on the screen, and provides a more efficient * way to reposition it without invalidating the whole action mode. * * @see Callback2#onGetContentRect(ActionMode, View, Rect) . */ public void invalidateContentRect() { } /** * Hide the action mode view from obstructing the content below for a short duration. * This only makes sense for action modes that support dynamic positioning on the screen. * If this method is called again before the hide duration expires, the later hide call will * cancel the former and then take effect. * NOTE that there is an internal limit to how long the mode can be hidden for. It's typically * about a few seconds. * * @param duration The number of milliseconds to hide for. * @see #DEFAULT_HIDE_DURATION */ public void hide(long duration) { } /** * 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(); /** * Called when the window containing the view that started this action mode gains or loses * focus. * * @param hasWindowFocus True if the window containing the view that started this action mode * now has focus, false otherwise. * */ public void onWindowFocusChanged(boolean hasWindowFocus) { } /** * 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 */ @TestApi 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. * * <p>An action mode's lifecycle is as follows: * <ul> * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial * creation</li> * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation * and any time the {@link ActionMode} is invalidated</li> * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a * contextual action button is clicked</li> * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode * is closed</li> * </ul> */ public interface Callback { /** * Called when action mode is first created. The menu supplied will be used to * generate action buttons for the action mode. * * @param mode ActionMode being created * @param menu Menu used to populate action buttons * @return true if the action mode should be created, false if entering this * mode should be aborted. */ public boolean onCreateActionMode(ActionMode mode, Menu menu); /** * Called to refresh an action mode's action menu whenever it is invalidated. * * @param mode ActionMode being prepared * @param menu Menu used to populate action buttons * @return true if the menu or action mode was updated, false otherwise. */ public boolean onPrepareActionMode(ActionMode mode, Menu menu); /** * Called to report a user click on an action button. * * @param mode The current ActionMode * @param item The item that was clicked * @return true if this callback handled the event, false if the standard MenuItem * invocation should continue. */ public boolean onActionItemClicked(ActionMode mode, MenuItem item); /** * Called when an action mode is about to be exited and destroyed. * * @param mode The current ActionMode being destroyed */ public void onDestroyActionMode(ActionMode mode); } /** * Extension of {@link ActionMode.Callback} to provide content rect information. This is * required for ActionModes with dynamic positioning such as the ones with type * {@link ActionMode#TYPE_FLOATING} to ensure the positioning doesn't obscure app content. If * an app fails to provide a subclass of this class, a default implementation will be used. */ public static abstract class Callback2 implements ActionMode.Callback { /** * Called when an ActionMode needs to be positioned on screen, potentially occluding view * content. Note this may be called on a per-frame basis. * * @param mode The ActionMode that requires positioning. * @param view The View that originated the ActionMode, in whose coordinates the Rect should * be provided. * @param outRect The Rect to be populated with the content position. Use this to specify * where the content in your app lives within the given view. This will be used * to avoid occluding the given content Rect with the created ActionMode. */ public void onGetContentRect(ActionMode mode, View view, Rect outRect) { if (view != null) { outRect.set(0, 0, view.getWidth(), view.getHeight()); } else { outRect.set(0, 0, 0, 0); } } } }