Rating2.java revision bb6ca486d1224e5d8c9427079a44223f55ce51c1
1/* 2 * Copyright 2018 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.annotation.NonNull; 20import android.annotation.Nullable; 21import android.annotation.IntDef; 22import android.annotation.SystemApi; 23import android.content.Context; 24import android.media.update.ApiLoader; 25import android.media.update.Rating2Provider; 26import android.os.Bundle; 27import android.util.Log; 28 29import java.lang.annotation.Retention; 30import java.lang.annotation.RetentionPolicy; 31 32/** 33 * A class to encapsulate rating information used as content metadata. 34 * A rating is defined by its rating style (see {@link #RATING_HEART}, 35 * {@link #RATING_THUMB_UP_DOWN}, {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, 36 * {@link #RATING_5_STARS} or {@link #RATING_PERCENTAGE}) and the actual rating value (which may 37 * be defined as "unrated"), both of which are defined when the rating instance is constructed 38 * through one of the factory methods. 39 * @hide 40 */ 41public final class Rating2 { 42 // Mostly same as the android.media.Rating, but it's no longer implements Parcelable for 43 // updatable support. 44 45 /** 46 * @hide 47 */ 48 @IntDef({RATING_NONE, RATING_HEART, RATING_THUMB_UP_DOWN, RATING_3_STARS, RATING_4_STARS, 49 RATING_5_STARS, RATING_PERCENTAGE}) 50 @Retention(RetentionPolicy.SOURCE) 51 public @interface Style {} 52 53 /** 54 * @hide 55 */ 56 @IntDef({RATING_3_STARS, RATING_4_STARS, RATING_5_STARS}) 57 @Retention(RetentionPolicy.SOURCE) 58 public @interface StarStyle {} 59 60 /** 61 * Indicates a rating style is not supported. A Rating2 will never have this 62 * type, but can be used by other classes to indicate they do not support 63 * Rating2. 64 */ 65 public final static int RATING_NONE = 0; 66 67 /** 68 * A rating style with a single degree of rating, "heart" vs "no heart". Can be used to 69 * indicate the content referred to is a favorite (or not). 70 */ 71 public final static int RATING_HEART = 1; 72 73 /** 74 * A rating style for "thumb up" vs "thumb down". 75 */ 76 public final static int RATING_THUMB_UP_DOWN = 2; 77 78 /** 79 * A rating style with 0 to 3 stars. 80 */ 81 public final static int RATING_3_STARS = 3; 82 83 /** 84 * A rating style with 0 to 4 stars. 85 */ 86 public final static int RATING_4_STARS = 4; 87 88 /** 89 * A rating style with 0 to 5 stars. 90 */ 91 public final static int RATING_5_STARS = 5; 92 93 /** 94 * A rating style expressed as a percentage. 95 */ 96 public final static int RATING_PERCENTAGE = 6; 97 98 private final Rating2Provider mProvider; 99 100 /** 101 * @hide 102 */ 103 @SystemApi 104 public Rating2(@NonNull Rating2Provider provider) { 105 mProvider = provider; 106 } 107 108 @Override 109 public String toString() { 110 return mProvider.toString_impl(); 111 } 112 113 /** 114 * @hide 115 */ 116 @SystemApi 117 public Rating2Provider getProvider() { 118 return mProvider; 119 } 120 121 @Override 122 public boolean equals(Object obj) { 123 return mProvider.equals_impl(obj); 124 } 125 126 @Override 127 public int hashCode() { 128 return mProvider.hashCode_impl(); 129 } 130 131 /** 132 * Create an instance from bundle object, previoulsy created by {@link #toBundle()} 133 * 134 * @param context context 135 * @param bundle bundle 136 * @return new Rating2 instance or {@code null} for error 137 */ 138 public static Rating2 fromBundle(@NonNull Context context, @Nullable Bundle bundle) { 139 return ApiLoader.getProvider(context).fromBundle_Rating2(context, bundle); 140 } 141 142 /** 143 * Return bundle for this object to share across the process. 144 * @return bundle of this object 145 */ 146 public Bundle toBundle() { 147 return mProvider.toBundle_impl(); 148 } 149 150 /** 151 * Return a Rating2 instance with no rating. 152 * Create and return a new Rating2 instance with no rating known for the given 153 * rating style. 154 * @param context context 155 * @param ratingStyle one of {@link #RATING_HEART}, {@link #RATING_THUMB_UP_DOWN}, 156 * {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, {@link #RATING_5_STARS}, 157 * or {@link #RATING_PERCENTAGE}. 158 * @return null if an invalid rating style is passed, a new Rating2 instance otherwise. 159 */ 160 public static @Nullable Rating2 newUnratedRating(@NonNull Context context, @Style int ratingStyle) { 161 return ApiLoader.getProvider(context).newUnratedRating_Rating2(context, ratingStyle); 162 } 163 164 /** 165 * Return a Rating2 instance with a heart-based rating. 166 * Create and return a new Rating2 instance with a rating style of {@link #RATING_HEART}, 167 * and a heart-based rating. 168 * @param context context 169 * @param hasHeart true for a "heart selected" rating, false for "heart unselected". 170 * @return a new Rating2 instance. 171 */ 172 public static @Nullable Rating2 newHeartRating(@NonNull Context context, boolean hasHeart) { 173 return ApiLoader.getProvider(context).newHeartRating_Rating2(context, hasHeart); 174 } 175 176 /** 177 * Return a Rating2 instance with a thumb-based rating. 178 * Create and return a new Rating2 instance with a {@link #RATING_THUMB_UP_DOWN} 179 * rating style, and a "thumb up" or "thumb down" rating. 180 * @param context context 181 * @param thumbIsUp true for a "thumb up" rating, false for "thumb down". 182 * @return a new Rating2 instance. 183 */ 184 public static @Nullable Rating2 newThumbRating(@NonNull Context context, boolean thumbIsUp) { 185 return ApiLoader.getProvider(context).newThumbRating_Rating2(context, thumbIsUp); 186 } 187 188 /** 189 * Return a Rating2 instance with a star-based rating. 190 * Create and return a new Rating2 instance with one of the star-base rating styles 191 * and the given integer or fractional number of stars. Non integer values can for instance 192 * be used to represent an average rating value, which might not be an integer number of stars. 193 * @param context context 194 * @param starRatingStyle one of {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, 195 * {@link #RATING_5_STARS}. 196 * @param starRating a number ranging from 0.0f to 3.0f, 4.0f or 5.0f according to 197 * the rating style. 198 * @return null if the rating style is invalid, or the rating is out of range, 199 * a new Rating2 instance otherwise. 200 */ 201 public static @Nullable Rating2 newStarRating(@NonNull Context context, 202 @StarStyle int starRatingStyle, float starRating) { 203 return ApiLoader.getProvider(context).newStarRating_Rating2( 204 context, starRatingStyle, starRating); 205 } 206 207 /** 208 * Return a Rating2 instance with a percentage-based rating. 209 * Create and return a new Rating2 instance with a {@link #RATING_PERCENTAGE} 210 * rating style, and a rating of the given percentage. 211 * @param context context 212 * @param percent the value of the rating 213 * @return null if the rating is out of range, a new Rating2 instance otherwise. 214 */ 215 public static @Nullable Rating2 newPercentageRating(@NonNull Context context, float percent) { 216 return ApiLoader.getProvider(context).newPercentageRating_Rating2(context, percent); 217 } 218 219 /** 220 * Return whether there is a rating value available. 221 * @return true if the instance was not created with {@link #newUnratedRating(Context, int)}. 222 */ 223 public boolean isRated() { 224 return mProvider.isRated_impl(); 225 } 226 227 /** 228 * Return the rating style. 229 * @return one of {@link #RATING_HEART}, {@link #RATING_THUMB_UP_DOWN}, 230 * {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, {@link #RATING_5_STARS}, 231 * or {@link #RATING_PERCENTAGE}. 232 */ 233 @Style 234 public int getRatingStyle() { 235 return mProvider.getRatingStyle_impl(); 236 } 237 238 /** 239 * Return whether the rating is "heart selected". 240 * @return true if the rating is "heart selected", false if the rating is "heart unselected", 241 * if the rating style is not {@link #RATING_HEART} or if it is unrated. 242 */ 243 public boolean hasHeart() { 244 return mProvider.hasHeart_impl(); 245 } 246 247 /** 248 * Return whether the rating is "thumb up". 249 * @return true if the rating is "thumb up", false if the rating is "thumb down", 250 * if the rating style is not {@link #RATING_THUMB_UP_DOWN} or if it is unrated. 251 */ 252 public boolean isThumbUp() { 253 return mProvider.isThumbUp_impl(); 254 } 255 256 /** 257 * Return the star-based rating value. 258 * @return a rating value greater or equal to 0.0f, or a negative value if the rating style is 259 * not star-based, or if it is unrated. 260 */ 261 public float getStarRating() { 262 return mProvider.getStarRating_impl(); 263 } 264 265 /** 266 * Return the percentage-based rating value. 267 * @return a rating value greater or equal to 0.0f, or a negative value if the rating style is 268 * not percentage-based, or if it is unrated. 269 */ 270 public float getPercentRating() { 271 return mProvider.getPercentRating_impl(); 272 } 273} 274