Package org.intellij.lang.annotations

## Annotation Type MagicConstant

-     @Retention(SOURCE)
      @Target({FIELD,PARAMETER,LOCAL_VARIABLE,ANNOTATION_TYPE,METHOD})
      public @interface MagicConstant

  This annotation intended to help IntelliJ IDEA and other IDEs to detect and auto-complete int and String constants used as an enumeration. For example, in the `Label(String, int)` constructor the `alignment` parameter can be one of the following int constants: `Label.LEFT`, `Label.CENTER` or `Label.RIGHT`

  So, if `@MagicConstant` annotation applied to this constructor, the IDE will check the constructor usages for the allowed values.

  E.g.

       new Label("text", 0); // 0 is not allowed
       new Label("text", Label.LEFT); // OK

  `@MagicConstant` can be applied to:

  - Field, local variable, parameter.
    E.g.

        @MagicConstant(intValues = {TOP, CENTER, BOTTOM})
         int textPosition;

    The IDE will check expressions assigned to the variable for allowed values:

          textPosition = 0; // not allowed
          textPosition = TOP; // OK

  - Method
    E.g.

        @MagicConstant(flagsFromClass = java.lang.reflect.Modifier.class)
          public native int getModifiers();

    The IDE will analyse getModifiers() method calls and check if its return value is used with allowed values:

          if (aClass.getModifiers() == 3) // not allowed
          if (aClass.getModifiers() == Modifier.PUBLIC) // OK

  - Annotation class
    Annotation class annotated with `@MagicConstant` created alias you can use to annotate everything as if it was annotated with `@MagicConstant` itself.
    E.g.

        @MagicConstant(flags = {Font.PLAIN, Font.BOLD, Font.ITALIC})

        @interface FontStyle {}

    The IDE will check constructs annotated with @FontStyle for allowed values:
    `@FontStyle int myStyle = 3; // not allowed
    ` `@FontStyle int myStyle = Font.BOLD | Font.ITALIC; // OK`
  The `@MagicConstant` annotation has SOURCE retention, i.e. it is removed upon compilation and does not create any runtime overhead.

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element | Description
    --- | --- | ---
    `long[]` | `flags` |
    `Class` | `flagsFromClass` |
    `long[]` | `intValues` |
    `String[]` | `stringValues` |
    `Class` | `valuesFromClass` |

- - ### Element Detail

    - #### intValues

          long[] intValues

      Returns:
        int values (typically named constants) which are allowed here. E.g.

             void setConfirmOpenNewProject(@MagicConstant(intValues = {OPEN_PROJECT_ASK, OPEN_PROJECT_NEW_WINDOW, OPEN_PROJECT_SAME_WINDOW})
                                           int confirmOpenNewProject);

      Default:
        {}

  - - #### stringValues

          String[] stringValues

      Returns:
        String values (typically named constants) which are allowed here.
      Default:
        {}

  - - #### flags

          long[] flags

      Returns:
        allowed int flags (i.e. values (typically named constants) which can be combined with bitwise OR operator (|). The difference from the `intValues()` is that flags are allowed to be combined (via plus:+ or bitwise OR: |) whereas values aren't. The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively. E.g.

             @MagicConstant(flags = {HierarchyEvent.PARENT_CHANGED,HierarchyEvent.DISPLAYABILITY_CHANGED,HierarchyEvent.SHOWING_CHANGED})
             int hFlags;

             hFlags = 3; // not allowed; should be "magic" constant.
             if (hFlags & (HierarchyEvent.PARENT_CHANGED | HierarchyEvent.SHOWING_CHANGED) != 0); // OK: combined several constants via bitwise OR

      Default:
        {}

  - - #### valuesFromClass

          Class valuesFromClass

      Returns:
        allowed values which are defined in the specified class public static final constants. E.g.

             @MagicConstant(valuesFromClass = Cursor.class)
             int cursorType;

             cursorType = 11; // not allowed; should be "magic" constant.
             cursorType = Cursor.E_RESIZE_CURSOR; // OK: "magic" constant used.

      Default:
        void.class

  - - #### flagsFromClass

          Class flagsFromClass

      Returns:
        allowed int flags which are defined in the specified class public static final constants. The difference from the `valuesFromClass()` is that flags are allowed to be combined (via plus:+ or bitwise OR: |) whereas values aren't. The literals "0" and "-1" are also allowed to denote absence and presense of all flags respectively. E.g.

             @MagicConstant(flagsFromClass = java.awt.InputEvent.class)
             int eventMask;

             eventMask = 10; // not allowed; should be "magic" constant.
             eventMask = InputEvent.CTRL_MASK | InputEvent.ALT_MASK; // OK: combined several constants via bitwise OR

      Default:
        void.class