ActionBar.java revision ac695c608ba620e2362f57126d7be453cf5b7e1b 
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 android.app;
18
19import android.graphics.drawable.Drawable;
20import android.view.View;
21import android.widget.SpinnerAdapter;
22
23/**
24 * This is the public interface to the contextual ActionBar.
25 * The ActionBar acts as a replacement for the title bar in Activities.
26 * It provides facilities for creating toolbar actions as well as
27 * methods of navigating around an application.
28 */
29public abstract class ActionBar {
30    /**
31     * Standard navigation mode. Consists of either a logo or icon
32     * and title text with an optional subtitle. Clicking any of these elements
33     * will dispatch onActionItemSelected to the registered Callback with
34     * a MenuItem with item ID android.R.id.home.
35     */
36    public static final int NAVIGATION_MODE_STANDARD = 0;
37
38    /**
39     * Dropdown list navigation mode. Instead of static title text this mode
40     * presents a dropdown menu for navigation within the activity.
41     */
42    public static final int NAVIGATION_MODE_DROPDOWN_LIST = 1;
43
44    /**
45     * Tab navigation mode. Instead of static title text this mode
46     * presents a series of tabs for navigation within the activity.
47     */
48    public static final int NAVIGATION_MODE_TABS = 2;
49
50    /**
51     * Custom navigation mode. This navigation mode is set implicitly whenever
52     * a custom navigation view is set. See {@link #setCustomNavigationMode(View)}.
53     */
54    public static final int NAVIGATION_MODE_CUSTOM = 3;
55
56    /**
57     * Use logo instead of icon if available. This flag will cause appropriate
58     * navigation modes to use a wider logo in place of the standard icon.
59     */
60    public static final int DISPLAY_USE_LOGO = 0x1;
61
62    /**
63     * Hide 'home' elements in this action bar, leaving more space for other
64     * navigation elements. This includes logo and icon.
65     */
66    public static final int DISPLAY_HIDE_HOME = 0x2;
67
68    /**
69     * Set the action bar into custom navigation mode, supplying a view
70     * for custom navigation.
71     *
72     * Custom navigation views appear between the application icon and
73     * any action buttons and may use any space available there. Common
74     * use cases for custom navigation views might include an auto-suggesting
75     * address bar for a browser or other navigation mechanisms that do not
76     * translate well to provided navigation modes.
77     *
78     * @param view Custom navigation view to place in the ActionBar.
79     */
80    public abstract void setCustomNavigationMode(View view);
81
82    /**
83     * Set the action bar into dropdown navigation mode and supply an adapter
84     * that will provide views for navigation choices.
85     *
86     * @param adapter An adapter that will provide views both to display
87     *                the current navigation selection and populate views
88     *                within the dropdown navigation menu.
89     * @param callback A NavigationCallback that will receive events when the user
90     *                 selects a navigation item.
91     */
92    public abstract void setDropdownNavigationMode(SpinnerAdapter adapter,
93            NavigationCallback callback);
94
95    /**
96     * Set the action bar into standard navigation mode, supplying a title and subtitle.
97     *
98     * Standard navigation mode is default. The title is automatically set to the
99     * name of your Activity. Subtitles are displayed underneath the title, usually
100     * in a smaller font or otherwise less prominently than the title. Subtitles are
101     * good for extended descriptions of activity state.
102     *
103     * @param title The action bar's title. null is treated as an empty string.
104     * @param subtitle The action bar's subtitle. null will remove the subtitle entirely.
105     */
106    public abstract void setStandardNavigationMode(CharSequence title, CharSequence subtitle);
107
108    /**
109     * Set the action bar into standard navigation mode, supplying a title and subtitle.
110     *
111     * Standard navigation mode is default. The title is automatically set to the
112     * name of your Activity on startup if an action bar is present.
113     *
114     * @param title The action bar's title. null is treated as an empty string.
115     */
116    public abstract void setStandardNavigationMode(CharSequence title);
117
118    /**
119     * Set the action bar into standard navigation mode, using the currently set title
120     * and/or subtitle.
121     *
122     * Standard navigation mode is default. The title is automatically set to the name of
123     * your Activity on startup if an action bar is present.
124     */
125    public abstract void setStandardNavigationMode();
126
127    /**
128     * Set the action bar's title. This will only be displayed in standard navigation mode.
129     *
130     * @param title Title to set
131     */
132    public abstract void setTitle(CharSequence title);
133
134    /**
135     * Set the action bar's subtitle. This will only be displayed in standard navigation mode.
136     * Set to null to disable the subtitle entirely.
137     *
138     * @param subtitle Subtitle to set
139     */
140    public abstract void setSubtitle(CharSequence subtitle);
141
142    /**
143     * Set display options. This changes all display option bits at once. To change
144     * a limited subset of display options, see {@link #setDisplayOptions(int, int)}.
145     *
146     * @param options A combination of the bits defined by the DISPLAY_ constants
147     *                defined in ActionBar.
148     */
149    public abstract void setDisplayOptions(int options);
150
151    /**
152     * Set selected display options. Only the options specified by mask will be changed.
153     * To change all display option bits at once, see {@link #setDisplayOptions(int)}.
154     *
155     * <p>Example: setDisplayOptions(0, DISPLAY_HIDE_HOME) will disable the
156     * {@link #DISPLAY_HIDE_HOME} option.
157     * setDisplayOptions(DISPLAY_HIDE_HOME, DISPLAY_HIDE_HOME | DISPLAY_USE_LOGO)
158     * will enable {@link #DISPLAY_HIDE_HOME} and disable {@link #DISPLAY_USE_LOGO}.
159     *
160     * @param options A combination of the bits defined by the DISPLAY_ constants
161     *                defined in ActionBar.
162     * @param mask A bit mask declaring which display options should be changed.
163     */
164    public abstract void setDisplayOptions(int options, int mask);
165
166    /**
167     * Set the ActionBar's background.
168     *
169     * @param d Background drawable
170     */
171    public abstract void setBackgroundDrawable(Drawable d);
172
173    /**
174     * @return The current custom navigation view.
175     */
176    public abstract View getCustomNavigationView();
177
178    /**
179     * Returns the current ActionBar title in standard mode.
180     * Returns null if {@link #getNavigationMode()} would not return
181     * {@link #NAVIGATION_MODE_STANDARD}.
182     *
183     * @return The current ActionBar title or null.
184     */
185    public abstract CharSequence getTitle();
186
187    /**
188     * Returns the current ActionBar subtitle in standard mode.
189     * Returns null if {@link #getNavigationMode()} would not return
190     * {@link #NAVIGATION_MODE_STANDARD}.
191     *
192     * @return The current ActionBar subtitle or null.
193     */
194    public abstract CharSequence getSubtitle();
195
196    /**
197     * Returns the current navigation mode. The result will be one of:
198     * <ul>
199     * <li>{@link #NAVIGATION_MODE_STANDARD}</li>
200     * <li>{@link #NAVIGATION_MODE_DROPDOWN_LIST}</li>
201     * <li>{@link #NAVIGATION_MODE_TABS}</li>
202     * <li>{@link #NAVIGATION_MODE_CUSTOM}</li>
203     * </ul>
204     *
205     * @return The current navigation mode.
206     *
207     * @see #setStandardNavigationMode()
208     * @see #setStandardNavigationMode(CharSequence)
209     * @see #setStandardNavigationMode(CharSequence, CharSequence)
210     * @see #setDropdownNavigationMode(SpinnerAdapter)
211     * @see #setTabNavigationMode()
212     * @see #setCustomNavigationMode(View)
213     */
214    public abstract int getNavigationMode();
215
216    /**
217     * @return The current set of display options.
218     */
219    public abstract int getDisplayOptions();
220
221    /**
222     * Set the action bar into tabbed navigation mode.
223     *
224     * @see #addTab(Tab)
225     * @see #insertTab(Tab, int)
226     * @see #removeTab(Tab)
227     * @see #removeTabAt(int)
228     */
229    public abstract void setTabNavigationMode();
230
231    /**
232     * Set the action bar into tabbed navigation mode.
233     *
234     * @param containerViewId Id of the container view where tab content fragments should appear.
235     *
236     * @see #addTab(Tab)
237     * @see #insertTab(Tab, int)
238     * @see #removeTab(Tab)
239     * @see #removeTabAt(int)
240     */
241    public abstract void setTabNavigationMode(int containerViewId);
242
243    /**
244     * Create and return a new {@link Tab}.
245     * This tab will not be included in the action bar until it is added.
246     *
247     * @return A new Tab
248     *
249     * @see #addTab(Tab)
250     * @see #insertTab(Tab, int)
251     */
252    public abstract Tab newTab();
253
254    /**
255     * Add a tab for use in tabbed navigation mode. The tab will be added at the end of the list.
256     *
257     * @param tab Tab to add
258     */
259    public abstract void addTab(Tab tab);
260
261    /**
262     * Insert a tab for use in tabbed navigation mode. The tab will be inserted at
263     * <code>position</code>.
264     *
265     * @param tab The tab to add
266     * @param position The new position of the tab
267     */
268    public abstract void insertTab(Tab tab, int position);
269
270    /**
271     * Remove a tab from the action bar.
272     *
273     * @param tab The tab to remove
274     */
275    public abstract void removeTab(Tab tab);
276
277    /**
278     * Remove a tab from the action bar.
279     *
280     * @param position Position of the tab to remove
281     */
282    public abstract void removeTabAt(int position);
283
284    /**
285     * Select the specified tab. If it is not a child of this action bar it will be added.
286     *
287     * @param tab Tab to select
288     */
289    public abstract void selectTab(Tab tab);
290
291    /**
292     * Select the tab at <code>position</code>
293     *
294     * @param position Position of the tab to select
295     */
296    public abstract void selectTabAt(int position);
297
298    /**
299     * Callback interface for ActionBar navigation events.
300     */
301    public interface NavigationCallback {
302        /**
303         * This method is called whenever a navigation item in your action bar
304         * is selected.
305         *
306         * @param itemPosition Position of the item clicked.
307         * @param itemId ID of the item clicked.
308         * @return True if the event was handled, false otherwise.
309         */
310        public boolean onNavigationItemSelected(int itemPosition, long itemId);
311    }
312
313    /**
314     * A tab in the action bar.
315     *
316     * <p>Tabs manage the hiding and showing of {@link Fragment}s.
317     */
318    public static abstract class Tab {
319        /**
320         * An invalid position for a tab.
321         *
322         * @see #getPosition()
323         */
324        public static final int INVALID_POSITION = -1;
325
326        /**
327         * Return the current position of this tab in the action bar.
328         *
329         * @return Current position, or {@link #INVALID_POSITION} if this tab is not currently in
330         *         the action bar.
331         */
332        public abstract int getPosition();
333
334        /**
335         * Return the icon associated with this tab.
336         *
337         * @return The tab's icon
338         */
339        public abstract Drawable getIcon();
340
341        /**
342         * Return the text of this tab.
343         *
344         * @return The tab's text
345         */
346        public abstract CharSequence getText();
347
348        /**
349         * Set the icon displayed on this tab.
350         *
351         * @param icon The drawable to use as an icon
352         */
353        public abstract void setIcon(Drawable icon);
354
355        /**
356         * Set the text displayed on this tab. Text may be truncated if there is not
357         * room to display the entire string.
358         *
359         * @param text The text to display
360         */
361        public abstract void setText(CharSequence text);
362
363        /**
364         * Returns the fragment that will be shown when this tab is selected.
365         *
366         * @return Fragment associated with this tab
367         */
368        public abstract Fragment getFragment();
369
370        /**
371         * Set the fragment that will be shown when this tab is selected.
372         *
373         * @param fragment Fragment to associate with this tab
374         */
375        public abstract void setFragment(Fragment fragment);
376
377        /**
378         * Select this tab. Only valid if the tab has been added to the action bar.
379         */
380        public abstract void select();
381    }
382}
383