Android APIs
public class

Spinner

extends AbsSpinner
implements DialogInterface.OnClickListener
java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.widget.AdapterView<T extends android.widget.Adapter>
         ↳ android.widget.AbsSpinner
           ↳ android.widget.Spinner

Class Overview

A view that displays one child at a time and lets the user pick among them. The items in the Spinner come from the Adapter associated with this view.

See the Spinners guide.

Summary

XML Attributes
Attribute Name Related Method Description
android:dropDownHorizontalOffset setDropDownHorizontalOffset(int) Horizontal offset from the spinner widget for positioning the dropdown in spinnerMode="dropdown". 
android:dropDownSelector List selector to use for spinnerMode="dropdown" display. 
android:dropDownVerticalOffset setDropDownVerticalOffset(int) Vertical offset from the spinner widget for positioning the dropdown in spinnerMode="dropdown". 
android:dropDownWidth setDropDownWidth(int) Width of the dropdown in spinnerMode="dropdown". 
android:gravity setGravity(int) Gravity setting for positioning the currently selected item. 
android:popupBackground setPopupBackgroundResource(int) Background drawable to use for the dropdown in spinnerMode="dropdown". 
android:prompt The prompt to display when the spinner's dialog is shown. 
android:spinnerMode Display mode for spinner options. 
[Expand]
Inherited XML Attributes
From class android.widget.AbsSpinner
From class android.view.ViewGroup
From class android.view.View
Constants
int MODE_DIALOG Use a dialog window for selecting spinner options.
int MODE_DROPDOWN Use a dropdown anchored to the Spinner for selecting spinner options.
[Expand]
Inherited Constants
From class android.widget.AdapterView
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Fields
From class android.view.View
Public Constructors
Spinner(Context context)
Construct a new spinner with the given context's theme.
Spinner(Context context, int mode)
Construct a new spinner with the given context's theme and the supplied mode of displaying choices.
Spinner(Context context, AttributeSet attrs)
Construct a new spinner with the given context's theme and the supplied attribute set.
Spinner(Context context, AttributeSet attrs, int defStyleAttr)
Construct a new spinner with the given context's theme, the supplied attribute set, and default style attribute.
Spinner(Context context, AttributeSet attrs, int defStyleAttr, int mode)
Construct a new spinner with the given context's theme, the supplied attribute set, and default style.
Spinner(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes, int mode)
Construct a new spinner with the given context's theme, the supplied attribute set, and default style.
Public Methods
int getBaseline()

Return the offset of the widget's text baseline from the widget's top boundary.

int getDropDownHorizontalOffset()
Get the configured horizontal offset in pixels for the spinner's popup window of choices.
int getDropDownVerticalOffset()
Get the configured vertical offset in pixels for the spinner's popup window of choices.
int getDropDownWidth()
Get the configured width of the spinner's popup window of choices in pixels.
int getGravity()
Describes how the selected item view is positioned.
Drawable getPopupBackground()
Get the background drawable for the spinner's popup window of choices.
CharSequence getPrompt()
void onClick(DialogInterface dialog, int which)
This method will be invoked when a button in the dialog is clicked.
void onInitializeAccessibilityEvent(AccessibilityEvent event)
Initializes an AccessibilityEvent with information about this View which is the event source.
void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info)
Initializes an AccessibilityNodeInfo with information about this view.
void onRestoreInstanceState(Parcelable state)
Hook allowing a view to re-apply a representation of its internal state that had previously been generated by onSaveInstanceState().
Parcelable onSaveInstanceState()
Hook allowing a view to generate a representation of its internal state that can later be used to create a new instance with that same state.
boolean onTouchEvent(MotionEvent event)
Implement this method to handle touch screen motion events.
boolean performClick()
Call this view's OnClickListener, if it is defined.
void setAdapter(SpinnerAdapter adapter)
Sets the Adapter used to provide the data which backs this Spinner.
void setDropDownHorizontalOffset(int pixels)
Set a horizontal offset in pixels for the spinner's popup window of choices.
void setDropDownVerticalOffset(int pixels)
Set a vertical offset in pixels for the spinner's popup window of choices.
void setDropDownWidth(int pixels)
Set the width of the spinner's popup window of choices in pixels.
void setEnabled(boolean enabled)
Set the enabled state of this view.
void setGravity(int gravity)
Describes how the selected item view is positioned.
void setOnItemClickListener(AdapterView.OnItemClickListener l)

