Class EmbedBuilder
- java.lang.Object
-
- net.dv8tion.jda.api.EmbedBuilder
-
public class EmbedBuilder extends java.lang.ObjectBuilder system used to buildMessageEmbeds.
A visual breakdown of an Embed and how it relates to this class is available at Embed Overview.- Since:
- 3.0
- Author:
- John A. Grosh
-
-
Field Summary
Fields Modifier and Type Field Description static java.util.regex.PatternURL_PATTERNstatic java.lang.StringZERO_WIDTH_SPACE
-
Constructor Summary
Constructors Constructor Description EmbedBuilder()Constructs a new EmbedBuilder instance, which can be used to createMessageEmbeds.EmbedBuilder(EmbedBuilder builder)Creates an EmbedBuilder using fields from an existing builderEmbedBuilder(MessageEmbed embed)Creates an EmbedBuilder using fields in an existing embed.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description EmbedBuilderaddBlankField(boolean inline)Adds a blank (empty) Field to the embed.EmbedBuilderaddField(java.lang.String name, java.lang.String value, boolean inline)Adds a Field to the embed.EmbedBuilderaddField(MessageEmbed.Field field)Copies the provided Field into a new Field for this builder.EmbedBuilderappendDescription(java.lang.CharSequence description)Appends to the description of the embed.MessageEmbedbuild()Returns aMessageEmbedthat has been checked as being valid for sending.EmbedBuilderclear()Resets this builder to default state.EmbedBuilderclearFields()Clears all fields from the embed, such as those created with theEmbedBuilder(MessageEmbed)constructor or via theaddFieldmethods.voidcopyFrom(EmbedBuilder builder)Copies the data from the given builder into this builder.voidcopyFrom(MessageEmbed embed)Copies the data from the given embed into this builder.java.lang.StringBuildergetDescriptionBuilder()TheStringBuilderused to build the description for the embed.java.util.List<MessageEmbed.Field>getFields()Modifiable list ofMessageEmbedFields that the builder will use forbuild().booleanisEmpty()Checks if the given embed is empty.booleanisValidLength()Checks whether the constructedMessageEmbedis within the limits for a bot account.intlength()The overall length of the current EmbedBuilder in displayed characters.EmbedBuildersetAuthor(java.lang.String name)Sets the Author of the embed.EmbedBuildersetAuthor(java.lang.String name, java.lang.String url)Sets the Author of the embed.EmbedBuildersetAuthor(java.lang.String name, java.lang.String url, java.lang.String iconUrl)Sets the Author of the embed.EmbedBuildersetColor(int color)Sets the raw RGB color value for the embed.EmbedBuildersetColor(java.awt.Color color)Sets the Color of the embed.EmbedBuildersetDescription(java.lang.CharSequence description)Sets the Description of the embed.EmbedBuildersetFooter(java.lang.String text)Sets the Footer of the embed without icon.EmbedBuildersetFooter(java.lang.String text, java.lang.String iconUrl)Sets the Footer of the embed.EmbedBuildersetImage(java.lang.String url)Sets the Image of the embed.EmbedBuildersetThumbnail(java.lang.String url)Sets the Thumbnail of the embed.EmbedBuildersetTimestamp(java.time.temporal.TemporalAccessor temporal)Sets the Timestamp of the embed.EmbedBuildersetTitle(java.lang.String title)Sets the Title of the embed.EmbedBuildersetTitle(java.lang.String title, java.lang.String url)Sets the Title of the embed.
-
-
-
Field Detail
-
ZERO_WIDTH_SPACE
public static final java.lang.String ZERO_WIDTH_SPACE
- See Also:
- Constant Field Values
-
URL_PATTERN
public static final java.util.regex.Pattern URL_PATTERN
-
-
Constructor Detail
-
EmbedBuilder
public EmbedBuilder()
Constructs a new EmbedBuilder instance, which can be used to createMessageEmbeds. These can then be sent to a channel usingMessageChannel.sendMessageEmbeds(MessageEmbed, MessageEmbed...).
Every part of an embed can be removed or cleared by providingnullto the setter method.
-
EmbedBuilder
public EmbedBuilder(@Nullable EmbedBuilder builder)Creates an EmbedBuilder using fields from an existing builder- Parameters:
builder- the existing builder
-
EmbedBuilder
public EmbedBuilder(@Nullable MessageEmbed embed)Creates an EmbedBuilder using fields in an existing embed.- Parameters:
embed- the existing embed
-
-
Method Detail
-
build
@Nonnull public MessageEmbed build()
Returns aMessageEmbedthat has been checked as being valid for sending.- Returns:
- the built, sendable
MessageEmbed - Throws:
java.lang.IllegalStateException- If the embed is empty. Can be checked withisEmpty().
-
clear
@Nonnull public EmbedBuilder clear()
Resets this builder to default state.
All parts will be either empty or null after this method has returned.- Returns:
- The current EmbedBuilder with default values
-
copyFrom
public void copyFrom(@Nullable EmbedBuilder builder)Copies the data from the given builder into this builder.
All the parts of the given builder will be applied to this one.- Parameters:
builder- the existing builder
-
copyFrom
public void copyFrom(@Nullable MessageEmbed embed)Copies the data from the given embed into this builder.
All the parts of the given embed will be applied to this builder.- Parameters:
embed- the existing embed
-
isEmpty
public boolean isEmpty()
Checks if the given embed is empty. Empty embeds will throw an exception if built.- Returns:
- true if the embed is empty and cannot be built
-
length
public int length()
The overall length of the current EmbedBuilder in displayed characters.
Represents theMessageEmbed.getLength()value.- Returns:
- length of the current builder state
-
isValidLength
public boolean isValidLength()
Checks whether the constructedMessageEmbedis within the limits for a bot account.- Returns:
- True, if the
lengthis less or equal to 6000 - See Also:
MessageEmbed.EMBED_MAX_LENGTH_BOT
-
setTitle
@Nonnull public EmbedBuilder setTitle(@Nullable java.lang.String title)
- Parameters:
title- the title of the embed- Returns:
- the builder after the title has been set
- Throws:
java.lang.IllegalArgumentException-- If the provided
titleis an empty String. - If the character limit for
title, defined byMessageEmbed.TITLE_MAX_LENGTHas 256, is exceeded.
- If the provided
-
setTitle
@Nonnull public EmbedBuilder setTitle(@Nullable java.lang.String title, @Nullable java.lang.String url)
- Parameters:
title- the title of the embedurl- Makes the title into a hyperlink pointed at this url.- Returns:
- the builder after the title has been set
- Throws:
java.lang.IllegalArgumentException-- If the provided
titleis an empty String. - If the character limit for
title, defined byMessageEmbed.TITLE_MAX_LENGTHas 256, is exceeded. - If the character limit for
url, defined byMessageEmbed.URL_MAX_LENGTHas 2000, is exceeded. - If the provided
urlis not a properly formatted http or https url.
- If the provided
-
getDescriptionBuilder
@Nonnull public java.lang.StringBuilder getDescriptionBuilder()
TheStringBuilderused to build the description for the embed.
Note: To reset the description usesetDescription(null)- Returns:
- StringBuilder with current description context
-
setDescription
@Nonnull public final EmbedBuilder setDescription(@Nullable java.lang.CharSequence description)
Sets the Description of the embed. This is where the main chunk of text for an embed is typically placed.- Parameters:
description- the description of the embed,nullto reset- Returns:
- the builder after the description has been set
- Throws:
java.lang.IllegalArgumentException- Ifdescriptionis longer than 4096 characters, as defined byMessageEmbed.DESCRIPTION_MAX_LENGTH
-
appendDescription
@Nonnull public EmbedBuilder appendDescription(@Nonnull java.lang.CharSequence description)
Appends to the description of the embed. This is where the main chunk of text for an embed is typically placed.- Parameters:
description- the string to append to the description of the embed- Returns:
- the builder after the description has been set
- Throws:
java.lang.IllegalArgumentException-- If the provided
descriptionString is null. - If the character limit for
description, defined byMessageEmbed.DESCRIPTION_MAX_LENGTHas 4096, is exceeded.
- If the provided
-
setTimestamp
@Nonnull public EmbedBuilder setTimestamp(@Nullable java.time.temporal.TemporalAccessor temporal)
Sets the Timestamp of the embed.Hint: You can get the current time using
Instant.now()or convert time from a millisecond representation by usingInstant.ofEpochMilli(long);- Parameters:
temporal- the temporal accessor of the timestamp- Returns:
- the builder after the timestamp has been set
-
setColor
@Nonnull public EmbedBuilder setColor(@Nullable java.awt.Color color)
Sets the Color of the embed.- Parameters:
color- TheColorof the embed ornullto use no color- Returns:
- the builder after the color has been set
- See Also:
setColor(int)
-
setColor
@Nonnull public EmbedBuilder setColor(int color)
Sets the raw RGB color value for the embed.- Parameters:
color- The raw rgb value, orRole.DEFAULT_COLOR_RAWto use no color- Returns:
- the builder after the color has been set
- See Also:
setColor(java.awt.Color)
-
setThumbnail
@Nonnull public EmbedBuilder setThumbnail(@Nullable java.lang.String url)
Sets the Thumbnail of the embed.Uploading images with Embeds
When uploading an image (usingMessageChannel.sendFile(...)) you can reference said image using the specified filename as URIattachment://filename.ext.Example
MessageChannel channel; // = reference of a MessageChannel EmbedBuilder embed = new EmbedBuilder(); InputStream file = new URL("https://http.cat/500").openStream(); embed.setThumbnail("attachment://cat.png") // we specify this in sendFile as "cat.png" .setDescription("This is a cute cat :3"); channel.sendFile(file, "cat.png").setEmbeds(embed.build()).queue();- Parameters:
url- the url of the thumbnail of the embed- Returns:
- the builder after the thumbnail has been set
- Throws:
java.lang.IllegalArgumentException-- If the character limit for
url, defined byMessageEmbed.URL_MAX_LENGTHas 2000, is exceeded. - If the provided
urlis not a properly formatted http or https url.
- If the character limit for
-
setImage
@Nonnull public EmbedBuilder setImage(@Nullable java.lang.String url)
Sets the Image of the embed.Uploading images with Embeds
When uploading an image (usingMessageChannel.sendFile(...)) you can reference said image using the specified filename as URIattachment://filename.ext.Example
MessageChannel channel; // = reference of a MessageChannel EmbedBuilder embed = new EmbedBuilder(); InputStream file = new URL("https://http.cat/500").openStream(); embed.setImage("attachment://cat.png") // we specify this in sendFile as "cat.png" .setDescription("This is a cute cat :3"); channel.sendFile(file, "cat.png").setEmbeds(embed.build()).queue();- Parameters:
url- the url of the image of the embed- Returns:
- the builder after the image has been set
- Throws:
java.lang.IllegalArgumentException-- If the character limit for
url, defined byMessageEmbed.URL_MAX_LENGTHas 2000, is exceeded. - If the provided
urlis not a properly formatted http or https url.
- If the character limit for
- See Also:
MessageChannel.sendFile(...)
-
setAuthor
@Nonnull public EmbedBuilder setAuthor(@Nullable java.lang.String name)
Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url. This convenience method just sets the name.- Parameters:
name- the name of the author of the embed. If this is not set, the author will not appear in the embed- Returns:
- the builder after the author has been set
- Throws:
java.lang.IllegalArgumentException- Ifnameis longer than 256 characters, as defined byMessageEmbed.AUTHOR_MAX_LENGTH
-
setAuthor
@Nonnull public EmbedBuilder setAuthor(@Nullable java.lang.String name, @Nullable java.lang.String url)
Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url. This convenience method just sets the name and the url.- Parameters:
name- the name of the author of the embed. If this is not set, the author will not appear in the embedurl- the url of the author of the embed- Returns:
- the builder after the author has been set
- Throws:
java.lang.IllegalArgumentException-- If the character limit for
name, defined byMessageEmbed.AUTHOR_MAX_LENGTHas 256, is exceeded. - If the character limit for
url, defined byMessageEmbed.URL_MAX_LENGTHas 2000, is exceeded. - If the provided
urlis not a properly formatted http or https url.
- If the character limit for
-
setAuthor
@Nonnull public EmbedBuilder setAuthor(@Nullable java.lang.String name, @Nullable java.lang.String url, @Nullable java.lang.String iconUrl)
Sets the Author of the embed. The author appears in the top left of the embed and can have a small image beside it along with the author's name being made clickable by way of providing a url.Uploading images with Embeds
When uploading an image (usingMessageChannel.sendFile(...)) you can reference said image using the specified filename as URIattachment://filename.ext.Example
MessageChannel channel; // = reference of a MessageChannel EmbedBuilder embed = new EmbedBuilder(); InputStream file = new URL("https://http.cat/500").openStream(); embed.setAuthor("Minn", null, "attachment://cat.png") // we specify this in sendFile as "cat.png" .setDescription("This is a cute cat :3"); channel.sendFile(file, "cat.png").setEmbeds(embed.build()).queue();- Parameters:
name- the name of the author of the embed. If this is not set, the author will not appear in the embedurl- the url of the author of the embediconUrl- the url of the icon for the author- Returns:
- the builder after the author has been set
- Throws:
java.lang.IllegalArgumentException-- If the character limit for
name, defined byMessageEmbed.AUTHOR_MAX_LENGTHas 256, is exceeded. - If the character limit for
url, defined byMessageEmbed.URL_MAX_LENGTHas 2000, is exceeded. - If the provided
urlis not a properly formatted http or https url. - If the character limit for
iconUrl, defined byMessageEmbed.URL_MAX_LENGTHas 2000, is exceeded. - If the provided
iconUrlis not a properly formatted http or https url.
- If the character limit for
-
setFooter
@Nonnull public EmbedBuilder setFooter(@Nullable java.lang.String text)
Sets the Footer of the embed without icon.- Parameters:
text- the text of the footer of the embed. If this is not set or set to null, the footer will not appear in the embed.- Returns:
- the builder after the footer has been set
- Throws:
java.lang.IllegalArgumentException- Iftextis longer than 2048 characters, as defined byMessageEmbed.TEXT_MAX_LENGTH
-
setFooter
@Nonnull public EmbedBuilder setFooter(@Nullable java.lang.String text, @Nullable java.lang.String iconUrl)
Sets the Footer of the embed.Uploading images with Embeds
When uploading an image (usingMessageChannel.sendFile(...)) you can reference said image using the specified filename as URIattachment://filename.ext.Example
MessageChannel channel; // = reference of a MessageChannel EmbedBuilder embed = new EmbedBuilder(); InputStream file = new URL("https://http.cat/500").openStream(); embed.setFooter("Cool footer!", "attachment://cat.png") // we specify this in sendFile as "cat.png" .setDescription("This is a cute cat :3"); channel.sendFile(file, "cat.png").setEmbeds(embed.build()).queue();- Parameters:
text- the text of the footer of the embed. If this is not set, the footer will not appear in the embed.iconUrl- the url of the icon for the footer- Returns:
- the builder after the footer has been set
- Throws:
java.lang.IllegalArgumentException-- If the character limit for
text, defined byMessageEmbed.TEXT_MAX_LENGTHas 2048, is exceeded. - If the character limit for
iconUrl, defined byMessageEmbed.URL_MAX_LENGTHas 2000, is exceeded. - If the provided
iconUrlis not a properly formatted http or https url.
- If the character limit for
-
addField
@Nonnull public EmbedBuilder addField(@Nullable MessageEmbed.Field field)
Copies the provided Field into a new Field for this builder.
For additional documentation, seeaddField(String, String, boolean)- Parameters:
field- the field object to add- Returns:
- the builder after the field has been added
-
addField
@Nonnull public EmbedBuilder addField(@Nullable java.lang.String name, @Nullable java.lang.String value, boolean inline)
Adds a Field to the embed.Note: If a blank string is provided to either
nameorvalue, the blank string is replaced withZERO_WIDTH_SPACE.- Parameters:
name- the name of the Field, displayed in bold above thevalue.value- the contents of the field.inline- whether or not this field should display inline.- Returns:
- the builder after the field has been added
- Throws:
java.lang.IllegalArgumentException-- If only
nameorvalueis set. Both must be set. - If the character limit for
name, defined byMessageEmbed.TITLE_MAX_LENGTHas 256, is exceeded. - If the character limit for
value, defined byMessageEmbed.VALUE_MAX_LENGTHas 1024, is exceeded.
- If only
-
addBlankField
@Nonnull public EmbedBuilder addBlankField(boolean inline)
Adds a blank (empty) Field to the embed.- Parameters:
inline- whether or not this field should display inline- Returns:
- the builder after the field has been added
-
clearFields
@Nonnull public EmbedBuilder clearFields()
Clears all fields from the embed, such as those created with theEmbedBuilder(MessageEmbed)constructor or via theaddFieldmethods.- Returns:
- the builder after the field has been added
-
getFields
@Nonnull public java.util.List<MessageEmbed.Field> getFields()
Modifiable list ofMessageEmbedFields that the builder will use forbuild().
You can add/remove Fields and restructure thisListand it will then be applied in the built MessageEmbed. These fields will be available again throughMessageEmbed.getFields().- Returns:
- Mutable List of
Fields
-
-