Package com.jagrosh.jdautilities.menu

Class Menu

java.lang.Object
com.jagrosh.jdautilities.menu.Menu
Direct Known Subclasses:
ButtonEmbedPaginator, ButtonMenu, EmbedPaginator, OrderedMenu, Paginator, SelectionDialog, Slideshow
public abstract class Menu extends Object
A frame for wrapping an EventWaiter into a "action, reaction" menu that waits on forms of user input such as reactions, or key-phrases.

Classes extending this are able to take a provided Message or MessageChannel and display a visualized "Menu" as or in it.

The JDA-Utilities default implementations of this superclass typically handle input through the assistance of things such as reactions, but the actual implementation is only limited to the events provided by Discord and handled through JDA.

For custom implementations, readability of creating and integrating may be improved by the implementation of a companion builder may be helpful (see the documentation on Menu.Builder for more info).

Author:
John Grosh
See Also:
Implementation Note:
While the standard JDA-Utilities implementations of this and Menu are all handled as embeds, there is no bias or advantage of implementing a custom Menu as a message without an embed.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Menu.Builder<T extends Menu.Builder<T,V>,V extends Menu>
    An extendable frame for a chain-method builder that constructs a specified type of Menu.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected Set<net.dv8tion.jda.api.entities.Role>
    roles
     
    protected final long
    timeout
     
    protected final TimeUnit
    unit
     
    protected Set<net.dv8tion.jda.api.entities.User>
    users
     
    protected final EventWaiter
    waiter
     

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Menu(EventWaiter waiter, Set<net.dv8tion.jda.api.entities.User> users, Set<net.dv8tion.jda.api.entities.Role> roles, long timeout, TimeUnit unit)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract void
    display(net.dv8tion.jda.api.entities.channel.middleman.MessageChannel channel)
    Displays this Menu in a MessageChannel.
    abstract void
    display(net.dv8tion.jda.api.entities.Message message)
    Displays this Menu as a designated Message.
    protected boolean
    isValidUser(net.dv8tion.jda.api.entities.User user)
    Checks to see if the provided User is valid to interact with this Menu.
    protected boolean
    isValidUser(net.dv8tion.jda.api.entities.User user, net.dv8tion.jda.api.entities.Guild guild)
    Checks to see if the provided User is valid to interact with this Menu.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • waiter

      protected final EventWaiter waiter

    • users

      protected Set<net.dv8tion.jda.api.entities.User> users

    • roles

      protected Set<net.dv8tion.jda.api.entities.Role> roles

    • timeout

      protected final long timeout

    • unit

      protected final TimeUnit unit

  • Constructor Details

    • Menu

      protected Menu(EventWaiter waiter, Set<net.dv8tion.jda.api.entities.User> users, Set<net.dv8tion.jda.api.entities.Role> roles, long timeout, TimeUnit unit)

  • Method Details

    • display

      public abstract void display(net.dv8tion.jda.api.entities.channel.middleman.MessageChannel channel)
      Displays this Menu in a MessageChannel.
      Parameters:
      channel - The MessageChannel to display this Menu in

    • display

      public abstract void display(net.dv8tion.jda.api.entities.Message message)
      Displays this Menu as a designated Message.
      The Message provided must be one sent by the bot! Trying to provided a Message authored by another User will prevent the Menu from being displayed!
      Parameters:
      message - The Message to display this Menu as

    • isValidUser

      protected boolean isValidUser(net.dv8tion.jda.api.entities.User user)
      Checks to see if the provided User is valid to interact with this Menu.

      This is a shortcut for isValidUser(User, Guild) where the Guild is null.

      Parameters:
      user - The User to validate.
      Returns:
      true if the User is valid, false otherwise.
      See Also:

    • isValidUser

      protected boolean isValidUser(net.dv8tion.jda.api.entities.User user, @Nullable net.dv8tion.jda.api.entities.Guild guild)
      Checks to see if the provided User is valid to interact with this Menu.

      For a User to be considered "valid" to use a Menu, the following logic (in order) is applied:

      • The User must not be a bot. If it is, this returns false immediately.
      • If no users and no roles were specified in the builder for this Menu, then this will return true.
      • If the User is among the users specified in the builder for this Menu, this will return true.
      • If the Guild is null, or if the User is not a member on the Guild, this will return false.
      • Finally, the determination will be if the User on the provided Guild has any of the builder-specified Roles.
      Custom-implementation-wise, it's highly recommended developers who might override this attempt to follow a similar logic for their Menus, as this provides a full-proof guard against exceptions when validating a User of a Menu.
      Parameters:
      user - The User to validate.
      guild - The Guild to validate the User on.
      Can be provided null safely.
      Returns:
      true if the User is valid, false otherwise.