javadocs and renaming of internal methods

Author: brachy84

src/main/java/com/cleanroommc/modularui/api/widget/IFocusedWidget.java

@@ -4,6 +4,7 @@
 
 /**
  * An interface for {@link IWidget}'s, that makes them focusable.
+ * Usually used for text fields to receive keyboard and mouse input first, no matter if its hovered or not.
  */
 public interface IFocusedWidget {
 

src/main/java/com/cleanroommc/modularui/api/widget/Interactable.java

@@ -108,8 +108,7 @@ default boolean onMouseScroll(ModularScreen.UpOrDown scrollDirection, int amount
      * @param mouseButton    mouse button that drags
      * @param timeSinceClick time since drag began
      */
-    default void onMouseDrag(int mouseButton, long timeSinceClick) {
-    }
+    default void onMouseDrag(int mouseButton, long timeSinceClick) {}
 
     /**
      * @return if left or right ctrl/cmd is pressed

src/main/java/com/cleanroommc/modularui/overlay/OverlayStack.java

@@ -58,9 +58,9 @@ public static void draw(int mouseX, int mouseY, float partialTicks) {
             screen.getContext().updateState(mouseX, mouseY, partialTicks);
             GlStateManager.enableBlend();
             GlStateManager.color(1f, 1f, 1f, 1f);
-            screen.drawScreen(mouseX, mouseY, partialTicks);
+            screen.drawScreen();
             GlStateManager.color(1f, 1f, 1f, 1f);
-            screen.drawForeground(partialTicks);
+            screen.drawForeground();
             if (screen.getContext().getHovered() != null) hovered = screen;
             fallback = screen;
         }

src/main/java/com/cleanroommc/modularui/screen/ClientScreenHandler.java

@@ -213,7 +213,7 @@ private static boolean handleMouseInput(int button, @Nullable ModularScreen muiS
             }
             acc.setEventButton(button);
             acc.setLastMouseEvent(Minecraft.getSystemTime());
-            if (muiScreen != null && muiScreen.handleDraggableInput(button, true)) return true;
+            if (muiScreen != null && muiScreen.onMouseInputPre(button, true)) return true;
             return doAction(muiScreen, ms -> ms.onMousePressed(button));
         }
         if (button != -1) {
@@ -227,7 +227,7 @@ private static boolean handleMouseInput(int button, @Nullable ModularScreen muiS
                 }
             }
             acc.setEventButton(-1);
-            if (muiScreen != null && muiScreen.handleDraggableInput(button, false)) return true;
+            if (muiScreen != null && muiScreen.onMouseInputPre(button, false)) return true;
             return doAction(muiScreen, ms -> ms.onMouseRelease(button));
         }
         if (acc.getEventButton() != -1 && acc.getLastMouseEvent() > 0L) {
@@ -344,15 +344,15 @@ public static void drawScreen(ModularScreen muiScreen, GuiScreen mcScreen, int m
     public static void drawScreenInternal(ModularScreen muiScreen, GuiScreen mcScreen, int mouseX, int mouseY, float partialTicks) {
         Stencil.reset();
         Stencil.apply(muiScreen.getScreenArea(), null);
-        muiScreen.drawScreen(mouseX, mouseY, partialTicks);
+        muiScreen.drawScreen();
         GlStateManager.disableLighting();
         GlStateManager.disableDepth();
         drawVanillaElements(mcScreen, mouseX, mouseY, partialTicks);
         GlStateManager.color(1.0F, 1.0F, 1.0F, 1.0F);
         GlStateManager.enableRescaleNormal();
         OpenGlHelper.setLightmapTextureCoords(OpenGlHelper.lightmapTexUnit, 240.0F, 240.0F);
         RenderHelper.disableStandardItemLighting();
-        muiScreen.drawForeground(partialTicks);
+        muiScreen.drawForeground();
         GlStateManager.enableLighting();
         GlStateManager.enableDepth();
         GlStateManager.enableRescaleNormal();
@@ -370,7 +370,7 @@ public static void drawContainer(ModularScreen muiScreen, GuiContainer mcScreen,
         int y = mcScreen.getGuiTop();
 
         acc.invokeDrawGuiContainerBackgroundLayer(partialTicks, mouseX, mouseY);
-        muiScreen.drawScreen(mouseX, mouseY, partialTicks);
+        muiScreen.drawScreen();
 
         GlStateManager.disableLighting();
         GlStateManager.disableDepth();
@@ -385,7 +385,7 @@ public static void drawContainer(ModularScreen muiScreen, GuiContainer mcScreen,
         GlStateManager.color(1.0F, 1.0F, 1.0F, 1.0F);
         RenderHelper.disableStandardItemLighting();
         acc.invokeDrawGuiContainerForegroundLayer(mouseX, mouseY);
-        muiScreen.drawForeground(partialTicks);
+        muiScreen.drawForeground();
         RenderHelper.enableGUIStandardItemLighting();
 
         acc.setHoveredSlot(null);

src/main/java/com/cleanroommc/modularui/screen/ModularScreen.java

@@ -37,7 +37,7 @@
 import java.util.function.Function;
 
 /**
- * This is the base class for all modular ui's. It only exists on client side.
+ * This is the base class for all modular UIs. It only exists on client side.
  * It handles drawing the screen, all panels and widget interactions.
  */
 @SideOnly(Side.CLIENT)
@@ -128,6 +128,11 @@ ModularPanel buildUI(ModularGuiContext context) {
         throw new UnsupportedOperationException();
     }
 
+    /**
+     * Should be called in custom {@link GuiScreen GuiScreen} constructors which implement {@link IMuiScreen}.
+     *
+     * @param wrapper the gui screen wrapping this screen
+     */
     @MustBeInvokedByOverriders
     public void construct(IMuiScreen wrapper) {
         if (this.screenWrapper != null) throw new IllegalStateException("ModularScreen is already constructed!");
@@ -149,6 +154,15 @@ public void constructOverlay(GuiScreen screen) {
         this.overlay = true;
     }
 
+    /**
+     * Called everytime the Game window changes its size. Overriding for additional logic is allowed, but super must be called.
+     * This method resizes the entire widget tree of every panel currently open and then updates the size of the {@link IMuiScreen} wrapper.
+     * <p>
+     * Do not call this method except in an override!
+     *
+     * @param width  with of the resized game window
+     * @param height height of the resized game window
+     */
     @MustBeInvokedByOverriders
     public void onResize(int width, int height) {
         this.context.updateScreenArea(width, height);
@@ -234,13 +248,22 @@ public boolean isPanelOpen(ModularPanel panel) {
         return this.panelManager.hasOpenPanel(panel);
     }
 
+    /**
+     * Called at the start of every client tick (20 times per second).
+     */
     @MustBeInvokedByOverriders
     public void onUpdate() {
         for (ModularPanel panel : this.panelManager.getOpenPanels()) {
             WidgetTree.onUpdate(panel);
         }
     }
 
+    /**
+     * Called 60 times per second in custom ticks. This logic is separate from rendering.
+     *
+     * @deprecated logic may be moved to rendering
+     */
+    @Deprecated
     @MustBeInvokedByOverriders
     public void onFrameUpdate() {
         this.panelManager.checkDirty();
@@ -255,7 +278,12 @@ public void onFrameUpdate() {
         this.context.onFrameUpdate();
     }
 
-    public void drawScreen(int mouseX, int mouseY, float partialTicks) {
+    /**
+     * Draws this screen and all open panels with their whole widget tree.
+     * <p>
+     * Do not call, only override!
+     */
+    public void drawScreen() {
         GlStateManager.disableRescaleNormal();
         RenderHelper.disableStandardItemLighting();
         GlStateManager.disableLighting();
@@ -281,7 +309,12 @@ public void drawScreen(int mouseX, int mouseY, float partialTicks) {
         GlStateManager.enableAlpha();
     }
 
-    public void drawForeground(float partialTicks) {
+    /**
+     * Called after all panels with their whole widget trees and potential additional elements are drawn.
+     * <p>
+     * Do not call, only override!
+     */
+    public void drawForeground() {
         GlStateManager.disableRescaleNormal();
         RenderHelper.disableStandardItemLighting();
         GlStateManager.disableLighting();
@@ -304,7 +337,11 @@ public void drawForeground(float partialTicks) {
         GlStateManager.enableAlpha();
     }
 
-    public boolean handleDraggableInput(int button, boolean pressed) {
+    /**
+     * Called when a mouse button is pressed or released. Used to handle dropping of currently dragged elements.
+     */
+    @ApiStatus.Internal
+    public final boolean onMouseInputPre(int button, boolean pressed) {
         if (this.context.hasDraggable()) {
             if (pressed) {
                 this.context.onMousePressed(button);
@@ -316,6 +353,15 @@ public boolean handleDraggableInput(int button, boolean pressed) {
         return false;
     }
 
+    /**
+     * Called when a mouse button is pressed. Tries to invoke
+     * {@link com.cleanroommc.modularui.api.widget.Interactable#onMousePressed(int) Interactable#onMousePressed(int)} on every widget under
+     * the mouse after gui action listeners have been called. Will try to focus widgets that have been interacted with.
+     * Focused widgets will be interacted with first in other interaction methods (mouse scroll, release and drag, key press and release).
+     *
+     * @param mouseButton mouse button (0 = left button, 1 = right button, 2 = scroll button, 4 and 5 = side buttons)
+     * @return true if the action was consumed and further processing should be canceled
+     */
     public boolean onMousePressed(int mouseButton) {
         for (IGuiAction.MousePressed action : getGuiActionListeners(IGuiAction.MousePressed.class)) {
             action.press(mouseButton);
@@ -334,6 +380,14 @@ public boolean onMousePressed(int mouseButton) {
         return false;
     }
 
+    /**
+     * Called when a mouse button is released. Tries to invoke
+     * {@link com.cleanroommc.modularui.api.widget.Interactable#onMouseRelease(int) Interactable#onMouseRelease(int)} on every widget under
+     * the mouse after gui action listeners have been called.
+     *
+     * @param mouseButton mouse button (0 = left button, 1 = right button, 2 = scroll button, 4 and 5 = side buttons)
+     * @return true if the action was consumed and further processing should be canceled
+     */
     public boolean onMouseRelease(int mouseButton) {
         for (IGuiAction.MouseReleased action : getGuiActionListeners(IGuiAction.MouseReleased.class)) {
             action.release(mouseButton);
@@ -352,6 +406,15 @@ public boolean onMouseRelease(int mouseButton) {
         return false;
     }
 
+    /**
+     * Called when a keyboard key is pressed. Tries to invoke
+     * {@link com.cleanroommc.modularui.api.widget.Interactable#onKeyPressed(char, int) Interactable#onKeyPressed(char, int)} on every
+     * widget under the mouse after gui action listeners have been called.
+     *
+     * @param typedChar the character of the pressed key or {@link Character#MIN_VALUE} for keys without a character
+     * @param keyCode   the key code of the pressed key (see constants at {@link org.lwjgl.input.Keyboard})
+     * @return true if the action was consumed and further processing should be canceled
+     */
     public boolean onKeyPressed(char typedChar, int keyCode) {
         for (IGuiAction.KeyPressed action : getGuiActionListeners(IGuiAction.KeyPressed.class)) {
             action.press(typedChar, keyCode);
@@ -367,6 +430,15 @@ public boolean onKeyPressed(char typedChar, int keyCode) {
         return false;
     }
 
+    /**
+     * Called when a keyboard key is released. Tries to invoke
+     * {@link com.cleanroommc.modularui.api.widget.Interactable#onKeyRelease(char, int) Interactable#onKeyRelease(char, int)} on every
+     * widget under the mouse after gui action listeners have been called.
+     *
+     * @param typedChar the character of the released key or {@link Character#MIN_VALUE} for keys without a character
+     * @param keyCode   the key code of the released key (see constants at {@link org.lwjgl.input.Keyboard})
+     * @return true if the action was consumed and further processing should be canceled
+     */
     public boolean onKeyRelease(char typedChar, int keyCode) {
         for (IGuiAction.KeyReleased action : getGuiActionListeners(IGuiAction.KeyReleased.class)) {
             action.release(typedChar, keyCode);
@@ -382,6 +454,16 @@ public boolean onKeyRelease(char typedChar, int keyCode) {
         return false;
     }
 
+    /**
+     * Called when a mouse button is released. Tries to invoke
+     * {@link com.cleanroommc.modularui.api.widget.Interactable#onMouseScroll(UpOrDown, int) Interactable#onMouseScroll(UpOrDown,int)} on every widget under
+     * the mouse after gui action listeners have been called.
+     *
+     * @param scrollDirection the direction of the scroll
+     * @param amount          the amount that has been scrolled. This value will always be > 0. It is not recommended to use this value to determine
+     *                        scroll speed
+     * @return true if the action was consumed and further processing should be canceled
+     */
     public boolean onMouseScroll(UpOrDown scrollDirection, int amount) {
         for (IGuiAction.MouseScroll action : getGuiActionListeners(IGuiAction.MouseScroll.class)) {
             action.scroll(scrollDirection, amount);
@@ -397,6 +479,15 @@ public boolean onMouseScroll(UpOrDown scrollDirection, int amount) {
         return false;
     }
 
+    /**
+     * Called every time the mouse pos changes and a mouse button is held down. Invokes
+     * {@link com.cleanroommc.modularui.api.widget.Interactable#onMouseDrag(int, long) Interactable#onMouseDrag(int,long)} on every widget
+     * under the mouse after gui action listeners have been called.
+     *
+     * @param mouseButton    mouse button that is held down (0 = left button, 1 = right button, 2 = scroll button, 4 and 5 = side buttons)
+     * @param timeSinceClick how long the button has been held down until now in milliseconds
+     * @return true if the action was consumed and further processing should be canceled
+     */
     public boolean onMouseDrag(int mouseButton, long timeSinceClick) {
         for (IGuiAction.MouseDrag action : getGuiActionListeners(IGuiAction.MouseDrag.class)) {
             action.drag(mouseButton, timeSinceClick);
@@ -412,29 +503,59 @@ public boolean onMouseDrag(int mouseButton, long timeSinceClick) {
         return false;
     }
 
+    /**
+     * Called with {@code true} after a widget which implements {@link com.cleanroommc.modularui.api.widget.IFocusedWidget IFocusedWidget}
+     * has consumed a mouse press and called with {@code false} if a widget is currently focused and anything else has consumed a mouse
+     * press. This is required for other mods like JEI/NEI to not interfere with inputs.
+     *
+     * @param focus true if the gui screen will be focused
+     */
     @ApiStatus.Internal
     public void setFocused(boolean focus) {
         this.screenWrapper.setFocused(focus);
     }
 
+    /**
+     * @return true if this screen is currently open and displayed on the screen
+     */
     public boolean isActive() {
         return getCurrent() == this;
     }
 
+    /**
+     * The owner of this screen. Usually a modid. This is mainly used to find theme overrides.
+     *
+     * @return owner of this screen
+     */
     @NotNull
     public String getOwner() {
         return this.owner;
     }
 
+    /**
+     * The name of this screen, which is also the name of the panel. Every UI under one owner should have a different name.
+     * Unfortunately there is no good way to verify this, so it's the UI implementors responsibility to set a proper name for the main panel.
+     * This is mainly used to find theme overrides.
+     *
+     * @return name of this screen
+     */
     @NotNull
     public String getName() {
         return this.name;
     }
 
+    /**
+     * @return the owner and name as a {@link ResourceLocation}
+     * @see #getOwner()
+     * @see #getName()
+     */
     public ResourceLocation getResourceLocation() {
         return new ResourceLocation(this.owner, this.name);
     }
 
+    /**
+     * @return true if this is an overlay for another screen
+     */
     public boolean isOverlay() {
         return overlay;
     }
@@ -565,16 +686,31 @@ public ITheme getCurrentTheme() {
         return this.currentTheme;
     }
 
+    /**
+     * Tries to use a specific theme for this screen. If the theme for this screen has been overriden via resource packs, this method does
+     * nothing.
+     *
+     * @param theme id of theme to use
+     * @return this for builder like usage
+     */
     public ModularScreen useTheme(String theme) {
         this.currentTheme = IThemeApi.get().getThemeForScreen(this, theme);
         return this;
     }
 
+    /**
+     * Sets if the gui should pause the game in the background. Pausing means every ticking will halt. If the client is connected to a
+     * dedicated server the UI will NEVER pause the game.
+     *
+     * @param pausesGame true if the ui should pause the game in the background.
+     * @return this for builder like usage
+     */
     public ModularScreen pausesGame(boolean pausesGame) {
         this.pausesGame = pausesGame;
         return this;
     }
 
+    // TODO move this to a more appropriate place
     public enum UpOrDown {
         UP(1), DOWN(-1);