com.actionbarsherlock
Class ActionBarSherlock

java.lang.Object
  com.actionbarsherlock.ActionBarSherlock

Direct Known Subclasses:

ActionBarSherlockCompat, ActionBarSherlockNative

public abstract class ActionBarSherlock
extends Object

Helper for implementing the action bar design pattern across all versions of Android.

This class will manage interaction with a custom action bar based on the Android 4.0 source code. The exposed API mirrors that of its native counterpart and you should refer to its documentation for instruction.

Author:

Jake Wharton

Nested Class Summary

static interface	ActionBarSherlock.Implementation Denotes an implementation of ActionBarSherlock which provides an action bar-enhanced experience.
static interface	ActionBarSherlock.OnActionModeFinishedListener Activity interface for action mode finished callback.
static interface	ActionBarSherlock.OnActionModeStartedListener Activity interface for action mode started callback.
static interface	ActionBarSherlock.OnCreateOptionsMenuListener Activity interface for menu creation callback.
static interface	ActionBarSherlock.OnCreatePanelMenuListener Activity interface for menu creation callback.
static interface	ActionBarSherlock.OnMenuItemSelectedListener Activity interface for menu item selection callback.
static interface	ActionBarSherlock.OnOptionsItemSelectedListener Activity interface for menu item selection callback.
static interface	ActionBarSherlock.OnPrepareOptionsMenuListener Activity interface for menu preparation callback.
static interface	ActionBarSherlock.OnPreparePanelListener Activity interface for menu preparation callback.

Field Summary

static int	FLAG_DELEGATE If set, the logic in these classes will assume that an Activity is dispatching all of the required events to the class.
protected android.app.Activity	mActivity Activity which is displaying the action bar.
protected boolean	mIsDelegate Whether delegating actions for the activity or managing ourselves.
protected MenuInflater	mMenuInflater Reference to our custom menu inflater which supports action items.
protected static String	TAG

Constructor Summary

protected

ActionBarSherlock(android.app.Activity activity, int flags)

Method Summary

abstract void	addContentView(android.view.View view, android.view.ViewGroup.LayoutParams params) Variation on setContentView(android.view.View, android.view.ViewGroup.LayoutParams) to add an additional content view to the screen.
protected boolean	callbackCreateOptionsMenu(Menu menu) Internal method to trigger the menu creation process.
protected boolean	callbackOptionsItemSelected(MenuItem item) Internal method for dispatching options menu selection to the owning activity callback.
protected boolean	callbackPrepareOptionsMenu(Menu menu) Internal method to trigger the menu preparation process.
boolean	dispatchCloseOptionsMenu() Notify the action bar that it should close its overflow menu if it is appropriate for the device.
void	dispatchConfigurationChanged(android.content.res.Configuration newConfig) Notify action bar of a configuration change event.
abstract boolean	dispatchCreateOptionsMenu(android.view.Menu menu) Notify the action bar that the Activity has triggered a menu creation which should happen on the conclusion of Activity.onCreate(android.os.Bundle).
void	dispatchDestroy() Notify the action bar that the activity has been destroyed.
abstract void	dispatchInvalidateOptionsMenu() Indicate that the menu should be recreated by calling ActionBarSherlock.OnCreateOptionsMenuListener.onCreateOptionsMenu(com.actionbarsherlock.view.Menu).
boolean	dispatchKeyEvent(android.view.KeyEvent event) Notify the action bar the user has created a key event.
boolean	dispatchMenuOpened(int featureId, android.view.Menu menu) Notify the action bar that the overflow menu has been opened.
boolean	dispatchOpenOptionsMenu() Notify the action bar that it should display its overflow menu if it is appropriate for the device.
abstract boolean	dispatchOptionsItemSelected(android.view.MenuItem item) Notify the action bar that a native options menu item has been selected.
void	dispatchPanelClosed(int featureId, android.view.Menu menu) Notify the action bar that the overflow menu has been closed.
void	dispatchPause() Notify the action bar that the activity is pausing.
void	dispatchPostCreate(android.os.Bundle savedInstanceState) Notify the class that the activity has finished its creation.
void	dispatchPostResume() Notify the action bar that the activity has finished its resuming.
abstract boolean	dispatchPrepareOptionsMenu(android.view.Menu menu) Notify the action bar that the Activity has triggered a menu preparation which usually means that the user has requested the overflow menu via a hardware menu key.
void	dispatchRestoreInstanceState(android.os.Bundle savedInstanceState)
void	dispatchSaveInstanceState(android.os.Bundle outState)
void	dispatchStop() Notify the action bar that the activity is stopping.
void	dispatchTitleChanged(CharSequence title, int color) Notify the action bar that the title has changed and the action bar should be updated to reflect the change.
void	ensureActionBar() Ensure that the action bar is attached.
abstract ActionBar	getActionBar() Get the current action bar instance.
MenuInflater	getMenuInflater() Get a menu inflater instance which supports the newer menu attributes.
protected abstract android.content.Context	getThemedContext()
abstract boolean	hasFeature(int featureId) Query for the availability of a certain feature.
static void	registerImplementation(Class<? extends ActionBarSherlock> implementationClass) Register an ActionBarSherlock implementation.
abstract boolean	requestFeature(int featureId) Enable extended screen features.
abstract void	setContentView(int layoutResId) Set the content of the activity inside the action bar.
void	setContentView(android.view.View view) Set the content of the activity inside the action bar.
abstract void	setContentView(android.view.View view, android.view.ViewGroup.LayoutParams params) Set the content of the activity inside the action bar.
abstract void	setProgress(int progress) Sets the progress for the progress bars in the title.
abstract void	setProgressBarIndeterminate(boolean indeterminate) Sets whether the horizontal progress bar in the title should be indeterminate (the circular is always indeterminate).
abstract void	setProgressBarIndeterminateVisibility(boolean visible) Sets the visibility of the indeterminate progress bar in the title.
abstract void	setProgressBarVisibility(boolean visible) Sets the visibility of the progress bar in the title.
abstract void	setSecondaryProgress(int secondaryProgress) Sets the secondary progress for the progress bar in the title.
abstract void	setTitle(CharSequence title) Change the title associated with this activity.
void	setTitle(int resId) Change the title associated with this activity.
abstract void	setUiOptions(int uiOptions) Set extra options that will influence the UI for this window.
abstract void	setUiOptions(int uiOptions, int mask) Set extra options that will influence the UI for this window.
abstract ActionMode	startActionMode(ActionMode.Callback callback) Start an action mode.
static boolean	unregisterImplementation(Class<? extends ActionBarSherlock> implementationClass) Unregister an ActionBarSherlock implementation.
static ActionBarSherlock	wrap(android.app.Activity activity) Wrap an activity with an action bar abstraction which will enable the use of a custom implementation on platforms where a native version does not exist.
static ActionBarSherlock	wrap(android.app.Activity activity, int flags) Wrap an activity with an action bar abstraction which will enable the use of a custom implementation on platforms where a native version does not exist.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TAG

