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 android.annotation.AttrRes; 20 import android.annotation.NonNull; 21 import android.content.res.Resources; 22 23 import java.util.Set; 24 import java.util.function.IntFunction; 25 26 /** 27 * An interface for mapping the string names of inspectable properties to integer identifiers. 28 * 29 * This interface is consumed by {@link InspectionCompanion#mapProperties(PropertyMapper)}. 30 * 31 * Mapping properties to IDs enables quick comparisons against shadow copies of inspectable 32 * objects without performing a large number of string comparisons. 33 * 34 * Properties that derive their value from an XML attribute should provide the attribute resource 35 * ID (e.g.: {@code R.attr.color}). For runtime or generated properties properties without 36 * attribute IDs, supply {@link Resources#ID_NULL} for {@code attributeId}. 37 * 38 * @see InspectionCompanion#mapProperties(PropertyMapper) 39 */ 40 public interface PropertyMapper { 41 /** 42 * Map a string name to an integer ID for a primitive boolean property. 43 * 44 * @param name The name of the property 45 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 46 * @return An integer ID for the property 47 * @throws PropertyConflictException If the property name is already mapped as another type. 48 */ mapBoolean(@onNull String name, @AttrRes int attributeId)49 int mapBoolean(@NonNull String name, @AttrRes int attributeId); 50 51 /** 52 * Map a string name to an integer ID for a primitive byte property. 53 * 54 * @param name The name of the property 55 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 56 * @return An integer ID for the property 57 * @throws PropertyConflictException If the property name is already mapped as another type. 58 */ mapByte(@onNull String name, @AttrRes int attributeId)59 int mapByte(@NonNull String name, @AttrRes int attributeId); 60 61 /** 62 * Map a string name to an integer ID for a primitive char property. 63 * 64 * @param name The name of the property 65 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 66 * @return An integer ID for the property 67 * @throws PropertyConflictException If the property name is already mapped as another type. 68 */ mapChar(@onNull String name, @AttrRes int attributeId)69 int mapChar(@NonNull String name, @AttrRes int attributeId); 70 71 /** 72 * Map a string name to an integer ID for a primitive double property. 73 * 74 * @param name The name of the property 75 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 76 * @return An integer ID for the property 77 * @throws PropertyConflictException If the property name is already mapped as another type. 78 */ mapDouble(@onNull String name, @AttrRes int attributeId)79 int mapDouble(@NonNull String name, @AttrRes int attributeId); 80 81 /** 82 * Map a string name to an integer ID for a primitive float property. 83 * 84 * @param name The name of the property 85 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 86 * @return An integer ID for the property 87 * @throws PropertyConflictException If the property name is already mapped as another type. 88 */ mapFloat(@onNull String name, @AttrRes int attributeId)89 int mapFloat(@NonNull String name, @AttrRes int attributeId); 90 91 /** 92 * Map a string name to an integer ID for a primitive int property. 93 * 94 * @param name The name of the property 95 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 96 * @return An integer ID for the property 97 * @throws PropertyConflictException If the property name is already mapped as another type. 98 */ mapInt(@onNull String name, @AttrRes int attributeId)99 int mapInt(@NonNull String name, @AttrRes int attributeId); 100 101 /** 102 * Map a string name to an integer ID for a primitive long property. 103 * 104 * @param name The name of the property 105 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 106 * @return An integer ID for the property 107 * @throws PropertyConflictException If the property name is already mapped as another type. 108 */ mapLong(@onNull String name, @AttrRes int attributeId)109 int mapLong(@NonNull String name, @AttrRes int attributeId); 110 111 /** 112 * Map a string name to an integer ID for a primitive short property. 113 * 114 * @param name The name of the property 115 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 116 * @return An integer ID for the property 117 * @throws PropertyConflictException If the property name is already mapped as another type. 118 */ mapShort(@onNull String name, @AttrRes int attributeId)119 int mapShort(@NonNull String name, @AttrRes int attributeId); 120 121 /** 122 * Map a string name to an integer ID for an object property. 123 * 124 * @param name The name of the property 125 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 126 * @return An integer ID for the property 127 * @throws PropertyConflictException If the property name is already mapped as another type. 128 */ mapObject(@onNull String name, @AttrRes int attributeId)129 int mapObject(@NonNull String name, @AttrRes int attributeId); 130 131 /** 132 * Map a string name to an integer ID for a color property. 133 * 134 * @param name The name of the property 135 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 136 * @return An integer ID for the property 137 * @throws PropertyConflictException If the property name is already mapped as another type. 138 * @see android.graphics.Color 139 */ mapColor(@onNull String name, @AttrRes int attributeId)140 int mapColor(@NonNull String name, @AttrRes int attributeId); 141 142 /** 143 * Map a string name to an integer ID for a gravity property. 144 * 145 * @param name The name of the property 146 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 147 * @return An integer ID for the property 148 * @throws PropertyConflictException If the property name is already mapped as another type. 149 * @see android.view.Gravity 150 */ mapGravity(@onNull String name, @AttrRes int attributeId)151 int mapGravity(@NonNull String name, @AttrRes int attributeId); 152 153 /** 154 * Map a string name to an integer ID for an enumeration packed into an int property. 155 * 156 * @param name The name of the property 157 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 158 * @param mapping A mapping from int to String 159 * @return An integer ID for the property 160 * @throws PropertyConflictException If the property name is already mapped as another type. 161 */ mapIntEnum( @onNull String name, @AttrRes int attributeId, @NonNull IntFunction<String> mapping)162 int mapIntEnum( 163 @NonNull String name, 164 @AttrRes int attributeId, 165 @NonNull IntFunction<String> mapping); 166 167 /** 168 * Map a string name to an integer ID for an attribute that contains resource IDs. 169 * 170 * @param name The name of the property 171 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 172 * @return An integer ID for the property 173 * @throws PropertyConflictException If the property name is already mapped as another type. 174 */ mapResourceId(@onNull String name, @AttrRes int attributeId)175 int mapResourceId(@NonNull String name, @AttrRes int attributeId); 176 177 /** 178 * Map a string name to an integer ID for a flag set packed into an int property. 179 * 180 * @param name The name of the property 181 * @param attributeId The attribute resource ID of this property, or {@link Resources#ID_NULL} 182 * @param mapping A mapping from int to a set of strings 183 * @return An integer ID for the property 184 * @throws PropertyConflictException If the property name is already mapped as another type. 185 */ mapIntFlag( @onNull String name, @AttrRes int attributeId, @NonNull IntFunction<Set<String>> mapping)186 int mapIntFlag( 187 @NonNull String name, 188 @AttrRes int attributeId, 189 @NonNull IntFunction<Set<String>> mapping); 190 191 /** 192 * Thrown from a map method if a property name is already mapped as different type. 193 */ 194 class PropertyConflictException extends RuntimeException { PropertyConflictException( @onNull String name, @NonNull String newPropertyType, @NonNull String existingPropertyType)195 public PropertyConflictException( 196 @NonNull String name, 197 @NonNull String newPropertyType, 198 @NonNull String existingPropertyType) { 199 super(String.format( 200 "Attempted to map property \"%s\" as type %s, but it is already mapped as %s.", 201 name, 202 newPropertyType, 203 existingPropertyType 204 )); 205 } 206 } 207 } 208