PaginatedMenu¶

class dpymenus.PaginatedMenu(ctx)¶

Represents an paginated, button-based response menu.

set_cancel_page(embed)¶

Sets the function that will be called when the cancel event runs. Returns itself for fluent-style chaining.

Parameters: embed (Embed) – Defines which page to display.
Return type: PaginatedMenu

set_timeout_page(embed)¶

Sets the function that will be called when the timeout event runs. Returns itself for fluent-style chaining.

Parameters: embed (Embed) – Defines which page to display.
Return type: PaginatedMenu

show_skip_buttons()¶

Adds two extra buttons for jumping to the first and last page. Returns itself for fluent-style chaining.

Return type: PaginatedMenu

hide_cancel_button()¶

Sets whether to show the cancel button or not. Returns itself for fluent-style chaining.

Return type: PaginatedMenu

buttons(buttons)¶

Replaces the default buttons. You must include 3 or 5 emoji/strings in the order they would be displayed. 0 and 5 are only shown if enable_skip_buttons is set, otherwise 2, 3, and 4 will be shown.

You can pass in None or an empty string for 0 and 5 if you do not intend on using them. If you only pass in 3 values, they will be filled in as the defaults for you. If you enable the skip buttons without having values set, it will use those defaults.

Returns itself for fluent-style chaining.

Parameters: buttons (List[ForwardRef]) – Which emoji reactions will replace the default buttons.
Return type: PaginatedMenu

async send_message(page)¶

Updates the output message. We override the base implementation because we always want to edit, even in a DM channel type.

Parameters: page (PageType) – A PageType to send to Discord.

async open()¶: The entry point to a new PaginatedMenu instance; starts the main menu loop. Manages gathering user input, basic validation, sending messages, and cancellation requests.

add_hook(when, event, callback)¶

Sets various callback attributes on the menu so users can hook into specific events. See https://dpymenus.com/lifecycle for the full list of events and hook structure.

Parameters

when (HookWhen) – Defines which point in the menu lifetime the callback will be executed.
event (HookEvent) – Defines which event in the menu lifetime the callback will be executed on.
callback (Callable) – References a function or method which will be executed based on the when and event params.

Return type

BaseMenu

add_pages(pages, template=None)¶

Adds a list of pages to a menu, setting their index based on the position in the list. Returns itself for fluent-style chaining.

Parameters

pages (List[ForwardRef]) – A list of pages to display; ordered from first to last in linear menus.
template (Template) – An optional Template to define a menu style.

Return type

BaseMenu

button_pressed(button)¶

Checks if the reaction the user pressed is equal to the argument.

Parameters: button (Button) – The reaction to compare against user input.
Return type: bool

async close()¶: Gracefully exits out of the menu, performing necessary cleanup of sessions, reactions, and messages.

disable_replies()¶

Disables the Reply feature on Discord from being used with this menu. Overrides the global settings. Returns itself for fluent-style chaining.

Return type: BaseMenu

async go_to(page=None)¶

Transitions to a specific page.

Parameters: page (Union[str, int, None]) – The name of the on_next function for a particular page or its page number. If this is not set, the next page in the list will be called.

static kill_tasks(pending)¶: Clears all remaining tasks in the task queue.

last_visited_page()¶

Returns the last visited page index.

Return type: int

async next()¶: Transitions to the next page.

persist_on_close()¶

Prevents message cleanup from running when a menu closes. Returns itself for fluent-style chaining.

Return type: BaseMenu

async previous()¶: Transitions to the previous page.

set_custom_check(fn)¶

Overrides the default check method for user responses. Returns itself for fluent-style chaining.

Parameters: fn (Callable) – A reference to a predicate function.
Return type: BaseMenu

set_data(data)¶

Sets a dictionary up for persistent state data. Returns itself for fluent-style chaining.

Parameters: data (Dict) – Structure representing variables that can be easily accessed across a menu instance.
Return type: TextMenu

set_destination(dest)¶

Sets the message destination for the menu. Returns itself for fluent-style chaining.

Parameters: dest (Union[User, TextChannel]) – Where, in Discord, to send and display the menu.
Return type: BaseMenu

set_initial_page(index)¶

Sets the initial page of the menu when opened based on a pages index in the add_pages list. Defaults to 0.

Parameters: index (int) – Which page index to start on.
Return type: BaseMenu

set_timeout(duration)¶

Sets the timeout on a menu. Returns itself for fluent-style chaining.

Parameters: duration (int) – Specifies how long, in seconds, before the menu will time out.
Return type: BaseMenu

show_command_message()¶

Persists user command invocation messages in the chat instead of deleting them after execution. Returns itself for fluent-style chaining.

Return type: BaseMenu

async to_first()¶: Transitions to the first page.

async to_last()¶: Transitions to the last page.