A spinner does not support item click events.

void setPopupBackgroundDrawable(Drawable background)
Set the background drawable for the spinner's popup window of choices.
void setPopupBackgroundResource(int resId)
Set the background drawable for the spinner's popup window of choices.
void setPrompt(CharSequence prompt)
Sets the prompt to display when the dialog is shown.
void setPromptId(int promptId)
Sets the prompt to display when the dialog is shown.
Protected Methods
void onDetachedFromWindow()
This is called when the view is detached from a window.
void onLayout(boolean changed, int l, int t, int r, int b)
Called from layout when this view should assign a size and position to each of its children.
void onMeasure(int widthMeasureSpec, int heightMeasureSpec)

Measure the view and its content to determine the measured width and the measured height.

[Expand]
Inherited Methods
From class android.widget.AbsSpinner
From class android.widget.AdapterView
From class android.view.ViewGroup
From class android.view.View
From class java.lang.Object
From interface android.content.DialogInterface.OnClickListener
From interface android.graphics.drawable.Drawable.Callback
From interface android.view.KeyEvent.Callback
From interface android.view.ViewManager
From interface android.view.ViewParent
From interface android.view.accessibility.AccessibilityEventSource

XML Attributes

android:dropDownHorizontalOffset

Horizontal offset from the spinner widget for positioning the dropdown in spinnerMode="dropdown".

Must be a dimension value, which is a floating point number appended with a unit such as "14.5sp". Available units are: px (pixels), dp (density-independent pixels), sp (scaled pixels based on preferred font size), in (inches), mm (millimeters).

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol dropDownHorizontalOffset.

Related Methods

android:dropDownSelector

List selector to use for spinnerMode="dropdown" display.

May be a reference to another resource, in the form "@[+][package:]type:name" or to a theme attribute in the form "?[package:][type:]name".

May be a color value, in the form of "#rgb", "#argb", "#rrggbb", or "#aarrggbb".

This corresponds to the global attribute resource symbol dropDownSelector.

Related Methods

android:dropDownVerticalOffset

Vertical offset from the spinner widget for positioning the dropdown in spinnerMode="dropdown".

Must be a dimension value, which is a floating point number appended with a unit such as "14.5sp". Available units are: px (pixels), dp (density-independent pixels), sp (scaled pixels based on preferred font size), in (inches), mm (millimeters).

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

This corresponds to the global attribute resource symbol dropDownVerticalOffset.

Related Methods

android:dropDownWidth

Width of the dropdown in spinnerMode="dropdown".

May be a dimension value, which is a floating point number appended with a unit such as "14.5sp". Available units are: px (pixels), dp (density-independent pixels), sp (scaled pixels based on preferred font size), in (inches), mm (millimeters).

This may also be a reference to a resource (in the form "@[package:]type:name") or theme attribute (in the form "?[package:][type:]name") containing a value of this type.

May be one of the following constant values.

ConstantValueDescription
fill_parent-1 The dropdown should fill the width of the screen. This constant is deprecated starting from API Level 8 and is replaced by match_parent.
match_parent-1 The dropdown should fit the width of the screen. Introduced in API Level 8.
wrap_content-2 The dropdown should fit the width of its anchor.

This corresponds to the global attribute resource symbol dropDownWidth.

Related Methods

android:gravity

Gravity setting for positioning the currently selected item.

Must be one or more (separated by '|') of the following constant values.

ConstantValueDescription
top0x30 Push object to the top of its container, not changing its size.
bottom0x50 Push object to the bottom of its container, not changing its size.
left0x03 Push object to the left of its container, not changing its size.
right0x05 Push object to the right of its container, not changing its size.
center_vertical0x10 Place object in the vertical center of its container, not changing its size.
fill_vertical0x70 Grow the vertical size of the object if needed so it completely fills its container.
center_horizontal0x01 Place object in the horizontal center of its container, not changing its size.
fill_horizontal0x07 Grow the horizontal size of the object if needed so it completely fills its container.
center0x11 Place the object in the center of its container in both the vertical and horizontal axis, not changing its size.
fill0x77 Grow the horizontal and vertical size of the object if needed so it completely fills its container.
clip_vertical0x80 Additional option that can be set to have the top and/or bottom edges of the child clipped to its container's bounds. The clip will be based on the vertical gravity: a top gravity will clip the bottom edge, a bottom gravity will clip the top edge, and neither will clip both edges.
clip_horizontal0x08 Additional option that can be set to have the left and/or right edges of the child clipped to its container's bounds. The clip will be based on the horizontal gravity: a left gravity will clip the right edge, a right gravity will clip the left edge, and neither will clip both edges.
start0x00800003 Push object to the beginning of its container, not changing its size.
end0x00800005 Push object to the end of its container, not changing its size.

