Interface Button

  • All Superinterfaces:
    Component, SerializableData

    public interface Button
    extends Component
    Represents a Message Button.
    These buttons are located below the message in ActionRows.

    Each button has either a custom_id or URL attached. The id has to be provided by the user and can be used to identify the button in the ButtonClickEvent.

    Example Usage

    
     public class HelloBot extends ListenerAdapter {
       public void onSlashCommand(SlashCommandEvent event) {
           if (event.getName().equals("hello")) {
               event.reply("Click the button to say hello")
                   .addActionRow(
                     Button.primary("hello", "Click Me"), // Button with only a label
                     Button.success("emoji", Emoji.fromMarkdown("<:minn:245267426227388416>"))) // Button with only an emoji
                   .queue();
           } else if (event.getName().equals("info")) {
               event.reply("Click the buttons for more info")
                   .addActionRow( // link buttons don't send events, they just open a link in the browser when clicked
                       Button.link("https://github.com/DV8FromTheWorld/JDA", "GitHub")
                         .withEmoji(Emoji.fromMarkdown("<:github:849286315580719104>")), // Link Button with label and emoji
                       Button.link("https://ci.dv8tion.net/job/JDA/javadoc/", "Javadocs")) // Link Button with only a label
                   .queue();
           }
       }
    
       public void onButtonClick(ButtonClickEvent event) {
           if (event.getComponentId().equals("hello")) {
               event.reply("Hello :)").queue();
           }
       }
     }
     
    To see what each button looks like here is an example cheatsheet:
    ButtonExample
    See Also:
    ReplyAction.addActionRow(Component...), ReplyAction.addActionRows(ActionRow...)
    • Method Detail

      • getLabel

        @Nonnull
        String getLabel()
        The visible text on the button.
        Returns:
        The button label
      • getUrl

        @Nullable
        String getUrl()
        The target URL for this button, if it is a LINK-Style Button.
        Returns:
        The target URL or null
      • isDisabled

        boolean isDisabled()
        Whether this button is disabled.

        You can use asDisabled() or asEnabled() to create enabled/disabled instances.

        Returns:
        True, if this button is disabled
      • asDisabled

        @Nonnull
        default Button asDisabled()
        Returns a copy of this button with isDisabled() set to true.
        Returns:
        New disabled button instance
      • asEnabled

        @Nonnull
        default Button asEnabled()
        Returns a copy of this button with isDisabled() set to false.
        Returns:
        New enabled button instance
      • withDisabled

        @Nonnull
        default Button withDisabled​(boolean disabled)
        Returns a copy of this button with isDisabled() set to the provided value.
        Parameters:
        disabled - True, if this button should be disabled
        Returns:
        New enabled/disabled button instance
      • withEmoji

        @Nonnull
        default Button withEmoji​(@Nullable
                                 Emoji emoji)
        Returns a copy of this button with the attached Emoji.
        Parameters:
        emoji - The emoji to use
        Returns:
        New button with emoji
      • withLabel

        @Nonnull
        default Button withLabel​(@Nonnull
                                 String label)
        Returns a copy of this button with the provided label.
        Parameters:
        label - The label to use
        Returns:
        New button with the changed label
        Throws:
        IllegalArgumentException - If the label is not between 1-80 characters
      • withId

        @Nonnull
        default Button withId​(@Nonnull
                              String id)
        Returns a copy of this button with the provided id.
        Parameters:
        id - The id to use
        Returns:
        New button with the changed id
        Throws:
        IllegalArgumentException - If the id is not between 1-100 characters
      • withUrl

        @Nonnull
        default Button withUrl​(@Nonnull
                               String url)
        Returns a copy of this button with the provided url.
        Parameters:
        url - The url to use
        Returns:
        New button with the changed url
        Throws:
        IllegalArgumentException - If the url is null, empty, or longer than 512 characters
      • withStyle

        @Nonnull
        default Button withStyle​(@Nonnull
                                 ButtonStyle style)
        Returns a copy of this button with the provided style.

        You cannot use this convert link buttons.

        Parameters:
        style - The style to use
        Returns:
        New button with the changed style
        Throws:
        IllegalArgumentException - If the style is null or tries to change whether this button is a LINK button
      • primary

        @Nonnull
        static Button primary​(@Nonnull
                              String id,
                              @Nonnull
                              String label)
        Creates a button with PRIMARY Style.
        The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.
        Parameters:
        id - The custom button ID
        label - The text to display on the button
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null, the label is longer than 80 characters, or the id is longer than 100 characters
      • primary

        @Nonnull
        static Button primary​(@Nonnull
                              String id,
                              @Nonnull
                              Emoji emoji)
        Creates a button with PRIMARY Style.
        The button is enabled and has no text label. To use labels you can use primary(id, label).withEmoji(emoji)

        To disable the button you can use asDisabled().

        Parameters:
        id - The custom button ID
        emoji - The emoji to use as the button label
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null or the id is longer than 100 characters
      • secondary

        @Nonnull
        static Button secondary​(@Nonnull
                                String id,
                                @Nonnull
                                String label)
        Creates a button with SECONDARY Style.
        The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.
        Parameters:
        id - The custom button ID
        label - The text to display on the button
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null, the label is longer than 80 characters, or the id is longer than 100 characters
      • secondary

        @Nonnull
        static Button secondary​(@Nonnull
                                String id,
                                @Nonnull
                                Emoji emoji)
        Creates a button with SECONDARY Style.
        The button is enabled and has no text label. To use labels you can use secondary(id, label).withEmoji(emoji)

        To disable the button you can use asDisabled().

        Parameters:
        id - The custom button ID
        emoji - The emoji to use as the button label
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null or the id is longer than 100 characters
      • success

        @Nonnull
        static Button success​(@Nonnull
                              String id,
                              @Nonnull
                              String label)
        Creates a button with SUCCESS Style.
        The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.
        Parameters:
        id - The custom button ID
        label - The text to display on the button
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null, the label is longer than 80 characters, or the id is longer than 100 characters
      • success

        @Nonnull
        static Button success​(@Nonnull
                              String id,
                              @Nonnull
                              Emoji emoji)
        Creates a button with SUCCESS Style.
        The button is enabled and has no text label. To use labels you can use success(id, label).withEmoji(emoji)

        To disable the button you can use asDisabled().

        Parameters:
        id - The custom button ID
        emoji - The emoji to use as the button label
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null or the id is longer than 100 characters
      • danger

        @Nonnull
        static Button danger​(@Nonnull
                             String id,
                             @Nonnull
                             String label)
        Creates a button with DANGER Style.
        The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.
        Parameters:
        id - The custom button ID
        label - The text to display on the button
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null, the label is longer than 80 characters, or the id is longer than 100 characters
      • danger

        @Nonnull
        static Button danger​(@Nonnull
                             String id,
                             @Nonnull
                             Emoji emoji)
        Creates a button with DANGER Style.
        The button is enabled and has no text label. To use labels you can use danger(id, label).withEmoji(emoji)

        To disable the button you can use asDisabled().

        Parameters:
        id - The custom button ID
        emoji - The emoji to use as the button label
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null or the id is longer than 100 characters
      • link

        @Nonnull
        static Button link​(@Nonnull
                           String url,
                           @Nonnull
                           String label)
        Creates a button with LINK Style.
        The button is enabled and has no emoji attached by default. You can use asDisabled() and withEmoji(Emoji) to further configure it.

        Note that link buttons never send a ButtonClickEvent. These buttons only open a link for the user.

        Parameters:
        url - The target URL for this button
        label - The text to display on the button
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null, the label is longer than 80 characters, or the url is longer than 512 characters
      • link

        @Nonnull
        static Button link​(@Nonnull
                           String url,
                           @Nonnull
                           Emoji emoji)
        Creates a button with LINK Style.
        The button is enabled and has no text label. To use labels you can use link(url, label).withEmoji(emoji)

        To disable the button you can use asDisabled().

        Note that link buttons never send a ButtonClickEvent. These buttons only open a link for the user.

        Parameters:
        url - The target URL for this button
        emoji - The emoji to use as the button label
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any argument is empty or null or the url is longer than 512 characters
      • of

        @Nonnull
        static Button of​(@Nonnull
                         ButtonStyle style,
                         @Nonnull
                         String idOrUrl,
                         @Nullable
                         String label,
                         @Nullable
                         Emoji emoji)
        Create an enabled button with the provided style, URL or ID, label and emoji.

        You can use asDisabled() to disable it.

        See link(String, String) or primary(String, String) for more details.

        Parameters:
        style - The button style
        idOrUrl - Either the ID or URL for this button
        label - The text to display on the button
        emoji - The emoji to use as the button label
        Returns:
        The button instance
        Throws:
        IllegalArgumentException - If any of the following scenarios occurs:
        • The style is null
        • You provide a URL that is null, empty or longer than 512 characters, or you provide an ID that is null, empty or longer than 100 characters
        • The label is non-null and longer than 80 characters
        • The label is null/empty, and the emoji is also null