rl-api: add MagicConstant annotations

2021-09-27 00:36:19 -06:00
parent 4f01dabed4
commit 22d1014bd3
8 changed files with 69 additions and 25 deletions
--- a/runelite-api/pom.xml
+++ b/runelite-api/pom.xml
@@ -50,6 +50,12 @@
 			<artifactId>jsr305</artifactId>
 			<scope>provided</scope>
 		</dependency>
+		<dependency>
+			<groupId>org.jetbrains</groupId>
+			<artifactId>annotations</artifactId>
+			<version>23.0.0</version>
+			<scope>provided</scope>
+		</dependency>

 		<dependency>
 			<groupId>junit</groupId>
--- a/runelite-api/src/main/java/net/runelite/api/Client.java
+++ b/runelite-api/src/main/java/net/runelite/api/Client.java
@@ -34,15 +34,18 @@ import javax.annotation.Nullable;
 import net.runelite.api.annotations.VisibleForDevtools;
 import net.runelite.api.annotations.VisibleForExternalPlugins;
 import net.runelite.api.clan.ClanChannel;
+import net.runelite.api.clan.ClanID;
 import net.runelite.api.clan.ClanSettings;
 import net.runelite.api.coords.LocalPoint;
 import net.runelite.api.coords.WorldPoint;
 import net.runelite.api.hooks.Callbacks;
 import net.runelite.api.hooks.DrawCallbacks;
 import net.runelite.api.vars.AccountType;
+import net.runelite.api.widgets.ItemQuantityMode;
 import net.runelite.api.widgets.Widget;
 import net.runelite.api.widgets.WidgetConfig;
 import net.runelite.api.widgets.WidgetInfo;
+import org.intellij.lang.annotations.MagicConstant;

 /**
 * Represents the RuneScape client.
@@ -392,7 +395,7 @@ public interface Client extends GameEngine
 	 * @return the created sprite
 	 */
 	@Nullable
-	SpritePixels createItemSprite(int itemId, int quantity, int border, int shadowColor, int stackable, boolean noted, int scale);
+	SpritePixels createItemSprite(int itemId, int quantity, int border, int shadowColor, @MagicConstant(valuesFromClass = ItemQuantityMode.class) int stackable, boolean noted, int scale);

 	/**
 	 * Loads and creates the sprite images of the passed archive and file IDs.
@@ -873,7 +876,7 @@ public interface Client extends GameEngine
 	 *
 	 * @return the widget flags table
 	 */
-	HashTable getWidgetFlags();
+	HashTable<IntegerNode> getWidgetFlags();

 	/**
 	 * Gets the widget node component table.
@@ -1937,7 +1940,7 @@ public interface Client extends GameEngine
 	 * @return
 	 * @see KeyCode
 	 */
-	boolean isKeyPressed(int keycode);
+	boolean isKeyPressed(@MagicConstant(valuesFromClass = KeyCode.class) int keycode);

 	/**
 	 * Get the list of message ids for the recently received cross-world messages. The upper 32 bits of the
@@ -1989,7 +1992,7 @@ public interface Client extends GameEngine
 	 * @see net.runelite.api.clan.ClanID
 	 */
 	@Nullable
-	ClanChannel getClanChannel(int clanId);
+	ClanChannel getClanChannel(@MagicConstant(valuesFromClass = ClanID.class) int clanId);

 	/**
 	 * Get clan settings by id
@@ -1998,7 +2001,7 @@ public interface Client extends GameEngine
 	 * @see net.runelite.api.clan.ClanID
 	 */
 	@Nullable
-	ClanSettings getClanSettings(int clanId);
+	ClanSettings getClanSettings(@MagicConstant(valuesFromClass = ClanID.class) int clanId);

 	void setUnlockedFps(boolean unlock);
 	void setUnlockedFpsTarget(int fps);
--- a/runelite-api/src/main/java/net/runelite/api/CollisionData.java
+++ b/runelite-api/src/main/java/net/runelite/api/CollisionData.java
@@ -24,6 +24,8 @@
 */
 package net.runelite.api;

+import org.intellij.lang.annotations.MagicConstant;
+
 /**
 * Represents tile collision data for the scene
 */