This corresponds to the global attribute resource symbol gravity.

Related Methods

android:popupBackground

Background drawable to use for the dropdown in spinnerMode="dropdown".

May be a reference to another resource, in the form "@[+][package:]type:name" or to a theme attribute in the form "?[package:][type:]name".

May be a color value, in the form of "#rgb", "#argb", "#rrggbb", or "#aarrggbb".

This corresponds to the global attribute resource symbol popupBackground.

Related Methods

android:prompt

The prompt to display when the spinner's dialog is shown.

Must be a reference to another resource, in the form "@[+][package:]type:name" or to a theme attribute in the form "?[package:][type:]name".

This corresponds to the global attribute resource symbol prompt.

Related Methods

android:spinnerMode

Display mode for spinner options.

Must be one of the following constant values.

ConstantValueDescription
dialog0 Spinner options will be presented to the user as a dialog window.
dropdown1 Spinner options will be presented to the user as an inline dropdown anchored to the spinner widget itself.

This corresponds to the global attribute resource symbol spinnerMode.

Related Methods

Constants

public static final int MODE_DIALOG

Added in API level 11

Use a dialog window for selecting spinner options.

Constant Value: 0 (0x00000000)

public static final int MODE_DROPDOWN

Added in API level 11

Use a dropdown anchored to the Spinner for selecting spinner options.

Constant Value: 1 (0x00000001)

Public Constructors

public Spinner (Context context)

Added in API level 1

Construct a new spinner with the given context's theme.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.

public Spinner (Context context, int mode)

Added in API level 11

Construct a new spinner with the given context's theme and the supplied mode of displaying choices. mode may be one of MODE_DIALOG or MODE_DROPDOWN.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.
mode Constant describing how the user will select choices from the spinner.
See Also

public Spinner (Context context, AttributeSet attrs)

Added in API level 1

Construct a new spinner with the given context's theme and the supplied attribute set.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.
attrs The attributes of the XML tag that is inflating the view.

public Spinner (Context context, AttributeSet attrs, int defStyleAttr)

Added in API level 1

Construct a new spinner with the given context's theme, the supplied attribute set, and default style attribute.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.
attrs The attributes of the XML tag that is inflating the view.
defStyleAttr An attribute in the current theme that contains a reference to a style resource that supplies default values for the view. Can be 0 to not look for defaults.

public Spinner (Context context, AttributeSet attrs, int defStyleAttr, int mode)

Added in API level 11

Construct a new spinner with the given context's theme, the supplied attribute set, and default style. mode may be one of MODE_DIALOG or MODE_DROPDOWN and determines how the user will select choices from the spinner.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.
attrs The attributes of the XML tag that is inflating the view.
defStyleAttr An attribute in the current theme that contains a reference to a style resource that supplies default values for the view. Can be 0 to not look for defaults.
mode Constant describing how the user will select choices from the spinner.
See Also

public Spinner (Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes, int mode)

Construct a new spinner with the given context's theme, the supplied attribute set, and default style. mode may be one of MODE_DIALOG or MODE_DROPDOWN and determines how the user will select choices from the spinner.

Parameters
context The Context the view is running in, through which it can access the current theme, resources, etc.
attrs The attributes of the XML tag that is inflating the view.
defStyleAttr An attribute in the current theme that contains a reference to a style resource that supplies default values for the view. Can be 0 to not look for defaults.
defStyleRes A resource identifier of a style resource that supplies default values for the view, used only if defStyleAttr is 0 or can not be found in the theme. Can be 0 to not look for defaults.
mode Constant describing how the user will select choices from the spinner.
See Also

Public Methods

public int getBaseline ()

Added in API level 1

Return the offset of the widget's text baseline from the widget's top boundary. If this widget does not support baseline alignment, this method returns -1.

Returns
  • the offset of the baseline within the widget's bounds or -1 if baseline alignment is not supported

public int getDropDownHorizontalOffset ()

Added in API level 16

