Merge pull request #1 from DenverCoderOne/feature/menu-with-buttons

Added button component menus

Author: TAG-Epic

README.md

@@ -1,18 +1,18 @@
 # nextcord-ext-menus
 
-## About 
+A Nextcord extension that makes working with reaction menus and button component menus a bit easier.
 
-A Nextcord extension that makes working with reaction menus a bit easier.
-
-## Installing
+# Installing
 
 Python **>=3.6.0** is required.
 
 ```py 
 pip install --upgrade nextcord-ext-menus
 ```
 
-## Getting Started
+# Getting Started
+
+## Reaction Menus
 
 To whet your appetite, the following examples show the fundamentals on how to create menus.
 
@@ -43,8 +43,7 @@ Now, within a command we just instantiate it and we start it like so:
 ```py
 @bot.command()
 async def menu_example(ctx):
-    m = MyMenu()
-    await m.start(ctx)
+    await MyMenu().start(ctx)
 ```
 
 If an error happens then an exception of type `menus.MenuError` is raised.
@@ -175,6 +174,61 @@ pages = menus.MenuPages(source=Source(), clear_reactions_after=True)
 await pages.start(ctx)
 ```
 
+## Button Component Menus
+
+Here is a button implementation of a basic menu that has a stop button and two reply reactions.
+
+Note that the `ButtonMenu` class is used instead of `Menu` in order to make it a `View`. `ButtonMenu` is a subclass of `Menu` and it therefore has all the same attributes and methods.
+
+Also note that `view=self` is passed with the initial message and `nextcord.ui.button` is used instead of `menus.button`.
+
+`ButtonMenu.disable` can be used to disable all buttons in the menu.
+
+`ButtonMenu.enable` can be used to enable all buttons in the menu.
+
+```py
+import nextcord
+from nextcord.ext import menus
+
+class MyButtonMenu(menus.ButtonMenu):
+    async def send_initial_message(self, ctx, channel):
+        return await channel.send(f'Hello {ctx.author}', view=self)
+
+    @nextcord.ui.button(emoji="\N{THUMBS UP SIGN}")
+    async def on_thumbs_up(self, button, interaction):
+        await self.message.edit(content=f"Thanks {interaction.user}!")
+
+    @nextcord.ui.button(emoji="\N{THUMBS DOWN SIGN}")
+    async def on_thumbs_down(self, button, interaction):
+        await self.message.edit(content=f"That's not nice {interaction.user}...")
+
+    @nextcord.ui.button(emoji="\N{BLACK SQUARE FOR STOP}\ufe0f")
+    async def on_stop(self, button, interaction):
+        await self.disable()
+        self.stop()
+```
+
+Instantiation is the same as above.
+
+```py
+await MyButtonMenu().start(ctx)
+```
+
+### Pagination
+
+A `ButtonMenuPages` class is provided for pagination with button components.
+
+`ButtonMenuPages` works the same way as the `MenuPages` class found above, but with button components instead of reactions.
+
+A `ButtonStyle` can optionally be passed in to customize the appearance.
+
+`MySource` is the same as defined above, but the menu is instantiated with:
+
+```py
+pages = menus.ButtonMenuPages(source=MySource(range(1, 100)), style=nextcord.ButtonStyle.primary)
+await pages.start(ctx)
+```
+
 ## License
 
 Copyright (c) 2021 The Nextcord Developers  

nextcord/ext/menus/__init__.py

@@ -6,13 +6,15 @@
 import logging
 import re
 from collections import OrderedDict, namedtuple
+from typing import List, Union
 
 # Needed for the setup.py script
 __version__ = '1.0.0'
 
 # consistency with the `nextcord` namespaced logging
 log = logging.getLogger(__name__)
 
+DEFAULT_TIMEOUT = 180.0
 
 class MenuError(Exception):
     pass
@@ -311,7 +313,7 @@ class Menu(metaclass=_MenuMeta):
         calling :meth:`send_initial_message`\, if for example you have a pre-existing
         message you want to attach a menu to.
     """
-    def __init__(self, *, timeout=180.0, delete_message_after=False,
+    def __init__(self, *, timeout=DEFAULT_TIMEOUT, delete_message_after=False,
                           clear_reactions_after=False, check_embeds=False, message=None):
 
         self.timeout = timeout
@@ -504,7 +506,15 @@ async def dummy():
 
     def should_add_reactions(self):
         """:class:`bool`: Whether to add reactions to this menu session."""
-        return len(self.buttons)
+        return len(self.buttons) > 0
+
+    def should_add_buttons(self):
+        """:class:`bool`: Whether to add button components to this menu session."""
+        return hasattr(self, 'children') and len(self.children) > 0
+
+    def should_add_reactions_or_buttons(self):
+        """:class:`bool`: Whether to add reactions or buttons to this menu session."""
+        return self.should_add_reactions() or self.should_add_buttons()
 
     def _verify_permissions(self, ctx, channel, permissions):
         if not permissions.send_messages:
@@ -698,7 +708,7 @@ async def start(self, ctx, *, channel=None, wait=False):
         if msg is None:
             self.message = msg = await self.send_initial_message(ctx, channel)
 
-        if self.should_add_reactions():
+        if self.should_add_reactions_or_buttons():
             # Start the task first so we can listen to reactions before doing anything
             for task in self.__tasks:
                 task.cancel()
@@ -761,6 +771,53 @@ def stop(self):
             task.cancel()
         self.__tasks.clear()
 
+class ButtonMenu(Menu, nextcord.ui.View):
+    r"""An interface that allows handling menus by using button interaction components.
+
+    Buttons should be marked with the :func:`nextcord.ui.button` decorator. Please note that
+    this expects the methods to have two parameters, the ``button`` and the ``interaction``.
+    The ``button`` is of type :class:`nextcord.ui.Button`.
+    The ``interaction`` is of type :class:`nextcord.Interaction`.
+    """
+    def __init__(self, timeout=DEFAULT_TIMEOUT, *args, **kwargs):
+        Menu.__init__(self, timeout=timeout, *args, **kwargs)
+        nextcord.ui.View.__init__(self, timeout=timeout)
+
+    async def _set_all_disabled(self, disable: bool):
+        """|coro|
+
+        Enables or disable all :class:`nextcord.ui.Button` components in the menu.
+
+        Parameters
+        ------------
+        disable: :class:`bool`
+            Whether to disable or enable the buttons.
+        """
+        for child in self.children:
+            child.disabled = disable
+        await self.message.edit(view=self)
+
+    async def enable(self):
+        """|coro|
+
+        Enables all :class:`nextcord.ui.Button` components in the menu.
+        """
+        await self._set_all_disabled(False)
+
+    async def disable(self):
+        """|coro|
+
+        Disables all :class:`nextcord.ui.Button` components in the menu.
+        """
+        await self._set_all_disabled(True)
+
+    def stop(self):
+        """Stops the internal loop and view interactions."""
+        # stop the menu loop
+        Menu.stop(self)
+        # stop view interactions
+        nextcord.ui.View.stop(self)
+
 
 class PageSource:
     """An interface representing a menu page's data source for the actual menu page.
@@ -797,7 +854,7 @@ async def prepare(self):
         return
 
     def is_paginating(self):
-        """An abstract method that notifies the :class:`MenuPages` whether or not
+        """An abstract method that notifies the :class:`MenuPagesBase` whether or not
         to start paginating. This signals whether to add reactions or not.
 
         Subclasses must implement this.
@@ -883,15 +940,21 @@ async def format_page(self, menu, page):
         raise NotImplementedError
 
 
-class MenuPages(Menu):
-    """A special type of Menu dedicated to pagination.
+class MenuPagesBase(ButtonMenu):
+    """A base class dedicated to pagination for reaction and button menus.
 
     Attributes
     ------------
     current_page: :class:`int`
         The current page that we are in. Zero-indexed
         between [0, :attr:`PageSource.max_pages`).
     """
+    FIRST_PAGE = '\N{BLACK LEFT-POINTING DOUBLE TRIANGLE WITH VERTICAL BAR}\ufe0f'
+    PREVIOUS_PAGE = '\N{BLACK LEFT-POINTING TRIANGLE}\ufe0f'
+    NEXT_PAGE = '\N{BLACK RIGHT-POINTING TRIANGLE}\ufe0f'
+    LAST_PAGE = '\N{BLACK RIGHT-POINTING DOUBLE TRIANGLE WITH VERTICAL BAR}\ufe0f'
+    STOP = '\N{BLACK SQUARE FOR STOP}\ufe0f'
+
     def __init__(self, source, **kwargs):
         self._source = source
         self.current_page = 0
@@ -954,6 +1017,8 @@ async def send_initial_message(self, ctx, channel):
         """
         page = await self._source.get_page(0)
         kwargs = await self._get_kwargs_from_page(page)
+        if hasattr(self, '__discord_ui_view__'):
+            kwargs['view'] = self
         return await channel.send(**kwargs)
 
     async def start(self, ctx, *, channel=None, wait=False):
@@ -982,24 +1047,35 @@ def _skip_double_triangle_buttons(self):
             return True
         return max_pages <= 2
 
-    @button('\N{BLACK LEFT-POINTING DOUBLE TRIANGLE WITH VERTICAL BAR}\ufe0f',
-            position=First(0), skip_if=_skip_double_triangle_buttons)
+
+class MenuPages(MenuPagesBase):
+    """A special type of Menu dedicated to pagination with reactions.
+
+    Attributes
+    ------------
+    current_page: :class:`int`
+        The current page that we are in. Zero-indexed
+        between [0, :attr:`PageSource.max_pages`).
+    """
+    def __init__(self, source, **kwargs):
+        super().__init__(source, **kwargs)
+
+    @button(MenuPagesBase.FIRST_PAGE, position=First(0), skip_if=MenuPagesBase._skip_double_triangle_buttons)
     async def go_to_first_page(self, payload):
         """go to the first page"""
         await self.show_page(0)
 
-    @button('\N{BLACK LEFT-POINTING TRIANGLE}\ufe0f', position=First(1))
+    @button(MenuPagesBase.PREVIOUS_PAGE, position=First(1))
     async def go_to_previous_page(self, payload):
         """go to the previous page"""
         await self.show_checked_page(self.current_page - 1)
 
-    @button('\N{BLACK RIGHT-POINTING TRIANGLE}\ufe0f', position=Last(0))
+    @button(MenuPagesBase.NEXT_PAGE, position=Last(0))
     async def go_to_next_page(self, payload):
         """go to the next page"""
         await self.show_checked_page(self.current_page + 1)
 
-    @button('\N{BLACK RIGHT-POINTING DOUBLE TRIANGLE WITH VERTICAL BAR}\ufe0f',
-            position=Last(1), skip_if=_skip_double_triangle_buttons)
+    @button(MenuPagesBase.LAST_PAGE, position=Last(1), skip_if=MenuPagesBase._skip_double_triangle_buttons)
     async def go_to_last_page(self, payload):
         """go to the last page"""
         # The call here is safe because it's guarded by skip_if
@@ -1011,6 +1087,80 @@ async def stop_pages(self, payload):
         self.stop()
 
 
+class MenuPaginationButton(nextcord.ui.Button['MenuPaginationButton']):
+    """
+    A custom button for pagination that will be disabled when unavailable.
+    """
+    def __init__(self, style: nextcord.ButtonStyle, emoji: Union[str, nextcord.Emoji, nextcord.PartialEmoji]):
+        super().__init__(style=style, emoji=emoji)
+        self._emoji = _cast_emoji(emoji)
+
+    async def callback(self, interaction: nextcord.Interaction):
+        """
+        Callback for when this button is pressed
+        """
+        assert self.view is not None
+        view: ButtonMenuPages = self.view
+
+        # change the current page
+        if self._emoji.name == view.FIRST_PAGE:
+            await view.show_page(0)
+        elif self._emoji.name == view.PREVIOUS_PAGE:
+            await view.show_checked_page(view.current_page - 1)
+        elif self._emoji.name == view.NEXT_PAGE:
+            await view.show_checked_page(view.current_page + 1)
+        elif self._emoji.name == view.LAST_PAGE:
+            await view.show_page(view._source.get_max_pages() - 1)
+        
+        # disable buttons that are unavailable
+        view._disable_unavailable_buttons()
+
+        # disable all buttons if stop is pressed
+        if self._emoji.name == view.STOP:
+            await view.disable()
+            view.stop()
+
+        # update the view
+        await interaction.response.edit_message(view=view)
+
+
+class ButtonMenuPages(MenuPagesBase):
+    """A special type of Menu dedicated to pagination with button components.
+
+    Parameters
+    -----------
+    style: :class:`nextcord.ui.ButtonStyle`
+        The button style to use for the pagination buttons.
+
+    Attributes
+    ------------
+    current_page: :class:`int`
+        The current page that we are in. Zero-indexed
+        between [0, :attr:`PageSource.max_pages`).
+    """
+    def __init__(self, source: PageSource, style: nextcord.ButtonStyle = nextcord.ButtonStyle.secondary, **kwargs):
+        super().__init__(source, **kwargs)
+        # add buttons to the view
+        for emoji in (self.FIRST_PAGE, self.PREVIOUS_PAGE, self.NEXT_PAGE, self.LAST_PAGE, self.STOP):
+            if emoji in (self.FIRST_PAGE, self.LAST_PAGE) and self._skip_double_triangle_buttons():
+                continue
+            self.add_item(MenuPaginationButton(style=style, emoji=emoji))
+        self._disable_unavailable_buttons()
+
+    def _disable_unavailable_buttons(self):
+        """
+        Disables buttons that are unavailable to be pressed.
+        """
+        buttons: List[MenuPaginationButton] = self.children
+        max_pages = self._source.get_max_pages()
+        for button in buttons:
+            if button.emoji.name in (self.FIRST_PAGE, self.PREVIOUS_PAGE):
+                button.disabled = self.current_page == 0
+            elif max_pages and button.emoji.name in (self.LAST_PAGE, self.NEXT_PAGE):
+                button.disabled = self.current_page == max_pages - 1
+
+
+
 class ListPageSource(PageSource):
     """A data source for a sequence of items.