protected static final String TAG

See Also:

Constant Field Values

FLAG_DELEGATE

public static final int FLAG_DELEGATE

If set, the logic in these classes will assume that an Activity is dispatching all of the required events to the class. This flag should only be used internally or if you are creating your own base activity modeled after one of the included types (e.g., SherlockActivity).

See Also:

Constant Field Values

mActivity

protected final android.app.Activity mActivity

Activity which is displaying the action bar. Also used for context.

mIsDelegate

protected final boolean mIsDelegate

Whether delegating actions for the activity or managing ourselves.

mMenuInflater

protected MenuInflater mMenuInflater

Reference to our custom menu inflater which supports action items.

Constructor Detail

ActionBarSherlock

protected ActionBarSherlock(android.app.Activity activity,
                            int flags)

Method Detail

registerImplementation

public static void registerImplementation(Class<? extends ActionBarSherlock> implementationClass)

Register an ActionBarSherlock implementation.

Parameters:

implementationClass - Target implementation class which extends ActionBarSherlock. This class must also be annotated with ActionBarSherlock.Implementation.

unregisterImplementation

public static boolean unregisterImplementation(Class<? extends ActionBarSherlock> implementationClass)

Unregister an ActionBarSherlock implementation. This should be considered very volatile and you should only use it if you know what you are doing. You have been warned.

Parameters:

implementationClass - Target implementation class.

Returns:

Boolean indicating whether the class was removed.

wrap

public static ActionBarSherlock wrap(android.app.Activity activity)

Wrap an activity with an action bar abstraction which will enable the use of a custom implementation on platforms where a native version does not exist.

Parameters:

activity - Activity to wrap.

Returns:

Instance to interact with the action bar.

wrap

public static ActionBarSherlock wrap(android.app.Activity activity,
                                     int flags)

Wrap an activity with an action bar abstraction which will enable the use of a custom implementation on platforms where a native version does not exist.

Parameters:

activity - Owning activity.

flags - Option flags to control behavior.

Returns:

Instance to interact with the action bar.

getActionBar

public abstract ActionBar getActionBar()

Get the current action bar instance.

Returns:

Action bar instance.

dispatchConfigurationChanged

public void dispatchConfigurationChanged(android.content.res.Configuration newConfig)

Notify action bar of a configuration change event. Should be dispatched after the call to the superclass implementation.

Parameters:
newConfig - The new device configuration.

