https://source.android.com/ 
/*
 * 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.



Developer Guides


For information about how to provide contextual actions with ActionMode, read the Menus
developer guide.




/**
 * 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 setType. 
/**
     * 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 setType. 
/**
     * 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 ViewConfiguration.getDefaultActionModeHideDuration(). 
/**
     * 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.

Like the tag available to views, this allows applications to associate arbitrary
data with an ActionMode for later reference.

Params:
  • tag – Tag to associate with this ActionMode
See Also:
/**
     * 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.

Like the tag available to views, this allows applications to associate arbitrary
data with an ActionMode for later reference.

See Also:
Returns:Tag associated with this ActionMode
/**
     * 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.

Params:
  • title – Title string to set
See Also:
/**
     * 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.

Params:
  • resId – Resource ID of a string to set as the title
See Also:
/**
     * 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.

Params:
  • subtitle – Subtitle string to set
See Also:
/**
     * 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.

Params:
  • resId – Resource ID of a string to set as the subtitle
See Also:
/**
     * 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.

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.


Params:
  • titleOptional – true if the title only presents optional information.
/**
     * 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;
    }

    
See Also:
Returns:true if this action mode has been given a hint to consider the
        title/subtitle display to be optional.
/**
     * @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;
    }

    
Returns:true if this action mode considers the title and subtitle fields
        as optional. Optional titles may not be displayed to the user.
/**
     * @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.

Params:
  • view – Custom view to use in place of the title/subtitle.
See Also:
/**
     * 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.

Params:
/**
     * 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.

Returns:One of TYPE_PRIMARY or TYPE_FLOATING.
/**
     * 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 Callback will have its 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. 
/**
     * 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 Also:
  • .
/**
     * 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.

Params:
  • duration – The number of milliseconds to hide for.
See Also:
/**
     * 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 Callback will have its Callback.onDestroyActionMode(ActionMode) method called. 
/**
     * 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.

Returns:The action mode's menu.
/**
     * 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.

Returns:Title text
/**
     * Returns the current title of this action mode.
     * @return Title text
     */
    public abstract CharSequence getTitle();

    
Returns the current subtitle of this action mode.

Returns:Subtitle text
/**
     * Returns the current subtitle of this action mode.
     * @return Subtitle text
     */
    public abstract CharSequence getSubtitle();

    
Returns the current custom view for this action mode.

Returns:The current custom view
/**
     * Returns the current custom view for this action mode.
     * @return The current custom view
     */
    public abstract View getCustomView();

    
Returns a MenuInflater with the ActionMode's context. 
/**
     * 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.

Params:
  • hasWindowFocus – True if the window containing the view that started this action mode
       now has focus, false otherwise.
/**
     * 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.

Returns:true if the UI used to show this action mode can take focus
@hideInternal use only
/**
     * 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 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:



/**
     * 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.

Params:
  • mode – ActionMode being created
  • menu – Menu used to populate action buttons
Returns:true if the action mode should be created, false if entering this
             mode should be aborted.
/**
         * 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.

Params:
  • mode – ActionMode being prepared
  • menu – Menu used to populate action buttons
Returns:true if the menu or action mode was updated, false otherwise.
/**
         * 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.

Params:
  • mode – The current ActionMode
  • item – The item that was clicked
Returns:true if this callback handled the event, false if the standard MenuItem
         invocation should continue.
/**
         * 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.

Params:
  • mode – The current ActionMode being destroyed
/**
         * 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 Callback to provide content rect information. This is required for ActionModes with dynamic positioning such as the ones with type 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. 
/**
     * 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.

Params:
  • mode – The ActionMode that requires positioning.
  • view – The View that originated the ActionMode, in whose coordinates the Rect should
         be provided.
  • 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.
/**
         * 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);
            }
        }

    }
}