com.jagrosh.jdautilities.menu

Class Menu

java.lang.Object

com.jagrosh.jdautilities.menu.Menu

Direct Known Subclasses:

ButtonMenu, OrderedMenu, Paginator, SelectionDialog, Slideshow

public abstract class Menu
extends java.lang.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:

EventWaiter, Menu.Builder

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 and 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 and Description
protected java.util.Set<net.dv8tion.jda.core.entities.Role>	roles
protected long	timeout
protected java.util.concurrent.TimeUnit	unit
protected java.util.Set<net.dv8tion.jda.core.entities.User>	users
protected EventWaiter	waiter

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Menu(EventWaiter waiter, java.util.Set<net.dv8tion.jda.core.entities.User> users, java.util.Set<net.dv8tion.jda.core.entities.Role> roles, long timeout, java.util.concurrent.TimeUnit unit)

Method Summary

Modifier and Type	Method and Description
abstract void	display(net.dv8tion.jda.core.entities.Message message) Displays this Menu as a designated Message.
abstract void	display(net.dv8tion.jda.core.entities.MessageChannel channel) Displays this Menu in a MessageChannel.
protected boolean	isValidUser(net.dv8tion.jda.core.entities.User user) Checks to see if the provided User is valid to interact with this Menu.
protected boolean	isValidUser(net.dv8tion.jda.core.entities.User user, net.dv8tion.jda.core.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 Detail

waiter

protected final EventWaiter waiter

users

protected java.util.Set<net.dv8tion.jda.core.entities.User> users

roles

protected java.util.Set<net.dv8tion.jda.core.entities.Role> roles

timeout

protected final long timeout

unit

protected final java.util.concurrent.TimeUnit unit

Constructor Detail

Menu

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

Method Detail

display

public abstract void display(net.dv8tion.jda.core.entities.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.core.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.core.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(User, Guild)

isValidUser

protected boolean isValidUser(net.dv8tion.jda.core.entities.User user,
                              @Nullable
                              net.dv8tion.jda.core.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.