@@ -42,5 +44,6 @@ public interface CollisionData
 	 * @return all collision flags for the tiles in the scene
 	 * @see Constants#SCENE_SIZE
 	 */
+	@MagicConstant(flagsFromClass = CollisionDataFlag.class)
 	int[][] getFlags();
 }
--- a/runelite-api/src/main/java/net/runelite/api/WidgetNode.java
+++ b/runelite-api/src/main/java/net/runelite/api/WidgetNode.java
@@ -24,6 +24,9 @@
 */
 package net.runelite.api;

+import net.runelite.api.widgets.WidgetModalMode;
+import org.intellij.lang.annotations.MagicConstant;
+
 /**
 * Represents a widget as an iterable node.
 */
@@ -40,5 +43,6 @@ public interface WidgetNode extends Node
 	/**
 	 * @see net.runelite.api.widgets.WidgetModalMode
 	 */
+	@MagicConstant(valuesFromClass = WidgetModalMode.class)
 	int getModalMode();
 }
--- a/runelite-api/src/main/java/net/runelite/api/events/ClanChannelChanged.java
+++ b/runelite-api/src/main/java/net/runelite/api/events/ClanChannelChanged.java
@@ -27,6 +27,8 @@ package net.runelite.api.events;
 import javax.annotation.Nullable;
 import lombok.Value;
 import net.runelite.api.clan.ClanChannel;
+import net.runelite.api.clan.ClanID;
+import org.intellij.lang.annotations.MagicConstant;

 /**
 * An event fired when the local player joins or leaves a clan channel.
@@ -43,6 +45,7 @@ public class ClanChannelChanged
 	 * The clan id, or -1 for guest clan
 	 * @see net.runelite.api.clan.ClanID
 	 */
+	@MagicConstant(valuesFromClass = ClanID.class)
 	private int clanId;
 	/**
 	 * Whether or not this was the guest clan channel
--- a/runelite-api/src/main/java/net/runelite/api/events/WidgetClosed.java
+++ b/runelite-api/src/main/java/net/runelite/api/events/WidgetClosed.java
@@ -25,6 +25,8 @@
 package net.runelite.api.events;

 import lombok.Value;
+import net.runelite.api.widgets.WidgetModalMode;
+import org.intellij.lang.annotations.MagicConstant;

 /**
 * Posted when an interface is about to be closed
@@ -40,6 +42,7 @@ public class WidgetClosed
 	/**
 	 * @see net.runelite.api.widgets.WidgetModalMode
 	 */
+	@MagicConstant(valuesFromClass = WidgetModalMode.class)
 	private final int modalMode;

 	/**
--- a/runelite-api/src/main/java/net/runelite/api/widgets/Widget.java
+++ b/runelite-api/src/main/java/net/runelite/api/widgets/Widget.java
@@ -29,6 +29,8 @@ import java.util.Collection;
 import javax.annotation.Nullable;
 import net.runelite.api.FontTypeFace;
 import net.runelite.api.Point;
+import org.intellij.lang.annotations.MagicConstant;
+import org.jetbrains.annotations.Range;

 /**
 * Represents an on-screen UI element that is drawn on the canvas.
@@ -59,6 +61,7 @@ public interface Widget
 	 *
 	 * @see WidgetType
 	 */
+	@MagicConstant(valuesFromClass = WidgetType.class)
 	int getType();

 	/**
@@ -66,7 +69,7 @@ public interface Widget
 	 *
 	 * @see WidgetType
 	 */
-	void setType(int type);
+	void setType(@MagicConstant(valuesFromClass = WidgetType.class) int type);

 	/**
 	 * Gets the type of content displayed by the widget.
@@ -81,9 +84,8 @@ public interface Widget
 	/**
 	 * Gets the current click configuration of the widget.
 	 * @see WidgetConfig
-	 *
-	 * @see WidgetConfig
 	 */
+	@MagicConstant(flagsFromClass = WidgetConfig.class)
 	int getClickMask();

 	/**
@@ -91,7 +93,7 @@ public interface Widget
 	 *
 	 * @see WidgetConfig
 	 */
