NumberPickerView

Another NumberPicker with more flexible attributes on Android platform

[Chinese][6]

Forewords

some android projects use the android.widget.NumberPicker to provide alternative choices, but the default style of NumberPicker has some inflexible attibutes, and complicated to be customized.This NumberPickerView extends from View, and provide a friendly experience.

ScreenShot

![Example Image][4]<br> picking an item dynamically

![Example Image][5]<br>

![Example Image][2]<br>

![Example Image][3]<br> a small project powered by NumberPickerView, a view which can pick or jump to a certain date with two modes, in Gregorian mode or in Chinese Lunar mode. The gif seem to be a little lag, but actually it runs smoothly. Check the project here: https://github.com/Carbs0126/GregorianLunarCalendar

Introduction

NumberPickerViewextends from View and has almost all functions of android.widget.NumberPicker except inputting fuction by EditText, but it has some advanced features, here are these two views' differences below:

Features of android.widget.NumberPicker

1. the NumberPicker's viewport can only show three items;
2. the value of friction is big, you can not pick a new value smoothly by fling;
3. no animation if you use setValue() in java code to set to a new value;
4. no animation if you use setDisplayValues() to change the content of NumberPicker;
5. has a bug if you set wrap mode by using setWrapSelectorWheel(), sometimes NumberPicker will not refresh canvas after setWrapSelectorWheel() until it receive a new MotionEvent;
6. no text hint at the center position;
7. cannot control NumberPicker to smoothly scroll to a certain item (position);
8. NumberPicker class in early version of some customized framework has bugs when changing maxValue and displayedValues.

Capabilities of NumberPickerView

1. the NumberPickerView's viewport can show more than three items;
2. able to set the value of friction in java code, you can pick a new value smoothly by fling, in java code, you can use the code below to make friction be twice as former<br> mNumberPickerView.setFriction(2 * ViewConfiguration.get(mContext).getScrollFriction());
3. items' texts has animation between selected mode and normal mode, including Gradient textColor and Gradient textSize;
4. able to choose if use animation when changing displayedValues;
5. able to setWrapSelectorWheel() dynamically in java code or in xml;
6. able to set a hint text at the center position, default is empty; can change the hint text's color and textSize;
7. able to scroll smoothly to a centain item (position);
8. support wrap_content mode,support item's padding
9. has some other attibutes to refine UI
10. not respond onValueChanged() during scrolling
11. press the certain item, NumberPickerView will scroll to this item automatically
12. you can set if the onValueChanged callbacks invoked in main thread or in sub thread;
13. NumberPickerView has some same compatible fuctions and interfaces with NumberPicker, this makes it easier to change NumberPicker to NumberPickerView in project:

    //compatible fuctions
    setOnValueChangedListener()
    setOnScrollListener()
    setDisplayedValues()/getDisplayedValues()
    setWrapSelectorWheel()/getWrapSelectorWheel()
    setMinValue()/getMinValue()
    setMaxValue()/getMaxValue()
    setValue()/getValue()

    //compatible interfaces
    OnValueChangeListener
    OnScrollListener

How to use

1.import to project

    implementation 'cn.carbswang.android:NumberPickerView:1.2.0'

or

    <dependency>
      <groupId>cn.carbswang.android</groupId>
      <artifactId>NumberPickerView</artifactId>
      <version>1.2.0</version>
      <type>pom</type>
    </dependency>

2.add a NumberPickerView in xml

    <cn.carbswang.android.numberpickerview.library.NumberPickerView
        android:id="@+id/picker"
        android:layout_width="wrap_content"
        android:layout_height="240dp"
        android:layout_centerHorizontal="true"
        android:layout_marginTop="20dp"
        android:background="#11333333"
        android:contentDescription="test_number_picker_view"
        app:npv_RespondChangeOnDetached="false"
        app:npv_ItemPaddingHorizontal="5dp"
        app:npv_ItemPaddingVertical="5dp"
        app:npv_ShownCount="5"
        app:npv_TextSizeNormal="16sp"
        app:npv_TextSizeSelected="20sp"
        app:npv_WrapSelectorWheel="true"/>

3.control NumberPickerView in Java code 1)if the displayedValues in NumberPickerView will NOT change, you can set data by this way: (same as using NumberPicker)

        picker.setMinValue(minValue);
        picker.setMaxValue(maxValue);
        picker.setValue(value);

