Package nl.pim16aap2.lightkeeper.framework

Class MenuHandle

java.lang.Object
nl.pim16aap2.lightkeeper.framework.MenuHandle
public final class MenuHandle extends Object
Handle for an open player menu.

Menu actions (clickAtIndex(int), clickItem(String), dragWithMaterial(java.lang.String, int...)) auto-wait for an open menu (bounded, default 10 seconds) before acting. This is the one deliberate implicit wait in the framework API: waiting for the menu is the only correct behavior before interacting with it. Probes and verifications (e.g. isOpen(), snapshot(), verifyMenuName(java.lang.String), verifyMenuClosed(), hasTitle(java.lang.String), hasItemAt(int, java.lang.String)) never wait; the explicit andWaitForMenuClose() waits for the opposite transition.

  • Method Details

    • player

      public PlayerHandle player()
      Gets the player associated with this menu handle.
      Returns:
      The associated player.

    • snapshot

      public MenuSnapshot snapshot()
      Retrieves the latest menu snapshot.
      Returns:
      The current menu snapshot.

    • verifyMenuName

      public MenuHandle verifyMenuName(String expectedTitle)
      Asserts that the menu is open and has the expected title.
      Parameters:
      expectedTitle - Expected title text.
      Returns:
      This handle.

    • isOpen

      public boolean isOpen()
      Checks whether an actionable menu is currently open. An instant probe suitable for waitUntil(...) conditions; never waits.
      Returns:
      true when a menu is open.

    • clickAtIndex

      public MenuHandle clickAtIndex(int slot)
      Clicks a slot in the open menu, auto-waiting for an open menu first (bounded, default 10 seconds).
      Parameters:
      slot - Inventory slot index.
      Returns:
      This handle.
      Throws:
      IllegalStateException - When no menu opens within the wait bound.

    • clickItem

      public MenuHandle clickItem(String displayNameFragment)
      Clicks the first menu item whose display name contains the given fragment, auto-waiting for an open menu first (bounded, default 10 seconds).
      Parameters:
      displayNameFragment - Fragment to match against item display names (case-sensitive contains).
      Returns:
      This handle.
      Throws:
      IllegalStateException - When no menu opens within the wait bound, or no item in the open menu matches the fragment.

    • dragWithMaterial

      public MenuHandle dragWithMaterial(String materialKey, int... slots)
      Performs a drag operation using a material over the provided slots, auto-waiting for an open menu first (bounded, default 10 seconds).
      Parameters:
      materialKey - Material identifier.
      slots - Target slot indices.
      Returns:
      This handle.
      Throws:
      IllegalStateException - When no menu opens within the wait bound.

    • andWaitTicks

      public MenuHandle andWaitTicks(int ticks)
      Waits for the requested number of ticks.
      Parameters:
      ticks - Tick count.
      Returns:
      This handle.

    • andWaitForMenuClose

      public MenuHandle andWaitForMenuClose()
      Waits until the menu closes using the default timeout.
      Returns:
      This handle.

    • andWaitForMenuClose

      public MenuHandle andWaitForMenuClose(Duration timeout)
      Waits until the menu closes.
      Parameters:
      timeout - Maximum wait duration.
      Returns:
      This handle.

    • verifyMenuClosed

      public MenuHandle verifyMenuClosed()
      Asserts that no menu is currently open.
      Returns:
      This handle.

    • hasTitle

      public boolean hasTitle(String expectedTitle)
      Checks whether the current open menu has the expected title.
      Parameters:
      expectedTitle - Expected title text.
      Returns:
      true when the menu is open with the expected title.

    • hasItemAt

      public boolean hasItemAt(int slot, String materialKey)
      Checks whether a slot contains a matching material key.
      Parameters:
      slot - Inventory slot index.
      materialKey - Expected material key.
      Returns:
      true when the slot matches.

    • hasItemAt

      public boolean hasItemAt(int slot, org.bukkit.inventory.ItemStack itemStack)
      Checks whether a slot matches an expected item stack snapshot.
      Parameters:
      slot - Inventory slot index.
      itemStack - Expected item stack.
      Returns:
      true when the slot matches.