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.

    • 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

        @NonNls
java.lang.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

        java.lang.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

        java.lang.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