ActionBar.java revision 7f9b90542e05b350d14bd63c16446c8ce2baf407
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.view.Window; 22import android.widget.SpinnerAdapter; 23 24/** 25 * This is the public interface to the contextual ActionBar. 26 * The ActionBar acts as a replacement for the title bar in Activities. 27 * It provides facilities for creating toolbar actions as well as 28 * methods of navigating around an application. 29 */ 30public abstract class ActionBar { 31 /** 32 * Standard navigation mode. Consists of either a logo or icon 33 * and title text with an optional subtitle. Clicking any of these elements 34 * will dispatch onActionItemSelected to the registered Callback with 35 * a MenuItem with item ID android.R.id.home. 36 */ 37 public static final int NAVIGATION_MODE_STANDARD = 0; 38 39 /** 40 * Dropdown list navigation mode. Instead of static title text this mode 41 * presents a dropdown menu for navigation within the activity. 42 */ 43 public static final int NAVIGATION_MODE_DROPDOWN_LIST = 1; 44 45 /** 46 * Tab navigation mode. Instead of static title text this mode 47 * presents a series of tabs for navigation within the activity. 48 */ 49 public static final int NAVIGATION_MODE_TABS = 2; 50 51 /** 52 * Custom navigation mode. This navigation mode is set implicitly whenever 53 * a custom navigation view is set. See {@link #setCustomNavigationMode(View)}. 54 */ 55 public static final int NAVIGATION_MODE_CUSTOM = 3; 56 57 /** 58 * Use logo instead of icon if available. This flag will cause appropriate 59 * navigation modes to use a wider logo in place of the standard icon. 60 */ 61 public static final int DISPLAY_USE_LOGO = 0x1; 62 63 /** 64 * Hide 'home' elements in this action bar, leaving more space for other 65 * navigation elements. This includes logo and icon. 66 */ 67 public static final int DISPLAY_HIDE_HOME = 0x2; 68 69 /** 70 * Set the action bar into custom navigation mode, supplying a view 71 * for custom navigation. 72 * 73 * Custom navigation views appear between the application icon and 74 * any action buttons and may use any space available there. Common 75 * use cases for custom navigation views might include an auto-suggesting 76 * address bar for a browser or other navigation mechanisms that do not 77 * translate well to provided navigation modes. 78 * 79 * @param view Custom navigation view to place in the ActionBar. 80 */ 81 public abstract void setCustomNavigationMode(View view); 82 83 /** 84 * Set the action bar into dropdown navigation mode and supply an adapter 85 * that will provide views for navigation choices. 86 * 87 * @param adapter An adapter that will provide views both to display 88 * the current navigation selection and populate views 89 * within the dropdown navigation menu. 90 * @param callback A NavigationCallback that will receive events when the user 91 * selects a navigation item. 92 */ 93 public abstract void setDropdownNavigationMode(SpinnerAdapter adapter, 94 NavigationCallback callback); 95 96 /** 97 * Set the action bar into dropdown navigation mode and supply an adapter that will 98 * provide views for navigation choices. 99 * 100 * @param adapter An adapter that will provide views both to display the current 101 * navigation selection and populate views within the dropdown 102 * navigation menu. 103 * @param callback A NavigationCallback that will receive events when the user 104 * selects a navigation item. 105 * @param defaultSelectedPosition Position within the provided adapter that should be 106 * selected from the outset. 107 */ 108 public abstract void setDropdownNavigationMode(SpinnerAdapter adapter, 109 NavigationCallback callback, int defaultSelectedPosition); 110 111 /** 112 * Set the selected navigation item in dropdown or tabbed navigation modes. 113 * 114 * @param position Position of the item to select. 115 */ 116 public abstract void setSelectedNavigationItem(int position); 117 118 /** 119 * Get the position of the selected navigation item in dropdown or tabbed navigation modes. 120 * 121 * @return Position of the selected item. 122 */ 123 public abstract int getSelectedNavigationItem(); 124 125 /** 126 * Set the action bar into standard navigation mode, using the currently set title 127 * and/or subtitle. 128 * 129 * Standard navigation mode is default. The title is automatically set to the name of 130 * your Activity on startup if an action bar is present. 131 */ 132 public abstract void setStandardNavigationMode(); 133 134 /** 135 * Set the action bar's title. This will only be displayed in standard navigation mode. 136 * 137 * @param title Title to set 138 * 139 * @see #setTitle(int) 140 */ 141 public abstract void setTitle(CharSequence title); 142 143 /** 144 * Set the action bar's title. This will only be displayed in standard navigation mode. 145 * 146 * @param resId Resource ID of title string to set 147 * 148 * @see #setTitle(CharSequence) 149 */ 150 public abstract void setTitle(int resId); 151 152 /** 153 * Set the action bar's subtitle. This will only be displayed in standard navigation mode. 154 * Set to null to disable the subtitle entirely. 155 * 156 * @param subtitle Subtitle to set 157 * 158 * @see #setSubtitle(int) 159 */ 160 public abstract void setSubtitle(CharSequence subtitle); 161 162 /** 163 * Set the action bar's subtitle. This will only be displayed in standard navigation mode. 164 * 165 * @param resId Resource ID of subtitle string to set 166 * 167 * @see #setSubtitle(CharSequence) 168 */ 169 public abstract void setSubtitle(int resId); 170 171 /** 172 * Set display options. This changes all display option bits at once. To change 173 * a limited subset of display options, see {@link #setDisplayOptions(int, int)}. 174 * 175 * @param options A combination of the bits defined by the DISPLAY_ constants 176 * defined in ActionBar. 177 */ 178 public abstract void setDisplayOptions(int options); 179 180 /** 181 * Set selected display options. Only the options specified by mask will be changed. 182 * To change all display option bits at once, see {@link #setDisplayOptions(int)}. 183 * 184 * <p>Example: setDisplayOptions(0, DISPLAY_HIDE_HOME) will disable the 185 * {@link #DISPLAY_HIDE_HOME} option. 186 * setDisplayOptions(DISPLAY_HIDE_HOME, DISPLAY_HIDE_HOME | DISPLAY_USE_LOGO) 187 * will enable {@link #DISPLAY_HIDE_HOME} and disable {@link #DISPLAY_USE_LOGO}. 188 * 189 * @param options A combination of the bits defined by the DISPLAY_ constants 190 * defined in ActionBar. 191 * @param mask A bit mask declaring which display options should be changed. 192 */ 193 public abstract void setDisplayOptions(int options, int mask); 194 195 /** 196 * Set the ActionBar's background. 197 * 198 * @param d Background drawable 199 */ 200 public abstract void setBackgroundDrawable(Drawable d); 201 202 /** 203 * @return The current custom navigation view. 204 */ 205 public abstract View getCustomNavigationView(); 206 207 /** 208 * Returns the current ActionBar title in standard mode. 209 * Returns null if {@link #getNavigationMode()} would not return 210 * {@link #NAVIGATION_MODE_STANDARD}. 211 * 212 * @return The current ActionBar title or null. 213 */ 214 public abstract CharSequence getTitle(); 215 216 /** 217 * Returns the current ActionBar subtitle in standard mode. 218 * Returns null if {@link #getNavigationMode()} would not return 219 * {@link #NAVIGATION_MODE_STANDARD}. 220 * 221 * @return The current ActionBar subtitle or null. 222 */ 223 public abstract CharSequence getSubtitle(); 224 225 /** 226 * Returns the current navigation mode. The result will be one of: 227 * <ul> 228 * <li>{@link #NAVIGATION_MODE_STANDARD}</li> 229 * <li>{@link #NAVIGATION_MODE_DROPDOWN_LIST}</li> 230 * <li>{@link #NAVIGATION_MODE_TABS}</li> 231 * <li>{@link #NAVIGATION_MODE_CUSTOM}</li> 232 * </ul> 233 * 234 * @return The current navigation mode. 235 * 236 * @see #setStandardNavigationMode() 237 * @see #setStandardNavigationMode(CharSequence) 238 * @see #setStandardNavigationMode(CharSequence, CharSequence) 239 * @see #setDropdownNavigationMode(SpinnerAdapter) 240 * @see #setTabNavigationMode() 241 * @see #setCustomNavigationMode(View) 242 */ 243 public abstract int getNavigationMode(); 244 245 /** 246 * @return The current set of display options. 247 */ 248 public abstract int getDisplayOptions(); 249 250 /** 251 * Set the action bar into tabbed navigation mode. 252 * 253 * @see #addTab(Tab) 254 * @see #insertTab(Tab, int) 255 * @see #removeTab(Tab) 256 * @see #removeTabAt(int) 257 */ 258 public abstract void setTabNavigationMode(); 259 260 /** 261 * Create and return a new {@link Tab}. 262 * This tab will not be included in the action bar until it is added. 263 * 264 * @return A new Tab 265 * 266 * @see #addTab(Tab) 267 * @see #insertTab(Tab, int) 268 */ 269 public abstract Tab newTab(); 270 271 /** 272 * Add a tab for use in tabbed navigation mode. The tab will be added at the end of the list. 273 * 274 * @param tab Tab to add 275 */ 276 public abstract void addTab(Tab tab); 277 278 /** 279 * Add a tab for use in tabbed navigation mode. The tab will be inserted at 280 * <code>position</code>. 281 * 282 * @param tab The tab to add 283 * @param position The new position of the tab 284 */ 285 public abstract void addTab(Tab tab, int position); 286 287 /** 288 * Remove a tab from the action bar. 289 * 290 * @param tab The tab to remove 291 */ 292 public abstract void removeTab(Tab tab); 293 294 /** 295 * Remove a tab from the action bar. 296 * 297 * @param position Position of the tab to remove 298 */ 299 public abstract void removeTabAt(int position); 300 301 /** 302 * Select the specified tab. If it is not a child of this action bar it will be added. 303 * 304 * @param tab Tab to select 305 */ 306 public abstract void selectTab(Tab tab); 307 308 /** 309 * Returns the currently selected tab if in tabbed navigation mode and there is at least 310 * one tab present. 311 * 312 * @return The currently selected tab or null 313 */ 314 public abstract Tab getSelectedTab(); 315 316 /** 317 * Retrieve the current height of the ActionBar. 318 * 319 * @return The ActionBar's height 320 */ 321 public abstract int getHeight(); 322 323 /** 324 * Show the ActionBar if it is not currently showing. 325 * If the window hosting the ActionBar does not have the feature 326 * {@link Window#FEATURE_ACTION_BAR_OVERLAY} it will resize application 327 * content to fit the new space available. 328 */ 329 public abstract void show(); 330 331 /** 332 * Hide the ActionBar if it is not currently showing. 333 * If the window hosting the ActionBar does not have the feature 334 * {@link Window#FEATURE_ACTION_BAR_OVERLAY} it will resize application 335 * content to fit the new space available. 336 */ 337 public abstract void hide(); 338 339 /** 340 * @return <code>true</code> if the ActionBar is showing, <code>false</code> otherwise. 341 */ 342 public abstract boolean isShowing(); 343 344 /** 345 * Callback interface for ActionBar navigation events. 346 */ 347 public interface NavigationCallback { 348 /** 349 * This method is called whenever a navigation item in your action bar 350 * is selected. 351 * 352 * @param itemPosition Position of the item clicked. 353 * @param itemId ID of the item clicked. 354 * @return True if the event was handled, false otherwise. 355 */ 356 public boolean onNavigationItemSelected(int itemPosition, long itemId); 357 } 358 359 /** 360 * A tab in the action bar. 361 * 362 * <p>Tabs manage the hiding and showing of {@link Fragment}s. 363 */ 364 public static abstract class Tab { 365 /** 366 * An invalid position for a tab. 367 * 368 * @see #getPosition() 369 */ 370 public static final int INVALID_POSITION = -1; 371 372 /** 373 * Return the current position of this tab in the action bar. 374 * 375 * @return Current position, or {@link #INVALID_POSITION} if this tab is not currently in 376 * the action bar. 377 */ 378 public abstract int getPosition(); 379 380 /** 381 * Return the icon associated with this tab. 382 * 383 * @return The tab's icon 384 */ 385 public abstract Drawable getIcon(); 386 387 /** 388 * Return the text of this tab. 389 * 390 * @return The tab's text 391 */ 392 public abstract CharSequence getText(); 393 394 /** 395 * Set the icon displayed on this tab. 396 * 397 * @param icon The drawable to use as an icon 398 */ 399 public abstract void setIcon(Drawable icon); 400 401 /** 402 * Set the text displayed on this tab. Text may be truncated if there is not 403 * room to display the entire string. 404 * 405 * @param text The text to display 406 */ 407 public abstract void setText(CharSequence text); 408 409 /** 410 * Set a custom view to be used for this tab. This overrides values set by 411 * {@link #setText(CharSequence)} and {@link #setIcon(Drawable)}. 412 * 413 * @param view Custom view to be used as a tab. 414 */ 415 public abstract void setCustomView(View view); 416 417 /** 418 * Retrieve a previously set custom view for this tab. 419 * 420 * @return The custom view set by {@link #setCustomView(View)}. 421 */ 422 public abstract View getCustomView(); 423 424 /** 425 * Give this Tab an arbitrary object to hold for later use. 426 * 427 * @param obj Object to store 428 */ 429 public abstract void setTag(Object obj); 430 431 /** 432 * @return This Tab's tag object. 433 */ 434 public abstract Object getTag(); 435 436 /** 437 * Set the {@link TabListener} that will handle switching to and from this tab. 438 * All tabs must have a TabListener set before being added to the ActionBar. 439 * 440 * @param listener Listener to handle tab selection events 441 */ 442 public abstract void setTabListener(TabListener listener); 443 444 /** 445 * Select this tab. Only valid if the tab has been added to the action bar. 446 */ 447 public abstract void select(); 448 } 449 450 /** 451 * Callback interface invoked when a tab is focused, unfocused, added, or removed. 452 */ 453 public interface TabListener { 454 /** 455 * Called when a tab enters the selected state. 456 * 457 * @param tab The tab that was selected 458 * @param ft A {@link FragmentTransaction} for queuing fragment operations to execute 459 * during a tab switch. The previous tab's unselect and this tab's select will be 460 * executed in a single transaction. 461 */ 462 public void onTabSelected(Tab tab, FragmentTransaction ft); 463 464 /** 465 * Called when a tab exits the selected state. 466 * 467 * @param tab The tab that was unselected 468 * @param ft A {@link FragmentTransaction} for queuing fragment operations to execute 469 * during a tab switch. This tab's unselect and the newly selected tab's select 470 * will be executed in a single transaction. 471 */ 472 public void onTabUnselected(Tab tab, FragmentTransaction ft); 473 474 /** 475 * Called when a tab that is already selected is chosen again by the user. 476 * Some applications may use this action to return to the top level of a category. 477 * 478 * @param tab The tab that was reselected. 479 * @param ft A {@link FragmentTransaction} for queuing fragment operations to execute 480 * once this method returns. 481 */ 482 public void onTabReselected(Tab tab, FragmentTransaction ft); 483 } 484} 485