Added feature requested in issue #113

Added missing documentation.

Fixed one occurence not using _get_max_item_count().

Author: Ayuto

addons/source-python/packages/source-python/menus/__init__.py

@@ -16,18 +16,26 @@
 
     from menus.esc import SimpleESCMenu as SimpleMenu
     from menus.esc import SimpleESCOption as SimpleOption
+
+    from menus.esc import ListESCMenu as ListMenu
+    from menus.esc import ListESCOption as ListOption
 else:
     from menus.radio import PagedRadioMenu as PagedMenu
     from menus.radio import PagedRadioOption as PagedOption
 
     from menus.radio import SimpleRadioMenu as SimpleMenu
     from menus.radio import SimpleRadioOption as SimpleOption
 
+    from menus.radio import ListRadioMenu as ListMenu
+    from menus.radio import ListRadioOption as ListOption
+
 
 # =============================================================================
 # >> ALL DECLARATION
 # =============================================================================
-__all__ = ('PagedMenu',
+__all__ = ('ListMenu',
+           'ListOption',
+           'PagedMenu',
            'PagedOption',
            'SimpleMenu',
            'SimpleOption',

addons/source-python/packages/source-python/menus/esc.py

@@ -178,6 +178,8 @@ def __init__(
         :param Color title_color: See :meth:`SimpleESCMenu.__init__`.
         :param bool fill: If True the menu will always have the same size by
             filling unused options.
+        :param _BaseMenu parent_menu: A menu that will be displayed when
+            hitting 'Back' on the first page.
         """
         super().__init__(
             data, select_callback, build_callback,
@@ -227,7 +229,7 @@ def _format_body(self, player_index, page, data):
         # Fill the rest of the menu with empty options
         if self.fill:
             option_num = len(page.options)
-            for index in range(5 - option_num):
+            for index in range(self._get_max_item_count() - option_num):
                 index += option_num + 1
                 button = data.find_key(str(index), True)
                 button.set_string('msg', '')
@@ -301,6 +303,38 @@ def _select(self, player_index, choice_index):
         return super()._select(player_index, choice_index)
 
 
+class ListESCMenu(PagedESCMenu):
+    """Creates a list-like ESC menu.
+
+    Navigation options are added automatically."""
+
+    def __init__(
+            self, data=None, select_callback=None, build_callback=None,
+            description=None, title=None, title_color=WHITE, fill=True,
+            parent_menu=None, items_per_page=5):
+        """Initialize the object.
+
+        :param iterable|None data: See :meth:`menus.base._BaseMenu.__init__`.
+        :param callable|None select_callback: See
+            :meth:`menus.base._BaseMenu.__init__`.
+        :param callable|None build_callback: See
+            :meth:`menus.base._BaseMenu.__init__`.
+        :param str|None description: See :meth:`SimpleESCMenu.__init__`.
+        :param str|None title: See :meth:`SimpleESCMenu.__init__`.
+        :param Color title_color: See :meth:`SimpleESCMenu.__init__`.
+        :param bool fill: See :meth:`PagedESCMenu.__init__`.
+        :param _BaseMenu parent_menu: See :meth:`PagedESCMenu.__init__`.
+        :param int items_per_page: Number of options that should be displayed
+            on a single page (5 is the maximum).
+        """
+        super().__init__(data, select_callback, build_callback, description,
+            title, title_color, fill, parent_menu)
+        self.items_per_page = items_per_page
+
+    def _get_max_item_count(self):
+        return self.items_per_page
+
+
 class SimpleESCOption(_BaseOption):
     """Provides options for :class:`SimpleESCMenu` objects."""
 
@@ -332,3 +366,25 @@ def _render(self, player_index, choice_index=None):
         """See :meth:`menus.base._MenuData._render`."""
         return '{0}. {1}'.format(
             choice_index, _translate_text(self.text, player_index))
+
+
+class ListESCOption(PagedESCOption):
+    """Provides options for :class:`ListESCMenu` objects."""
+
+    def __init__(self, text, highlight=True, enumerated=True):
+        """Initialize the option.
+
+        :param str text: See :meth:`menus.base._BaseOption.__init__`.
+        :param bool hightlight: See :meth:`SimpleESCMenu.__init__`.
+        :param bool enumerated: If True the number of the option will be added
+            in front of the text.
+        """
+        super().__init__(text, None, highlight, False)
+        self.enumerated = enumerated
+
+    def _render(self, player_index, choice_index=None):
+        """See :meth:`menus.base._MenuData._render`."""
+        if self.enumerated:
+            return super()._render(player_index, choice_index)
+
+        return _translate_text(self.text, player_index)

addons/source-python/packages/source-python/menus/radio.py

@@ -157,6 +157,8 @@ def __init__(
             the body.
         :param bool fill: If True the menu will be filled so that it will
             always have the same  size.
+        :param _BaseMenu parent_menu: A menu that will be displayed when
+            hitting 'Back' on the first page.
         """
         super().__init__(data, select_callback, build_callback)
 
@@ -311,6 +313,40 @@ def _select(self, player_index, choice_index):
         return super()._select(player_index, choice_index)
 
 
+class ListRadioMenu(PagedRadioMenu):
+    """Creates a list-like radio menu.
+
+    Navigation options are added automatically."""
+
+    def __init__(
+            self, data=None, select_callback=None, build_callback=None,
+            description=None, title=None, top_separator='-' * 30,
+            bottom_separator='-' * 30, fill=True, parent_menu=None,
+            items_per_page=10):
+        """Initialize the object.
+
+        :param iterable|None data: See :meth:`menus.base._BaseMenu.__init__`.
+        :param callable|None select_callback: See
+            :meth:`menus.base._BaseMenu.__init__`.
+        :param callable|None build_callback: See
+            :meth:`menus.base._BaseMenu.__init__`.
+        :param str|None description: See :meth:`PagedRadioMenu.__init__`.
+        :param str|None title: See :meth:`PagedRadioMenu.__init__`.
+        :param str top_separator: See :meth:`PagedRadioMenu.__init__`.
+        :param str bottom_separator: See :meth:`PagedRadioMenu.__init__`.
+        :param bool fill: See :meth:`PagedRadioMenu.__init__`.
+        :param _BaseMenu parent_menu: See :meth:`PagedRadioMenu.__init__`.
+        :param int items_per_page: Number of options that should be displayed
+            on a single page.
+        """
+        super().__init__(data, select_callback, build_callback, description,
+            title, top_separator, bottom_separator, fill, parent_menu)
+        self.items_per_page = items_per_page
+
+    def _get_max_item_count(self):
+        return self.items_per_page
+
+
 class _BaseRadioOption(_BaseOption):
     """Base class for radio options."""
 
@@ -359,3 +395,28 @@ def _render(self, player_index, choice_index):
             choice_index,
             _translate_text(self.text, player_index)
         )
+
+
+class ListRadioOption(PagedRadioOption):
+    """Provides options for :class:`ListRadioMenu` objects."""
+
+    def __init__(self, text, highlight=True, enumerated=True):
+        """Initialize the option.
+
+        :param str text: See :meth:`menus.base._BaseOption.__init__`.
+        :param bool hightlight: If True the text will be highlighted.
+        :param bool enumerated: If True the number of the option will be added
+            in front of the text.
+
+        .. note:: ``highlight`` only works if ``enumerated`` is set to True.
+        """
+        super().__init__(text, None, highlight, False)
+        self.enumerated = enumerated
+
+    def _render(self, player_index, choice_index):
+        """See :meth:`menus.base._MenuData._render`."""
+        if self.enumerated:
+            return super()._render(player_index, choice_index)
+
+        return '{}{}\n'.format(self._get_highlight_prefix(),
+            _translate_text(self.text, player_index))