Get the configured horizontal offset in pixels for the spinner's popup window of choices. Only valid in MODE_DROPDOWN; other modes will return 0.

Related XML Attributes
Returns
  • Horizontal offset in pixels

public int getDropDownVerticalOffset ()

Added in API level 16

Get the configured vertical offset in pixels for the spinner's popup window of choices. Only valid in MODE_DROPDOWN; other modes will return 0.

Related XML Attributes
Returns
  • Vertical offset in pixels

public int getDropDownWidth ()

Added in API level 16

Get the configured width of the spinner's popup window of choices in pixels. The returned value may also be MATCH_PARENT meaning the popup window will match the width of the Spinner itself, or WRAP_CONTENT to wrap to the measured size of contained dropdown list items.

Related XML Attributes
Returns
  • Width in pixels, WRAP_CONTENT, or MATCH_PARENT

public int getGravity ()

Added in API level 16

Describes how the selected item view is positioned. The default is determined by the current theme.

Returns

public Drawable getPopupBackground ()

Added in API level 16

Get the background drawable for the spinner's popup window of choices. Only valid in MODE_DROPDOWN; other modes will return null.

Related XML Attributes
Returns
  • background Background drawable

public CharSequence getPrompt ()

Added in API level 1

Returns
  • The prompt to display when the dialog is shown

public void onClick (DialogInterface dialog, int which)

Added in API level 1

This method will be invoked when a button in the dialog is clicked.

Parameters
dialog The dialog that received the click.
which The button that was clicked (e.g. BUTTON1) or the position of the item clicked.

public void onInitializeAccessibilityEvent (AccessibilityEvent event)

Added in API level 14

Initializes an AccessibilityEvent with information about this View which is the event source. In other words, the source of an accessibility event is the view whose state change triggered firing the event.

Example: Setting the password property of an event in addition to properties set by the super implementation: 

 public void onInitializeAccessibilityEvent(AccessibilityEvent event) {
     super.onInitializeAccessibilityEvent(event);
     event.setPassword(true);
 }

If an View.AccessibilityDelegate has been specified via calling setAccessibilityDelegate(AccessibilityDelegate) its onInitializeAccessibilityEvent(View, AccessibilityEvent) is responsible for handling this call.

Note: Always call the super implementation before adding information to the event, in case the default implementation has basic information to add.

Parameters
event The event to initialize.

public void onInitializeAccessibilityNodeInfo (AccessibilityNodeInfo info)

Added in API level 14

Initializes an AccessibilityNodeInfo with information about this view. The base implementation sets:

Subclasses should override this method, call the super implementation, and set additional attributes.

If an View.AccessibilityDelegate has been specified via calling setAccessibilityDelegate(AccessibilityDelegate) its onInitializeAccessibilityNodeInfo(View, AccessibilityNodeInfo) is responsible for handling this call.

Parameters
info The instance to initialize.

public void onRestoreInstanceState (Parcelable state)

Added in API level 1

Hook allowing a view to re-apply a representation of its internal state that had previously been generated by onSaveInstanceState(). This function will never be called with a null state.

Parameters
state The frozen state that had previously been returned by onSaveInstanceState().

public Parcelable onSaveInstanceState ()

Added in API level 1

Hook allowing a view to generate a representation of its internal state that can later be used to create a new instance with that same state. This state should only contain information that is not persistent or can not be reconstructed later. For example, you will never store your current position on screen because that will be computed again when a new instance of the view is placed in its view hierarchy.

Some examples of things you may store here: the current cursor position in a text view (but usually not the text itself since that is stored in a content provider or other persistent storage), the currently selected item in a list view.

Returns
  • Returns a Parcelable object containing the view's current dynamic state, or null if there is nothing interesting to save. The default implementation returns null.

public boolean onTouchEvent (MotionEvent event)

Added in API level 1

Implement this method to handle touch screen motion events.

If this method is used to detect click actions, it is recommended that the actions be performed by implementing and calling performClick(). This will ensure consistent system behavior, including:

  • obeying click sound preferences
  • dispatching OnClickListener calls
  • handling ACTION_CLICK when accessibility features are enabled

Parameters
event The motion event.
Returns
  • True if the event was handled, false otherwise.

public boolean performClick ()

Added in API level 1

Call this view's OnClickListener, if it is defined. Performs all normal actions associated with clicking: reporting accessibility event, playing a sound, etc.

Returns
  • True there was an assigned OnClickListener that was called, false otherwise is returned.

