279 lines
9.2 KiB
Java
279 lines
9.2 KiB
Java
/*
|
|
* 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.support.v7.view;
|
|
|
|
import android.view.Menu;
|
|
import android.view.MenuInflater;
|
|
import android.view.MenuItem;
|
|
import android.view.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.
|
|
* <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 {
|
|
|
|
private Object mTag;
|
|
private boolean mTitleOptionalHint;
|
|
|
|
/**
|
|
* 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(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.
|
|
*
|
|
* <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);
|
|
|
|
/**
|
|
* 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 android.support.v7.app.AppCompatDelegate#startSupportActionMode(Callback)} (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);
|
|
}
|
|
}
|