actionbarsherlock/src/com/actionbarsherlock/view/ActionMode.java

   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 com.actionbarsherlock.view;
  18
  19 import android.view.View;
  20
  21
  22 /**
  23  * Represents a contextual mode of the user interface. Action modes can be used for
  24  * modal interactions with content and replace parts of the normal UI until finished.
  25  * Examples of good action modes include selection modes, search, content editing, etc.
  26  */
  27 public abstract class ActionMode {
  28     private Object mTag;
  29
  30     /**
  31      * Set a tag object associated with this ActionMode.
  32      *
  33      * <p>Like the tag available to views, this allows applications to associate arbitrary
  34      * data with an ActionMode for later reference.
  35      *
  36      * @param tag Tag to associate with this ActionMode
  37      *
  38      * @see #getTag()
  39      */
  40     public void setTag(Object tag) {
  41         mTag = tag;
  42     }
  43
  44     /**
  45      * Retrieve the tag object associated with this ActionMode.
  46      *
  47      * <p>Like the tag available to views, this allows applications to associate arbitrary
  48      * data with an ActionMode for later reference.
  49      *
  50      * @return Tag associated with this ActionMode
  51      *
  52      * @see #setTag(Object)
  53      */
  54     public Object getTag() {
  55         return mTag;
  56     }
  57
  58     /**
  59      * Set the title of the action mode. This method will have no visible effect if
  60      * a custom view has been set.
  61      *
  62      * @param title Title string to set
  63      *
  64      * @see #setTitle(int)
  65      * @see #setCustomView(View)
  66      */
  67     public abstract void setTitle(CharSequence title);
  68
  69     /**
  70      * Set the title of the action mode. This method will have no visible effect if
  71      * a custom view has been set.
  72      *
  73      * @param resId Resource ID of a string to set as the title
  74      *
  75      * @see #setTitle(CharSequence)
  76      * @see #setCustomView(View)
  77      */
  78     public abstract void setTitle(int resId);
  79
  80     /**
  81      * Set the subtitle of the action mode. This method will have no visible effect if
  82      * a custom view has been set.
  83      *
  84      * @param subtitle Subtitle string to set
  85      *
  86      * @see #setSubtitle(int)
  87      * @see #setCustomView(View)
  88      */
  89     public abstract void setSubtitle(CharSequence subtitle);
  90
  91     /**
  92      * Set the subtitle of the action mode. This method will have no visible effect if
  93      * a custom view has been set.
  94      *
  95      * @param resId Resource ID of a string to set as the subtitle
  96      *
  97      * @see #setSubtitle(CharSequence)
  98      * @see #setCustomView(View)
  99      */
 100     public abstract void setSubtitle(int resId);
 101
 102     /**
 103      * Set a custom view for this action mode. The custom view will take the place of
 104      * the title and subtitle. Useful for things like search boxes.
 105      *
 106      * @param view Custom view to use in place of the title/subtitle.
 107      *
 108      * @see #setTitle(CharSequence)
 109      * @see #setSubtitle(CharSequence)
 110      */
 111     public abstract void setCustomView(View view);
 112
 113     /**
 114      * Invalidate the action mode and refresh menu content. The mode's
 115      * {@link ActionMode.Callback} will have its
 116      * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called.
 117      * If it returns true the menu will be scanned for updated content and any relevant changes
 118      * will be reflected to the user.
 119      */
 120     public abstract void invalidate();
 121
 122     /**
 123      * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will
 124      * have its {@link Callback#onDestroyActionMode(ActionMode)} method called.
 125      */
 126     public abstract void finish();
 127
 128     /**
 129      * Returns the menu of actions that this action mode presents.
 130      * @return The action mode's menu.
 131      */
 132     public abstract Menu getMenu();
 133
 134     /**
 135      * Returns the current title of this action mode.
 136      * @return Title text
 137      */
 138     public abstract CharSequence getTitle();
 139
 140     /**
 141      * Returns the current subtitle of this action mode.
 142      * @return Subtitle text
 143      */
 144     public abstract CharSequence getSubtitle();
 145
 146     /**
 147      * Returns the current custom view for this action mode.
 148      * @return The current custom view
 149      */
 150     public abstract View getCustomView();
 151
 152     /**
 153      * Returns a {@link MenuInflater} with the ActionMode's context.
 154      */
 155     public abstract MenuInflater getMenuInflater();
 156
 157     /**
 158      * Returns whether the UI presenting this action mode can take focus or not.
 159      * This is used by internal components within the framework that would otherwise
 160      * present an action mode UI that requires focus, such as an EditText as a custom view.
 161      *
 162      * @return true if the UI used to show this action mode can take focus
 163      * @hide Internal use only
 164      */
 165     public boolean isUiFocusable() {
 166         return true;
 167     }
 168
 169     /**
 170      * Callback interface for action modes. Supplied to
 171      * {@link View#startActionMode(Callback)}, a Callback
 172      * configures and handles events raised by a user's interaction with an action mode.
 173      *
 174      * <p>An action mode's lifecycle is as follows:
 175      * <ul>
 176      * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial
 177      * creation</li>
 178      * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation
 179      * and any time the {@link ActionMode} is invalidated</li>
 180      * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a
 181      * contextual action button is clicked</li>
 182      * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode
 183      * is closed</li>
 184      * </ul>
 185      */
 186     public interface Callback {
 187         /**
 188          * Called when action mode is first created. The menu supplied will be used to
 189          * generate action buttons for the action mode.
 190          *
 191          * @param mode ActionMode being created
 192          * @param menu Menu used to populate action buttons
 193          * @return true if the action mode should be created, false if entering this
 194          *              mode should be aborted.
 195          */
 196         public boolean onCreateActionMode(ActionMode mode, Menu menu);
 197
 198         /**
 199          * Called to refresh an action mode's action menu whenever it is invalidated.
 200          *
 201          * @param mode ActionMode being prepared
 202          * @param menu Menu used to populate action buttons
 203          * @return true if the menu or action mode was updated, false otherwise.
 204          */
 205         public boolean onPrepareActionMode(ActionMode mode, Menu menu);
 206
 207         /**
 208          * Called to report a user click on an action button.
 209          *
 210          * @param mode The current ActionMode
 211          * @param item The item that was clicked
 212          * @return true if this callback handled the event, false if the standard MenuItem
 213          *          invocation should continue.
 214          */
 215         public boolean onActionItemClicked(ActionMode mode, MenuItem item);
 216
 217         /**
 218          * Called when an action mode is about to be exited and destroyed.
 219          *
 220          * @param mode The current ActionMode being destroyed
 221          */
 222         public void onDestroyActionMode(ActionMode mode);
 223     }
 224 }