NumberPicker


public class NumberPicker
extends LinearLayout

java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.widget.LinearLayout
         ↳ android.widget.NumberPicker


A widget that enables the user to select a number from a predefined range. There are two flavors of this widget and which one is presented to the user depends on the current theme.

  • If the current theme is derived from R.style.Theme the widget presents the current value as an editable input field with an increment button above and a decrement button below. Long pressing the buttons allows for a quick change of the current value. Tapping on the input field allows to type in a desired value.
  • If the current theme is derived from R.style.Theme_Holo or R.style.Theme_Holo_Light the widget presents the current value as an editable input field with a lesser value above and a greater value below. Tapping on the lesser or greater value selects it by animating the number axis up or down to make the chosen value current. Flinging up or down allows for multiple increments or decrements of the current value. Long pressing on the lesser and greater values also allows for a quick change of the current value. Tapping on the current value allows to type in a desired value.
  • If the current theme is derived from R.style.Theme_Material the widget presents the current value as a scrolling vertical selector with the selected value in the center and the previous and following numbers above and below, separated by a divider. The value is changed by flinging vertically. The thickness of the divider can be changed by using the R.attr.selectionDividerHeight attribute and the color of the divider can be changed by using the R.attr.colorControlNormal attribute.

For an example of using this widget, see TimePicker.

Summary

Nested classes

interface NumberPicker.Formatter

Interface used to format current value into a string for presentation. 

interface NumberPicker.OnScrollListener

Interface to listen for the picker scroll state. 

interface NumberPicker.OnValueChangeListener

Interface to listen for changes of the current value. 

Inherited XML attributes

Inherited constants

Inherited fields

Public constructors

NumberPicker(Context context)

Create a new number picker.

NumberPicker(Context context, AttributeSet attrs)

Create a new number picker.

NumberPicker(Context context, AttributeSet attrs, int defStyleAttr)

Create a new number picker