2)if the displayedValues in NumberPickerView will change, you can set data by this way: (same as using NumberPicker)

        int minValue = getMinValue();
        int oldMaxValue = getMaxValue();
        int oldSpan = oldMaxValue - minValue + 1;
        int newMaxValue = display.length - 1;
        int newSpan = newMaxValue - minValue + 1;
        if (newSpan > oldSpan) {
            setDisplayedValues(display);
            setMaxValue(newMaxValue);
        } else {
            setMaxValue(newMaxValue);
            setDisplayedValues(display);
        }

OR use NumberPickerView's method: <br> refreshByNewDisplayedValues(String[] display)<br> but make sure the minValue will NOT change before and after using this method, and display should not be null, and its length should be greater than 0.

4.NumberPickerView also have methods to scroll smoothly <br> public void smoothScrollToValue(int fromValue, int toValue, boolean needRespond)<br>

the same point between this method and setValue(int)is you can set the current picked item dynamically, the difference is this method can make NumberPickerView scroll smoothly from fromValue to toValue by choosing short distance, the third argument needRespond is a boolean flag used to set if you want NumberPickerView invoke its onValueChanged callback when scrolling finished this time, because if several NumberPickerViews have interconnections, the early stopped NumberPickerView invoking callbacks will effect the latter stopped ones. So you can set this flag to be false to avoid invoking onValueChanged callback this time. <br>

and you'd better not use this method in onCreate(Bundle savedInstanceState), if have to do this, you can use in this way:

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        //some code ...
        mNumberPickerView.post(new Runnable() {
            @Override
            public void run() {
                //call smoothScrollToValue()
            }
        });
    }

5.introduction of attibutes in xml

    <declare-styleable name="NumberPickerView">
        <attr name="npv_ShownCount" format="reference|integer" />//the count of shown items , default is 3
        <attr name="npv_ShowDivider" format="reference|boolean" />//if show dividers
        <attr name="npv_DividerColor" format="reference|color" />//color of two dividers
        <attr name="npv_DividerMarginLeft" format="reference|dimension" />//divider's margin to the left
        <attr name="npv_DividerMarginRight" format="reference|dimension" />//divider's margin to the right
        <attr name="npv_DividerHeight" format="reference|dimension" />//divider's height
        <attr name="npv_TextColorNormal" format="reference|color" />//unselected textColor
        <attr name="npv_TextColorSelected" format="reference|color" />//selected textColor
        <attr name="npv_TextColorHint" format="reference|color" />//hint text color (the text in the center item)
        <attr name="npv_TextSizeNormal" format="reference|dimension" />//unselected textSize
        <attr name="npv_TextSizeSelected" format="reference|dimension" />//selected textColor
        <attr name="npv_TextSizeHint" format="reference|dimension" />//hint text size
        <attr name="npv_TextArray" format="reference" />//displayedValues
        <attr name="npv_MinValue" format="reference|integer" />//minValue, see as setMinValue()
        <attr name="npv_MaxValue" format="reference|integer" />//maxValue, see as setMaxValue()
        <attr name="npv_WrapSelectorWheel" format="reference|boolean" />//if set wrap mode, see as setWrapSelectorWheel(boolean)
        <attr name="npv_HintText" format="reference|string" />//hint text
        <attr name="npv_EmptyItemHint" format="reference|string" />//empty item's text,only shown when WrapSelectorWheel==false or displayedValues length not large than showCount
        <attr name="npv_MarginStartOfHint" format="reference|dimension" />//distance between hint and the right side of the max wide text in displayedValues
        <attr name="npv_MarginEndOfHint" format="reference|dimension" />//distance between hint and the right side of the view
        <attr name="npv_ItemPaddingHorizontal" format="reference|dimension" />//item's horizontal padding, used for wrap_content mode
        <attr name="npv_ItemPaddingVertical" format="reference|dimension" />//item's vertical padding, used for wrap_content mode
        <attr name="npv_RespondChangeOnDetached" format="reference|boolean" />//for reusable `Dialog/PopupWindow`.
        <attr name="npv_SelectedItemBackground" format="reference" />//for selected item background.
        //If `Dialog/PopupWindow` is hiding meanwhile `NumberPickerView` is still scrolling, then we need it to stop scrolling 
        //and respond (or not) `OnValueChange` callbacks and change the previous picked value. 
        //Add a new attr `npv_RespondChangeOnDetached` as a flag to set if respondding `onValueChange` call