Add support v4 methods for Resources.getColor() and ColorStateList

Also adds annotations and cleans up docs.

Bug: 23519770
Change-Id: Ifc7cc0e50a92718099bfb4bf95fe754d656cf610
diff --git a/v4/api/current.txt b/v4/api/current.txt
index 9f8a03c..843b449 100644
--- a/v4/api/current.txt
+++ b/v4/api/current.txt
@@ -1118,6 +1118,8 @@
 
   public class ResourcesCompat {
     ctor public ResourcesCompat();
+    method public int getColor(android.content.res.Resources, int, android.content.res.Resources.Theme) throws android.content.res.Resources.NotFoundException;
+    method public android.content.res.ColorStateList getColorStateList(android.content.res.Resources, int, android.content.res.Resources.Theme) throws android.content.res.Resources.NotFoundException;
     method public static android.graphics.drawable.Drawable getDrawable(android.content.res.Resources, int, android.content.res.Resources.Theme) throws android.content.res.Resources.NotFoundException;
     method public static android.graphics.drawable.Drawable getDrawableForDensity(android.content.res.Resources, int, int, android.content.res.Resources.Theme) throws android.content.res.Resources.NotFoundException;
   }
diff --git a/v4/api23/android/support/v4/content/ResourcesCompatApi23.java b/v4/api23/android/support/v4/content/ResourcesCompatApi23.java
new file mode 100644
index 0000000..c44f9ce
--- /dev/null
+++ b/v4/api23/android/support/v4/content/ResourcesCompatApi23.java
@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2015 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.support.v4.content.res;
+
+import android.content.res.ColorStateList;
+import android.content.res.Resources;
+import android.content.res.Resources.NotFoundException;
+import android.content.res.Resources.Theme;
+
+class ResourcesCompatApi23 {
+    public static int getColor(Resources res, int id, Theme theme) throws NotFoundException {
+        return res.getColor(id, theme);
+    }
+
+    public static ColorStateList getColorStateList(Resources res, int id, Theme theme)
+            throws NotFoundException {
+        return res.getColorStateList(id, theme);
+    }
+}
diff --git a/v4/java/android/support/v4/content/res/ResourcesCompat.java b/v4/java/android/support/v4/content/res/ResourcesCompat.java
index 252977b..ec50295 100644
--- a/v4/java/android/support/v4/content/res/ResourcesCompat.java
+++ b/v4/java/android/support/v4/content/res/ResourcesCompat.java
@@ -16,11 +16,18 @@
 
 package android.support.v4.content.res;
 
+import android.content.res.ColorStateList;
 import android.content.res.Resources;
 import android.content.res.Resources.NotFoundException;
 import android.content.res.Resources.Theme;
 import android.graphics.drawable.Drawable;
-import android.os.Build;
+import android.support.annotation.ColorInt;
+import android.support.annotation.ColorRes;
+import android.support.annotation.DrawableRes;
+import android.support.annotation.NonNull;
+import android.support.annotation.Nullable;
+
+import static android.os.Build.VERSION.SDK_INT;
 
 /**
  * Helper for accessing features in {@link android.content.res.Resources}
@@ -45,11 +52,11 @@
      * @throws NotFoundException Throws NotFoundException if the given ID does
      *         not exist.
      */
+    @Nullable
     @SuppressWarnings("deprecation")
-    public static Drawable getDrawable(Resources res, int id, Theme theme)
-            throws NotFoundException {
-        final int version = Build.VERSION.SDK_INT;
-        if (version >= 21) {
+    public static Drawable getDrawable(@NonNull Resources res, @DrawableRes int id,
+            @Nullable Theme theme) throws NotFoundException {
+        if (SDK_INT >= 21) {
             return ResourcesCompatApi21.getDrawable(res, id, theme);
         } else {
             return res.getDrawable(id);
@@ -65,7 +72,7 @@
      * this method simply calls through to {@link Resources#getDrawable(int)}.
      * <p>
      * Prior to API level 21, the theme will not be applied and this method
-     * calls through to Resources.getDrawableForDensity(int, int).
+     * calls through to Resources#getDrawableForDensity(int, int).
      *
      * @param id The desired resource identifier, as generated by the aapt
      *           tool. This integer encodes the package, type, and resource
@@ -76,18 +83,76 @@
      *              {@code null}.
      * @return Drawable An object that can be used to draw this resource.
      * @throws NotFoundException Throws NotFoundException if the given ID does
-     *             not exist.
+     *         not exist.
      */
+    @Nullable
     @SuppressWarnings("deprecation")
-    public static Drawable getDrawableForDensity(Resources res, int id, int density, Theme theme)
-            throws NotFoundException {
-        final int version = Build.VERSION.SDK_INT;
-        if (version >= 21) {
+    public static Drawable getDrawableForDensity(@NonNull Resources res, @DrawableRes int id,
+            int density, @Nullable Theme theme) throws NotFoundException {
+        if (SDK_INT >= 21) {
             return ResourcesCompatApi21.getDrawableForDensity(res, id, density, theme);
-        } else if (version >= 15) {
+        } else if (SDK_INT >= 15) {
             return ResourcesCompatIcsMr1.getDrawableForDensity(res, id, density);
         } else {
             return res.getDrawable(id);
         }
     }
+
+    /**
+     * Returns a themed color integer associated with a particular resource ID.
+     * If the resource holds a complex {@link ColorStateList}, then the default
+     * color from the set is returned.
+     * <p>
+     * Prior to API level 23, the theme will not be applied and this method
+     * calls through to {@link Resources#getColor(int)}.
+     *
+     * @param id The desired resource identifier, as generated by the aapt
+     *           tool. This integer encodes the package, type, and resource
+     *           entry. The value 0 is an invalid identifier.
+     * @param theme The theme used to style the color attributes, may be
+     *              {@code null}.
+     * @return A single color value in the form {@code 0xAARRGGBB}.
+     * @throws NotFoundException Throws NotFoundException if the given ID does
+     *         not exist.
+     */
+    @ColorInt
+    @SuppressWarnings("deprecation")
+    public int getColor(@NonNull Resources res, @ColorRes int id, @Nullable Theme theme)
+            throws NotFoundException {
+        if (SDK_INT >= 23) {
+            return ResourcesCompatApi23.getColor(res, id, theme);
+        } else {
+            return res.getColor(id);
+        }
+    }
+
+    /**
+     * Returns a themed color state list associated with a particular resource
+     * ID. The resource may contain either a single raw color value or a
+     * complex {@link ColorStateList} holding multiple possible colors.
+     * <p>
+     * Prior to API level 23, the theme will not be applied and this method
+     * calls through to {@link Resources#getColorStateList(int)}.
+     *
+     * @param id The desired resource identifier of a {@link ColorStateList},
+     *           as generated by the aapt tool. This integer encodes the
+     *           package, type, and resource entry. The value 0 is an invalid
+     *           identifier.
+     * @param theme The theme used to style the color attributes, may be
+     *              {@code null}.
+     * @return A themed ColorStateList object containing either a single solid
+     *         color or multiple colors that can be selected based on a state.
+     * @throws NotFoundException Throws NotFoundException if the given ID does
+     *         not exist.
+     */
+    @Nullable
+    @SuppressWarnings("deprecation")
+    public ColorStateList getColorStateList(@NonNull Resources res, @ColorRes int id,
+            @Nullable Theme theme) throws NotFoundException {
+        if (SDK_INT >= 23) {
+            return ResourcesCompatApi23.getColorStateList(res, id, theme);
+        } else {
+            return res.getColorStateList(id);
+        }
+    }
 }