net.dv8tion.jda.api.entities.GuildWelcomeScreen Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of JDA Show documentation
Show all versions of JDA Show documentation
Java wrapper for the popular chat & VOIP service: Discord https://discord.com
/*
* Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.dv8tion.jda.api.entities;
import net.dv8tion.jda.api.entities.channel.middleman.GuildChannel;
import net.dv8tion.jda.api.entities.channel.middleman.StandardGuildChannel;
import net.dv8tion.jda.api.entities.emoji.CustomEmoji;
import net.dv8tion.jda.api.entities.emoji.Emoji;
import net.dv8tion.jda.api.entities.emoji.EmojiUnion;
import net.dv8tion.jda.api.managers.GuildWelcomeScreenManager;
import net.dv8tion.jda.api.utils.data.SerializableData;
import net.dv8tion.jda.internal.entities.GuildWelcomeScreenImpl;
import net.dv8tion.jda.internal.utils.Checks;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.List;
/**
* The welcome screen of a {@link Guild}.
* This welcome screen will be shown to all members after joining the Guild.
*
* @see Guild#retrieveWelcomeScreen()
* @see Invite.Guild#getWelcomeScreen()
*/
public interface GuildWelcomeScreen
{
/** The maximum length of a welcome screen description ({@value}) */
int MAX_DESCRIPTION_LENGTH = 140;
/** The maximum amount of welcome channel a welcome screen can show ({@value}) */
int MAX_WELCOME_CHANNELS = 5;
/**
* The {@link Guild Guild}, or {@code null} if this welcome screen came from an {@link Invite}
*
* @return The Guild, or {@code null}
*/
@Nullable
Guild getGuild();
/**
* Returns the {@link GuildWelcomeScreenManager Manager} for this guild's welcome screen.
*
* @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
* If the currently logged in account does not have {@link net.dv8tion.jda.api.Permission#MANAGE_SERVER Permission.MANAGE_SERVER}
* @throws IllegalStateException
* If welcome screen came from an {@link Invite}
*
* @return The GuildWelcomeScreenManager for this guild's welcome screen
*
* @see Guild#modifyWelcomeScreen()
*/
@Nonnull
GuildWelcomeScreenManager getManager();
/**
* The server description shown in the welcome screen.
*
This will be {@code null} if the welcome screen has no description.
*
* @return The server description shown in the welcome screen or {@code null}
*/
@Nullable
String getDescription();
/**
* The channels shown in the welcome screen.
*
* @return Possibly-empty, unmodifiable list of the channels shown in the welcome screen
*/
@Nonnull
List getChannels();
/**
* POJO for the recommended channels information provided by a welcome screen.
*
Recommended channels are shown in the welcome screen after joining a server.
*
* @see GuildWelcomeScreen#getChannels()
*/
interface Channel extends ISnowflake, SerializableData
{
/** Maximum length of a channel description ({@value}) */
int MAX_DESCRIPTION_LENGTH = 42;
/**
* Constructs a new welcome channel.
*
* @param channel
* The Discord channel to be presented to the user
* @param description
* The description of the channel, must not be longer than {@value #MAX_DESCRIPTION_LENGTH}
*
* @throws IllegalArgumentException
*
* - If the channel is null
* - If the description is null, blank, or longer than {@value #MAX_DESCRIPTION_LENGTH}
*
*
* @return The new welcome channel
*/
@Nonnull
static Channel of(@Nonnull StandardGuildChannel channel, @Nonnull String description)
{
return of(channel, description, null);
}
/**
* Constructs a new welcome channel.
*
* @param channel
* The Discord channel to be presented the user
* @param description
* The description of the channel, must not be longer than {@value #MAX_DESCRIPTION_LENGTH}
* @param emoji
* The emoji to show beside the channel
*
* @throws IllegalArgumentException
*
* - If the channel is null
* - If the description is null, blank, or longer than {@value #MAX_DESCRIPTION_LENGTH}
*
*
* @return The new welcome channel
*/
@Nonnull
static Channel of(@Nonnull StandardGuildChannel channel, @Nonnull String description, @Nullable Emoji emoji)
{
Checks.notNull(channel, "Channel");
Checks.notBlank(description, "Description");
Checks.notLonger(description, MAX_DESCRIPTION_LENGTH, "Description");
return new GuildWelcomeScreenImpl.ChannelImpl(channel.getGuild(), channel.getIdLong(), description, (EmojiUnion) emoji);
}
/**
* The {@link Guild Guild}, or {@code null} if this welcome channel came from an {@link Invite}
*
* @return The Guild, or {@code null}
*/
@Nullable
Guild getGuild();
/**
* The id of this recommended channel.
*
* @return The id of this recommended channel
*/
@Override
long getIdLong();
/**
* Returns the {@link GuildChannel} that is linked to this recommended channel.
*
This will be {@code null} if the linked channel was deleted, or if the welcome screen comes from an {@link Invite.Guild invite guild}.
*
* @return The {@link GuildChannel} that is linked to this recommended channel or {@code null}
*/
@Nullable
GuildChannel getChannel();
/**
* The description of this recommended channel shown in the welcome screen.
*
* @return The description of this recommended channel
*/
@Nonnull
String getDescription();
/**
* The emoji that is used for this recommended channel.
*
This will return {@code null} if no emoji was set
*
* The emoji will always be from this guild, if not a unicode emoji
*
{@link CustomEmoji#isAnimated()} will always return {@code false} if:
*
* - This welcome screen came from an {@link Invite.Guild invite's guild}
* - {@link net.dv8tion.jda.api.utils.cache.CacheFlag#EMOJI CacheFlag.EMOJI} is disabled
*
*
* @return The emoji that is used for this recommended channel or {@code null}
*/
@Nullable
EmojiUnion getEmoji();
}
}