TypedValue.java revision 8aca9e335f9b2eb060878b2e6cbe241928d83dc9
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.util;
18
19/**
20 * Container for a dynamically typed data value.  Primarily used with
21 * {@link android.content.res.Resources} for holding resource values.
22 */
23public class TypedValue {
24    /** The value contains no data. */
25    public static final int TYPE_NULL = 0x00;
26
27    /** The <var>data</var> field holds a resource identifier. */
28    public static final int TYPE_REFERENCE = 0x01;
29    /** The <var>data</var> field holds an attribute resource
30     *  identifier (referencing an attribute in the current theme
31     *  style, not a resource entry). */
32    public static final int TYPE_ATTRIBUTE = 0x02;
33    /** The <var>string</var> field holds string data.  In addition, if
34     *  <var>data</var> is non-zero then it is the string block
35     *  index of the string and <var>assetCookie</var> is the set of
36     *  assets the string came from. */
37    public static final int TYPE_STRING = 0x03;
38    /** The <var>data</var> field holds an IEEE 754 floating point number. */
39    public static final int TYPE_FLOAT = 0x04;
40    /** The <var>data</var> field holds a complex number encoding a
41     *  dimension value. */
42    public static final int TYPE_DIMENSION = 0x05;
43    /** The <var>data</var> field holds a complex number encoding a fraction
44     *  of a container. */
45    public static final int TYPE_FRACTION = 0x06;
46
47    /** Identifies the start of plain integer values.  Any type value
48     *  from this to {@link #TYPE_LAST_INT} means the
49     *  <var>data</var> field holds a generic integer value. */
50    public static final int TYPE_FIRST_INT = 0x10;
51
52    /** The <var>data</var> field holds a number that was
53     *  originally specified in decimal. */
54    public static final int TYPE_INT_DEC = 0x10;
55    /** The <var>data</var> field holds a number that was
56     *  originally specified in hexadecimal (0xn). */
57    public static final int TYPE_INT_HEX = 0x11;
58    /** The <var>data</var> field holds 0 or 1 that was originally
59     *  specified as "false" or "true". */
60    public static final int TYPE_INT_BOOLEAN = 0x12;
61
62    /** Identifies the start of integer values that were specified as
63     *  color constants (starting with '#'). */
64    public static final int TYPE_FIRST_COLOR_INT = 0x1c;
65
66    /** The <var>data</var> field holds a color that was originally
67     *  specified as #aarrggbb. */
68    public static final int TYPE_INT_COLOR_ARGB8 = 0x1c;
69    /** The <var>data</var> field holds a color that was originally
70     *  specified as #rrggbb. */
71    public static final int TYPE_INT_COLOR_RGB8 = 0x1d;
72    /** The <var>data</var> field holds a color that was originally
73     *  specified as #argb. */
74    public static final int TYPE_INT_COLOR_ARGB4 = 0x1e;
75    /** The <var>data</var> field holds a color that was originally
76     *  specified as #rgb. */
77    public static final int TYPE_INT_COLOR_RGB4 = 0x1f;
78
79    /** Identifies the end of integer values that were specified as color
80     *  constants. */
81    public static final int TYPE_LAST_COLOR_INT = 0x1f;
82
83    /** Identifies the end of plain integer values. */
84    public static final int TYPE_LAST_INT = 0x1f;
85
86    /* ------------------------------------------------------------ */
87
88    /** Complex data: bit location of unit information. */
89    public static final int COMPLEX_UNIT_SHIFT = 0;
90    /** Complex data: mask to extract unit information (after shifting by
91     *  {@link #COMPLEX_UNIT_SHIFT}). This gives us 16 possible types, as
92     *  defined below. */
93    public static final int COMPLEX_UNIT_MASK = 0xf;
94
95    /** {@link #TYPE_DIMENSION} complex unit: Value is raw pixels. */
96    public static final int COMPLEX_UNIT_PX = 0;
97    /** {@link #TYPE_DIMENSION} complex unit: Value is Device Independent
98     *  Pixels. */
99    public static final int COMPLEX_UNIT_DIP = 1;
100    /** {@link #TYPE_DIMENSION} complex unit: Value is a scaled pixel. */
101    public static final int COMPLEX_UNIT_SP = 2;
102    /** {@link #TYPE_DIMENSION} complex unit: Value is in points. */
103    public static final int COMPLEX_UNIT_PT = 3;
104    /** {@link #TYPE_DIMENSION} complex unit: Value is in inches. */
105    public static final int COMPLEX_UNIT_IN = 4;
106    /** {@link #TYPE_DIMENSION} complex unit: Value is in millimeters. */
107    public static final int COMPLEX_UNIT_MM = 5;
108
109    /** {@link #TYPE_FRACTION} complex unit: A basic fraction of the overall
110     *  size. */
111    public static final int COMPLEX_UNIT_FRACTION = 0;
112    /** {@link #TYPE_FRACTION} complex unit: A fraction of the parent size. */
113    public static final int COMPLEX_UNIT_FRACTION_PARENT = 1;
114
115    /** Complex data: where the radix information is, telling where the decimal
116     *  place appears in the mantissa. */
117    public static final int COMPLEX_RADIX_SHIFT = 4;
118    /** Complex data: mask to extract radix information (after shifting by
119     * {@link #COMPLEX_RADIX_SHIFT}). This give us 4 possible fixed point
120     * representations as defined below. */
121    public static final int COMPLEX_RADIX_MASK = 0x3;
122
123    /** Complex data: the mantissa is an integral number -- i.e., 0xnnnnnn.0 */
124    public static final int COMPLEX_RADIX_23p0 = 0;
125    /** Complex data: the mantissa magnitude is 16 bits -- i.e, 0xnnnn.nn */
126    public static final int COMPLEX_RADIX_16p7 = 1;
127    /** Complex data: the mantissa magnitude is 8 bits -- i.e, 0xnn.nnnn */
128    public static final int COMPLEX_RADIX_8p15 = 2;
129    /** Complex data: the mantissa magnitude is 0 bits -- i.e, 0x0.nnnnnn */
130    public static final int COMPLEX_RADIX_0p23 = 3;
131
132    /** Complex data: bit location of mantissa information. */
133    public static final int COMPLEX_MANTISSA_SHIFT = 8;
134    /** Complex data: mask to extract mantissa information (after shifting by
135     *  {@link #COMPLEX_MANTISSA_SHIFT}). This gives us 23 bits of precision;
136     *  the top bit is the sign. */
137    public static final int COMPLEX_MANTISSA_MASK = 0xffffff;
138
139    /* ------------------------------------------------------------ */
140
141    /**
142     * If {@link #density} is equal to this value, then the density should be
143     * treated as the system's default density value: {@link DisplayMetrics#DENSITY_DEFAULT}.
144     */
145    public static final int DENSITY_DEFAULT = 0;
146
147    /**
148     * If {@link #density} is equal to this value, then there is no density
149     * associated with the resource and it should not be scaled.
150     */
151    public static final int DENSITY_NONE = 0xffff;
152
153    /* ------------------------------------------------------------ */
154
155    /** The type held by this value, as defined by the constants here.
156     *  This tells you how to interpret the other fields in the object. */
157    public int type;
158
159    /** If the value holds a string, this is it. */
160    public CharSequence string;
161
162    /** Basic data in the value, interpreted according to {@link #type} */
163    public int data;
164
165    /** Additional information about where the value came from; only
166     *  set for strings. */
167    public int assetCookie;
168
169    /** If Value came from a resource, this holds the corresponding resource id. */
170    public int resourceId;
171
172    /** If Value came from a resource, these are the configurations for which
173     *  its contents can change. */
174    public int changingConfigurations = -1;
175
176    /**
177     * If the Value came from a resource, this holds the corresponding pixel density.
178     * */
179    public int density;
180
181    /* ------------------------------------------------------------ */
182
183    /** Return the data for this value as a float.  Only use for values
184     *  whose type is {@link #TYPE_FLOAT}. */
185    public final float getFloat() {
186        return Float.intBitsToFloat(data);
187    }
188
189    private static final float MANTISSA_MULT =
190        1.0f / (1<<TypedValue.COMPLEX_MANTISSA_SHIFT);
191    private static final float[] RADIX_MULTS = new float[] {
192        1.0f*MANTISSA_MULT, 1.0f/(1<<7)*MANTISSA_MULT,
193        1.0f/(1<<15)*MANTISSA_MULT, 1.0f/(1<<23)*MANTISSA_MULT
194    };
195
196    /**
197     * Retrieve the base value from a complex data integer.  This uses the
198     * {@link #COMPLEX_MANTISSA_MASK} and {@link #COMPLEX_RADIX_MASK} fields of
199     * the data to compute a floating point representation of the number they
200     * describe.  The units are ignored.
201     *
202     * @param complex A complex data value.
203     *
204     * @return A floating point value corresponding to the complex data.
205     */
206    public static float complexToFloat(int complex)
207    {
208        return (complex&(TypedValue.COMPLEX_MANTISSA_MASK
209                   <<TypedValue.COMPLEX_MANTISSA_SHIFT))
210            * RADIX_MULTS[(complex>>TypedValue.COMPLEX_RADIX_SHIFT)
211                            & TypedValue.COMPLEX_RADIX_MASK];
212    }
213
214    /**
215     * Converts a complex data value holding a dimension to its final floating
216     * point value. The given <var>data</var> must be structured as a
217     * {@link #TYPE_DIMENSION}.
218     *
219     * @param data A complex data value holding a unit, magnitude, and
220     *             mantissa.
221     * @param metrics Current display metrics to use in the conversion --
222     *                supplies display density and scaling information.
223     *
224     * @return The complex floating point value multiplied by the appropriate
225     * metrics depending on its unit.
226     */
227    public static float complexToDimension(int data, DisplayMetrics metrics)
228    {
229        return applyDimension(
230            (data>>COMPLEX_UNIT_SHIFT)&COMPLEX_UNIT_MASK,
231            complexToFloat(data),
232            metrics);
233    }
234
235    /**
236     * Converts a complex data value holding a dimension to its final value
237     * as an integer pixel offset.  This is the same as
238     * {@link #complexToDimension}, except the raw floating point value is
239     * truncated to an integer (pixel) value.
240     * The given <var>data</var> must be structured as a
241     * {@link #TYPE_DIMENSION}.
242     *
243     * @param data A complex data value holding a unit, magnitude, and
244     *             mantissa.
245     * @param metrics Current display metrics to use in the conversion --
246     *                supplies display density and scaling information.
247     *
248     * @return The number of pixels specified by the data and its desired
249     * multiplier and units.
250     */
251    public static int complexToDimensionPixelOffset(int data,
252            DisplayMetrics metrics)
253    {
254        return (int)applyDimension(
255                (data>>COMPLEX_UNIT_SHIFT)&COMPLEX_UNIT_MASK,
256                complexToFloat(data),
257                metrics);
258    }
259
260    /**
261     * Converts a complex data value holding a dimension to its final value
262     * as an integer pixel size.  This is the same as
263     * {@link #complexToDimension}, except the raw floating point value is
264     * converted to an integer (pixel) value for use as a size.  A size
265     * conversion involves rounding the base value, and ensuring that a
266     * non-zero base value is at least one pixel in size.
267     * The given <var>data</var> must be structured as a
268     * {@link #TYPE_DIMENSION}.
269     *
270     * @param data A complex data value holding a unit, magnitude, and
271     *             mantissa.
272     * @param metrics Current display metrics to use in the conversion --
273     *                supplies display density and scaling information.
274     *
275     * @return The number of pixels specified by the data and its desired
276     * multiplier and units.
277     */
278    public static int complexToDimensionPixelSize(int data,
279            DisplayMetrics metrics)
280    {
281        final float value = complexToFloat(data);
282        final float f = applyDimension(
283                (data>>COMPLEX_UNIT_SHIFT)&COMPLEX_UNIT_MASK,
284                value,
285                metrics);
286        final int res = (int)(f+0.5f);
287        if (res != 0) return res;
288        if (value == 0) return 0;
289        if (value > 0) return 1;
290        return -1;
291    }
292
293    /**
294     * @hide Was accidentally exposed in API level 1 for debugging purposes.
295     * Kept for compatibility just in case although the debugging code has been removed.
296     */
297    @Deprecated
298    public static float complexToDimensionNoisy(int data, DisplayMetrics metrics)
299    {
300        return complexToDimension(data, metrics);
301    }
302
303    /**
304     * Converts an unpacked complex data value holding a dimension to its final floating
305     * point value. The two parameters <var>unit</var> and <var>value</var>
306     * are as in {@link #TYPE_DIMENSION}.
307     *
308     * @param unit The unit to convert from.
309     * @param value The value to apply the unit to.
310     * @param metrics Current display metrics to use in the conversion --
311     *                supplies display density and scaling information.
312     *
313     * @return The complex floating point value multiplied by the appropriate
314     * metrics depending on its unit.
315     */
316    public static float applyDimension(int unit, float value,
317                                       DisplayMetrics metrics)
318    {
319        switch (unit) {
320        case COMPLEX_UNIT_PX:
321            return value;
322        case COMPLEX_UNIT_DIP:
323            return value * metrics.density;
324        case COMPLEX_UNIT_SP:
325            return value * metrics.scaledDensity;
326        case COMPLEX_UNIT_PT:
327            return value * metrics.xdpi * (1.0f/72);
328        case COMPLEX_UNIT_IN:
329            return value * metrics.xdpi;
330        case COMPLEX_UNIT_MM:
331            return value * metrics.xdpi * (1.0f/25.4f);
332        }
333        return 0;
334    }
335
336    /**
337     * Return the data for this value as a dimension.  Only use for values
338     * whose type is {@link #TYPE_DIMENSION}.
339     *
340     * @param metrics Current display metrics to use in the conversion --
341     *                supplies display density and scaling information.
342     *
343     * @return The complex floating point value multiplied by the appropriate
344     * metrics depending on its unit.
345     */
346    public float getDimension(DisplayMetrics metrics)
347    {
348        return complexToDimension(data, metrics);
349    }
350
351    /**
352     * Converts a complex data value holding a fraction to its final floating
353     * point value. The given <var>data</var> must be structured as a
354     * {@link #TYPE_FRACTION}.
355     *
356     * @param data A complex data value holding a unit, magnitude, and
357     *             mantissa.
358     * @param base The base value of this fraction.  In other words, a
359     *             standard fraction is multiplied by this value.
360     * @param pbase The parent base value of this fraction.  In other
361     *             words, a parent fraction (nn%p) is multiplied by this
362     *             value.
363     *
364     * @return The complex floating point value multiplied by the appropriate
365     * base value depending on its unit.
366     */
367    public static float complexToFraction(int data, float base, float pbase)
368    {
369        switch ((data>>COMPLEX_UNIT_SHIFT)&COMPLEX_UNIT_MASK) {
370        case COMPLEX_UNIT_FRACTION:
371            return complexToFloat(data) * base;
372        case COMPLEX_UNIT_FRACTION_PARENT:
373            return complexToFloat(data) * pbase;
374        }
375        return 0;
376    }
377
378    /**
379     * Return the data for this value as a fraction.  Only use for values whose
380     * type is {@link #TYPE_FRACTION}.
381     *
382     * @param base The base value of this fraction.  In other words, a
383     *             standard fraction is multiplied by this value.
384     * @param pbase The parent base value of this fraction.  In other
385     *             words, a parent fraction (nn%p) is multiplied by this
386     *             value.
387     *
388     * @return The complex floating point value multiplied by the appropriate
389     * base value depending on its unit.
390     */
391    public float getFraction(float base, float pbase)
392    {
393        return complexToFraction(data, base, pbase);
394    }
395
396    /**
397     * Regardless of the actual type of the value, try to convert it to a
398     * string value.  For example, a color type will be converted to a
399     * string of the form #aarrggbb.
400     *
401     * @return CharSequence The coerced string value.  If the value is
402     *         null or the type is not known, null is returned.
403     */
404    public final CharSequence coerceToString()
405    {
406        int t = type;
407        if (t == TYPE_STRING) {
408            return string;
409        }
410        return coerceToString(t, data);
411    }
412
413    private static final String[] DIMENSION_UNIT_STRS = new String[] {
414        "px", "dip", "sp", "pt", "in", "mm"
415    };
416    private static final String[] FRACTION_UNIT_STRS = new String[] {
417        "%", "%p"
418    };
419
420    /**
421     * Perform type conversion as per {@link #coerceToString()} on an
422     * explicitly supplied type and data.
423     *
424     * @param type The data type identifier.
425     * @param data The data value.
426     *
427     * @return String The coerced string value.  If the value is
428     *         null or the type is not known, null is returned.
429     */
430    public static final String coerceToString(int type, int data)
431    {
432        switch (type) {
433        case TYPE_NULL:
434            return null;
435        case TYPE_REFERENCE:
436            return "@" + data;
437        case TYPE_ATTRIBUTE:
438            return "?" + data;
439        case TYPE_FLOAT:
440            return Float.toString(Float.intBitsToFloat(data));
441        case TYPE_DIMENSION:
442            return Float.toString(complexToFloat(data)) + DIMENSION_UNIT_STRS[
443                (data>>COMPLEX_UNIT_SHIFT)&COMPLEX_UNIT_MASK];
444        case TYPE_FRACTION:
445            return Float.toString(complexToFloat(data)*100) + FRACTION_UNIT_STRS[
446                (data>>COMPLEX_UNIT_SHIFT)&COMPLEX_UNIT_MASK];
447        case TYPE_INT_HEX:
448            return "0x" + Integer.toHexString(data);
449        case TYPE_INT_BOOLEAN:
450            return data != 0 ? "true" : "false";
451        }
452
453        if (type >= TYPE_FIRST_COLOR_INT && type <= TYPE_LAST_COLOR_INT) {
454            return "#" + Integer.toHexString(data);
455        } else if (type >= TYPE_FIRST_INT && type <= TYPE_LAST_INT) {
456            return Integer.toString(data);
457        }
458
459        return null;
460    }
461
462    public void setTo(TypedValue other)
463    {
464        type = other.type;
465        string = other.string;
466        data = other.data;
467        assetCookie = other.assetCookie;
468        resourceId = other.resourceId;
469        density = other.density;
470    }
471
472    public String toString()
473    {
474        StringBuilder sb = new StringBuilder();
475        sb.append("TypedValue{t=0x").append(Integer.toHexString(type));
476        sb.append("/d=0x").append(Integer.toHexString(data));
477        if (type == TYPE_STRING) {
478            sb.append(" \"").append(string != null ? string : "<null>").append("\"");
479        }
480        if (assetCookie != 0) {
481            sb.append(" a=").append(assetCookie);
482        }
483        if (resourceId != 0) {
484            sb.append(" r=0x").append(Integer.toHexString(resourceId));
485        }
486        sb.append("}");
487        return sb.toString();
488    }
489};
490
491