Interactive Menus & TUI

Relevant source files

The following files were used as context for generating this wiki page:

• redbot/core/utils/views.py
• redbot/core/utils/menus.py
• redbot/core/commands/help.py
• redbot/core/core_commands.py
• redbot/core/_events.py
• redbot/core/dev_commands.py

Red-DiscordBot provides a robust set of utilities for creating interactive user interfaces within Discord. These interfaces range from multi-page paginated menus using buttons and select menus to confirmation prompts and secure API key entry modals. The system handles both modern Discord Components (Views) and legacy reaction-based interactions to ensure compatibility across different client capabilities and user preferences. Sources: redbot/core/utils/views.py, redbot/core/utils/menus.py

The system also includes Terminal User Interface (TUI) elements used during bot startup and within development commands. This includes rich console tables for displaying bot metadata and interactive REPL (Read-Eval-Print Loop) sessions for real-time debugging. Sources: redbot/core/_events.py, redbot/core/dev_commands.py

Core Menu Architecture

The menu system primary utilizes discord.ui.View to manage interactive components. The SimpleMenu class acts as the standard container for paginated content, integrating navigation buttons and select menus.

Menu Logic Flow

When a command invokes a menu, the system determines the interaction method based on bot settings and channel permissions. If button-based menus are enabled, it initializes a discord.ui.View. If only reactions are available, it falls back to a reaction-controlled message.

The logic flow for menu initialization and pagination. Sources: redbot/core/utils/menus.py:159-224, redbot/core/utils/views.py:214-257

Paginated View Components

The SimpleMenu class coordinates several sub-components to handle navigation:

• _SimplePageSource: Manages the list of items (strings, embeds, or dictionaries) and provides formatted page content to the view.
• _NavigateButton: A standard button that modifies the view's current_page index based on a specific direction (forward, backward, first, last).
• _SelectMenu: A dropdown menu that allows users to jump directly to specific pages. It dynamically adjusts its options if the page count exceeds 25 to remain within Discord's API limits.
• _StopButton: Deletes the menu message or removes the view upon user request.

Sources: redbot/core/utils/views.py:19-71

Menu Configuration & Settings

The behavior of menus, particularly in the help system, is controlled by HelpSettings. Users and owners can configure how navigation elements appear using the HelpMenuSetting enumeration. Sources: redbot/core/commands/help.py:73-79

Setting Value	Enum Name	Behavior Description
0	disabled	Disables pagination menus; sends flat messages.
1	reactions	Uses legacy emoji reactions for navigation.
2	buttons	Uses Discord Buttons for navigation.
3	select	Uses Buttons and a Select Menu for navigation.
4	selectonly	Uses only a Select Menu for navigation.

Sources: redbot/core/commands/help.py:101-131

Interface Interaction Sequence

Interaction with a view-based menu follows a strict sequence to ensure security and state management:

The sequence of events during a button interaction. Sources: redbot/core/utils/views.py:259-281

Specialized Interactive Views

Beyond simple pagination, the framework provides specialized views for common bot tasks.

Confirmation View

ConfirmView displays "Yes" and "No" buttons. It stores the result in a result boolean attribute, which the calling command awaits.

• Logic: The view stops and calls on_timeout immediately after a button is pressed to clean up the interface.
• Persistence: It allows disabling buttons instead of removing them if configured via disable_buttons=True.

Sources: redbot/core/utils/views.py:381-540

API Management (Modals)

For secure data entry, such as API tokens, Red uses SetApiView and SetApiModal.

1. View: Displays a "Set API token" button.
2. Interaction Check: Restricts access to bot owners only.
3. Modal: Opens a discord.ui.Modal with TextInput components.
4. Submission: The on_submit callback parses the input using a dictionary converter and saves it via bot.set_shared_api_tokens.

Sources: redbot/core/utils/views.py:284-378

TUI and Console Formatting

Red utilizes a TUI approach for console output during the bot's lifecycle and for specific developer tools.

Startup TUI

Upon successful connection, the bot renders an ASCII art banner followed by metadata panels. The rich library renders these as organized columns containing:

• Instance Panel: Displays the username, prefix, language, and Red version.
• Counts Panel: Displays shard, server, and unique user counts.

Sources: redbot/core/_events.py:76-118

Developer REPL

The Dev cog provides an interactive REPL session within a Discord channel.

• State Management: The REPL tracks active sessions per channel in the self.sessions dictionary.
• Execution Loop: It uses bot.wait_for("message") to capture code, wraps it in an async function, compiles it with ast.PyCF_ALLOW_TOP_LEVEL_AWAIT, and executes it within a shared environment.
• Output Sanitization: The sanitize_output function scans for the bot's token in the execution result and replaces it with [EXPUNGED] before sending it to the channel.

Sources: redbot/core/dev_commands.py:28-55, redbot/core/dev_commands.py:465-515

Summary

Interactive Menus & TUI in Red provide a standardized way to handle complex user interactions. By abstracting discord.ui components into reusable classes like SimpleMenu and ConfirmView, the bot ensures consistent behavior across various cogs. The integration of legacy reaction support and modern button/modal interfaces allows for high accessibility, while the startup TUI and interactive REPL provide critical diagnostic information to bot administrators.