public void setAdapter (SpinnerAdapter adapter)

Added in API level 1

Sets the Adapter used to provide the data which backs this Spinner.

Note that Spinner overrides getViewTypeCount() on the Adapter associated with this view. Calling getItemViewType(int) on the object returned from getAdapter() will always return 0. Calling getViewTypeCount() will always return 1.

Parameters
adapter The SpinnerAdapter to use for this Spinner
See Also

public void setDropDownHorizontalOffset (int pixels)

Added in API level 16

Set a horizontal offset in pixels for the spinner's popup window of choices. Only valid in MODE_DROPDOWN; this method is a no-op in other modes.

Related XML Attributes
Parameters
pixels Horizontal offset in pixels

public void setDropDownVerticalOffset (int pixels)

Added in API level 16

Set a vertical offset in pixels for the spinner's popup window of choices. Only valid in MODE_DROPDOWN; this method is a no-op in other modes.

Related XML Attributes
Parameters
pixels Vertical offset in pixels

public void setDropDownWidth (int pixels)

Added in API level 16

Set the width of the spinner's popup window of choices in pixels. This value may also be set to MATCH_PARENT to match the width of the Spinner itself, or WRAP_CONTENT to wrap to the measured size of contained dropdown list items.

Only valid in MODE_DROPDOWN; this method is a no-op in other modes.

Related XML Attributes
Parameters
pixels Width in pixels, WRAP_CONTENT, or MATCH_PARENT

public void setEnabled (boolean enabled)

Added in API level 1

Set the enabled state of this view. The interpretation of the enabled state varies by subclass.

Parameters
enabled True if this view is enabled, false otherwise.

public void setGravity (int gravity)

Added in API level 11

Describes how the selected item view is positioned. Currently only the horizontal component is used. The default is determined by the current theme.

Related XML Attributes
Parameters
gravity See Gravity

public void setOnItemClickListener (AdapterView.OnItemClickListener l)

Added in API level 1

A spinner does not support item click events. Calling this method will raise an exception.

Instead use setOnItemSelectedListener(AdapterView.OnItemSelectedListener).

Parameters
l this listener will be ignored

public void setPopupBackgroundDrawable (Drawable background)

Added in API level 16

Set the background drawable for the spinner's popup window of choices. Only valid in MODE_DROPDOWN; this method is a no-op in other modes.

Related XML Attributes
Parameters
background Background drawable

public void setPopupBackgroundResource (int resId)

Added in API level 16

Set the background drawable for the spinner's popup window of choices. Only valid in MODE_DROPDOWN; this method is a no-op in other modes.

Related XML Attributes
Parameters
resId Resource ID of a background drawable

public void setPrompt (CharSequence prompt)

Added in API level 1

Sets the prompt to display when the dialog is shown.

Parameters
prompt the prompt to set

public void setPromptId (int promptId)

Added in API level 1

Sets the prompt to display when the dialog is shown.

Parameters
promptId the resource ID of the prompt to display when the dialog is shown

Protected Methods

protected void onDetachedFromWindow ()

Added in API level 1

This is called when the view is detached from a window. At this point it no longer has a surface for drawing.

protected void onLayout (boolean changed, int l, int t, int r, int b)

Added in API level 1

Called from layout when this view should assign a size and position to each of its children. Derived classes with children should override this method and call layout on each of their children.

Parameters
changed This is a new size or position for this view
l Left position, relative to parent
t Top position, relative to parent
r Right position, relative to parent
b Bottom position, relative to parent
See Also

protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

Added in API level 1

Measure the view and its content to determine the measured width and the measured height. This method is invoked by measure(int, int) and should be overriden by subclasses to provide accurate and efficient measurement of their contents.

CONTRACT: When overriding this method, you must call setMeasuredDimension(int, int) to store the measured width and height of this view. Failure to do so will trigger an IllegalStateException, thrown by measure(int, int). Calling the superclass' onMeasure(int, int) is a valid use.

The base class implementation of measure defaults to the background size, unless a larger size is allowed by the MeasureSpec. Subclasses should override onMeasure(int, int) to provide better measurements of their content.

If this method is overridden, it is the subclass's responsibility to make sure the measured height and width are at least the view's minimum height and width (getSuggestedMinimumHeight() and getSuggestedMinimumWidth()).

Parameters
widthMeasureSpec horizontal space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.
heightMeasureSpec vertical space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.