dispatchPostResume

public void dispatchPostResume()

Notify the action bar that the activity has finished its resuming. This should be dispatched after the call to the superclass implementation.

dispatchPause

public void dispatchPause()

Notify the action bar that the activity is pausing. This should be dispatched before the call to the superclass implementation.

dispatchStop

public void dispatchStop()

Notify the action bar that the activity is stopping. This should be called before the superclass implementation.

dispatchInvalidateOptionsMenu

public abstract void dispatchInvalidateOptionsMenu()

Indicate that the menu should be recreated by calling ActionBarSherlock.OnCreateOptionsMenuListener.onCreateOptionsMenu(com.actionbarsherlock.view.Menu).

dispatchOpenOptionsMenu

public boolean dispatchOpenOptionsMenu()

Notify the action bar that it should display its overflow menu if it is appropriate for the device. The implementation should conditionally call the superclass method only if this method returns false.

Returns:

true if the opening of the menu was handled internally.

dispatchCloseOptionsMenu

public boolean dispatchCloseOptionsMenu()

Notify the action bar that it should close its overflow menu if it is appropriate for the device. This implementation should conditionally call the superclass method only if this method returns false.

Returns:
true if the closing of the menu was handled internally.

dispatchPostCreate

public void dispatchPostCreate(android.os.Bundle savedInstanceState)

Notify the class that the activity has finished its creation. This should be called after the superclass implementation.

Parameters:
savedInstanceState - If the activity is being re-initialized after
                           previously being shut down then this Bundle
                           contains the data it most recently supplied in
                           Activity#onSaveInstanceState(Bundle)}.
                           Note: Otherwise it is null.

dispatchTitleChanged

public void dispatchTitleChanged(CharSequence title,
                                 int color)

Notify the action bar that the title has changed and the action bar should be updated to reflect the change. This should be called before the superclass implementation.

Parameters:
title - New activity title.
color - New activity color.

dispatchKeyEvent

public boolean dispatchKeyEvent(android.view.KeyEvent event)

Notify the action bar the user has created a key event. This is used to toggle the display of the overflow action item with the menu key and to close the action mode or expanded action item with the back key.

Parameters:
event - Description of the key event.
Returns:
true if the event was handled.

dispatchCreateOptionsMenu

public abstract boolean dispatchCreateOptionsMenu(android.view.Menu menu)

Notify the action bar that the Activity has triggered a menu creation which should happen on the conclusion of Activity.onCreate(android.os.Bundle). This will be used to gain a reference to the native menu for native and overflow binding as well as to indicate when compatibility create should occur for the first time.

Parameters:

menu - Activity native menu.

Returns:

true since we always want to say that we have a native

dispatchPrepareOptionsMenu

public abstract boolean dispatchPrepareOptionsMenu(android.view.Menu menu)

Notify the action bar that the Activity has triggered a menu preparation which usually means that the user has requested the overflow menu via a hardware menu key. You should return the result of this method call and not call the superclass implementation.

Parameters:

menu - Activity native menu.

Returns:

true if menu display should proceed.

dispatchOptionsItemSelected

public abstract boolean dispatchOptionsItemSelected(android.view.MenuItem item)

Notify the action bar that a native options menu item has been selected. The implementation should return the result of this method call.

Parameters:

item - Options menu item.

Returns:

@{code true} if the selection was handled.

dispatchMenuOpened

public boolean dispatchMenuOpened(int featureId,
                                  android.view.Menu menu)

Notify the action bar that the overflow menu has been opened. The implementation should conditionally return true if this method returns true, otherwise return the result of the superclass method.

Parameters:

featureId - Window feature which triggered the event.

menu - Activity native menu.

Returns:

true if the event was handled by this method.

dispatchPanelClosed

public void dispatchPanelClosed(int featureId,
                                android.view.Menu menu)

Notify the action bar that the overflow menu has been closed. This method should be called before the superclass implementation.

Parameters:

featureId -

menu -

dispatchDestroy

public void dispatchDestroy()

Notify the action bar that the activity has been destroyed. This method should be called before the superclass implementation.

dispatchSaveInstanceState

public void dispatchSaveInstanceState(android.os.Bundle outState)

dispatchRestoreInstanceState

public void dispatchRestoreInstanceState(android.os.Bundle savedInstanceState)

callbackCreateOptionsMenu

protected final boolean callbackCreateOptionsMenu(Menu menu)

Internal method to trigger the menu creation process.

Returns:

true if menu creation should proceed.

callbackPrepareOptionsMenu

protected final boolean callbackPrepareOptionsMenu(Menu menu)

Internal method to trigger the menu preparation process.

Returns:

true if menu preparation should proceed.

callbackOptionsItemSelected

