io.github.freya022.botcommands.api.pagination.BasicPaginationBuilder Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of BotCommands Show documentation

A Kotlin-first (and Java) framework that makes creating Discord bots a piece of cake, using the JDA library.

There is a newer version: 3.0.0-alpha.22

package io.github.freya022.botcommands.api.pagination;

import io.github.freya022.botcommands.api.components.Components;
import io.github.freya022.botcommands.api.components.data.InteractionConstraints;
import io.github.freya022.botcommands.api.pagination.paginator.BasicPaginatorBuilder;
import net.dv8tion.jda.api.entities.Message;
import net.dv8tion.jda.api.interactions.callbacks.IDeferrableCallback;
import net.dv8tion.jda.internal.utils.Checks;
import org.jetbrains.annotations.NotNull;

import java.util.concurrent.TimeUnit;

/**
 * Provides base for a pagination builder
 *
 * @param  Type of the implementor
 * @param  Type of the implementor {@link #build()} return type
 */
@SuppressWarnings("unchecked")
public abstract class BasicPaginationBuilder, R extends BasicPagination> {
	protected InteractionConstraints constraints = InteractionConstraints.empty();
	protected TimeoutInfo timeout;

	protected final Components componentsService;

	protected BasicPaginationBuilder(Components componentsService) {
		this.componentsService = componentsService;
	}

	/**
	 * Sets the timeout for this pagination instance
	 * 
On timeout, only the consumer is called, no message are deleted and it is up to you to clean up components with {@link BasicPagination#cleanup()}
	 *
	 * 

How to manipulate the message on timeout, for example you want to delete the message, or replace its content:
	 * 
	 *     For application commands: You can use the {@link IDeferrableCallback#getHook() Interaction hook} of application event
	 *     For text commands: You can use {@link BasicPagination#setMessage(Message)} when the message has been sent successfully, so in your queue success consumer,
	 *     you will then receive that same message in the {@link PaginationTimeoutConsumer} you have set
	 * 
	 *
	 * @param timeout     Amount of time before the timeout occurs
	 * @param timeoutUnit Unit of time for the supplied timeout
	 * @param onTimeout   The consumer fired on timeout, long operations should not run here
	 * @return This builder for chaining convenience
	 */
	public T setTimeout(long timeout, @NotNull TimeUnit timeoutUnit, @NotNull PaginationTimeoutConsumer onTimeout) {
		Checks.positive(timeout, "Timeout");
		Checks.notNull(onTimeout, "Timeout consumer");
		Checks.notNull(timeoutUnit, "Timeout TimeUnit");

		this.timeout = new TimeoutInfo<>(timeout, timeoutUnit, onTimeout);

		return (T) this;
	}

	/**
	 * Sets the interaction constraints for this pagination object
	 * 
These constraints control who can use this pagination object, including {@link BasicPaginatorBuilder#useDeleteButton(boolean) delete buttons}
	 *
	 * @param constraints The {@link InteractionConstraints} for this pagination object
	 * @return This builder for chaining convenience
	 *
	 * @see InteractionConstraints Factory methods of InteractionConstraints
	 */
	public T setConstraints(@NotNull InteractionConstraints constraints) {
		this.constraints = constraints;

		return (T) this;
	}

	/**
	 * Builds this pagination instance
	 *
	 * @return The newly created pagination instance
	 */
	@NotNull
	public abstract R build();
}