diff --git a/src/main/java/com/cleanroommc/modularui/animation/Animator.java b/src/main/java/com/cleanroommc/modularui/animation/Animator.java index 014652eb3..af4e7e68b 100644 --- a/src/main/java/com/cleanroommc/modularui/animation/Animator.java +++ b/src/main/java/com/cleanroommc/modularui/animation/Animator.java @@ -63,6 +63,10 @@ public int advance(int elapsedTime) { return elapsedTime; } + /** + * + * @return {@code true} when the animation should be stopped + */ protected boolean onUpdate() { return this.onUpdate != null && this.onUpdate.test(getRawValue()); } @@ -171,8 +175,9 @@ public Animator curve(IInterpolation curve) { } /** - * Sets a function which is executed everytime the progress updates, that is on every frame. - * The argument of the function is the interpolated value. + * Sets a predicate function which is executed everytime the progress updates, that is on every frame. + * The argument of the function is the interpolated value.
+ * The predicate's return value effects {@link Animator#onUpdate()}'s return value. * * @param onUpdate update function * @return this @@ -183,8 +188,12 @@ public Animator onUpdate(DoublePredicate onUpdate) { } /** - * Sets a function which is executed everytime the progress updates, that is on every frame. - * The argument of the function is the interpolated value. + * Sets a consumer function which is executed everytime the progress updates, that is on every frame. + * The argument of the function is the interpolated value.
+ * The consumer will always be wrapped in q {@link DoublePredicate} returning false. + * + * @see Animator#onUpdate() + * @see Animator#onUpdate(DoublePredicate) * * @param onUpdate update function * @return this diff --git a/src/main/java/com/cleanroommc/modularui/animation/BaseAnimator.java b/src/main/java/com/cleanroommc/modularui/animation/BaseAnimator.java index bee3b77cc..73ea085ef 100644 --- a/src/main/java/com/cleanroommc/modularui/animation/BaseAnimator.java +++ b/src/main/java/com/cleanroommc/modularui/animation/BaseAnimator.java @@ -94,10 +94,10 @@ public final byte getDirection() { } /** - * Sets if the animation should reverse animate once after it finished. - * If the animation started in reverse it will animate forward on finish. + * Sets if the animation should be reversed after it finished. + * If the animation started in reverse, it will animate forwards after finishing. * - * @param reverseOnFinish if animation should bounce back on finish + * @param reverseOnFinish if animation should bounce back after finishing * @return this */ public A reverseOnFinish(boolean reverseOnFinish) { @@ -106,7 +106,7 @@ public A reverseOnFinish(boolean reverseOnFinish) { } /** - * Sets how often the animation should repeat. If {@link #reverseOnFinish(boolean)} is set to true, it will repeat the whole cycle. + * Sets how often the animation should repeat. If {@link #reverseOnFinish(boolean)} is set to {@code true}, it will repeat the whole cycle. * If the number of repeats is negative, it will repeat infinitely. * * @param repeats how often the animation should repeat. diff --git a/src/main/java/com/cleanroommc/modularui/animation/MutableObjectAnimator.java b/src/main/java/com/cleanroommc/modularui/animation/MutableObjectAnimator.java index a338bb8ca..299a09fe7 100644 --- a/src/main/java/com/cleanroommc/modularui/animation/MutableObjectAnimator.java +++ b/src/main/java/com/cleanroommc/modularui/animation/MutableObjectAnimator.java @@ -31,6 +31,12 @@ protected boolean onUpdate() { return super.onUpdate(); } + /** + * Sets an additional consumer function, that gets executed on every progress update (animation frame) + * before the {@link Animator#onUpdate()}. + * @param consumer the extra consumer + * @return this + */ public MutableObjectAnimator intermediateConsumer(Consumer consumer) { this.intermediateConsumer = consumer; return this; diff --git a/src/main/java/com/cleanroommc/modularui/animation/ParallelAnimator.java b/src/main/java/com/cleanroommc/modularui/animation/ParallelAnimator.java index e0e1b0cd2..15ffa9320 100644 --- a/src/main/java/com/cleanroommc/modularui/animation/ParallelAnimator.java +++ b/src/main/java/com/cleanroommc/modularui/animation/ParallelAnimator.java @@ -16,7 +16,7 @@ public class ParallelAnimator extends BaseAnimator implements public ParallelAnimator(List animators) { this.animators = new ArrayList<>(animators); this.animators.forEach(animator -> { - if (animator instanceof BaseAnimator baseAnimator) { + if (animator instanceof BaseAnimator baseAnimator) { baseAnimator.setParent(this); } }); @@ -26,7 +26,7 @@ public ParallelAnimator(IAnimator... animators) { this.animators = new ArrayList<>(); Collections.addAll(this.animators, animators); this.animators.forEach(animator -> { - if (animator instanceof BaseAnimator baseAnimator) { + if (animator instanceof BaseAnimator baseAnimator) { baseAnimator.setParent(this); } }); diff --git a/src/main/java/com/cleanroommc/modularui/api/IPanelHandler.java b/src/main/java/com/cleanroommc/modularui/api/IPanelHandler.java index abe9372be..91be472ed 100644 --- a/src/main/java/com/cleanroommc/modularui/api/IPanelHandler.java +++ b/src/main/java/com/cleanroommc/modularui/api/IPanelHandler.java @@ -9,13 +9,12 @@ import org.jetbrains.annotations.ApiStatus; /** - * This class can handle opening and closing of a {@link ModularPanel}. It makes sure, that the same panel is not created multiple - * times and instead reused. + * This class handles the opening and closing of a {@link ModularPanel}. It ensures, that the same panel is only created once & reused! *

Using {@link #openPanel()} is the only way to open multiple panels.

*

Panels can be closed with {@link #closePanel()}, but also with {@link ModularPanel#closeIfOpen()}. With the difference, that the method from this interface also works on server side.

- * Synced panels must be created with {@link PanelSyncManager#panel(String, PanelSyncHandler.IPanelBuilder, boolean)}. - * If the panel does not contain any synced widgets, a simple panel handler using {@link #simple(ModularPanel, SecondaryPanel.IPanelBuilder, boolean)} - * is likely what you need. + * Synced panels must be created with {@link PanelSyncManager#syncedPanel(String, boolean, PanelSyncHandler.IPanelBuilder)}. + * If a panel does not contain any synced widgets, a simple panel handler using {@link #simple(ModularPanel, SecondaryPanel.IPanelBuilder, boolean)} + * is likely what you should use. */ @ApiStatus.NonExtendable public interface IPanelHandler { @@ -38,19 +37,20 @@ static IPanelHandler simple(ModularPanel parent, SecondaryPanel.IPanelBuilder pr boolean isPanelOpen(); /** - * Opens the panel. If there is no cached panel, one will be created. + * Opens the panel. If there is no cached panel, it creates one instead. * Can be called on both sides if this handler is synced. */ void openPanel(); /** * Initiates the closing animation if the panel is open. + * This will also close any open sub panel. * Can be called on both sides if this handler is synced. */ void closePanel(); /** - * Initiates the closing animation of all sub panels. + * Initiates the closing animation for all sub panels. * Usually for internal use. */ void closeSubPanels(); @@ -78,16 +78,16 @@ default boolean togglePanel() { /** * Deletes the current cached panel. Should not be used frequently. - * This only works on panels which don't have {@link ItemSlotSH} sync handlers. + * This only works on panels, which don't have synchronized {@link ItemSlotSH} handlers. * - * @throws UnsupportedOperationException if this handler has ItemSlot sync handlers + * @throws UnsupportedOperationException if this handler has synchronized ItemSlot handlers */ void deleteCachedPanel(); /** * If this is a sub panel of another panel. A sub panel will be closed when its parent is closed. * - * @return true if this is a sub panel + * @return {@code true} if this is a sub panel */ boolean isSubPanel(); } diff --git a/src/main/java/com/cleanroommc/modularui/api/MCHelper.java b/src/main/java/com/cleanroommc/modularui/api/MCHelper.java index 1d1d4c7bd..9247d2f8f 100644 --- a/src/main/java/com/cleanroommc/modularui/api/MCHelper.java +++ b/src/main/java/com/cleanroommc/modularui/api/MCHelper.java @@ -95,6 +95,14 @@ public static FontRenderer getFontRenderer() { return null; } + /** + * Collects the provided item's tooltip depending on the {@link net.minecraft.client.gui.inventory.GuiContainer} it's displayed in. + * If the NEI mod is loaded, then all containers tooltip handlers for the given {@code item} will be executed and their result returned. + * Otherwise, each tooltip will be prefixed with a text color. The amount of tooltips depends additionally on the clients advanced tooltip display setting. + * + * @param item the provided item stack + * @return a list of strings representing the processed tooltips for the item stack + */ public static List getItemToolTip(ItemStack item) { if (!hasMc()) return Collections.emptyList(); if (ModularUI.Mods.NEI.isLoaded() && getMc().currentScreen instanceof GuiContainer guiContainer) @@ -123,6 +131,12 @@ private static List getNEIItemTooltip(ItemStack item, GuiContainer guiCo return tooltips; } + /** + * Collects the fluid's tooltip, depending on GT5U's loaded state, the clients advanced tooltip display setting and whether shift is pressed. + * + * @param fluid the provided fluid stack + * @return a list of strings representing the processed tooltips for the fluid stack + */ public static List getFluidTooltip(FluidStack fluid) { List tooltip = new ArrayList<>(); tooltip.add(fluid.getLocalizedName()); @@ -141,6 +155,12 @@ public static List getFluidTooltip(FluidStack fluid) { return tooltip; } + /** + * Collects fluid's additional tooltip, depending on NEI's loaded state and whether shift is pressed. + * + * @param fluid fluid the provided fluid stack + * @return a list of strings representing the processed tooltips for the fluid stack + */ public static List getAdditionalFluidTooltip(FluidStack fluid) { List tooltip = new ArrayList<>(); if (Interactable.hasShiftDown()) { diff --git a/src/main/java/com/cleanroommc/modularui/api/NEISettings.java b/src/main/java/com/cleanroommc/modularui/api/NEISettings.java index 723c8bf8a..ae2dc4d62 100644 --- a/src/main/java/com/cleanroommc/modularui/api/NEISettings.java +++ b/src/main/java/com/cleanroommc/modularui/api/NEISettings.java @@ -12,7 +12,9 @@ * Keeps track of everything related to NEI in a Modular GUI. * By default, NEI is disabled in client only GUIs. * This class can be safely interacted with even when NEI is not installed. + * @see RecipeViewerSettings */ +@Deprecated @ApiStatus.NonExtendable public interface NEISettings { diff --git a/src/main/java/com/cleanroommc/modularui/api/RecipeViewerSettings.java b/src/main/java/com/cleanroommc/modularui/api/RecipeViewerSettings.java index ffa25d60b..d3fc23add 100644 --- a/src/main/java/com/cleanroommc/modularui/api/RecipeViewerSettings.java +++ b/src/main/java/com/cleanroommc/modularui/api/RecipeViewerSettings.java @@ -35,6 +35,7 @@ public interface RecipeViewerSettings { /** * Only enable recipe viewer in synced GUIs + * @see com.cleanroommc.modularui.integration.recipeviewer.RecipeViewerState#DEFAULT RecipeViewerState#DEFAULT */ void defaultState(); @@ -46,7 +47,7 @@ public interface RecipeViewerSettings { * Checks if recipe viewer is enabled for a given screen * * @param screen modular screen - * @return true if jei is enabled + * @return true if recipe viewer is enabled */ boolean isEnabled(ModularScreen screen); diff --git a/src/main/java/com/cleanroommc/modularui/api/UIFactory.java b/src/main/java/com/cleanroommc/modularui/api/UIFactory.java index fc4b18cc4..4432e3eda 100644 --- a/src/main/java/com/cleanroommc/modularui/api/UIFactory.java +++ b/src/main/java/com/cleanroommc/modularui/api/UIFactory.java @@ -33,7 +33,7 @@ public interface UIFactory { String getFactoryName(); /** - * Creates the main panel for the GUI. Is called on client and server side. + * Creates the main panel for the GUI. It's called on client and server side. * * @param guiData gui data * @param syncManager sync manager @@ -44,7 +44,7 @@ public interface UIFactory { ModularPanel createPanel(D guiData, PanelSyncManager syncManager, UISettings settings); /** - * Creates the screen for the GUI. Is only called on client side. + * Creates the screen for the GUI. It's only called on client side. * * @param guiData gui data * @param mainPanel main panel created in {@link #createPanel(GuiData, PanelSyncManager, UISettings)} @@ -55,9 +55,9 @@ public interface UIFactory { ModularScreen createScreen(D guiData, ModularPanel mainPanel); /** - * Creates the screen wrapper for the GUI. Is only called on client side. + * Creates the screen wrapper for the GUI. It's only called on client side. * - * @param container container for the gui + * @param container container for the GUI * @param screen the screen which was created in {@link #createScreen(GuiData, ModularPanel)} * @return new screen wrapper * @throws IllegalStateException if the wrapping screen is not a {@link net.minecraft.client.gui.inventory.GuiContainer GuiContainer} or if the @@ -80,20 +80,20 @@ default ModularContainer createContainer() { } /** - * A default function to check if the current interacting player can interact with the ui. If not overridden on {@link UISettings}, + * A default function to check if the current interacting player can interact with the UI. If not overridden on {@link UISettings}, * then this is called every tick while a UI opened by this factory is open. Once this function returns false, the UI is immediately * closed. * * @param player current interacting player * @param guiData gui data of the current ui - * @return if the player can interact with the player. + * @return if the player can interact with the UI. */ default boolean canInteractWith(EntityPlayer player, D guiData) { return player == guiData.getPlayer(); } /** - * Writes the gui data to a buffer. + * Writes the gui data to the provided buffer. * * @param guiData gui data * @param buffer buffer @@ -102,9 +102,9 @@ default boolean canInteractWith(EntityPlayer player, D guiData) { void writeGuiData(D guiData, PacketBuffer buffer); /** - * Reads and creates the gui data from the buffer. + * Reads and creates the gui data from the provided buffer. * - * @param player player + * @param player current interacting player * @param buffer buffer * @return new gui data */ diff --git a/src/main/java/com/cleanroommc/modularui/api/drawable/IDrawable.java b/src/main/java/com/cleanroommc/modularui/api/drawable/IDrawable.java index 891ecf2c9..ed10b6c37 100644 --- a/src/main/java/com/cleanroommc/modularui/api/drawable/IDrawable.java +++ b/src/main/java/com/cleanroommc/modularui/api/drawable/IDrawable.java @@ -61,7 +61,7 @@ default void drawAtZero(GuiContext context, int width, int height, WidgetTheme w } /** - * Draws this drawable in a given area. The padding of the area is not applied here. + * Draws this drawable in a given area without any padding. * * @param context current context to draw with * @param area draw area @@ -98,7 +98,8 @@ default void drawAtZero(GuiContext context, Area area, WidgetTheme widgetTheme) } /** - * Draws this drawable at the current (0|0) with the given area's size and its padding applied (this means its technically not at 0|0). + * Draws this drawable always with padding applied at (0|0) shifting the actual drawable content being drawn within + * ({@code 0 + padding.left} | {@code 0 + padding.top}) and ({@code area.paddedWith()}|{@code area.paddedHeight()}).
* This is useful inside widgets since GL is transformed to their position when they are drawing. The padding of the area is not applied * here. * diff --git a/src/main/java/com/cleanroommc/modularui/api/drawable/IIcon.java b/src/main/java/com/cleanroommc/modularui/api/drawable/IIcon.java index 25b7872b0..fc52da3d4 100644 --- a/src/main/java/com/cleanroommc/modularui/api/drawable/IIcon.java +++ b/src/main/java/com/cleanroommc/modularui/api/drawable/IIcon.java @@ -13,17 +13,17 @@ public interface IIcon extends IDrawable { /** - * @return the drawable this icon wraps or null if it doesn't wrap anything + * @return the drawable this icon wraps or {@code null} if it doesn't wrap anything */ @Nullable IDrawable getWrappedDrawable(); /** - * @return width of this icon or 0 if the width should be dynamic + * @return width of this icon or {@code 0} if the width should be dynamic */ int getWidth(); /** - * @return height of this icon or 0 of the height should be dynamic + * @return height of this icon or {@code 0} of the height should be dynamic */ int getHeight(); @@ -42,7 +42,7 @@ default int getDefaultHeight() { } /** - * @return the margin of this icon. Only used if width or height is 0 + * @return the margin of this icon. Only used if width or height is {@code 0} */ Box getMargin(); @@ -56,17 +56,17 @@ default IDrawable getRootDrawable() { } /** - * This returns a hoverable wrapper of this icon. This is only used in {@link com.cleanroommc.modularui.drawable.text.RichText RichText}. * This allows this icon to have its own tooltip. + * @return a hoverable wrapper of this icon. This is only used in {@link com.cleanroommc.modularui.drawable.text.RichText RichText} */ default HoverableIcon asHoverable() { return new HoverableIcon(this); } /** - * This returns an interactable wrapper of this icon. This is only used in - * {@link com.cleanroommc.modularui.drawable.text.RichText RichText}. This allows this icon to be able to listen to clicks and other - * inputs. + * This allows this icon to be able to listen to clicks and other inputs. + * @return an interactable wrapper of this icon. This is only used in + * {@link com.cleanroommc.modularui.drawable.text.RichText RichText}. */ default InteractableIcon asInteractable() { return new InteractableIcon(this); diff --git a/src/main/java/com/cleanroommc/modularui/api/drawable/IInterpolation.java b/src/main/java/com/cleanroommc/modularui/api/drawable/IInterpolation.java index 0c14a6d93..5d05de61a 100644 --- a/src/main/java/com/cleanroommc/modularui/api/drawable/IInterpolation.java +++ b/src/main/java/com/cleanroommc/modularui/api/drawable/IInterpolation.java @@ -1,8 +1,9 @@ package com.cleanroommc.modularui.api.drawable; /** - * A function which interpolates between two values. + * A functional interface interpolating between two values. */ +@FunctionalInterface public interface IInterpolation { /** diff --git a/src/main/java/com/cleanroommc/modularui/api/drawable/IKey.java b/src/main/java/com/cleanroommc/modularui/api/drawable/IKey.java index ec17ca805..2a86a08e2 100644 --- a/src/main/java/com/cleanroommc/modularui/api/drawable/IKey.java +++ b/src/main/java/com/cleanroommc/modularui/api/drawable/IKey.java @@ -69,7 +69,7 @@ public interface IKey extends IDrawable, IJsonSerializable { * Creates a translated text. * * @param key translation key - * @return text key + * @return the text key */ static IKey lang(@NotNull String key) { return new LangKey(key); @@ -80,7 +80,7 @@ static IKey lang(@NotNull String key) { * * @param key translation key * @param args translation arguments - * @return text key + * @return the text key */ static IKey lang(@NotNull String key, @Nullable Object... args) { return new LangKey(key, args); @@ -91,7 +91,7 @@ static IKey lang(@NotNull String key, @Nullable Object... args) { * * @param key translation key * @param argsSupplier translation arguments supplier - * @return text key + * @return the text key */ static IKey lang(@NotNull String key, @NotNull Supplier argsSupplier) { return new LangKey(key, argsSupplier); @@ -101,7 +101,7 @@ static IKey lang(@NotNull String key, @NotNull Supplier argsSupplier) * Creates a translated text. * * @param keySupplier translation key supplier - * @return text key + * @return the text key */ static IKey lang(@NotNull Supplier keySupplier) { return new LangKey(keySupplier); @@ -112,7 +112,7 @@ static IKey lang(@NotNull Supplier keySupplier) { * * @param keySupplier translation key supplier * @param argsSupplier translation arguments supplier - * @return text key + * @return the text key */ static IKey lang(@NotNull Supplier keySupplier, @NotNull Supplier argsSupplier) { return new LangKey(keySupplier, argsSupplier); @@ -122,7 +122,7 @@ static IKey lang(@NotNull Supplier keySupplier, @NotNull Supplier getter) { return dynamicKey(() -> IKey.str(getter.get())); @@ -172,7 +172,7 @@ static IKey dynamic(@NotNull Supplier<@NotNull String> getter) { * Creates a dynamic text key. * * @param getter key supplier - * @return dynamic text key + * @return the dynamic text key */ static IKey dynamicKey(@NotNull Supplier<@NotNull IKey> getter) { return new DynamicKey(getter); @@ -258,8 +258,9 @@ default AnimatedText withAnimation() { } /** - * @return a formatting state of this key + * @return the formatting state of this key */ + //TODO: consider un-defaulting this, as this looks like to be just a normal abstract function of an interface default @Nullable FormattingState getFormatting() { return null; } diff --git a/src/main/java/com/cleanroommc/modularui/api/drawable/IRichTextBuilder.java b/src/main/java/com/cleanroommc/modularui/api/drawable/IRichTextBuilder.java index 1dc19aa52..c31b44085 100644 --- a/src/main/java/com/cleanroommc/modularui/api/drawable/IRichTextBuilder.java +++ b/src/main/java/com/cleanroommc/modularui/api/drawable/IRichTextBuilder.java @@ -34,9 +34,9 @@ default T add(String s) { } /** - * Adds a drawable to the current line. If the drawable is not a {@link IIcon} it will convert to one with {@link IDrawable#asIcon()}. - * If that icon then has no default height (<=0) then it is set to the default text height (9 pixel). If the width of the icon is not - * set, then the width of the widest tooltip line is used. + * Adds a drawable to the current line. If the drawable is not an {@link IIcon}, it will be converted to (be) one using {@link IDrawable#asIcon()}. + * If that resulting icon has no default height ({@code <=0}) then it is set to the default text height (of {@code 9} pixels). If the width of the icon is not + * set, then the width of the widest tooltip line will be used. * * @param drawable drawable to add. * @return this @@ -70,7 +70,7 @@ default T addLine(IDrawable line) { } /** - * Starts a new line. This is always preferred over {@code "\n"} or {@code IKey.str("\n)}, it reduces computation a lot and maybe saves + * Starts a new line. This is always preferred over {@code "\n"} or {@code IKey.str("\n")}, it reduces computation a lot and maybe saves * a tiny bit of memory. * * @return this diff --git a/src/main/java/com/cleanroommc/modularui/api/layout/ILayoutWidget.java b/src/main/java/com/cleanroommc/modularui/api/layout/ILayoutWidget.java index a5d62ab83..8785de8c4 100644 --- a/src/main/java/com/cleanroommc/modularui/api/layout/ILayoutWidget.java +++ b/src/main/java/com/cleanroommc/modularui/api/layout/ILayoutWidget.java @@ -11,23 +11,24 @@ public interface ILayoutWidget extends INotifyEnabled { /** * Called after the children tried to calculate their size. This method responsible for laying out its children - * in itself. This includes calling {@link IResizeable#setSizeResized(boolean, boolean)} or one of its variants after a size with - * {@link com.cleanroommc.modularui.widget.sizer.Area#setSize(GuiAxis, int)} or one of its variants on each child. The same goes for - * position. If this widget also applies margin and padding (this is usually the case), then {@link IResizeable#setMarginPaddingApplied(boolean)} - * or one of its variants needs to be called to. + * within itself. This includes calling {@link IResizeable#setSizeResized(boolean, boolean)} or one of its variants after a size with + * {@link com.cleanroommc.modularui.widget.sizer.Area#setSize(GuiAxis, int)} or one of its variants on each child. + * The same applies to position modifications.
+ * If this widget also applies margin and padding (this is usually the case), then {@link IResizeable#setMarginPaddingApplied(boolean)} + * or one of its variants needs to be called too. *

- * Note that even if {@link #shouldIgnoreChildSize(IWidget)} returns false at least one of the {@code setResized} methods in - * {@link IResizeable} must be called. There is a no arg variant {@link IResizeable#updateResized()} which can also be used. - * Not doing so may result failure to resize the widget tree fully. + * Note that even if {@link #shouldIgnoreChildSize(IWidget)} returns {@code false} at least one of the {@code setResized} methods in + * {@link IResizeable} must be called. There is a no arg variant {@link IResizeable#updateResized()}, which can also be used. + * Not doing so may result in failure to resize the widget tree fully. * - * @return true if the layout was successful and no further iteration is needed + * @return {@code true} if the layout was successful and no further iteration is needed */ boolean layoutWidgets(); /** * Called after post calculation of this widget. The last call guarantees, that this widget is fully calculated. * - * @return true if the layout was successful and no further iteration is needed + * @return {@code true} if the layout was successful and no further iteration is needed */ default boolean postLayoutWidgets() { return true; @@ -38,10 +39,10 @@ default boolean canCoverByDefaultSize(GuiAxis axis) { } /** - * Called when determining wrapping size of this widget. - * If this method returns true, size and margin of the queried child will be ignored for calculation. - * Typically return true when the child is disabled and you want to collapse it for layout. - * This method should also be used for layouting children with {@link #layoutWidgets} if it might return true. + * Called when determining the wrapping size of this widget. + * If this method returns {@code true}, size and margin of the queried child will be ignored for calculation.
+ * Typically return {@code true} when the children are disabled and you want to collapse them for layout-ing.
+ * This method should also be used for layout-ing children with {@link #layoutWidgets} if it might return {@code true}. */ default boolean shouldIgnoreChildSize(IWidget child) { return false; diff --git a/src/main/java/com/cleanroommc/modularui/api/layout/IResizeParent.java b/src/main/java/com/cleanroommc/modularui/api/layout/IResizeParent.java index b4ad84519..55ad0cd1d 100644 --- a/src/main/java/com/cleanroommc/modularui/api/layout/IResizeParent.java +++ b/src/main/java/com/cleanroommc/modularui/api/layout/IResizeParent.java @@ -6,34 +6,43 @@ public interface IResizeParent { /** - * @return area of the element + * @return the mutable layout area of the element */ Area getArea(); /** - * @return true if the relative x position is calculated + * @return {@code true} if the relative x position has been calculated */ boolean isXCalculated(); /** - * @return true if the relative y position is calculated + * @return {@code true} if the relative y position has been calculated */ boolean isYCalculated(); /** - * @return true if the width is calculated + * @return {@code true} if the width has been calculated */ boolean isWidthCalculated(); /** - * @return true if the height is calculated + * @return {@code true} if the height has been calculated */ boolean isHeightCalculated(); + /** + * @return {@code true} if all child elements have been calculated + */ boolean areChildrenCalculated(); boolean isLayoutDone(); + /** + * Returns whether this element may need another layout pass. + * + * @param isParentLayout {@code true} if this is the parent layer + * @return {@code true} if this element can be laid out again + */ boolean canRelayout(boolean isParentLayout); default boolean isSizeCalculated(GuiAxis axis) { @@ -45,7 +54,7 @@ default boolean isPosCalculated(GuiAxis axis) { } /** - * @return true if the relative position and size are fully calculated + * @return {@code true} if the relative position and size are fully calculated and doesn't need further layout recalculation iterations. */ default boolean isSelfFullyCalculated(boolean isParentLayout) { return isSelfFullyCalculated() && !canRelayout(isParentLayout); @@ -64,12 +73,12 @@ default boolean isFullyCalculated(boolean isParentLayout) { } /** - * @return true if margin and padding are applied on the x-axis + * @return {@code true} if margin and padding are applied on the x-axis */ boolean isXMarginPaddingApplied(); /** - * @return true if margin and padding are applied on the y-axis + * @return {@code true} if margin and padding are applied on the y-axis */ boolean isYMarginPaddingApplied(); } diff --git a/src/main/java/com/cleanroommc/modularui/api/layout/IResizeable.java b/src/main/java/com/cleanroommc/modularui/api/layout/IResizeable.java index 73a9eb558..cc15113a7 100644 --- a/src/main/java/com/cleanroommc/modularui/api/layout/IResizeable.java +++ b/src/main/java/com/cleanroommc/modularui/api/layout/IResizeable.java @@ -4,7 +4,7 @@ /** * An interface that handles resizing of widgets. - * Usually this interface is not implemented by the users of this library or will even interact with it. + * Usually this interface doesn't have to be implemented or interacted with, by the users of this library. */ public interface IResizeable extends IResizeParent { @@ -14,23 +14,24 @@ public interface IResizeable extends IResizeParent { void initResizing(boolean onOpen); /** - * Resizes the given element + * Attempts to resize this element. * * @param isParentLayout if the parent is a layout widget - * @return true if element is fully resized + * @return {@code true} if this element is fully resized, or {@code false} if it requires another pass */ + //TODO: this seems like another of the per-iteration situations? boolean resize(boolean isParentLayout); /** - * Called if {@link #resize(boolean)} returned false after children have been resized. + * Called when {@link #resize(boolean)} returned {@code false} after children have been resized. * - * @return if element is fully resized + * @return {@code true} if the element is fully resized */ boolean postResize(); /** - * Called after all elements in the tree are resized and the absolute positions needs to be calculated from the - * relative postion. + * Called after all elements in the tree are resized and the absolute positions need to be calculated from their + * relative positions. */ default void preApplyPos() {} @@ -112,24 +113,33 @@ default void updateResized() { } /** - * Sets if margin and padding on the x-axis is applied + * Sets whether margin and padding should be applied on the x-axis. * - * @param b true if margin and padding are applied + * @param b true if margin and padding should be applied */ void setXMarginPaddingApplied(boolean b); /** - * Sets if margin and padding on the y-axis is applied + * Sets whether margin and padding should be applied on the y-axis. * - * @param b true if margin and padding are applied + * @param b true if margin and padding should be applied */ void setYMarginPaddingApplied(boolean b); + /** + * Sets whether margin and padding should be applied on the x- and y-axis. + * @param b true if margin and padding should be applied + */ default void setMarginPaddingApplied(boolean b) { setXMarginPaddingApplied(b); setYMarginPaddingApplied(b); } + /** + * Sets whether margin and padding should be applied on the given axis. + * @param axis the axis to apply to + * @param b true if margin and padding should be applied + */ default void setMarginPaddingApplied(GuiAxis axis, boolean b) { if (axis.isHorizontal()) { setXMarginPaddingApplied(b); diff --git a/src/main/java/com/cleanroommc/modularui/integration/nei/ModularUINEIGuiHandler.java b/src/main/java/com/cleanroommc/modularui/integration/nei/ModularUINEIGuiHandler.java index 4b8f05fa3..df0f1183f 100644 --- a/src/main/java/com/cleanroommc/modularui/integration/nei/ModularUINEIGuiHandler.java +++ b/src/main/java/com/cleanroommc/modularui/integration/nei/ModularUINEIGuiHandler.java @@ -18,7 +18,7 @@ public boolean hideItemPanelSlot(GuiContainer gui, int x, int y, int w, int h) { return false; } ModularScreen screen = muiScreen.getScreen(); - if (!screen.getContext().getRecipeViewerSettings().isRecipeViewerEnabled(screen)) { + if (!screen.getContext().getRecipeViewerSettings().isEnabled(screen)) { return false; } Area.SHARED.set(x, y, w, h); diff --git a/src/main/java/com/cleanroommc/modularui/integration/nei/NEIUtil.java b/src/main/java/com/cleanroommc/modularui/integration/nei/NEIUtil.java index a1d09e1e0..ec68e2f34 100644 --- a/src/main/java/com/cleanroommc/modularui/integration/nei/NEIUtil.java +++ b/src/main/java/com/cleanroommc/modularui/integration/nei/NEIUtil.java @@ -9,7 +9,7 @@ public class NEIUtil { public static ItemStack getNEIDragAndDropTarget(ModularGuiContext context) { - if (context.getScreen().isOverlay() || !context.getRecipeViewerSettings().isRecipeViewerEnabled(context.getScreen())) { + if (context.getScreen().isOverlay() || !context.getRecipeViewerSettings().isEnabled(context.getScreen())) { return null; } if (ItemPanels.itemPanel.draggedStack != null) { diff --git a/src/main/java/com/cleanroommc/modularui/screen/ClientScreenHandler.java b/src/main/java/com/cleanroommc/modularui/screen/ClientScreenHandler.java index 1a0a26d5b..448a86701 100644 --- a/src/main/java/com/cleanroommc/modularui/screen/ClientScreenHandler.java +++ b/src/main/java/com/cleanroommc/modularui/screen/ClientScreenHandler.java @@ -74,6 +74,7 @@ import java.util.List; import java.util.function.Predicate; +//TODO: have to come back to this @ApiStatus.Internal @SideOnly(Side.CLIENT) public class ClientScreenHandler { @@ -486,7 +487,7 @@ public static void drawContainer(ModularScreen muiScreen, GuiContainer mcScreen, GlStateManager.color(1.0F, 1.0F, 1.0F, 1.0F); RenderHelper.enableGUIStandardItemLighting(); - if (muiScreen.getContext().getRecipeViewerSettings().isRecipeViewerEnabled(muiScreen)) { + if (muiScreen.getContext().getRecipeViewerSettings().isEnabled(muiScreen)) { // Copied from GuiContainerManager#renderObjects but without translation for (IContainerDrawHandler drawHandler : GuiContainerManager.drawHandlers) { drawHandler.renderObjects(mcScreen, mouseX, mouseY); diff --git a/src/main/java/com/cleanroommc/modularui/screen/RecipeViewerSettingsImpl.java b/src/main/java/com/cleanroommc/modularui/screen/RecipeViewerSettingsImpl.java index 93b7b25ed..cb6721c01 100644 --- a/src/main/java/com/cleanroommc/modularui/screen/RecipeViewerSettingsImpl.java +++ b/src/main/java/com/cleanroommc/modularui/screen/RecipeViewerSettingsImpl.java @@ -29,47 +29,26 @@ public class RecipeViewerSettingsImpl implements RecipeViewerSettings { private final List recipeViewerExclusionWidgets = new ArrayList<>(); private final List recipeViewerExclusionAreas = new ArrayList<>(); - /** - * Force recipe viewer to be enabled - */ @Override public void enable() { this.recipeViewerState = RecipeViewerState.ENABLED; } - /** - * Force recipe viewer to be disabled - */ @Override public void disable() { this.recipeViewerState = RecipeViewerState.DISABLED; } - /** - * Only enabled recipe viewer in synced GUIs - */ @Override public void defaultState() { this.recipeViewerState = RecipeViewerState.DEFAULT; } - /** - * Checks if recipe viewer is enabled for a given screen - * - * @param screen modular screen - * @return true if recipe viewer is enabled - */ @Override public boolean isEnabled(ModularScreen screen) { return this.recipeViewerState.test(screen); } - /** - * Adds an exclusion zone. Recipe viewer will always try to avoid exclusion zones.
- * If a widgets wishes to have an exclusion zone it should use {@link #addExclusionArea(IWidget)}! - * - * @param area exclusion area - */ @Override public void addExclusionArea(Rectangle area) { if (!this.recipeViewerExclusionAreas.contains(area)) { @@ -77,22 +56,11 @@ public void addExclusionArea(Rectangle area) { } } - /** - * Removes an exclusion zone. - * - * @param area exclusion area to remove (must be the same instance) - */ @Override public void removeExclusionArea(Rectangle area) { this.recipeViewerExclusionAreas.remove(area); } - /** - * Adds an exclusion zone of a widget. Recipe viewer will always try to avoid exclusion zones.
- * Useful when a widget is outside its panel. - * - * @param area widget - */ @Override public void addExclusionArea(IWidget area) { if (!this.recipeViewerExclusionWidgets.contains(area)) { @@ -100,11 +68,6 @@ public void addExclusionArea(IWidget area) { } } - /** - * Removes a widget exclusion area. - * - * @param area widget - */ @Override public void removeExclusionArea(IWidget area) { this.recipeViewerExclusionWidgets.remove(area); diff --git a/src/main/java/com/cleanroommc/modularui/widget/sizer/Area.java b/src/main/java/com/cleanroommc/modularui/widget/sizer/Area.java index c267eaeeb..2e86a2ec2 100644 --- a/src/main/java/com/cleanroommc/modularui/widget/sizer/Area.java +++ b/src/main/java/com/cleanroommc/modularui/widget/sizer/Area.java @@ -13,16 +13,34 @@ import java.util.Objects; /** - * A rectangular widget area, composed of a position and a size. - * Also has fields for a relative position, a layer and margin & padding. + * A rectangular widget area, composed of a starting position in the top-left corner and a size. + * Also has fields for a relative position, a layer and margin & padding.

+ * + *

+ * To modify the margin or padding, use {@link #getMargin()} or {@link #getPadding()} + * and then call their respective setters, such as {@link Box#all(int, int, int, int)}. + *

+ * + *

+ * Common naming conventions used by methods, variables, and parameters may include the following: + *

+ *
    + *
  • {@code s}: start or starting coordinate
    • + *
  • {@code m}: middle or midpoint coordinate
    • + *
  • {@code e}: end coordinate
    • + *
  • {@code r}: relative coordinate
    • + *
*/ public class Area extends Rectangle implements IAnimatable { public static boolean isInside(int x, int y, int w, int h, int px, int py) { + // why does this even need a static object for a simple check? + // if at all, instances may use a shared & stateless static method SHARED.set(x, y, w, h); return SHARED.isInside(px, py); } + @Deprecated public static final Area SHARED = new Area(); public static final Area ZERO = new Area(); @@ -133,17 +151,23 @@ public byte getPanelLayer() { public void setPanelLayer(byte panelLayer) {} /** - * Calculate X based on anchor value + * Positive values shift to the right, and negative values to the left.
+ * Note: the fraction is expected to be a float, so {@code 1.0f} would be 100%. + * @return shifts x-coordinate by a fraction of the current width + * @see #offsetX(int) */ - public int x(float anchor) { - return this.x + (int) (this.width * anchor); + public int x(float shiftByWidth) { + return this.x + (int) (this.width * shiftByWidth); } /** - * Calculate X based on anchor value + * Positive values shift to the bottom, and negative values to the top.
+ * Note: the fraction is expected to be a float, so {@code 1.0f} would be 100%. + * @return shifts y-coordinate by a fraction of the current height + * @see #offsetY(int) */ - public int y(float anchor) { - return this.y + (int) (this.height * anchor); + public int y(float shiftByHeight) { + return this.y + (int) (this.height * shiftByHeight); } public int getPoint(GuiAxis axis) { @@ -215,6 +239,10 @@ void applyPos(int parentX, int parentY) { this.y = parentY + this.ry; } + /** + * + * @return this width with margin applied + */ public int requestedWidth() { return this.width + getMargin().horizontal(); } @@ -223,6 +251,10 @@ public int paddedWidth() { return this.width - getPadding().horizontal(); } + /** + * + * @return this height with margin applied + */ public int requestedHeight() { return this.height + getMargin().vertical(); } @@ -231,6 +263,10 @@ public int paddedHeight() { return this.height - getPadding().vertical(); } + /** + * + * @return this size with margin applied + */ public int requestedSize(GuiAxis axis) { return axis.isHorizontal() ? requestedWidth() : requestedHeight(); } @@ -248,15 +284,16 @@ public int relativeEndY() { } /** - * Check whether given position is inside the rect. * Use {@link com.cleanroommc.modularui.api.widget.IWidget#isInside(IViewportStack, int, int)} rather than this! + * @return whether a given position is inside this rect. */ + //TODO consider deprecating this, to really warn the user of this function to use the alternative(s) public boolean isInside(int x, int y) { return x >= this.x && x < this.x + this.width && y >= this.y && y < this.y + this.height; } /** - * Check whether given rect intersects this rect + * @return whether a given rectangle intersects this rect */ public boolean intersects(Rectangle2D area) { return this.x < area.getX() + area.getWidth() && this.y < area.getY() + area.getHeight() @@ -264,7 +301,7 @@ public boolean intersects(Rectangle2D area) { } /** - * Clamp given area inside of this one + * Clamp given area inside this one */ public void clamp(Area area) { int x1 = area.x(); @@ -281,11 +318,15 @@ public void clamp(Area area) { } /** - * Increases or decreases the size of this area. The position will change so that the center of the new - * area is in the same place. - * The size will change with double of the given value. The position will change with the negative of the given value. + * Expands or shrinks the size of this area in both axes. The center position will remain at the same coordinates. + * The size will change by double of the given value. The position will change by the negative of the given value. *
- * In short, it will push or pull all four edges by the given amount. + * In short, it will push or pull all four edges equally by the given amount. + * + *
    + *
  • see {@link #offset(int)} for only modifying the position
    • + *
  • see {@link #grow(int)} for only modifying the size
    • + *
* * @param expand amount to expand area by (no restrictions) */ @@ -295,14 +336,13 @@ public void expand(int expand) { } /** - * Increases or decreases the size of this area. The position will change so that the center of the new - * area is in the same place. - * The size will change with double of the given value. The position will change with the negative of the given value. + * Expands or shrinks the size of this area axis-independently. The center position will remain at the same coordinates. + * The size will change by double of the given values. The position will change by the negative of the given values. *
- * In short, it will push or pull all four edges by the given amount. + * In short, it will push or pull all four edges by the given amounts. * - * @param expandX amount to expand x-axis by (no restrictions) - * @param expandY amount to expand y-axis by (no restrictions) + * @param expandX amount to expand the x-axis by (no restrictions) + * @param expandY amount to expand the y-axis by (no restrictions) */ public void expand(int expandX, int expandY) { this.expandX(expandX); @@ -310,13 +350,12 @@ public void expand(int expandX, int expandY) { } /** - * Increases or decreases the width of this area. The x position will change so that the center of the new - * area is in the same place. - * The width will change with double of the given value. The x position will change with the negative of the given value. + * Expands or shrinks the width of this area. The center position will remain at the same coordinates. + * The width will change by double of the given value. The x position will change by the negative of the given value. *
* In short, it will push or pull the left and right edges by the given amount. * - * @param expand amount to expand x-axis by (no restrictions) + * @param expand amount to expand the x-axis by (no restrictions) */ public void expandX(int expand) { offsetX(-expand); @@ -324,13 +363,12 @@ public void expandX(int expand) { } /** - * Increases or decreases the height of this area. The y position will change so that the center of the new - * area is in the same place. - * The height will change with double of the given value. The y position will change with the negative of the given value. + * Expands or shrinks the height of this area. The center position will remain at the same coordinates. + * The height will change by double of the given value. The y position will change by the negative of the given value. *
* In short, it will push or pull the top and bottom edges by the given amount. * - * @param expand amount to expand y-axis by (no restrictions) + * @param expand amount to expand the y-axis by (no restrictions) */ public void expandY(int expand) { offsetY(-expand); @@ -338,9 +376,14 @@ public void expandY(int expand) { } /** - * Increases or decreases the position of the area by the given amount, but doesn't change its size. + * Increases or decreases the starting position of the area by the given amount, but doesn't change its size. * - * @param offset amount to change position by (no restrictions) + *
    + *
  • see {@link #grow(int)} for only modifying the size
    • + *
  • see {@link #expand(int)} for modifying both
    • + *
+ * + * @param offset amount to change the position by (no restrictions) */ public void offset(int offset) { offsetX(offset); @@ -348,10 +391,10 @@ public void offset(int offset) { } /** - * Increases or decreases the position of the area by the given amount, but doesn't change its size. + * Increases or decreases the position of the area by the given amounts, but doesn't change its size. * - * @param offsetX amount to change x position by (no restrictions) - * @param offsetY amount to change y position by (no restrictions) + * @param offsetX amount to change the x position by (no restrictions) + * @param offsetY amount to change the y position by (no restrictions) */ public void offset(int offsetX, int offsetY) { offsetX(offsetX); @@ -361,7 +404,7 @@ public void offset(int offsetX, int offsetY) { /** * Increases or decreases the x position of the area by the given amount, but doesn't change its size. * - * @param offset amount to change x position by (no restrictions) + * @param offset amount to change the x position by (no restrictions) */ public void offsetX(int offset) { this.x += offset; @@ -370,7 +413,7 @@ public void offsetX(int offset) { /** * Increases or decreases the y position of the area by the given amount, but doesn't change its size. * - * @param offset amount to change y position by (no restrictions) + * @param offset amount to change the y position by (no restrictions) */ public void offsetY(int offset) { this.y += offset; @@ -379,7 +422,12 @@ public void offsetY(int offset) { /** * Increases or decreases the size of the area by the given amount, but doesn't change its position. * - * @param grow amount to change size by (no restrictions) + *
    + *
  • see {@link #offset(int)} for only modifying the position
    • + *
  • see {@link #expand(int)} for modifying both
    • + *
+ * + * @param grow amount to change the size by (no restrictions) */ public void grow(int grow) { growW(grow); @@ -387,10 +435,10 @@ public void grow(int grow) { } /** - * Increases or decreases the size of the area by the given amount, but doesn't change its position. + * Increases or decreases the size of the area by the given amounts, but doesn't change its position. * - * @param growW amount to change width by (no restrictions) - * @param growH amount to change height by (no restrictions) + * @param growW amount to change the width by (no restrictions) + * @param growH amount to change the height by (no restrictions) */ public void grow(int growW, int growH) { growW(growW); @@ -400,7 +448,7 @@ public void grow(int growW, int growH) { /** * Increases or decreases the width of the area by the given amount, but doesn't change its position. * - * @param grow amount to change width by (no restrictions) + * @param grow amount to change the width by (no restrictions) */ public void growW(int grow) { this.width += grow; @@ -409,14 +457,14 @@ public void growW(int grow) { /** * Increases or decreases the height of the area by the given amount, but doesn't change its position. * - * @param grow amount to change height by (no restrictions) + * @param grow amount to change the height by (no restrictions) */ public void growH(int grow) { this.height += grow; } /** - * Set all values + * Sets all values */ public void set(int x, int y, int w, int h) { this.setPos(x, y); @@ -424,7 +472,7 @@ public void set(int x, int y, int w, int h) { } /** - * Set the position + * Sets the position */ public void setPos(int x, int y) { this.x = x; @@ -432,7 +480,7 @@ public void setPos(int x, int y) { } /** - * Set the size + * Sets the size */ public void setSize(int w, int h) { this.width = w; @@ -448,12 +496,13 @@ public void setSize(Rectangle rectangle) { } /** - * Sets position and size by specifying top left and bottom right corner position. + * Sets position and size by specifying two opposing corner positions, their ordering doesn't matter. + * The given coordinates will always be recalculated to be top-left and bottom-right. * - * @param sx x position of top left corner - * @param sy y position of top left corner - * @param ex x position of bottom right corner - * @param ey y position of bottom right corner + * @param sx x-coordinate of the first corner + * @param sy y coordinate of the first corner + * @param ex x-coordinate of the second corner + * @param ey y-coordinate of the second corner */ public void setPos(int sx, int sy, int ex, int ey) { int x0 = Math.min(sx, ex); @@ -476,8 +525,10 @@ public void set(Rectangle area) { } /** - * Transforms the four corners of this rectangle with the given pose stack. The new rectangle can be rotated. - * Then a min fit rectangle, which is aligned with the screen axis, is put around the corners. + * Transforms the four corners of this rectangle with the given viewport stack. + * The resulting transformed rectangle may be rotated or skewed. + * So a minimum-fit bounding box will be applied around the transformation result, + * which will always be aligned with the screen axis and contain all corners. * * @param stack pose stack */ @@ -500,9 +551,9 @@ public Box getPadding() { } /** - * This creates a copy with size, pos, margin padding and z layer. + * Creates a copy with size, pos, margin padding, and z layer. * - * @return copy + * @return the copy */ public Area createCopy() { return new Area(this); diff --git a/src/main/java/com/cleanroommc/modularui/widget/sizer/Box.java b/src/main/java/com/cleanroommc/modularui/widget/sizer/Box.java index 631893d60..a0e607417 100644 --- a/src/main/java/com/cleanroommc/modularui/widget/sizer/Box.java +++ b/src/main/java/com/cleanroommc/modularui/widget/sizer/Box.java @@ -25,7 +25,7 @@ public class Box implements IAnimatable { protected int bottom; public Box all(int all) { - return this.all(all, all); + return this.all(all, all, all, all); } public Box all(int horizontal, int vertical) { diff --git a/src/main/java/com/cleanroommc/modularui/widget/sizer/ResizeNode.java b/src/main/java/com/cleanroommc/modularui/widget/sizer/ResizeNode.java index 6134d9c71..9f8a11c52 100644 --- a/src/main/java/com/cleanroommc/modularui/widget/sizer/ResizeNode.java +++ b/src/main/java/com/cleanroommc/modularui/widget/sizer/ResizeNode.java @@ -10,6 +10,12 @@ import java.util.ArrayList; import java.util.List; +/** + * Base node used by the widget resize tree. + *

+ * A resize node tracks parent-child relationships, resize validation states. + * Nodes may have a default parent and, temporarily, an override parent. + */ public abstract class ResizeNode implements IResizeable, ITreeNode { private ResizeNode defaultParent; @@ -18,17 +24,37 @@ public abstract class ResizeNode implements IResizeable, ITreeNode { private boolean defaultParentIsDelegating = false; private boolean requiresResize = true; + /** + * Returns the mutable list of child resize nodes. + * + * @return child resize nodes + */ @ApiStatus.Internal @Override public List getChildren() { return children; } + /** + * Returns the effective parent of this node. + *

+ * If a parent override is present, it takes precedence over the default parent. + * + * @return the effective parent, or {@code null} if this node has no parent + */ @Override public ResizeNode getParent() { return parentOverride != null ? parentOverride : defaultParent; } + /** + * Replaces another node in the resize tree with this node. + *

+ * Parent references and child references are transferred from the replaced node to this node. The replaced node is + * disposed after replacement. + * + * @param node the node to replace + */ @ApiStatus.Internal public void replacementOf(ResizeNode node) { if (this == node) return; @@ -78,6 +104,9 @@ public void replacementOf(ResizeNode node) { node.dispose(); } + /** + * Detaches this node from its parent and clears all parent and child references. + */ public void dispose() { if (getParent() != null) getParent().children.remove(this); this.defaultParent = null; @@ -96,11 +125,22 @@ private boolean removeFromParent(ResizeNode parent, ResizeNode parent2, ResizeNo return false; } + /** + * Initializes this node before it is used by the resize tree. + * + * @param defaultParent the default parent node + * @param root the root resize node + */ @ApiStatus.Internal public void initialize(ResizeNode defaultParent, ResizeNode root) { setDefaultParent(defaultParent); } + /** + * Sets the default parent for this node. + * + * @param resizeNode the default parent, or {@code null} to detach from the default parent + */ @ApiStatus.Internal public void setDefaultParent(ResizeNode resizeNode) { //ModularUI.LOGGER.info("Set default parent of {} to {}. Current: default: {}, override: {}", this, resizeNode, this.defaultParent, this.parentOverride); @@ -112,6 +152,13 @@ public void setDefaultParent(ResizeNode resizeNode) { } } + /** + * Sets an override parent for this node. + *

+ * While present, the override parent is used as the effective parent instead of the default parent. + * + * @param resizeNode the override parent, or {@code null} to restore the default parent + */ protected void setParentOverride(ResizeNode resizeNode) { //ModularUI.LOGGER.info("Set override parent of {} to {}. Current: default: {}, override: {}", this, resizeNode, this.defaultParent, this.parentOverride); if (resizeNode == this) throw new IllegalArgumentException("Tried to set itself as parent override in " + this); @@ -124,11 +171,19 @@ protected void setParentOverride(ResizeNode resizeNode) { } } + /** + * Sets whether calls should be delegated to the default parent when this node has an override parent. + * + * @param defaultParentIsDelegating {@code true} to delegate resize lifecycle calls to the default parent + */ @ApiStatus.Internal public void setDefaultParentIsDelegating(boolean defaultParentIsDelegating) { this.defaultParentIsDelegating = defaultParentIsDelegating; } + /** + * @return {@code true} if this node currently has an override parent + */ public boolean hasParentOverride() { return this.parentOverride != null; } @@ -140,12 +195,21 @@ public void initResizing(boolean onOpen) { } } + /** + * Resets implementation-specific resize state. + */ public void reset() {} + /** + * Marks this node as requiring another resize pass. + */ public void markDirty() { this.requiresResize = true; } + /** + * Called when this node has completed resizing. + */ public void onResized() { this.requiresResize = false; if (this.defaultParentIsDelegating && this.parentOverride != null) { @@ -153,12 +217,18 @@ public void onResized() { } } + /** + * Called after the full resize tree has completed resizing. + */ public void postFullResize() { if (this.defaultParentIsDelegating && this.parentOverride != null) { this.defaultParent.postFullResize(); } } + /** + * @return {@code true} if this node requires a resize pass + */ public boolean requiresResize() { return this.requiresResize; } @@ -219,14 +289,29 @@ public boolean isLayout() { return false; } + /** + * Lays out child nodes. + * + * @return {@code true} if child layout completed + */ public boolean layoutChildren() { return true; } + /** + * Performs post-layout processing for child nodes. + * + * @return {@code true} if post-layout processing completed + */ public boolean postLayoutChildren() { return true; } + /** + * Validates or expands this node on the requested axis. + * + * @param axis the axis to check + */ @ApiStatus.Internal public void checkExpanded(@Nullable GuiAxis axis) {} @@ -258,10 +343,19 @@ public boolean isExpanded() { return false; } + /** + * @return {@code true} if this node occupies the full available size + */ public abstract boolean isFullSize(); + /** + * @return {@code true} if this node has a fixed size + */ public abstract boolean hasFixedSize(); + /** + * @return human-readable information for resize debugging + */ public abstract String getDebugDisplayName(); @Override