1/*
2 * Copyright (C) 2014 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.support.v4.content.res;
18
19import android.content.res.ColorStateList;
20import android.content.res.Resources;
21import android.content.res.Resources.NotFoundException;
22import android.content.res.Resources.Theme;
23import android.graphics.drawable.Drawable;
24import android.support.annotation.ColorInt;
25import android.support.annotation.ColorRes;
26import android.support.annotation.DrawableRes;
27import android.support.annotation.NonNull;
28import android.support.annotation.Nullable;
29
30import static android.os.Build.VERSION.SDK_INT;
31
32/**
33 * Helper for accessing features in {@link android.content.res.Resources}
34 * introduced after API level 4 in a backwards compatible fashion.
35 */
36public final class ResourcesCompat {
37    /**
38     * Return a drawable object associated with a particular resource ID and
39     * styled for the specified theme. Various types of objects will be
40     * returned depending on the underlying resource -- for example, a solid
41     * color, PNG image, scalable image, etc.
42     * <p>
43     * Prior to API level 21, the theme will not be applied and this method
44     * simply calls through to {@link Resources#getDrawable(int)}.
45     *
46     * @param id The desired resource identifier, as generated by the aapt
47     *           tool. This integer encodes the package, type, and resource
48     *           entry. The value 0 is an invalid identifier.
49     * @param theme The theme used to style the drawable attributes, may be
50     *              {@code null}.
51     * @return Drawable An object that can be used to draw this resource.
52     * @throws NotFoundException Throws NotFoundException if the given ID does
53     *         not exist.
54     */
55    @Nullable
56    @SuppressWarnings("deprecation")
57    public static Drawable getDrawable(@NonNull Resources res, @DrawableRes int id,
58            @Nullable Theme theme) throws NotFoundException {
59        if (SDK_INT >= 21) {
60            return ResourcesCompatApi21.getDrawable(res, id, theme);
61        } else {
62            return res.getDrawable(id);
63        }
64    }
65
66
67    /**
68     * Return a drawable object associated with a particular resource ID for
69     * the given screen density in DPI and styled for the specified theme.
70     * <p>
71     * Prior to API level 15, the theme and density will not be applied and
72     * this method simply calls through to {@link Resources#getDrawable(int)}.
73     * <p>
74     * Prior to API level 21, the theme will not be applied and this method
75     * calls through to Resources#getDrawableForDensity(int, int).
76     *
77     * @param id The desired resource identifier, as generated by the aapt
78     *           tool. This integer encodes the package, type, and resource
79     *           entry. The value 0 is an invalid identifier.
80     * @param density The desired screen density indicated by the resource as
81     *                found in {@link android.util.DisplayMetrics}.
82     * @param theme The theme used to style the drawable attributes, may be
83     *              {@code null}.
84     * @return Drawable An object that can be used to draw this resource.
85     * @throws NotFoundException Throws NotFoundException if the given ID does
86     *         not exist.
87     */
88    @Nullable
89    @SuppressWarnings("deprecation")
90    public static Drawable getDrawableForDensity(@NonNull Resources res, @DrawableRes int id,
91            int density, @Nullable Theme theme) throws NotFoundException {
92        if (SDK_INT >= 21) {
93            return ResourcesCompatApi21.getDrawableForDensity(res, id, density, theme);
94        } else if (SDK_INT >= 15) {
95            return ResourcesCompatIcsMr1.getDrawableForDensity(res, id, density);
96        } else {
97            return res.getDrawable(id);
98        }
99    }
100
101    /**
102     * Returns a themed color integer associated with a particular resource ID.
103     * If the resource holds a complex {@link ColorStateList}, then the default
104     * color from the set is returned.
105     * <p>
106     * Prior to API level 23, the theme will not be applied and this method
107     * calls through to {@link Resources#getColor(int)}.
108     *
109     * @param id The desired resource identifier, as generated by the aapt
110     *           tool. This integer encodes the package, type, and resource
111     *           entry. The value 0 is an invalid identifier.
112     * @param theme The theme used to style the color attributes, may be
113     *              {@code null}.
114     * @return A single color value in the form {@code 0xAARRGGBB}.
115     * @throws NotFoundException Throws NotFoundException if the given ID does
116     *         not exist.
117     */
118    @ColorInt
119    @SuppressWarnings("deprecation")
120    public static int getColor(@NonNull Resources res, @ColorRes int id, @Nullable Theme theme)
121            throws NotFoundException {
122        if (SDK_INT >= 23) {
123            return ResourcesCompatApi23.getColor(res, id, theme);
124        } else {
125            return res.getColor(id);
126        }
127    }
128
129    /**
130     * Returns a themed color state list associated with a particular resource
131     * ID. The resource may contain either a single raw color value or a
132     * complex {@link ColorStateList} holding multiple possible colors.
133     * <p>
134     * Prior to API level 23, the theme will not be applied and this method
135     * calls through to {@link Resources#getColorStateList(int)}.
136     *
137     * @param id The desired resource identifier of a {@link ColorStateList},
138     *           as generated by the aapt tool. This integer encodes the
139     *           package, type, and resource entry. The value 0 is an invalid
140     *           identifier.
141     * @param theme The theme used to style the color attributes, may be
142     *              {@code null}.
143     * @return A themed ColorStateList object containing either a single solid
144     *         color or multiple colors that can be selected based on a state.
145     * @throws NotFoundException Throws NotFoundException if the given ID does
146     *         not exist.
147     */
148    @Nullable
149    @SuppressWarnings("deprecation")
150    public static ColorStateList getColorStateList(@NonNull Resources res, @ColorRes int id,
151            @Nullable Theme theme) throws NotFoundException {
152        if (SDK_INT >= 23) {
153            return ResourcesCompatApi23.getColorStateList(res, id, theme);
154        } else {
155            return res.getColorStateList(id);
156        }
157    }
158
159    private ResourcesCompat() {}
160}
161