-	Widget setClickMask(int mask);
+	Widget setClickMask(@MagicConstant(flagsFromClass = WidgetConfig.class) int mask);

 	/**
 	 * Gets the parent widget, if this widget is a child.
@@ -246,7 +248,7 @@ public interface Widget
 	/**
 	 * Gets the Model/NPC/Item ID displayed in the widget.
 	 *
-	 * @see WidgetModelType
+	 * @see #getModelType()
 	 */
 	int getModelId();

@@ -262,6 +264,7 @@ public interface Widget
 	 *
 	 * @see WidgetModelType
 	 */
+	@MagicConstant(valuesFromClass = WidgetModelType.class)
 	int getModelType();

 	/**
@@ -270,7 +273,7 @@ public interface Widget
 	 * @param type the new model type
 	 * @see WidgetModelType
 	 */
-	Widget setModelType(int type);
+	Widget setModelType(@MagicConstant(valuesFromClass = WidgetModelType.class) int type);

 	/**
 	 * Gets the sequence ID used to animate the model in the widget
@@ -290,6 +293,7 @@ public interface Widget
 	 * Gets the x rotation of the model displayed in the widget.
 	 * 0 = no rotation, 2047 = full rotation
 	 */
+	@Range(from = 0, to = 2047)
 	int getRotationX();

 	/**
@@ -300,12 +304,13 @@ public interface Widget
 	 *
 	 * @param modelX the new model x rotation value
 	 */
-	Widget setRotationX(int modelX);
+	Widget setRotationX(@Range(from = 0, to = 2047) int modelX);

 	/**
 	 * Gets the y rotation of the model displayed in the widget.
 	 * 0 = no rotation, 2047 = full rotation
 	 */
+	@Range(from = 0, to = 2047)
 	int getRotationY();

 	/**
@@ -316,12 +321,13 @@ public interface Widget
 	 *
 	 * @param modelY the new model y rotation value
 	 */
-	Widget setRotationY(int modelY);
+	Widget setRotationY(@Range(from = 0, to = 2047) int modelY);

 	/**
 	 * Gets the z rotation of the model displayed in the widget.
 	 * 0 = no rotation, 2047 = full rotation
 	 */
+	@Range(from = 0, to = 2047)
 	int getRotationZ();

 	/**
@@ -332,7 +338,7 @@ public interface Widget
 	 *
 	 * @param modelZ the new model z rotation value
 	 */
-	Widget setRotationZ(int modelZ);
+	Widget setRotationZ(@Range(from = 0, to = 2047) int modelZ);

 	/**
 	 * Gets the amount zoomed in on the model displayed in the widget.
@@ -577,8 +583,13 @@ public interface Widget
 	 */
 	Widget setOriginalY(int originalY);

+	/**
+	 * Sets the X/Y coordinates
+	 */
 	Widget setPos(int x, int y);
-	Widget setPos(int x, int y, int xMode, int yMode);
+	Widget setPos(int x, int y,
+		@MagicConstant(valuesFromClass = WidgetPositionMode.class) int xMode,
+		@MagicConstant(valuesFromClass = WidgetPositionMode.class) int yMode);

 	/**
 	 * Gets the height coordinate of this widget before being adjusted by
@@ -609,7 +620,9 @@ public interface Widget
 	Widget setOriginalWidth(int originalWidth);

 	Widget setSize(int width, int height);
-	Widget setSize(int width, int height, int widthMode, int heightMode);
+	Widget setSize(int width, int height,
+		@MagicConstant(valuesFromClass = WidgetSizeMode.class) int widthMode,
+		@MagicConstant(valuesFromClass = WidgetSizeMode.class) int heightMode);

 	/**
 	 * Gets the menu options available on the widget as a sparse array.
@@ -622,14 +635,14 @@ public interface Widget
 	 * @param index the index of the new widget in the children list or -1 to append to the back
 	 * @param type  the {@link WidgetType} of the widget
 	 */
-	Widget createChild(int index, int type);
+	Widget createChild(int index, @MagicConstant(valuesFromClass = WidgetType.class) int type);

 	/**
 	 * Creates a dynamic widget child at the end of the children list
 	 *
 	 * @param type  the {@link WidgetType} of the widget
 	 */
