• Home
• io.github.freya022
• BotCommands
• 3.0.0-alpha.7
• source code
• Components.kt

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

io.github.freya022.botcommands.api.components.Components.kt Maven / Gradle / Ivy

package io.github.freya022.botcommands.api.components

import io.github.freya022.botcommands.api.ReceiverConsumer
import io.github.freya022.botcommands.api.components.builder.button.EphemeralButtonBuilder
import io.github.freya022.botcommands.api.components.builder.button.PersistentButtonBuilder
import io.github.freya022.botcommands.api.components.builder.group.ComponentGroupBuilder
import io.github.freya022.botcommands.api.components.builder.group.EphemeralComponentGroupBuilder
import io.github.freya022.botcommands.api.components.builder.group.PersistentComponentGroupBuilder
import io.github.freya022.botcommands.api.components.builder.select.ephemeral.EphemeralEntitySelectBuilder
import io.github.freya022.botcommands.api.components.builder.select.ephemeral.EphemeralStringSelectBuilder
import io.github.freya022.botcommands.api.components.builder.select.persistent.PersistentEntitySelectBuilder
import io.github.freya022.botcommands.api.components.builder.select.persistent.PersistentStringSelectBuilder
import io.github.freya022.botcommands.api.core.BContext
import io.github.freya022.botcommands.api.core.config.BComponentsConfig
import io.github.freya022.botcommands.api.core.service.ConditionalServiceChecker
import io.github.freya022.botcommands.api.core.service.annotations.BService
import io.github.freya022.botcommands.api.core.service.annotations.ConditionalService
import io.github.freya022.botcommands.api.utils.ButtonContent
import io.github.freya022.botcommands.internal.components.controller.ComponentController
import io.github.freya022.botcommands.internal.utils.reference
import io.github.freya022.botcommands.internal.utils.requireUser
import io.github.freya022.botcommands.internal.utils.throwUser
import io.github.oshai.kotlinlogging.KotlinLogging
import kotlinx.coroutines.runBlocking
import net.dv8tion.jda.api.entities.emoji.Emoji
import net.dv8tion.jda.api.interactions.components.ActionComponent
import net.dv8tion.jda.api.interactions.components.buttons.ButtonStyle
import net.dv8tion.jda.api.interactions.components.selections.EntitySelectMenu.SelectTarget

/**
 * This class lets you create smart components such as buttons, select menus, and groups.
 *
 * Every component can either be persistent or ephemeral, all components can be configured to:
 *  - Be used once
 *  - Have timeouts
 *  - Have handlers
 *  - Have constraints (checks before the button can be used)
 *
 * Except component groups which can only have its timeout configured.
 *
 * ### Persistent components
 *  - Kept after restart
 *  - Handlers are methods; they can have arguments passed to them
 *  - Timeouts are also methods, additionally, they will be rescheduled when the bot restarts
 *
 * ### Ephemeral components
 *  - Are deleted once the bot restarts
 *  - Handlers are closures, they can capture objects, but you [shouldn't capture JDA entities](https://jda.wiki/using-jda/troubleshooting/#cannot-get-reference-as-it-has-already-been-garbage-collected)
 *  - Timeouts are also closures, but are not rescheduled when restarting
 *
 * ### Component groups
 *  - If deleted, all contained components are deleted
 *  - If one of the contained components is deleted, then all of its subsequent groups are also deleted
 *
 * ### Java example
 * ```java
 * @Command
 * public class SlashButton extends ApplicationCommand {
 *     private static final String BUTTON_LISTENER_NAME = "SlashButton: persistentButton"; //ClassName: theButtonPurpose
 *
 *     private final Components componentsService;
 *
 *     public SlashButton(Components componentsService) {
 *         this.componentsService = componentsService;
 *     }
 *
 *     @JDASlashCommand(name = "button", description = "Try out the new buttons!")
 *     public void onSlashButton(GuildSlashEvent event) {
 *         final List components = new ArrayList<>();
 *
 *         components.add(componentsService.ephemeralButton(ButtonStyle.PRIMARY, "Click me under 5 seconds", builder -> {
 *             builder.timeout(5, TimeUnit.SECONDS, () -> {
 *                 event.getHook()
 *                         .editOriginalComponents(ActionRow.of(
 *                                 components.stream().map(Button::asDisabled).collect(Collectors.toList())
 *                         ))
 *                         .queue();
 *             });
 *
 *             builder.bindTo(buttonEvent -> {
 *                 buttonEvent.editButton(buttonEvent.getButton().asDisabled()).queue();
 *             });
 *         }));
 *
 *         components.add(componentsService.persistentButton(ButtonStyle.SECONDARY, "Click me anytime", builder -> {
 *             builder.bindTo(BUTTON_LISTENER_NAME);
 *         }));
 *
 *         event.replyComponents(ActionRow.of(components))
 *                 .setContent(TimeFormat.RELATIVE.format(Instant.now().plus(Duration.ofSeconds(5))))
 *                 .setEphemeral(true)
 *                 .queue();
 *     }
 *
 *     @JDAButtonListener(name = BUTTON_LISTENER_NAME)
 *     public void onPersistentButtonClick(ButtonEvent event) {
 *         event.editButton(event.getButton().asDisabled()).queue();
 *     }
 * }
 * ```
 *
 * ### Kotlin example
 * ```kt
 * private const val buttonListenerName = "SlashButton: persistentButton" //ClassName: theButtonPurpose
 *
 * @Command
 * class SlashButton(private val componentsService: Components) : ApplicationCommand() {
 *     @JDASlashCommand(name = "button", description = "Try out the new buttons!")
 *     fun onSlashButton(event: GuildSlashEvent) {
 *         val components: MutableList = arrayListOf()
 *         components += componentsService.ephemeralButton(ButtonStyle.PRIMARY, "Click me under 5 seconds") {
 *             timeout(5.seconds) {
 *                 event.hook.editOriginalComponents(components.map(Button::asDisabled).row()).queue()
 *             }
 *             bindTo { buttonEvent ->
 *                 buttonEvent.editButton(buttonEvent.button.asDisabled()).await() // Coroutines!
 *             }
 *         }
 *
 *         components += componentsService.persistentButton(ButtonStyle.SECONDARY, "Click me anytime") {
 *             bindTo(buttonListenerName)
 *         }
 *
 *         event.replyComponents(listOf(components.row()))
 *             .setContent(TimeFormat.RELATIVE.format(Instant.now() + 5.seconds.toJavaDuration()))
 *             .setEphemeral(true)
 *             .queue()
 *     }
 *
 *     @JDAButtonListener(name = buttonListenerName)
 *     suspend fun onPersistentButtonClick(event: ButtonEvent) {
 *         event.editButton(event.button.asDisabled()).await()
 *     }
 * }
 * ```
 */
