Class EmbedBuilder
- java.lang.Object
-
- net.dv8tion.jda.core.EmbedBuilder
-
public class EmbedBuilder extends java.lang.Object
Builder system used to buildMessageEmbeds
.
A visual breakdown of an Embed and how it relates to this class is available at https://imgur.com/a/yOb5n.- Since:
- 3.0
- Author:
- John A. Grosh
-
-
Field Summary
Fields Modifier and Type Field Description static java.util.regex.Pattern
URL_PATTERN
static java.lang.String
ZERO_WIDTH_SPACE
-
Constructor Summary
Constructors Constructor Description EmbedBuilder()
Creates an EmbedBuilder to be used to creates an embed to send.EmbedBuilder(EmbedBuilder builder)
EmbedBuilder(MessageEmbed embed)
Creates an EmbedBuilder using fields in an existing embed.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description EmbedBuilder
addBlankField(boolean inline)
Adds a blank (empty) Field to the embed.EmbedBuilder
addField(java.lang.String name, java.lang.String value, boolean inline)
Adds a Field to the embed.EmbedBuilder
addField(MessageEmbed.Field field)
Copies the provided Field into a new Field for this builder.EmbedBuilder
appendDescription(java.lang.CharSequence description)
Appends to the description of the embed.MessageEmbed
build()
Returns aMessageEmbed
that has been checked as being valid for sending.EmbedBuilder
clear()
Resets this builder to default state.EmbedBuilder
clearFields()
Clears all fields from the embed, such as those created with theEmbedBuilder(MessageEmbed)
constructor or via theaddField
methods.java.lang.StringBuilder
getDescriptionBuilder()
TheStringBuilder
used to build the description for the embed.java.util.List<MessageEmbed.Field>
getFields()
Modifiable list ofMessageEmbed
Fields that the builder will use forbuild()
.boolean
isEmpty()
Checks if the given embed is empty.boolean
isValidLength(AccountType type)
Checks whether the constructedMessageEmbed
is within the limits for the specifiedAccountType
Bot: 6000 Client: 2000int
length()
The overall length of the current EmbedBuilder in displayed characters.EmbedBuilder
setAuthor(java.lang.String name)
Sets the Author of the embed.EmbedBuilder
setAuthor(java.lang.String name, java.lang.String url)
Sets the Author of the embed.EmbedBuilder
setAuthor(java.lang.String name, java.lang.String url, java.lang.String iconUrl)
Sets the Author of the embed.EmbedBuilder
setColor(int color)
Sets the raw RGB color value for the embed.EmbedBuilder
setColor(java.awt.Color color)
Sets the Color of the embed.EmbedBuilder
setDescription(java.lang.CharSequence description)
Sets the Description of the embed.EmbedBuilder
setFooter(java.lang.String text, java.lang.String iconUrl)
Sets the Footer of the embed.EmbedBuilder
setImage(java.lang.String url)
Sets the Image of the embed.EmbedBuilder
setThumbnail(java.lang.String url)
Sets the Thumbnail of the embed.EmbedBuilder
setTimestamp(java.time.temporal.TemporalAccessor temporal)
Sets the Timestamp of the embed.EmbedBuilder
setTitle(java.lang.String title)
Sets the Title of the embed.EmbedBuilder
setTitle(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()
Creates an EmbedBuilder to be used to creates an embed to send.
Every part of an embed can be removed or cleared by providingnull
to the setter method.
-
EmbedBuilder
public EmbedBuilder(EmbedBuilder builder)
-
EmbedBuilder
public EmbedBuilder(MessageEmbed embed)
Creates an EmbedBuilder using fields in an existing embed.- Parameters:
embed
- the existing embed
-
-
Method Detail
-
build
public MessageEmbed build()
Returns aMessageEmbed
that 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
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
-
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(AccountType type)
Checks whether the constructedMessageEmbed
is within the limits for the specifiedAccountType
- Parameters:
type
- TheAccountType
to validate- Returns:
- True, if the
length
is less or equal to the specific limit - Throws:
java.lang.IllegalArgumentException
- If provided withnull
-
setTitle
public EmbedBuilder setTitle(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
title
is an empty String. - If the length of
title
is greater thanMessageEmbed.TITLE_MAX_LENGTH
.
- If the provided
-
setTitle
public EmbedBuilder setTitle(java.lang.String title, 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
title
is an empty String. - If the length of
title
is greater thanMessageEmbed.TITLE_MAX_LENGTH
. - If the length of
url
is longer thanMessageEmbed.URL_MAX_LENGTH
. - If the provided
url
is not a properly formatted http or https url.
- If the provided
-
getDescriptionBuilder
public java.lang.StringBuilder getDescriptionBuilder()
TheStringBuilder
used to build the description for the embed.
Note: To reset the description usesetDescription(null)
- Returns:
- StringBuilder with current description context
-
setDescription
public final EmbedBuilder setDescription(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,null
to reset- Returns:
- the builder after the description has been set
- Throws:
java.lang.IllegalArgumentException
- If the length ofdescription
is greater thanMessageEmbed.TEXT_MAX_LENGTH
-
appendDescription
public EmbedBuilder appendDescription(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
description
String is null - If the length of
description
is greater thanMessageEmbed.TEXT_MAX_LENGTH
.
- If the provided
-
setTimestamp
public EmbedBuilder setTimestamp(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
public EmbedBuilder setColor(java.awt.Color color)
Sets the Color of the embed. Example- Parameters:
color
- TheColor
of the embed ornull
to use no color- Returns:
- the builder after the color has been set
- See Also:
setColor(int)
-
setColor
public EmbedBuilder setColor(int color)
Sets the raw RGB color value for the embed. Example- Parameters:
color
- The raw rgb value, orRole.DEFAULT_COLOR_RAW
to use no color- Returns:
- the builder after the color has been set
- See Also:
setColor(java.awt.Color)
-
setThumbnail
public EmbedBuilder setThumbnail(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 MessageBuilder message = new MessageBuilder(); 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"); message.setEmbed(embed.build()); channel.sendFile(file, "cat.png", message.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 length of
url
is longer thanMessageEmbed.URL_MAX_LENGTH
. - If the provided
url
is not a properly formatted http or https url.
- If the length of
-
setImage
public EmbedBuilder setImage(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 MessageBuilder message = new MessageBuilder(); 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"); message.setEmbed(embed.build()); channel.sendFile(file, "cat.png", message.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 length of
url
is longer thanMessageEmbed.URL_MAX_LENGTH
. - If the provided
url
is not a properly formatted http or https url.
- If the length of
- See Also:
MessageChannel.sendFile(...)
-
setAuthor
public EmbedBuilder setAuthor(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
-
setAuthor
public EmbedBuilder setAuthor(java.lang.String name, 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 length of
url
is longer thanMessageEmbed.URL_MAX_LENGTH
. - If the provided
url
is not a properly formatted http or https url.
- If the length of
-
setAuthor
public EmbedBuilder setAuthor(java.lang.String name, java.lang.String url, 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 MessageBuilder message = new MessageBuilder(); 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"); message.setEmbed(embed.build()); channel.sendFile(file, "cat.png", message.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 length of
url
is longer thanMessageEmbed.URL_MAX_LENGTH
. - If the provided
url
is not a properly formatted http or https url. - If the length of
iconUrl
is longer thanMessageEmbed.URL_MAX_LENGTH
. - If the provided
iconUrl
is not a properly formatted http or https url.
- If the length of
-
setFooter
public EmbedBuilder setFooter(java.lang.String text, 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 MessageBuilder message = new MessageBuilder(); 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"); message.setEmbed(embed.build()); channel.sendFile(file, "cat.png", message.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 length of
text
is longer thanMessageEmbed.TEXT_MAX_LENGTH
. - If the length of
iconUrl
is longer thanMessageEmbed.URL_MAX_LENGTH
. - If the provided
iconUrl
is not a properly formatted http or https url.
- If the length of
-
addField
public EmbedBuilder addField(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
public EmbedBuilder addField(java.lang.String name, java.lang.String value, boolean inline)
Adds a Field to the embed.Note: If a blank string is provided to either
name
orvalue
, 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
name
orvalue
is set. Both must be set. - If the length of
name
is greater thanMessageEmbed.TITLE_MAX_LENGTH
. - If the length of
value
is greater thanMessageEmbed.VALUE_MAX_LENGTH
.
- If only
-
addBlankField
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
public EmbedBuilder clearFields()
Clears all fields from the embed, such as those created with theEmbedBuilder(MessageEmbed)
constructor or via theaddField
methods.- Returns:
- the builder after the field has been added
-
getFields
public java.util.List<MessageEmbed.Field> getFields()
Modifiable list ofMessageEmbed
Fields that the builder will use forbuild()
.
You can add/remove Fields and restructure thisList
and it will then be applied in the built MessageEmbed. These fields will be available again throughMessageEmbed.getFields()
.- Returns:
- Mutable List of
Fields
-
-