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 17 package android.view.inspector; 18 19 import static java.lang.annotation.ElementType.FIELD; 20 import static java.lang.annotation.ElementType.METHOD; 21 import static java.lang.annotation.ElementType.TYPE; 22 import static java.lang.annotation.RetentionPolicy.SOURCE; 23 24 import android.annotation.TestApi; 25 import android.content.res.Resources; 26 27 import java.lang.annotation.Retention; 28 import java.lang.annotation.Target; 29 30 /** 31 * Marks a getter of a property on an inspectable node. 32 * 33 * This annotation is inherited by default. If a child class doesn't add it to a getter, but a 34 * parent class does, the property will be inspected, even if the child overrides the definition 35 * of the getter. If a child class defines a property of the same name of a property on the parent 36 * but on a different getter, the inspector will use the child's getter when inspecting instances 37 * of the child, and the parent's otherwise. 38 * 39 * @see InspectionCompanion#mapProperties(PropertyMapper) 40 * @see InspectionCompanion#readProperties(Object, PropertyReader) 41 * @hide 42 */ 43 @Target({METHOD, FIELD}) 44 @Retention(SOURCE) 45 @TestApi 46 public @interface InspectableProperty { 47 /** 48 * The name of the property. 49 * 50 * If left empty (the default), the property name will be inferred from the name of the getter 51 * method. 52 * 53 * @return The name of the property. 54 */ name()55 String name() default ""; 56 57 /** 58 * If the property is inflated from XML, the resource ID of its XML attribute. 59 * 60 * If left as {ID_NULL}, and {@link #hasAttributeId()} is true, the attribute ID will be 61 * inferred from {@link #name()}. 62 * 63 * @return The attribute ID of the property or {@link Resources#ID_NULL} 64 */ attributeId()65 int attributeId() default Resources.ID_NULL; 66 67 /** 68 * If this property has an attribute ID. 69 * 70 * Set to false if the annotated property does not have an attribute ID, that is, it is not 71 * inflated from an XML attribute. This will prevent the automatic inference of the attribute 72 * ID if {@link #attributeId()} is set to {@link Resources#ID_NULL}. 73 * 74 * @return Whether to infer an attribute ID if not supplied 75 */ hasAttributeId()76 boolean hasAttributeId() default true; 77 78 /** 79 * Specify how to interpret a value type packed into a primitive integer. 80 * 81 * @return A {@link ValueType} 82 */ valueType()83 ValueType valueType() default ValueType.INFERRED; 84 85 /** 86 * For enumerations packed into primitive {int} properties, map the values to string names. 87 * 88 * Note that {@link #enumMapping()} cannot be used simultaneously with {@link #flagMapping()}. 89 * 90 * @return An array of {@link EnumEntry}, empty if not applicable 91 * @see android.annotation.IntDef 92 */ enumMapping()93 EnumEntry[] enumMapping() default {}; 94 95 /** 96 * For flags packed into primitive {int} properties, model the string names of the flags. 97 * 98 * Note that {@link #flagMapping()} cannot be used simultaneously with {@link #enumMapping()}. 99 * 100 * @return An array of {@link FlagEntry}, empty if not applicable 101 * @see android.annotation.IntDef 102 * @see IntFlagMapping 103 */ flagMapping()104 FlagEntry[] flagMapping() default {}; 105 106 107 /** 108 * One entry in an enumeration packed into a primitive {int}. 109 * 110 * @see IntEnumMapping 111 * @hide 112 */ 113 @Target({TYPE}) 114 @Retention(SOURCE) 115 @TestApi 116 @interface EnumEntry { 117 /** 118 * The string name of this enumeration value. 119 * 120 * @return A string name 121 */ name()122 String name(); 123 124 /** 125 * The integer value of this enumeration value. 126 * 127 * @return An integer value 128 */ value()129 int value(); 130 } 131 132 /** 133 * One flag value of many that may be packed into a primitive {int}. 134 * 135 * @see IntFlagMapping 136 * @hide 137 */ 138 @Target({TYPE}) 139 @Retention(SOURCE) 140 @TestApi 141 @interface FlagEntry { 142 /** 143 * The string name of this flag. 144 * 145 * @return A string name 146 */ name()147 String name(); 148 149 /** 150 * A target value that the property's value must equal after masking. 151 * 152 * If a mask is not supplied (i.e., {@link #mask()} is 0), the target will be reused as the 153 * mask. This handles the common case where no flags mutually exclude each other. 154 * 155 * @return The target value to compare against 156 */ target()157 int target(); 158 159 /** 160 * A mask that the property will be bitwise anded with before comparing to the target. 161 * 162 * If set to 0 (the default), the value of {@link #target()} will be used as a mask. Zero 163 * was chosen as the default since bitwise and with zero is always zero. 164 * 165 * @return A mask, or 0 to use the target as a mask 166 */ mask()167 int mask() default 0; 168 } 169 170 /** 171 * The type of value packed into a primitive {int}. 172 * 173 * @hide 174 */ 175 @TestApi 176 enum ValueType { 177 /** 178 * No special handling, property is considered to be a numeric value. 179 * 180 * @hide 181 */ 182 @TestApi 183 NONE, 184 185 /** 186 * The default the annotation processor infers the value type from context. 187 * 188 * @hide 189 */ 190 @TestApi 191 INFERRED, 192 193 /** 194 * Value packs an enumeration. 195 * 196 * This is inferred if {@link #enumMapping()} is specified. 197 * 198 * @see EnumEntry 199 * @hide 200 */ 201 @TestApi 202 INT_ENUM, 203 204 /** 205 * Value packs flags, of which many may be enabled at once. 206 * 207 * This is inferred if {@link #flagMapping()} is specified. 208 * 209 * @see FlagEntry 210 * @hide 211 */ 212 @TestApi 213 INT_FLAG, 214 215 /** 216 * Value packs color information. 217 * 218 * This is inferred from {@link android.annotation.ColorInt}, or 219 * {@link android.annotation.ColorLong} on the getter method. 220 * 221 * @see android.graphics.Color 222 * @hide 223 */ 224 @TestApi 225 COLOR, 226 227 /** 228 * Value packs gravity information. 229 * 230 * This type is not inferred, and is non-trivial to represent using {@link FlagEntry}. 231 * 232 * @see android.view.Gravity 233 * @hide 234 */ 235 @TestApi 236 GRAVITY, 237 238 /** 239 * Value is a resource ID 240 * 241 * This type is inferred from the presence of a resource ID annotation such as 242 * {@link android.annotation.AnyRes}. 243 * 244 * @hide 245 */ 246 @TestApi 247 RESOURCE_ID 248 } 249 } 250