RatingBar.java revision 617feb99a06e7ffb3894e86a286bf30e085f321a
1/* 2 * Copyright (C) 2007 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.widget; 18 19import android.content.Context; 20import android.content.res.TypedArray; 21import android.graphics.drawable.shapes.RectShape; 22import android.graphics.drawable.shapes.Shape; 23import android.util.AttributeSet; 24import android.view.accessibility.AccessibilityEvent; 25import android.view.accessibility.AccessibilityNodeInfo; 26 27import com.android.internal.R; 28 29/** 30 * A RatingBar is an extension of SeekBar and ProgressBar that shows a rating in 31 * stars. The user can touch/drag or use arrow keys to set the rating when using 32 * the default size RatingBar. The smaller RatingBar style ( 33 * {@link android.R.attr#ratingBarStyleSmall}) and the larger indicator-only 34 * style ({@link android.R.attr#ratingBarStyleIndicator}) do not support user 35 * interaction and should only be used as indicators. 36 * <p> 37 * When using a RatingBar that supports user interaction, placing widgets to the 38 * left or right of the RatingBar is discouraged. 39 * <p> 40 * The number of stars set (via {@link #setNumStars(int)} or in an XML layout) 41 * will be shown when the layout width is set to wrap content (if another layout 42 * width is set, the results may be unpredictable). 43 * <p> 44 * The secondary progress should not be modified by the client as it is used 45 * internally as the background for a fractionally filled star. 46 * 47 * @attr ref android.R.styleable#RatingBar_numStars 48 * @attr ref android.R.styleable#RatingBar_rating 49 * @attr ref android.R.styleable#RatingBar_stepSize 50 * @attr ref android.R.styleable#RatingBar_isIndicator 51 */ 52public class RatingBar extends AbsSeekBar { 53 54 /** 55 * A callback that notifies clients when the rating has been changed. This 56 * includes changes that were initiated by the user through a touch gesture 57 * or arrow key/trackball as well as changes that were initiated 58 * programmatically. 59 */ 60 public interface OnRatingBarChangeListener { 61 62 /** 63 * Notification that the rating has changed. Clients can use the 64 * fromUser parameter to distinguish user-initiated changes from those 65 * that occurred programmatically. This will not be called continuously 66 * while the user is dragging, only when the user finalizes a rating by 67 * lifting the touch. 68 * 69 * @param ratingBar The RatingBar whose rating has changed. 70 * @param rating The current rating. This will be in the range 71 * 0..numStars. 72 * @param fromUser True if the rating change was initiated by a user's 73 * touch gesture or arrow key/horizontal trackbell movement. 74 */ 75 void onRatingChanged(RatingBar ratingBar, float rating, boolean fromUser); 76 77 } 78 79 private int mNumStars = 5; 80 81 private int mProgressOnStartTracking; 82 83 private OnRatingBarChangeListener mOnRatingBarChangeListener; 84 85 public RatingBar(Context context, AttributeSet attrs, int defStyleAttr) { 86 this(context, attrs, defStyleAttr, 0); 87 } 88 89 public RatingBar(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes) { 90 super(context, attrs, defStyleAttr, defStyleRes); 91 92 final TypedArray a = context.obtainStyledAttributes( 93 attrs, R.styleable.RatingBar, defStyleAttr, defStyleRes); 94 final int numStars = a.getInt(R.styleable.RatingBar_numStars, mNumStars); 95 setIsIndicator(a.getBoolean(R.styleable.RatingBar_isIndicator, !mIsUserSeekable)); 96 final float rating = a.getFloat(R.styleable.RatingBar_rating, -1); 97 final float stepSize = a.getFloat(R.styleable.RatingBar_stepSize, -1); 98 a.recycle(); 99 100 if (numStars > 0 && numStars != mNumStars) { 101 setNumStars(numStars); 102 } 103 104 if (stepSize >= 0) { 105 setStepSize(stepSize); 106 } else { 107 setStepSize(0.5f); 108 } 109 110 if (rating >= 0) { 111 setRating(rating); 112 } 113 114 // A touch inside a star fill up to that fractional area (slightly more 115 // than 1 so boundaries round up). 116 mTouchProgressOffset = 1.1f; 117 } 118 119 public RatingBar(Context context, AttributeSet attrs) { 120 this(context, attrs, com.android.internal.R.attr.ratingBarStyle); 121 } 122 123 public RatingBar(Context context) { 124 this(context, null); 125 } 126 127 /** 128 * Sets the listener to be called when the rating changes. 129 * 130 * @param listener The listener. 131 */ 132 public void setOnRatingBarChangeListener(OnRatingBarChangeListener listener) { 133 mOnRatingBarChangeListener = listener; 134 } 135 136 /** 137 * @return The listener (may be null) that is listening for rating change 138 * events. 139 */ 140 public OnRatingBarChangeListener getOnRatingBarChangeListener() { 141 return mOnRatingBarChangeListener; 142 } 143 144 /** 145 * Whether this rating bar should only be an indicator (thus non-changeable 146 * by the user). 147 * 148 * @param isIndicator Whether it should be an indicator. 149 * 150 * @attr ref android.R.styleable#RatingBar_isIndicator 151 */ 152 public void setIsIndicator(boolean isIndicator) { 153 mIsUserSeekable = !isIndicator; 154 setFocusable(!isIndicator); 155 } 156 157 /** 158 * @return Whether this rating bar is only an indicator. 159 * 160 * @attr ref android.R.styleable#RatingBar_isIndicator 161 */ 162 public boolean isIndicator() { 163 return !mIsUserSeekable; 164 } 165 166 /** 167 * Sets the number of stars to show. In order for these to be shown 168 * properly, it is recommended the layout width of this widget be wrap 169 * content. 170 * 171 * @param numStars The number of stars. 172 */ 173 public void setNumStars(final int numStars) { 174 if (numStars <= 0) { 175 return; 176 } 177 178 mNumStars = numStars; 179 180 // This causes the width to change, so re-layout 181 requestLayout(); 182 } 183 184 /** 185 * Returns the number of stars shown. 186 * @return The number of stars shown. 187 */ 188 public int getNumStars() { 189 return mNumStars; 190 } 191 192 /** 193 * Sets the rating (the number of stars filled). 194 * 195 * @param rating The rating to set. 196 */ 197 public void setRating(float rating) { 198 setProgress(Math.round(rating * getProgressPerStar())); 199 } 200 201 /** 202 * Gets the current rating (number of stars filled). 203 * 204 * @return The current rating. 205 */ 206 public float getRating() { 207 return getProgress() / getProgressPerStar(); 208 } 209 210 /** 211 * Sets the step size (granularity) of this rating bar. 212 * 213 * @param stepSize The step size of this rating bar. For example, if 214 * half-star granularity is wanted, this would be 0.5. 215 */ 216 public void setStepSize(float stepSize) { 217 if (stepSize <= 0) { 218 return; 219 } 220 221 final float newMax = mNumStars / stepSize; 222 final int newProgress = (int) (newMax / getMax() * getProgress()); 223 setMax((int) newMax); 224 setProgress(newProgress); 225 } 226 227 /** 228 * Gets the step size of this rating bar. 229 * 230 * @return The step size. 231 */ 232 public float getStepSize() { 233 return (float) getNumStars() / getMax(); 234 } 235 236 /** 237 * @return The amount of progress that fits into a star 238 */ 239 private float getProgressPerStar() { 240 if (mNumStars > 0) { 241 return 1f * getMax() / mNumStars; 242 } else { 243 return 1; 244 } 245 } 246 247 @Override 248 Shape getDrawableShape() { 249 // TODO: Once ProgressBar's TODOs are fixed, this won't be needed 250 return new RectShape(); 251 } 252 253 @Override 254 void onProgressRefresh(float scale, boolean fromUser) { 255 super.onProgressRefresh(scale, fromUser); 256 257 // Keep secondary progress in sync with primary 258 updateSecondaryProgress(getProgress()); 259 260 if (!fromUser) { 261 // Callback for non-user rating changes 262 dispatchRatingChange(false); 263 } 264 } 265 266 /** 267 * The secondary progress is used to differentiate the background of a 268 * partially filled star. This method keeps the secondary progress in sync 269 * with the progress. 270 * 271 * @param progress The primary progress level. 272 */ 273 private void updateSecondaryProgress(int progress) { 274 final float ratio = getProgressPerStar(); 275 if (ratio > 0) { 276 final float progressInStars = progress / ratio; 277 final int secondaryProgress = (int) (Math.ceil(progressInStars) * ratio); 278 setSecondaryProgress(secondaryProgress); 279 } 280 } 281 282 @Override 283 protected synchronized void onMeasure(int widthMeasureSpec, int heightMeasureSpec) { 284 super.onMeasure(widthMeasureSpec, heightMeasureSpec); 285 286 if (mSampleTile != null) { 287 // TODO: Once ProgressBar's TODOs are gone, this can be done more 288 // cleanly than mSampleTile 289 final int width = mSampleTile.getWidth() * mNumStars; 290 setMeasuredDimension(resolveSizeAndState(width, widthMeasureSpec, 0), 291 getMeasuredHeight()); 292 } 293 } 294 295 @Override 296 void onStartTrackingTouch() { 297 mProgressOnStartTracking = getProgress(); 298 299 super.onStartTrackingTouch(); 300 } 301 302 @Override 303 void onStopTrackingTouch() { 304 super.onStopTrackingTouch(); 305 306 if (getProgress() != mProgressOnStartTracking) { 307 dispatchRatingChange(true); 308 } 309 } 310 311 @Override 312 void onKeyChange() { 313 super.onKeyChange(); 314 dispatchRatingChange(true); 315 } 316 317 void dispatchRatingChange(boolean fromUser) { 318 if (mOnRatingBarChangeListener != null) { 319 mOnRatingBarChangeListener.onRatingChanged(this, getRating(), 320 fromUser); 321 } 322 } 323 324 @Override 325 public synchronized void setMax(int max) { 326 // Disallow max progress = 0 327 if (max <= 0) { 328 return; 329 } 330 331 super.setMax(max); 332 } 333 334 @Override 335 public void onInitializeAccessibilityEvent(AccessibilityEvent event) { 336 super.onInitializeAccessibilityEvent(event); 337 event.setClassName(RatingBar.class.getName()); 338 } 339 340 @Override 341 public void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) { 342 super.onInitializeAccessibilityNodeInfo(info); 343 info.setClassName(RatingBar.class.getName()); 344 } 345} 346