1/* 2 * Copyright (C) 2013 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.media; 18 19import android.graphics.Bitmap; 20import android.os.Parcel; 21import android.os.Parcelable; 22import android.util.Log; 23 24/** 25 * A class to encapsulate rating information used as content metadata. 26 * A rating is defined by its rating style (see {@link #RATING_HEART}, 27 * {@link #RATING_THUMB_UP_DOWN}, {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, 28 * {@link #RATING_5_STARS} or {@link #RATING_PERCENTAGE}) and the actual rating value (which may 29 * be defined as "unrated"), both of which are defined when the rating instance is constructed 30 * through one of the factory methods. 31 */ 32public final class Rating implements Parcelable { 33 34 private final static String TAG = "Rating"; 35 36 /** 37 * A rating style with a single degree of rating, "heart" vs "no heart". Can be used to 38 * indicate the content referred to is a favorite (or not). 39 */ 40 public final static int RATING_HEART = 1; 41 42 /** 43 * A rating style for "thumb up" vs "thumb down". 44 */ 45 public final static int RATING_THUMB_UP_DOWN = 2; 46 47 /** 48 * A rating style with 0 to 3 stars. 49 */ 50 public final static int RATING_3_STARS = 3; 51 52 /** 53 * A rating style with 0 to 4 stars. 54 */ 55 public final static int RATING_4_STARS = 4; 56 57 /** 58 * A rating style with 0 to 5 stars. 59 */ 60 public final static int RATING_5_STARS = 5; 61 62 /** 63 * A rating style expressed as a percentage. 64 */ 65 public final static int RATING_PERCENTAGE = 6; 66 67 private final static float RATING_NOT_RATED = -1.0f; 68 69 private final int mRatingStyle; 70 71 private final float mRatingValue; 72 73 private Rating(int ratingStyle, float rating) { 74 mRatingStyle = ratingStyle; 75 mRatingValue = rating; 76 } 77 78 79 /** 80 * @hide 81 */ 82 @Override 83 public String toString () { 84 return "Rating:style=" + mRatingStyle + " rating=" 85 + (mRatingValue < 0.0f ? "unrated" : String.valueOf(mRatingValue)); 86 } 87 88 @Override 89 public int describeContents() { 90 return mRatingStyle; 91 } 92 93 @Override 94 public void writeToParcel(Parcel dest, int flags) { 95 dest.writeInt(mRatingStyle); 96 dest.writeFloat(mRatingValue); 97 } 98 99 public static final Parcelable.Creator<Rating> CREATOR 100 = new Parcelable.Creator<Rating>() { 101 /** 102 * Rebuilds a Rating previously stored with writeToParcel(). 103 * @param p Parcel object to read the Rating from 104 * @return a new Rating created from the data in the parcel 105 */ 106 public Rating createFromParcel(Parcel p) { 107 return new Rating(p.readInt(), p.readFloat()); 108 } 109 public Rating[] newArray(int size) { 110 return new Rating[size]; 111 } 112 }; 113 114 /** 115 * Return a Rating instance with no rating. 116 * Create and return a new Rating instance with no rating known for the given 117 * rating style. 118 * @param ratingStyle one of {@link #RATING_HEART}, {@link #RATING_THUMB_UP_DOWN}, 119 * {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, {@link #RATING_5_STARS}, 120 * or {@link #RATING_PERCENTAGE}. 121 * @return null if an invalid rating style is passed, a new Rating instance otherwise. 122 */ 123 public static Rating newUnratedRating(int ratingStyle) { 124 switch(ratingStyle) { 125 case RATING_HEART: 126 case RATING_THUMB_UP_DOWN: 127 case RATING_3_STARS: 128 case RATING_4_STARS: 129 case RATING_5_STARS: 130 case RATING_PERCENTAGE: 131 return new Rating(ratingStyle, RATING_NOT_RATED); 132 default: 133 return null; 134 } 135 } 136 137 /** 138 * Return a Rating instance with a heart-based rating. 139 * Create and return a new Rating instance with a rating style of {@link #RATING_HEART}, 140 * and a heart-based rating. 141 * @param hasHeart true for a "heart selected" rating, false for "heart unselected". 142 * @return a new Rating instance. 143 */ 144 public static Rating newHeartRating(boolean hasHeart) { 145 return new Rating(RATING_HEART, hasHeart ? 1.0f : 0.0f); 146 } 147 148 /** 149 * Return a Rating instance with a thumb-based rating. 150 * Create and return a new Rating instance with a {@link #RATING_THUMB_UP_DOWN} 151 * rating style, and a "thumb up" or "thumb down" rating. 152 * @param thumbIsUp true for a "thumb up" rating, false for "thumb down". 153 * @return a new Rating instance. 154 */ 155 public static Rating newThumbRating(boolean thumbIsUp) { 156 return new Rating(RATING_THUMB_UP_DOWN, thumbIsUp ? 1.0f : 0.0f); 157 } 158 159 /** 160 * Return a Rating instance with a star-based rating. 161 * Create and return a new Rating instance with one of the star-base rating styles 162 * and the given integer or fractional number of stars. Non integer values can for instance 163 * be used to represent an average rating value, which might not be an integer number of stars. 164 * @param starRatingStyle one of {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, 165 * {@link #RATING_5_STARS}. 166 * @param starRating a number ranging from 0.0f to 3.0f, 4.0f or 5.0f according to 167 * the rating style. 168 * @return null if the rating style is invalid, or the rating is out of range, 169 * a new Rating instance otherwise. 170 */ 171 public static Rating newStarRating(int starRatingStyle, float starRating) { 172 float maxRating = -1.0f; 173 switch(starRatingStyle) { 174 case RATING_3_STARS: 175 maxRating = 3.0f; 176 break; 177 case RATING_4_STARS: 178 maxRating = 4.0f; 179 break; 180 case RATING_5_STARS: 181 maxRating = 5.0f; 182 break; 183 default: 184 Log.e(TAG, "Invalid rating style (" + starRatingStyle + ") for a star rating"); 185 return null; 186 } 187 if ((starRating < 0.0f) || (starRating > maxRating)) { 188 Log.e(TAG, "Trying to set out of range star-based rating"); 189 return null; 190 } 191 return new Rating(starRatingStyle, starRating); 192 } 193 194 /** 195 * Return a Rating instance with a percentage-based rating. 196 * Create and return a new Rating instance with a {@link #RATING_PERCENTAGE} 197 * rating style, and a rating of the given percentage. 198 * @param percent the value of the rating 199 * @return null if the rating is out of range, a new Rating instance otherwise. 200 */ 201 public static Rating newPercentageRating(float percent) { 202 if ((percent < 0.0f) || (percent > 100.0f)) { 203 Log.e(TAG, "Invalid percentage-based rating value"); 204 return null; 205 } else { 206 return new Rating(RATING_PERCENTAGE, percent); 207 } 208 } 209 210 /** 211 * Return whether there is a rating value available. 212 * @return true if the instance was not created with {@link #newUnratedRating(int)}. 213 */ 214 public boolean isRated() { 215 return mRatingValue >= 0.0f; 216 } 217 218 /** 219 * Return the rating style. 220 * @return one of {@link #RATING_HEART}, {@link #RATING_THUMB_UP_DOWN}, 221 * {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, {@link #RATING_5_STARS}, 222 * or {@link #RATING_PERCENTAGE}. 223 */ 224 public int getRatingStyle() { 225 return mRatingStyle; 226 } 227 228 /** 229 * Return whether the rating is "heart selected". 230 * @return true if the rating is "heart selected", false if the rating is "heart unselected", 231 * if the rating style is not {@link #RATING_HEART} or if it is unrated. 232 */ 233 public boolean hasHeart() { 234 if (mRatingStyle != RATING_HEART) { 235 return false; 236 } else { 237 return (mRatingValue == 1.0f); 238 } 239 } 240 241 /** 242 * Return whether the rating is "thumb up". 243 * @return true if the rating is "thumb up", false if the rating is "thumb down", 244 * if the rating style is not {@link #RATING_THUMB_UP_DOWN} or if it is unrated. 245 */ 246 public boolean isThumbUp() { 247 if (mRatingStyle != RATING_THUMB_UP_DOWN) { 248 return false; 249 } else { 250 return (mRatingValue == 1.0f); 251 } 252 } 253 254 /** 255 * Return the star-based rating value. 256 * @return a rating value greater or equal to 0.0f, or a negative value if the rating style is 257 * not star-based, or if it is unrated. 258 */ 259 public float getStarRating() { 260 switch (mRatingStyle) { 261 case RATING_3_STARS: 262 case RATING_4_STARS: 263 case RATING_5_STARS: 264 if (isRated()) { 265 return mRatingValue; 266 } 267 default: 268 return -1.0f; 269 } 270 } 271 272 /** 273 * Return the percentage-based rating value. 274 * @return a rating value greater or equal to 0.0f, or a negative value if the rating style is 275 * not percentage-based, or if it is unrated. 276 */ 277 public float getPercentRating() { 278 if ((mRatingStyle != RATING_PERCENTAGE) || !isRated()) { 279 return -1.0f; 280 } else { 281 return mRatingValue; 282 } 283 } 284}