-	Widget createChild(int type);
+	Widget createChild(@MagicConstant(valuesFromClass = WidgetType.class) int type);

 	/**
 	 * Removes all of this widget's dynamic children
@@ -821,11 +834,13 @@ public interface Widget
 	/**
 	 * Returns widget {@link net.runelite.api.widgets.ItemQuantityMode}.
 	 */
+	@MagicConstant(valuesFromClass = ItemQuantityMode.class)
 	int getItemQuantityMode();

 	/**
 	 * Sets the widget {@link net.runelite.api.widgets.ItemQuantityMode}
 	 */
+	@MagicConstant(valuesFromClass = ItemQuantityMode.class)
 	Widget setItemQuantityMode(int itemQuantityMode);

 	/**
@@ -833,6 +848,7 @@ public interface Widget
 	 *
 	 * @see WidgetPositionMode
 	 */
+	@MagicConstant(valuesFromClass = WidgetPositionMode.class)
 	int getXPositionMode();

 	/**
@@ -841,13 +857,14 @@ public interface Widget
 	 *
 	 * @see WidgetPositionMode
 	 */
-	Widget setXPositionMode(int xpm);
+	Widget setXPositionMode(@MagicConstant(valuesFromClass = WidgetPositionMode.class) int xpm);

 	/**
 	 * Gets the mode that the Y position is calculated from the original Y position
 	 *
 	 * @see WidgetPositionMode
 	 */
+	@MagicConstant(valuesFromClass = WidgetPositionMode.class)
 	int getYPositionMode();

 	/**
@@ -856,7 +873,7 @@ public interface Widget
 	 *
 	 * @see WidgetPositionMode
 	 */
-	Widget setYPositionMode(int ypm);
+	Widget setYPositionMode(@MagicConstant(valuesFromClass = WidgetPositionMode.class) int ypm);

 	/**
 	 * Get the line height for this widget.
@@ -877,6 +894,7 @@ public interface Widget
 	 *
 	 * @see WidgetTextAlignment
 	 */
+	@MagicConstant(valuesFromClass = WidgetTextAlignment.class)
 	int getXTextAlignment();

 	/**
@@ -884,13 +902,14 @@ public interface Widget
 	 *
 	 * @see WidgetTextAlignment
 	 */
-	Widget setXTextAlignment(int xta);
+	Widget setXTextAlignment(@MagicConstant(valuesFromClass = WidgetTextAlignment.class) int xta);

 	/**
 	 * Gets the Y axis text position mode
 	 *
 	 * @see WidgetTextAlignment
 	 */
+	@MagicConstant(valuesFromClass = WidgetTextAlignment.class)
 	int getYTextAlignment();

 	/**
@@ -898,13 +917,14 @@ public interface Widget
 	 *
 	 * @see WidgetTextAlignment
 	 */
-	Widget setYTextAlignment(int yta);
+	Widget setYTextAlignment(@MagicConstant(valuesFromClass = WidgetTextAlignment.class) int yta);

 	/**
 	 * Gets the mode controlling widget width
 	 *
 	 * @see WidgetSizeMode
 	 */
+	@MagicConstant(valuesFromClass = WidgetSizeMode.class)
 	int getWidthMode();

 	/**
@@ -913,13 +933,14 @@ public interface Widget
 	 *
 	 * @see WidgetSizeMode
 	 */
-	Widget setWidthMode(int widthMode);
+	Widget setWidthMode(@MagicConstant(valuesFromClass = WidgetSizeMode.class) int widthMode);

 	/**
 	 * Gets the mode controlling widget width
 	 *
 	 * @see WidgetSizeMode
 	 */
+	@MagicConstant(valuesFromClass = WidgetSizeMode.class)
 	int getHeightMode();

 	/**
@@ -928,7 +949,7 @@ public interface Widget
 	 *
 	 * @see WidgetSizeMode
 	 */
-	Widget setHeightMode(int heightMode);
+	Widget setHeightMode(@MagicConstant(valuesFromClass = WidgetSizeMode.class) int heightMode);

 	/**
 	 * Gets the font that this widget uses