NumberPicker(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

Create a new number picker

Public methods

void computeScroll()

Called by a parent to request that a child update its values for mScrollX and mScrollY if necessary.

boolean dispatchKeyEvent(KeyEvent event)

Dispatch a key event to the next view on the focus path.

boolean dispatchTouchEvent(MotionEvent event)

Pass the touch screen motion event down to the target view, or this view if it is the target.

boolean dispatchTrackballEvent(MotionEvent event)

Pass a trackball motion event down to the focused view.

AccessibilityNodeProvider getAccessibilityNodeProvider()

Gets the provider for managing a virtual view hierarchy rooted at this View and reported to AccessibilityServices that explore the window content.

String[] getDisplayedValues()

Gets the values to be displayed instead of string values.

int getMaxValue()

Returns the max value of the picker.

int getMinValue()

Returns the min value of the picker.

int getSelectionDividerHeight()

Retrieve the height for the divider that separates the currently selected value from the others.

int getSolidColor()

Override this if your view is known to always be drawn on top of a solid color background, and needs to draw fading edges.

int getTextColor()
float getTextSize()
int getValue()

Returns the value of the picker.

boolean getWrapSelectorWheel()

Gets whether the selector wheel wraps when reaching the min/max value.

void jumpDrawablesToCurrentState()

Call Drawable.jumpToCurrentState() on all Drawable objects associated with this view. If you override this method you must call through to the superclass implementation.

boolean onInterceptTouchEvent(MotionEvent event)

Implement this method to intercept all touch screen motion events.

boolean onTouchEvent(MotionEvent event)

Implement this method to handle touch screen motion events.

boolean performClick()

Call this view's OnClickListener, if it is defined.

boolean performLongClick()

Calls this view's OnLongClickListener, if it is defined.

void scrollBy(int x, int y)

Move the scrolled position of your view.

void setDisplayedValues(String[] displayedValues)

Sets the values to be displayed.

void setEnabled(boolean enabled)

Set the enabled state of this view.

void setFormatter(NumberPicker.Formatter formatter)

Set the formatter to be used for formatting the current value.

void setMaxValue(int maxValue)

Sets the max value of the picker.

void setMinValue(int minValue)

Sets the min value of the picker.

void setOnLongPressUpdateInterval(long intervalMillis)

Sets the speed at which the numbers be incremented and decremented when the up and down buttons are long pressed respectively.

void setOnScrollListener(NumberPicker.OnScrollListener onScrollListener)

Set listener to be notified for scroll state changes.

void setOnValueChangedListener(NumberPicker.OnValueChangeListener onValueChangedListener)

Sets the listener to be notified on change of the current value.

void setSelectionDividerHeight(int height)

Set the height for the divider that separates the currently selected value from the others.

void setTextColor(int color)

Sets the text color for all the states (normal, selected, focused) to be the given color.

void setTextSize(float size)

Sets the text size to the given value.

void setValue(int value)

Set the current value for the number picker.

void setWrapSelectorWheel(boolean wrapSelectorWheel)

Sets whether the selector wheel shown during flinging/scrolling should wrap around the NumberPicker#getMinValue() and NumberPicker#getMaxValue() values.

Protected methods

int computeVerticalScrollExtent()

Compute the vertical extent of the vertical scrollbar's thumb within the vertical range.

int computeVerticalScrollOffset()

Compute the vertical offset of the vertical scrollbar's thumb within the horizontal range.

int computeVerticalScrollRange()

Compute the vertical range that the vertical scrollbar represents.

boolean dispatchHoverEvent(MotionEvent event)

Dispatch a hover event.

void drawableStateChanged()

This function is called whenever the state of the view changes in such a way that it impacts the state of drawables being shown. If you override this method you must call through to the superclass implementation.

float getBottomFadingEdgeStrength()

Returns the strength, or intensity, of the bottom faded edge.

float getTopFadingEdgeStrength()

Returns the strength, or intensity, of the top faded edge.

void onDetachedFromWindow()

This is called when the view is detached from a window.

void onDraw(Canvas canvas)

Implement this to do your drawing.

void onLayout(boolean changed, int left, int top, int right, int bottom)

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.

Inherited methods

Public constructors

NumberPicker

Added in API level 11
public NumberPicker (Context context)

Create a new number picker.

Parameters
context Context: The application environment.

NumberPicker

Added in API level 11
public NumberPicker (Context context, 
                AttributeSet attrs)

Create a new number picker.

Parameters
context Context: The application environment.

attrs AttributeSet: A collection of attributes.

NumberPicker

Added in API level 11
public NumberPicker (Context context, 
                AttributeSet attrs, 
                int defStyleAttr)

Create a new number picker

Parameters
context Context: the application environment.

attrs AttributeSet: a collection of attributes.

defStyleAttr int: 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.

NumberPicker

Added in API level 21
public NumberPicker (Context context, 
                AttributeSet attrs, 
                int defStyleAttr, 
                int defStyleRes)

Create a new number picker

Parameters
context Context: the application environment.

attrs AttributeSet: a collection of attributes.

defStyleAttr int: 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 int: 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.

Public methods

computeScroll

Added in API level 11
public void computeScroll ()

Called by a parent to request that a child update its values for mScrollX and mScrollY if necessary. This will typically be done if the child is animating a scroll using a Scroller object.

dispatchKeyEvent

Added in API level 11
public boolean dispatchKeyEvent (KeyEvent event)

Dispatch a key event to the next view on the focus path. This path runs from the top of the view tree down to the currently focused view. If this view has focus, it will dispatch to itself. Otherwise it will dispatch the next node down the focus path. This method also fires any key listeners.

Parameters
event KeyEvent: The key event to be dispatched.

Returns
boolean True if the event was handled, false otherwise.

dispatchTouchEvent

Added in API level 11
public boolean dispatchTouchEvent (MotionEvent event)

Pass the touch screen motion event down to the target view, or this view if it is the target.

Parameters
event MotionEvent: The motion event to be dispatched.

Returns
boolean True if the event was handled by the view, false otherwise.

dispatchTrackballEvent

Added in API level 11
public boolean dispatchTrackballEvent (MotionEvent event)

Pass a trackball motion event down to the focused view.

Parameters
event MotionEvent: The motion event to be dispatched.

Returns
boolean True if the event was handled by the view, false otherwise.

getAccessibilityNodeProvider

Added in API level 16
public AccessibilityNodeProvider getAccessibilityNodeProvider ()

Gets the provider for managing a virtual view hierarchy rooted at this View and reported to AccessibilityServices that explore the window content.

If this method returns an instance, this instance is responsible for managing AccessibilityNodeInfos describing the virtual sub-tree rooted at this View including the one representing the View itself. Similarly the returned instance is responsible for performing accessibility actions on any virtual view or the root view itself.

If an AccessibilityDelegate has been specified via calling setAccessibilityDelegate(android.view.View.AccessibilityDelegate) its AccessibilityDelegate#getAccessibilityNodeProvider(View) is responsible for handling this call.

Returns
AccessibilityNodeProvider The provider.

getDisplayedValues

Added in API level 11
public String[] getDisplayedValues ()

Gets the values to be displayed instead of string values.

Returns
String[] The displayed values.

getMaxValue

Added in API level 11
public int getMaxValue ()

Returns the max value of the picker.

Returns
int The max value.

getMinValue

Added in API level 11
public int getMinValue ()

Returns the min value of the picker.

Returns
int The min value

getSelectionDividerHeight

Added in API level 29
public int getSelectionDividerHeight ()

Retrieve the height for the divider that separates the currently selected value from the others.
The units of this value are pixels.

Returns
int The height of the divider The units of this value are pixels. {}

getSolidColor

Added in API level 11
public int getSolidColor ()

Override this if your view is known to always be drawn on top of a solid color background, and needs to draw fading edges. Returning a non-zero color enables the view system to optimize the drawing of the fading edges. If you do return a non-zero color, the alpha should be set to 0xFF.

Returns
int The known solid color background for this view, or 0 if the color may vary

getTextColor

Added in API level 29
public int getTextColor ()

Returns
int the text color.

getTextSize

Added in API level 29
public float getTextSize ()

Returns
float the size (in pixels) of the text size in this NumberPicker. Value is 0.0 or greater

getValue

Added in API level 11
public int getValue ()

Returns the value of the picker.

Returns
int The value.

getWrapSelectorWheel

Added in API level 11
public boolean getWrapSelectorWheel ()

Gets whether the selector wheel wraps when reaching the min/max value.

Returns
boolean True if the selector wheel wraps.

jumpDrawablesToCurrentState

Added in API level 11
public void jumpDrawablesToCurrentState ()

Call Drawable.jumpToCurrentState() on all Drawable objects associated with this view.

Also calls StateListAnimator#jumpToCurrentState() if there is a StateListAnimator attached to this view.
If you override this method you must call through to the superclass implementation. If you override this method you must call through to the superclass implementation.

onInterceptTouchEvent

Added in API level 11
public boolean onInterceptTouchEvent (MotionEvent event)

Implement this method to intercept all touch screen motion events. This allows you to watch events as they are dispatched to your children, and take ownership of the current gesture at any point.

Using this function takes some care, as it has a fairly complicated interaction with View.onTouchEvent(MotionEvent), and using it requires implementing that method as well as this one in the correct way. Events will be received in the following order:

  1. You will receive the down event here.
  2. The down event will be handled either by a child of this view group, or given to your own onTouchEvent() method to handle; this means you should implement onTouchEvent() to return true, so you will continue to see the rest of the gesture (instead of looking for a parent view to handle it). Also, by returning true from onTouchEvent(), you will not receive any following events in onInterceptTouchEvent() and all touch processing must happen in onTouchEvent() like normal.
  3. For as long as you return false from this function, each following event (up to and including the final up) will be delivered first here and then to the target's onTouchEvent().
  4. If you return true from here, you will not receive any following events: the target view will receive the same event but with the action MotionEvent#ACTION_CANCEL, and all further events will be delivered to your onTouchEvent() method and no longer appear here.

Parameters
event MotionEvent: The motion event being dispatched down the hierarchy.

Returns
boolean Return true to steal motion events from the children and have them dispatched to this ViewGroup through onTouchEvent(). The current target will receive an ACTION_CANCEL event, and no further messages will be delivered here.

onTouchEvent

Added in API level 11
public boolean onTouchEvent (MotionEvent event)

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 MotionEvent: The motion event.

Returns
boolean True if the event was handled, false otherwise.

performClick

Added in API level 11
public boolean performClick ()

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

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

performLongClick

Added in API level 11
public boolean performLongClick ()

Calls this view's OnLongClickListener, if it is defined. Invokes the context menu if the OnLongClickListener did not consume the event.

Returns
boolean true if one of the above receivers consumed the event, false otherwise

scrollBy

Added in API level 11
public void scrollBy (int x, 
                int y)

Move the scrolled position of your view. This will cause a call to onScrollChanged(int, int, int, int) and the view will be invalidated.

Parameters
x int: the amount of pixels to scroll by horizontally

y int: the amount of pixels to scroll by vertically

setDisplayedValues

Added in API level 11
public void setDisplayedValues (String[] displayedValues)

Sets the values to be displayed.

Parameters
displayedValues String: The displayed values. Note: The length of the displayed values array must be equal to the range of selectable numbers which is equal to getMaxValue() - getMinValue() + 1.

setEnabled

Added in API level 11
public void setEnabled (boolean enabled)

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

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

setFormatter

Added in API level 11
public void setFormatter (NumberPicker.Formatter formatter)

Set the formatter to be used for formatting the current value.

Note: If you have provided alternative values for the values this formatter is never invoked.

Parameters
formatter NumberPicker.Formatter: The formatter object. If formatter is null, String#valueOf(int) will be used.

setMaxValue

Added in API level 11
public void setMaxValue (int maxValue)

Sets the max value of the picker.

Parameters
maxValue int: The max value inclusive. Note: The length of the displayed values array set via setDisplayedValues(java.lang.String[]) must be equal to the range of selectable numbers which is equal to getMaxValue() - getMinValue() + 1.

setMinValue

Added in API level 11
public void setMinValue (int minValue)

Sets the min value of the picker.

Parameters
minValue int: The min value inclusive. Note: The length of the displayed values array set via setDisplayedValues(java.lang.String[]) must be equal to the range of selectable numbers which is equal to getMaxValue() - getMinValue() + 1.

setOnLongPressUpdateInterval

Added in API level 11
public void setOnLongPressUpdateInterval (long intervalMillis)

Sets the speed at which the numbers be incremented and decremented when the up and down buttons are long pressed respectively.

The default value is 300 ms.

Parameters
intervalMillis long: The speed (in milliseconds) at which the numbers will be incremented and decremented.

setOnScrollListener

Added in API level 11
public void setOnScrollListener (NumberPicker.OnScrollListener onScrollListener)

Set listener to be notified for scroll state changes.

Parameters
onScrollListener NumberPicker.OnScrollListener: The listener.

setOnValueChangedListener

Added in API level 11
public void setOnValueChangedListener (NumberPicker.OnValueChangeListener onValueChangedListener)

Sets the listener to be notified on change of the current value.

Parameters
onValueChangedListener NumberPicker.OnValueChangeListener: The listener.

setSelectionDividerHeight

Added in API level 29
public void setSelectionDividerHeight (int height)

Set the height for the divider that separates the currently selected value from the others.

Parameters
height int: The height to be set Value is 0 or greater The units of this value are pixels.

setTextColor

Added in API level 29
public void setTextColor (int color)

Sets the text color for all the states (normal, selected, focused) to be the given color.

Parameters
color int: A color value in the form 0xAARRGGBB.

setTextSize

Added in API level 29
public void setTextSize (float size)

Sets the text size to the given value. This value must be > 0

Parameters
size float: The size in pixel units. Value is 0.0 or greater

setValue

Added in API level 11
public void setValue (int value)

Set the current value for the number picker.

If the argument is less than the NumberPicker#getMinValue() and NumberPicker#getWrapSelectorWheel() is false the current value is set to the NumberPicker#getMinValue() value.

If the argument is less than the NumberPicker#getMinValue() and NumberPicker#getWrapSelectorWheel() is true the current value is set to the NumberPicker#getMaxValue() value.

If the argument is more than the NumberPicker#getMaxValue() and NumberPicker#getWrapSelectorWheel() is false the current value is set to the NumberPicker#getMaxValue() value.

If the argument is more than the NumberPicker#getMaxValue() and NumberPicker#getWrapSelectorWheel() is true the current value is set to the NumberPicker#getMinValue() value.

Parameters
value int: The current value.

setWrapSelectorWheel

Added in API level 11
public void setWrapSelectorWheel (boolean wrapSelectorWheel)

Sets whether the selector wheel shown during flinging/scrolling should wrap around the NumberPicker#getMinValue() and NumberPicker#getMaxValue() values.

By default if the range (max - min) is more than the number of items shown on the selector wheel the selector wheel wrapping is enabled.

Note: If the number of items, i.e. the range ( getMaxValue() - getMinValue()) is less than the number of items shown on the selector wheel, the selector wheel will not wrap. Hence, in such a case calling this method is a NOP.

Parameters
wrapSelectorWheel boolean: Whether to wrap.

Protected methods

computeVerticalScrollExtent

Added in API level 11
protected int computeVerticalScrollExtent ()

Compute the vertical extent of the vertical scrollbar's thumb within the vertical range. This value is used to compute the length of the thumb within the scrollbar's track.

The range is expressed in arbitrary units that must be the same as the units used by computeVerticalScrollRange() and computeVerticalScrollOffset().

The default extent is the drawing height of this view.

Returns
int the vertical extent of the scrollbar's thumb

computeVerticalScrollOffset

Added in API level 11
protected int computeVerticalScrollOffset ()

Compute the vertical offset of the vertical scrollbar's thumb within the horizontal range. This value is used to compute the position of the thumb within the scrollbar's track.

The range is expressed in arbitrary units that must be the same as the units used by computeVerticalScrollRange() and computeVerticalScrollExtent().

The default offset is the scroll offset of this view.

Returns
int the vertical offset of the scrollbar's thumb

computeVerticalScrollRange

Added in API level 11
protected int computeVerticalScrollRange ()

Compute the vertical range that the vertical scrollbar represents.

The range is expressed in arbitrary units that must be the same as the units used by computeVerticalScrollExtent() and computeVerticalScrollOffset().

Returns
int the total vertical range represented by the vertical scrollbar

The default range is the drawing height of this view.

dispatchHoverEvent

Added in API level 14
protected boolean dispatchHoverEvent (MotionEvent event)

Dispatch a hover event.

Do not call this method directly. Call dispatchGenericMotionEvent(android.view.MotionEvent) instead.

Parameters
event MotionEvent: The motion event to be dispatched.

Returns
boolean True if the event was handled by the view, false otherwise.

drawableStateChanged

Added in API level 11
protected void drawableStateChanged ()

This function is called whenever the state of the view changes in such a way that it impacts the state of drawables being shown.

If the View has a StateListAnimator, it will also be called to run necessary state change animations.

Be sure to call through to the superclass when overriding this function.
If you override this method you must call through to the superclass implementation. If you override this method you must call through to the superclass implementation.

getBottomFadingEdgeStrength

Added in API level 11
protected float getBottomFadingEdgeStrength ()

Returns the strength, or intensity, of the bottom faded edge. The strength is a value between 0.0 (no fade) and 1.0 (full fade). The default implementation returns 0.0 or 1.0 but no value in between. Subclasses should override this method to provide a smoother fade transition when scrolling occurs.

Returns
float the intensity of the bottom fade as a float between 0.0f and 1.0f

getTopFadingEdgeStrength

Added in API level 11
protected float getTopFadingEdgeStrength ()

Returns the strength, or intensity, of the top faded edge. The strength is a value between 0.0 (no fade) and 1.0 (full fade). The default implementation returns 0.0 or 1.0 but no value in between. Subclasses should override this method to provide a smoother fade transition when scrolling occurs.

Returns
float the intensity of the top fade as a float between 0.0f and 1.0f

onDetachedFromWindow

Added in API level 11
protected void onDetachedFromWindow ()

This is called when the view is detached from a window. At this point it no longer has a surface for drawing.
If you override this method you must call through to the superclass implementation.

onDraw

Added in API level 11
protected void onDraw (Canvas canvas)

Implement this to do your drawing.

Parameters
canvas Canvas: the canvas on which the background will be drawn This value cannot be null.

onLayout

Added in API level 11
protected void onLayout (boolean changed, 
                int left, 
                int top, 
                int right, 
                int bottom)

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 boolean: This is a new size or position for this view

left int: Left position, relative to parent

top int: Top position, relative to parent

right int: Right position, relative to parent

bottom int: Bottom position, relative to parent

onMeasure

Added in API level 11
protected void onMeasure (int widthMeasureSpec, 
                int heightMeasureSpec)

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 overridden 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 int: horizontal space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.

heightMeasureSpec int: vertical space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.