FileDocCategorySizeDatePackage
RatingBar.javaAPI DocAndroid 1.5 API10242Wed May 06 22:41:56 BST 2009android.widget

RatingBar

public class RatingBar extends AbsSeekBar
A RatingBar is an extension of SeekBar and ProgressBar that shows a rating in stars. The user can touch/drag or use arrow keys to set the rating when using the default size RatingBar. The smaller RatingBar style ( {@link android.R.attr#ratingBarStyleSmall}) and the larger indicator-only style ({@link android.R.attr#ratingBarStyleIndicator}) do not support user interaction and should only be used as indicators.

When using a RatingBar that supports user interaction, placing widgets to the left or right of the RatingBar is discouraged.

The number of stars set (via {@link #setNumStars(int)} or in an XML layout) will be shown when the layout width is set to wrap content (if another layout width is set, the results may be unpredictable).

The secondary progress should not be modified by the client as it is used internally as the background for a fractionally filled star.

attr
ref android.R.styleable#RatingBar_numStars
attr
ref android.R.styleable#RatingBar_rating
attr
ref android.R.styleable#RatingBar_stepSize
attr
ref android.R.styleable#RatingBar_isIndicator

Fields Summary
private int
mNumStars
private int
mProgressOnStartTracking
private OnRatingBarChangeListener
mOnRatingBarChangeListener
Constructors Summary
public RatingBar(android.content.Context context, android.util.AttributeSet attrs, int defStyle)

    
           
        super(context, attrs, defStyle);
        
        TypedArray a = context.obtainStyledAttributes(attrs, R.styleable.RatingBar,
                defStyle, 0);
        final int numStars = a.getInt(R.styleable.RatingBar_numStars, mNumStars);
        setIsIndicator(a.getBoolean(R.styleable.RatingBar_isIndicator, !mIsUserSeekable));
        final float rating = a.getFloat(R.styleable.RatingBar_rating, -1);
        final float stepSize = a.getFloat(R.styleable.RatingBar_stepSize, -1);
        a.recycle();

        if (numStars > 0 && numStars != mNumStars) {
            setNumStars(numStars);            
        }
        
        if (stepSize >= 0) {
            setStepSize(stepSize);
        } else {
            setStepSize(0.5f);
        }
        
        if (rating >= 0) {
            setRating(rating);
        }
        
        // A touch inside a star fill up to that fractional area (slightly more
        // than 1 so boundaries round up).
        mTouchProgressOffset = 1.1f;
    
public RatingBar(android.content.Context context, android.util.AttributeSet attrs)

        this(context, attrs, com.android.internal.R.attr.ratingBarStyle);
    
public RatingBar(android.content.Context context)

        this(context, null);
    
Methods Summary
voiddispatchRatingChange(boolean fromUser)

        if (mOnRatingBarChangeListener != null) {
            mOnRatingBarChangeListener.onRatingChanged(this, getRating(),
                    fromUser);
        }
    
android.graphics.drawable.shapes.ShapegetDrawableShape()

        // TODO: Once ProgressBar's TODOs are fixed, this won't be needed
        return new RectShape();
    
public intgetNumStars()
Returns the number of stars shown.

return
The number of stars shown.

        return mNumStars;
    
public android.widget.RatingBar$OnRatingBarChangeListenergetOnRatingBarChangeListener()

return
The listener (may be null) that is listening for rating change events.

        return mOnRatingBarChangeListener;
    
private floatgetProgressPerStar()

return
The amount of progress that fits into a star

        if (mNumStars > 0) {
            return 1f * getMax() / mNumStars;
        } else {
            return 1;
        }
    
public floatgetRating()
Gets the current rating (number of stars filled).

return
The current rating.

        return getProgress() / getProgressPerStar();        
    
public floatgetStepSize()
Gets the step size of this rating bar.

return
The step size.

        return (float) getNumStars() / getMax();
    
public booleanisIndicator()

return
Whether this rating bar is only an indicator.

        return !mIsUserSeekable;
    
voidonKeyChange()

        super.onKeyChange();
        dispatchRatingChange(true);
    
protected synchronized voidonMeasure(int widthMeasureSpec, int heightMeasureSpec)

        super.onMeasure(widthMeasureSpec, heightMeasureSpec);
        
        if (mSampleTile != null) {
            // TODO: Once ProgressBar's TODOs are gone, this can be done more
            // cleanly than mSampleTile
            final int width = mSampleTile.getWidth() * mNumStars;
            setMeasuredDimension(resolveSize(width, widthMeasureSpec), mMeasuredHeight);
        }
    
voidonProgressRefresh(float scale, boolean fromUser)

        super.onProgressRefresh(scale, fromUser);

        // Keep secondary progress in sync with primary
        updateSecondaryProgress(getProgress());
        
        if (!fromUser) {
            // Callback for non-user rating changes
            dispatchRatingChange(false);
        }
    
voidonStartTrackingTouch()

        mProgressOnStartTracking = getProgress();
        
        super.onStartTrackingTouch();
    
voidonStopTrackingTouch()

        super.onStopTrackingTouch();

        if (getProgress() != mProgressOnStartTracking) {
            dispatchRatingChange(true);
        }
    
public voidsetIsIndicator(boolean isIndicator)
Whether this rating bar should only be an indicator (thus non-changeable by the user).

param
isIndicator Whether it should be an indicator.

        mIsUserSeekable = !isIndicator;
        setFocusable(!isIndicator);
    
public synchronized voidsetMax(int max)

        // Disallow max progress = 0
        if (max <= 0) {
            return;
        }
        
        super.setMax(max);
    
public voidsetNumStars(int numStars)
Sets the number of stars to show. In order for these to be shown properly, it is recommended the layout width of this widget be wrap content.

param
numStars The number of stars.

        if (numStars <= 0) {
            return;
        }
        
        mNumStars = numStars;
        
        // This causes the width to change, so re-layout
        requestLayout();
    
public voidsetOnRatingBarChangeListener(android.widget.RatingBar$OnRatingBarChangeListener listener)
Sets the listener to be called when the rating changes.

param
listener The listener.

        mOnRatingBarChangeListener = listener;
    
public voidsetRating(float rating)
Sets the rating (the number of stars filled).

param
rating The rating to set.

        setProgress(Math.round(rating * getProgressPerStar()));
    
public voidsetStepSize(float stepSize)
Sets the step size (granularity) of this rating bar.

param
stepSize The step size of this rating bar. For example, if half-star granularity is wanted, this would be 0.5.

        if (stepSize <= 0) {
            return;
        }
        
        final float newMax = mNumStars / stepSize;
        final int newProgress = (int) (newMax / getMax() * getProgress());
        setMax((int) newMax);
        setProgress(newProgress);
    
private voidupdateSecondaryProgress(int progress)
The secondary progress is used to differentiate the background of a partially filled star. This method keeps the secondary progress in sync with the progress.

param
progress The primary progress level.

        final float ratio = getProgressPerStar();
        if (ratio > 0) {
            final float progressInStars = progress / ratio;
            final int secondaryProgress = (int) (Math.ceil(progressInStars) * ratio);
            setSecondaryProgress(secondaryProgress);
        }