@BService
@ConditionalService(Components.Companion::class)
class Components internal constructor(private val componentController: ComponentController) {
    private val logger = KotlinLogging.logger { }

    // -------------------- Persistent groups --------------------

    fun newPersistentGroup(block: ReceiverConsumer, vararg components: ActionComponent): ComponentGroup = runBlocking {
        createGroup({ PersistentComponentGroupBuilder(it).apply(block) }, *components)
    }

    @JvmSynthetic
    suspend fun newPersistentGroup(vararg components: ActionComponent, block: ReceiverConsumer): ComponentGroup =
        createGroup({ PersistentComponentGroupBuilder(it).apply(block) }, *components)

    // -------------------- Ephemeral groups --------------------

    fun newEphemeralGroup(block: ReceiverConsumer, vararg components: ActionComponent): ComponentGroup = runBlocking {
        createGroup({ EphemeralComponentGroupBuilder(it).apply(block) }, *components)
    }

    @JvmSynthetic
    suspend fun newEphemeralGroup(vararg components: ActionComponent, block: ReceiverConsumer): ComponentGroup =
        createGroup({ EphemeralComponentGroupBuilder(it).apply(block) }, *components)

    // -------------------- Persistent buttons --------------------

    /** See [Button.of][net.dv8tion.jda.api.interactions.components.buttons.Button.of] */
    @JvmOverloads
    fun persistentButton(style: ButtonStyle, label: String? = null, emoji: Emoji? = null, block: ReceiverConsumer) =
        PersistentButtonBuilder(style, componentController).apply(block).build(label, emoji)
    /** See [Button.of][net.dv8tion.jda.api.interactions.components.buttons.Button.of] */
    fun persistentButton(style: ButtonStyle, content: ButtonContent, block: ReceiverConsumer) =
        persistentButton(style, content.text, content.emoji, block)

    // -------------------- Ephemeral buttons --------------------

    /** See [Button.of][net.dv8tion.jda.api.interactions.components.buttons.Button.of] */
    @JvmOverloads
    fun ephemeralButton(style: ButtonStyle, label: String? = null, emoji: Emoji? = null, block: ReceiverConsumer) =
        EphemeralButtonBuilder(style, componentController).apply(block).build(label, emoji)
    /** See [Button.of][net.dv8tion.jda.api.interactions.components.buttons.Button.of] */
    fun ephemeralButton(style: ButtonStyle, content: ButtonContent, block: ReceiverConsumer) =
        ephemeralButton(style, content.text, content.emoji, block)

    // -------------------- Persistent select menus --------------------

    fun persistentStringSelectMenu(block: ReceiverConsumer) =
        PersistentStringSelectBuilder(componentController).apply(block).doBuild()
    fun persistentEntitySelectMenu(target: SelectTarget, block: ReceiverConsumer) =
        persistentEntitySelectMenu(listOf(target), block)
    fun persistentEntitySelectMenu(targets: List, block: ReceiverConsumer) =
        PersistentEntitySelectBuilder(componentController, targets).apply(block).doBuild()

    // -------------------- Ephemeral select menus --------------------

    fun ephemeralStringSelectMenu(block: ReceiverConsumer) =
        EphemeralStringSelectBuilder(componentController).apply(block).doBuild()
    fun ephemeralEntitySelectMenu(target: SelectTarget, block: ReceiverConsumer) =
        ephemeralEntitySelectMenu(listOf(target), block)
    fun ephemeralEntitySelectMenu(targets: List, block: ReceiverConsumer) =
        EphemeralEntitySelectBuilder(componentController, targets).apply(block).doBuild()

    @JvmName("deleteComponentsById")
    fun deleteComponentsByIdJava(ids: Collection) = runBlocking { deleteComponentsById(ids) }

    @JvmSynthetic
    suspend fun deleteComponentsById(ids: Collection) {
        componentController.deleteComponentsById(ids.mapNotNull { it.toIntOrNull() })
    }

    private suspend fun createGroup(factory: (List) -> ComponentGroupBuilder, vararg components: ActionComponent): ComponentGroup {
        requireUser(components.none { it.id == null }) {
            "Cannot make groups with link buttons"
        }

        return components
            .map { it.id?.toIntOrNull() ?: throwUser("Cannot put external components in groups") }
            .let { componentIds -> factory(componentIds) }
            .let { componentController.insertGroup(it) }
    }

    internal companion object : ConditionalServiceChecker {
        override fun checkServiceAvailability(context: BContext, checkedClass: Class<*>): String? {
            if (context.componentsConfig.useComponents) {
                return null
            }

            return "Components needs to be enabled, see ${BComponentsConfig::useComponents.reference}"
        }
    }
}