Interface LayoutComponent

All Superinterfaces:
Component, Iterable<ItemComponent>, SerializableData
All Known Implementing Classes:
ActionRow

public interface LayoutComponent extends SerializableData, Iterable<ItemComponent>, Component
Represents a top-level layout used for ItemComponents such as Buttons.

Components must always be contained within such a layout.

See Also:
  • Method Details

    • getComponents

      @Nonnull List<ItemComponent> getComponents()
      List representation of this component layout.
      This list is modifiable. Note that empty layouts are not supported.
      Returns:
      List of components in this layout
    • isMessageCompatible

      default boolean isMessageCompatible()
      Description copied from interface: Component
      Whether this Component is compatible with Messages.
      If the component in question is a LayoutComponent, this also checks every component inside it.
      Specified by:
      isMessageCompatible in interface Component
      Returns:
      True, if this Component is compatible with messages.
    • isModalCompatible

      default boolean isModalCompatible()
      Description copied from interface: Component
      Whether this Component is compatible with Modals.
      If the component in question is a LayoutComponent, this also checks every component inside it.
      Specified by:
      isModalCompatible in interface Component
      Returns:
      True, if this Component is compatible with modals.
    • getActionComponents

      @Nonnull default @Unmodifiable List<ActionComponent> getActionComponents()
      Immutable filtered copy of getComponents() elements which are ActionComponents.
      Returns:
      Immutable List copy of ActionComponents in this layout
    • getButtons

      @Nonnull default @Unmodifiable List<Button> getButtons()
      List of buttons in this component layout.
      Returns:
      Immutable List of Buttons
    • isDisabled

      default boolean isDisabled()
      Whether all components in this layout are disabled.
      Note that this is a universal quantifier, which means false does not imply isEnabled()!
      Returns:
      True, if all components are disabled
    • isEnabled

      default boolean isEnabled()
      Whether all components in this layout are enabled.
      Note that this is a universal quantifier, which means false does not imply isDisabled()!
      Returns:
      True, if all components are enabled
    • withDisabled

      @Nonnull @CheckReturnValue LayoutComponent withDisabled(boolean disabled)
      Returns a new instance of this LayoutComponent with all components set to disabled/enabled.
      This does not modify the layout this was called on. To do this in-place, you can use getComponents().
      Parameters:
      disabled - True if the components should be set to disabled, false if they should be enabled
      Returns:
      The new layout component with all components updated
      See Also:
    • asDisabled

      Returns a new instance of this LayoutComponent with all components set to disabled.
      This does not modify the layout this was called on. To do this in-place, you can use getComponents().
      Returns:
      The new layout component with all components updated
      See Also:
    • asEnabled

      Returns a new instance of this LayoutComponent with all components set to enabled.
      This does not modify the layout this was called on. To do this in-place, you can use getComponents().
      Returns:
      The new layout component with all components updated
      See Also:
    • isEmpty

      default boolean isEmpty()
      Check whether this layout is empty.
      Identical to getComponents().isEmpty()
      Returns:
      True, if this layout has no components
    • isValid

      default boolean isValid()
      Check whether this is a valid layout configuration.
      This checks that there is at least one component in this layout and it does not violate ItemComponent.getMaxPerRow().
      Returns:
      True, if this layout is valid
    • createCopy

      Creates a copy of this LayoutComponent.
      This does not create copies of the contained components.
      Returns:
      A copy of this LayoutComponent
    • updateComponent

      @Nullable default ItemComponent updateComponent(@Nonnull String id, @Nullable ItemComponent newComponent)
      Find and replace a component in this layout.
      This will locate and replace the existing component with the specified ID. If you provide null it will be removed instead.
      Parameters:
      id - The custom id of this component, can also be a URL for a Button with ButtonStyle.LINK
      newComponent - The new component or null to remove it
      Returns:
      The old ItemComponent that was replaced or removed
      Throws:
      IllegalArgumentException - If the provided id is null
    • updateComponent

      static boolean updateComponent(@Nonnull List<? extends LayoutComponent> layouts, @Nonnull String id, @Nullable ItemComponent newComponent)
      Find and replace a component in this list of layouts.
      This will locate and replace the existing component with the specified ID. If you provide null it will be removed instead.

      If one of the layouts is empty after removing the component, it will be removed from the list. This is an inplace operation and modifies the provided list directly.

      Parameters:
      layouts - The layouts to modify
      id - The custom id of this component, can also be a URL for a Button with ButtonStyle.LINK
      newComponent - The new component or null to remove it
      Returns:
      True, if any of the layouts was modified
      Throws:
      UnsupportedOperationException - If the list cannot be modified
      IllegalArgumentException - If the provided id or list is null or the replace operation results in an invalid layout
    • updateComponent

      @Nullable default ItemComponent updateComponent(@Nonnull ItemComponent component, @Nullable ItemComponent newComponent)
      Find and replace a component in this layout.
      This will locate and replace the existing component by checking for equality. If you provide null it will be removed instead.

      Example

      
       public void disableButton(ActionRow row, Button button) {
           row.updateComponent(button, button.asDisabled());
       }
       
      Parameters:
      component - The component that should be replaced
      newComponent - The new component or null to remove it
      Returns:
      The old ItemComponent that was replaced or removed
      Throws:
      IllegalArgumentException - If the provided component is null
    • updateComponent

      static boolean updateComponent(@Nonnull List<? extends LayoutComponent> layouts, @Nonnull ItemComponent component, @Nullable ItemComponent newComponent)
      Find and replace a component in this list of layouts.
      This will locate and replace the existing component by checking for equality. If you provide null it will be removed instead.

      If one of the layouts is empty after removing the component, it will be removed from the list. This is an inplace operation and modifies the provided list directly.

      Parameters:
      layouts - The layouts to modify
      component - The component that should be replaced
      newComponent - The new component or null to remove it
      Returns:
      True, if any of the layouts was modified
      Throws:
      UnsupportedOperationException - If the list cannot be modified
      IllegalArgumentException - If the provided component or list is null or the replace operation results in an invalid layout