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
17package androidx.appcompat.view;
18
19import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
20
21import android.view.Menu;
22import android.view.MenuInflater;
23import android.view.MenuItem;
24import android.view.View;
25
26import androidx.annotation.RestrictTo;
27
28/**
29 * Represents a contextual mode of the user interface. Action modes can be used to provide
30 * alternative interaction modes and replace parts of the normal UI until finished.
31 * Examples of good action modes include text selection and contextual actions.
32 * <div class="special reference">
33 *
34 * <h3>Developer Guides</h3>
35 * <p>For information about how to provide contextual actions with {@code ActionMode},
36 * read the <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Menus</a>
37 * developer guide.</p>
38 *
39 * </div>
40 */
41public abstract class ActionMode {
42
43    private Object mTag;
44    private boolean mTitleOptionalHint;
45
46    /**
47     * Set a tag object associated with this ActionMode.
48     *
49     * <p>Like the tag available to views, this allows applications to associate arbitrary
50     * data with an ActionMode for later reference.
51     *
52     * @param tag Tag to associate with this ActionMode
53     *
54     * @see #getTag()
55     */
56    public void setTag(Object tag) {
57        mTag = tag;
58    }
59
60    /**
61     * Retrieve the tag object associated with this ActionMode.
62     *
63     * <p>Like the tag available to views, this allows applications to associate arbitrary
64     * data with an ActionMode for later reference.
65     *
66     * @return Tag associated with this ActionMode
67     *
68     * @see #setTag(Object)
69     */
70    public Object getTag() {
71        return mTag;
72    }
73
74    /**
75     * Set the title of the action mode. This method will have no visible effect if
76     * a custom view has been set.
77     *
78     * @param title Title string to set
79     *
80     * @see #setTitle(int)
81     * @see #setCustomView(View)
82     */
83    public abstract void setTitle(CharSequence title);
84
85    /**
86     * Set the title of the action mode. This method will have no visible effect if
87     * a custom view has been set.
88     *
89     * @param resId Resource ID of a string to set as the title
90     *
91     * @see #setTitle(CharSequence)
92     * @see #setCustomView(View)
93     */
94    public abstract void setTitle(int resId);
95
96    /**
97     * Set the subtitle of the action mode. This method will have no visible effect if
98     * a custom view has been set.
99     *
100     * @param subtitle Subtitle string to set
101     *
102     * @see #setSubtitle(int)
103     * @see #setCustomView(View)
104     */
105    public abstract void setSubtitle(CharSequence subtitle);
106
107    /**
108     * Set the subtitle of the action mode. This method will have no visible effect if
109     * a custom view has been set.
110     *
111     * @param resId Resource ID of a string to set as the subtitle
112     *
113     * @see #setSubtitle(CharSequence)
114     * @see #setCustomView(View)
115     */
116    public abstract void setSubtitle(int resId);
117
118    /**
119     * Set whether or not the title/subtitle display for this action mode
120     * is optional.
121     *
122     * <p>In many cases the supplied title for an action mode is merely
123     * meant to add context and is not strictly required for the action
124     * mode to be useful. If the title is optional, the system may choose
125     * to hide the title entirely rather than truncate it due to a lack
126     * of available space.</p>
127     *
128     * <p>Note that this is merely a hint; the underlying implementation
129     * may choose to ignore this setting under some circumstances.</p>
130     *
131     * @param titleOptional true if the title only presents optional information.
132     */
133    public void setTitleOptionalHint(boolean titleOptional) {
134        mTitleOptionalHint = titleOptional;
135    }
136
137    /**
138     * @return true if this action mode has been given a hint to consider the
139     *         title/subtitle display to be optional.
140     *
141     * @see #setTitleOptionalHint(boolean)
142     * @see #isTitleOptional()
143     */
144    public boolean getTitleOptionalHint() {
145        return mTitleOptionalHint;
146    }
147
148    /**
149     * @return true if this action mode considers the title and subtitle fields
150     *         as optional. Optional titles may not be displayed to the user.
151     */
152    public boolean isTitleOptional() {
153        return false;
154    }
155
156    /**
157     * Set a custom view for this action mode. The custom view will take the place of
158     * the title and subtitle. Useful for things like search boxes.
159     *
160     * @param view Custom view to use in place of the title/subtitle.
161     *
162     * @see #setTitle(CharSequence)
163     * @see #setSubtitle(CharSequence)
164     */
165    public abstract void setCustomView(View view);
166
167    /**
168     * Invalidate the action mode and refresh menu content. The mode's
169     * {@link ActionMode.Callback} will have its
170     * {@link Callback#onPrepareActionMode(ActionMode, Menu)} method called.
171     * If it returns true the menu will be scanned for updated content and any relevant changes
172     * will be reflected to the user.
173     */
174    public abstract void invalidate();
175
176    /**
177     * Finish and close this action mode. The action mode's {@link ActionMode.Callback} will
178     * have its {@link Callback#onDestroyActionMode(ActionMode)} method called.
179     */
180    public abstract void finish();
181
182    /**
183     * Returns the menu of actions that this action mode presents.
184     *
185     * @return The action mode's menu.
186     */
187    public abstract Menu getMenu();
188
189    /**
190     * Returns the current title of this action mode.
191     *
192     * @return Title text
193     */
194    public abstract CharSequence getTitle();
195
196    /**
197     * Returns the current subtitle of this action mode.
198     *
199     * @return Subtitle text
200     */
201    public abstract CharSequence getSubtitle();
202
203    /**
204     * Returns the current custom view for this action mode.
205     *
206     * @return The current custom view
207     */
208    public abstract View getCustomView();
209
210    /**
211     * Returns a {@link MenuInflater} with the ActionMode's context.
212     */
213    public abstract MenuInflater getMenuInflater();
214
215    /**
216     * Returns whether the UI presenting this action mode can take focus or not.
217     * This is used by internal components within the framework that would otherwise
218     * present an action mode UI that requires focus, such as an EditText as a custom view.
219     *
220     * @return true if the UI used to show this action mode can take focus
221     * @hide Internal use only
222     */
223    @RestrictTo(LIBRARY_GROUP)
224    public boolean isUiFocusable() {
225        return true;
226    }
227
228    /**
229     * Callback interface for action modes. Supplied to
230     * {@link androidx.appcompat.app.AppCompatDelegate#startSupportActionMode(Callback)} (Callback)},
231     * a Callback configures and handles events raised by a user's interaction with an action mode.
232     *
233     * <p>An action mode's lifecycle is as follows:
234     * <ul>
235     * <li>{@link Callback#onCreateActionMode(ActionMode, Menu)} once on initial
236     * creation</li>
237     * <li>{@link Callback#onPrepareActionMode(ActionMode, Menu)} after creation
238     * and any time the {@link ActionMode} is invalidated</li>
239     * <li>{@link Callback#onActionItemClicked(ActionMode, MenuItem)} any time a
240     * contextual action button is clicked</li>
241     * <li>{@link Callback#onDestroyActionMode(ActionMode)} when the action mode
242     * is closed</li>
243     * </ul>
244     */
245    public interface Callback {
246
247        /**
248         * Called when action mode is first created. The menu supplied will be used to
249         * generate action buttons for the action mode.
250         *
251         * @param mode ActionMode being created
252         * @param menu Menu used to populate action buttons
253         * @return true if the action mode should be created, false if entering this
254         *              mode should be aborted.
255         */
256        public boolean onCreateActionMode(ActionMode mode, Menu menu);
257
258        /**
259         * Called to refresh an action mode's action menu whenever it is invalidated.
260         *
261         * @param mode ActionMode being prepared
262         * @param menu Menu used to populate action buttons
263         * @return true if the menu or action mode was updated, false otherwise.
264         */
265        public boolean onPrepareActionMode(ActionMode mode, Menu menu);
266
267        /**
268         * Called to report a user click on an action button.
269         *
270         * @param mode The current ActionMode
271         * @param item The item that was clicked
272         * @return true if this callback handled the event, false if the standard MenuItem
273         *         invocation should continue.
274         */
275        public boolean onActionItemClicked(ActionMode mode, MenuItem item);
276
277        /**
278         * Called when an action mode is about to be exited and destroyed.
279         *
280         * @param mode The current ActionMode being destroyed
281         */
282        public void onDestroyActionMode(ActionMode mode);
283    }
284}
285