content: /*
   * Copyright 2018 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.view.inspector;
  
  import static java.lang.annotation.ElementType.FIELD;
  import static java.lang.annotation.ElementType.METHOD;
  import static java.lang.annotation.ElementType.TYPE;
  import static java.lang.annotation.RetentionPolicy.SOURCE;
  
  import android.annotation.TestApi;
  import android.content.res.Resources;
  
  import java.lang.annotation.Retention;
  import java.lang.annotation.Target;
  
  /**
   * Marks a getter of a property on an inspectable node.
   *
   * This annotation is inherited by default. If a child class doesn't add it to a getter, but a
   * parent class does, the property will be inspected, even if the child overrides the definition
   * of the getter. If a child class defines a property of the same name of a property on the parent
   * but on a different getter, the inspector will use the child's getter when inspecting instances
   * of the child, and the parent's otherwise.
   *
   * @see InspectionCompanion#mapProperties(PropertyMapper)
   * @see InspectionCompanion#readProperties(Object, PropertyReader)
   * @hide
   */
  @Target({METHOD, FIELD})
  @Retention(SOURCE)
  @TestApi
  public @interface InspectableProperty {
      /**
       * The name of the property.
       *
       * If left empty (the default), the property name will be inferred from the name of the getter
       * method.
       *
       * @return The name of the property.
       */
      String name() default "";
  
      /**
       * If the property is inflated from XML, the resource ID of its XML attribute.
       *
       * If left as {ID_NULL}, and {@link #hasAttributeId()} is true, the attribute ID will be
       * inferred from {@link #name()}.
       *
       * @return The attribute ID of the property or {@link Resources#ID_NULL}
       */
      int attributeId() default Resources.ID_NULL;
  
      /**
       * If this property has an attribute ID.
       *
       * Set to false if the annotated property does not have an attribute ID, that is, it is not
       * inflated from an XML attribute. This will prevent the automatic inference of the attribute
       * ID if {@link #attributeId()} is set to {@link Resources#ID_NULL}.
       *
       * @return Whether to infer an attribute ID if not supplied
       */
      boolean hasAttributeId() default true;
  
      /**
       * Specify how to interpret a value type packed into a primitive integer.
       *
       * @return A {@link ValueType}
       */
      ValueType valueType() default ValueType.INFERRED;
  
      /**
       * For enumerations packed into primitive {int} properties, map the values to string names.
       *
       * Note that {@link #enumMapping()} cannot be used simultaneously with {@link #flagMapping()}.
       *
       * @return An array of {@link EnumEntry}, empty if not applicable
       * @see android.annotation.IntDef
       */
      EnumEntry[] enumMapping() default {};
  
      /**
       * For flags packed into primitive {int} properties, model the string names of the flags.
       *
       * Note that {@link #flagMapping()} cannot be used simultaneously with {@link #enumMapping()}.
       *
       * @return An array of {@link FlagEntry}, empty if not applicable
       * @see android.annotation.IntDef
       * @see IntFlagMapping
       */
      FlagEntry[] flagMapping() default {};
  
  
      /**
       * One entry in an enumeration packed into a primitive {int}.
       *
       * @see IntEnumMapping
       * @hide
       */
      @Target({TYPE})
      @Retention(SOURCE)
      @TestApi
      @interface EnumEntry {
          /**
           * The string name of this enumeration value.
           *
           * @return A string name
           */
          String name();
  
          /**
           * The integer value of this enumeration value.
           *
           * @return An integer value
           */
          int value();
      }
  
      /**
       * One flag value of many that may be packed into a primitive {int}.
       *
       * @see IntFlagMapping
       * @hide
       */
      @Target({TYPE})
      @Retention(SOURCE)
      @TestApi
      @interface FlagEntry {
          /**
           * The string name of this flag.
           *
           * @return A string name
           */
          String name();
  
          /**
           * A target value that the property's value must equal after masking.
           *
           * If a mask is not supplied (i.e., {@link #mask()} is 0), the target will be reused as the
           * mask. This handles the common case where no flags mutually exclude each other.
           *
           * @return The target value to compare against
           */
          int target();
  
          /**
           * A mask that the property will be bitwise anded with before comparing to the target.
           *
           * If set to 0 (the default), the value of {@link #target()} will be used as a mask. Zero
           * was chosen as the default since bitwise and with zero is always zero.
           *
           * @return A mask, or 0 to use the target as a mask
           */
          int mask() default 0;
      }
  
      /**
       * The type of value packed into a primitive {int}.
       *
       * @hide
       */
      @TestApi
      enum ValueType {
          /**
           * No special handling, property is considered to be a numeric value.
           *
           * @hide
           */
          @TestApi
          NONE,
  
          /**
           * The default the annotation processor infers the value type from context.
           *
           * @hide
           */
          @TestApi
          INFERRED,
  
          /**
           * Value packs an enumeration.
           *
           * This is inferred if {@link #enumMapping()} is specified.
           *
           * @see EnumEntry
           * @hide
           */
          @TestApi
          INT_ENUM,
  
          /**
           * Value packs flags, of which many may be enabled at once.
           *
           * This is inferred if {@link #flagMapping()} is specified.
           *
           * @see FlagEntry
           * @hide
           */
          @TestApi
          INT_FLAG,
  
          /**
           * Value packs color information.
           *
           * This is inferred from {@link android.annotation.ColorInt}, or
           * {@link android.annotation.ColorLong} on the getter method.
           *
           * @see android.graphics.Color
           * @hide
           */
          @TestApi
          COLOR,
  
          /**
           * Value packs gravity information.
           *
           * This type is not inferred, and is non-trivial to represent using {@link FlagEntry}.
           *
           * @see android.view.Gravity
           * @hide
           */
          @TestApi
          GRAVITY,
  
          /**
           * Value is a resource ID
           *
           * This type is inferred from the presence of a resource ID annotation such as
           * {@link android.annotation.AnyRes}.
           *
           * @hide
           */
          @TestApi
          RESOURCE_ID
      }
  }
  