protected final boolean callbackOptionsItemSelected(MenuItem item)

Internal method for dispatching options menu selection to the owning activity callback.

Parameters:

item - Selected options menu item.

Returns:

true if the item selection was handled in the callback.

hasFeature

public abstract boolean hasFeature(int featureId)

Query for the availability of a certain feature.

Parameters:

featureId - The feature ID to check.

Returns:

true if feature is enabled, false otherwise.

requestFeature

public abstract boolean requestFeature(int featureId)

Enable extended screen features. This must be called before setContentView(). May be called as many times as desired as long as it is before setContentView(). If not called, no extended features will be available. You can not turn off a feature once it is requested.

Parameters:

featureId - The desired features, defined as constants by Window.

Returns:

Returns true if the requested feature is supported and now enabled.

setUiOptions

public abstract void setUiOptions(int uiOptions)

Set extra options that will influence the UI for this window.

Parameters:

uiOptions - Flags specifying extra options for this window.

setUiOptions

public abstract void setUiOptions(int uiOptions,
                                  int mask)

Set extra options that will influence the UI for this window. Only the bits filtered by mask will be modified.

Parameters:

uiOptions - Flags specifying extra options for this window.

mask - Flags specifying which options should be modified. Others will remain unchanged.

setContentView

public abstract void setContentView(int layoutResId)

Set the content of the activity inside the action bar.

Parameters:

layoutResId - Layout resource ID.

setContentView

public void setContentView(android.view.View view)

Set the content of the activity inside the action bar.

Parameters:

view - The desired content to display.

setContentView

public abstract void setContentView(android.view.View view,
                                    android.view.ViewGroup.LayoutParams params)

Set the content of the activity inside the action bar.

Parameters:

view - The desired content to display.

params - Layout parameters to apply to the view.

addContentView

public abstract void addContentView(android.view.View view,
                                    android.view.ViewGroup.LayoutParams params)

Variation on setContentView(android.view.View, android.view.ViewGroup.LayoutParams) to add an additional content view to the screen. Added after any existing ones on the screen -- existing views are NOT removed.

Parameters:

view - The desired content to display.

params - Layout parameters for the view.

setTitle

public abstract void setTitle(CharSequence title)

Change the title associated with this activity.

setTitle

public void setTitle(int resId)

Change the title associated with this activity.

setProgressBarVisibility

public abstract void setProgressBarVisibility(boolean visible)

Sets the visibility of the progress bar in the title.

In order for the progress bar to be shown, the feature must be requested via #requestWindowFeature(int).

Parameters:

visible - Whether to show the progress bars in the title.

setProgressBarIndeterminateVisibility

public abstract void setProgressBarIndeterminateVisibility(boolean visible)

Sets the visibility of the indeterminate progress bar in the title.

In order for the progress bar to be shown, the feature must be requested via #requestWindowFeature(int).

Parameters:

visible - Whether to show the progress bars in the title.

setProgressBarIndeterminate

public abstract void setProgressBarIndeterminate(boolean indeterminate)

Sets whether the horizontal progress bar in the title should be indeterminate (the circular is always indeterminate).

In order for the progress bar to be shown, the feature must be requested via #requestWindowFeature(int).

Parameters:

indeterminate - Whether the horizontal progress bar should be indeterminate.

setProgress

public abstract void setProgress(int progress)

Sets the progress for the progress bars in the title.

In order for the progress bar to be shown, the feature must be requested via #requestWindowFeature(int).

Parameters:

progress - The progress for the progress bar. Valid ranges are from 0 to 10000 (both inclusive). If 10000 is given, the progress bar will be completely filled and will fade out.

setSecondaryProgress

public abstract void setSecondaryProgress(int secondaryProgress)

Sets the secondary progress for the progress bar in the title. This progress is drawn between the primary progress (set via setProgress(int) and the background. It can be ideal for media scenarios such as showing the buffering progress while the default progress shows the play progress.

In order for the progress bar to be shown, the feature must be requested via #requestWindowFeature(int).

Parameters:

secondaryProgress - The secondary progress for the progress bar. Valid ranges are from 0 to 10000 (both inclusive).

getMenuInflater

public MenuInflater getMenuInflater()

Get a menu inflater instance which supports the newer menu attributes.

Returns:

Menu inflater instance.

getThemedContext

protected abstract android.content.Context getThemedContext()

startActionMode

public abstract ActionMode startActionMode(ActionMode.Callback callback)

Start an action mode.

Parameters:

callback - Callback that will manage lifecycle events for this context mode.

Returns:

The ContextMode that was started, or null if it was canceled.

See Also:

ActionMode

ensureActionBar

public void ensureActionBar()

Ensure that the action bar is attached.