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