RadioButtons: use a layout parameter instead of grid labels

doronbehar · doronbehar · commit 609da0cf225c · 2025-12-07T12:32:59.000+02:00
diff --git a/doc/release/next_whats_new/radio_buttons_2d_grid.rst b/doc/release/next_whats_new/radio_buttons_2d_grid.rst
@@ -1,16 +1,17 @@
-RadioButtons widget supports 2D grid layout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+RadioButtons widget supports flexible layouts
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The `.widgets.RadioButtons` widget now supports arranging buttons in a 2D grid
-layout. Pass a list of lists of strings as the *labels* parameter to arrange
-buttons in a grid where each inner list represents a row.
+The `.widgets.RadioButtons` widget now supports arranging buttons in different
+layouts via the new *layout* parameter. You can arrange buttons vertically
+(default), horizontally, or in a 2D grid by passing a ``(rows, cols)`` tuple.
 
 The *active* parameter and the ``RadioButtons.index_selected`` attribute
-continue to use a single integer index into the flattened array, reading
-left-to-right, top-to-bottom. The column positions are automatically calculated
-based on the maximum text width in each column, ensuring optimal spacing.
+continue to use a single integer index into the labels list. For grid layouts,
+buttons are positioned left-to-right, top-to-bottom. The column positions are
+automatically calculated based on the maximum text width in each column,
+ensuring optimal spacing.
 
-See :doc:`/gallery/widgets/radio_buttons_grid` for a complete example.
+See :doc:`/gallery/widgets/radio_buttons_grid` for a ``(rows, cols)`` example.
 
 .. plot::
     :include-source: true
@@ -23,23 +24,22 @@ See :doc:`/gallery/widgets/radio_buttons_grid` for a complete example.
     t = np.arange(0.0, 2.0, 0.01)
     s = np.sin(2*np.pi*t)
 
-    fig, (ax_plot, ax_buttons) = plt.subplots(1, 2, figsize=(8, 4),
-                                               width_ratios=[3, 1])
-
-    line, = ax_plot.plot(t, s, lw=2, color='red')
-    ax_plot.set_xlabel('Time (s)')
-    ax_plot.set_ylabel('Amplitude')
-
-    ax_buttons.set_facecolor('lightgray')
-    ax_buttons.set_title('Line Color', fontsize=12, pad=10)
-
-    colors = [
-        ['red', 'orange', 'yellow'],
-        ['green', 'blue', 'purple'],
-        ['brown', 'pink', 'gray'],
-    ]
-
-    radio = RadioButtons(ax_buttons, colors, active=0)
+    fig, axes = plt.subplot_mosaic(
+        [
+            ['main'],
+            ['.'],
+            ['buttons'],
+        ],
+        height_ratios=[8, 0.4, 1],
+    )
+
+    line, = axes['main'].plot(t, s, lw=2, color='red')
+    axes['main'].set_xlabel('Time (s)')
+    axes['main'].set_ylabel('Amplitude')
+
+    axes['buttons'].set_facecolor('lightgray')
+    colors = ['red', 'orange', 'yellow', 'green', 'blue', 'purple', 'brown', 'black']
+    radio = RadioButtons(axes['buttons'], colors, active=0, layout='horizontal')
 
     def color_func(label):
         line.set_color(label)
diff --git a/galleries/examples/widgets/radio_buttons_grid.py b/galleries/examples/widgets/radio_buttons_grid.py
@@ -5,8 +5,8 @@
 
 Using radio buttons in a 2D grid layout.
 
-Radio buttons can be arranged in a 2D grid by passing a list of lists of
-strings as the *labels* parameter. This is useful when you have multiple
+Radio buttons can be arranged in a 2D grid by passing a ``(rows, cols)``
+tuple to the *layout* parameter. This is useful when you have multiple
 related options that are best displayed in a grid format rather than a
 vertical list.
 
@@ -26,7 +26,7 @@
 fig, (ax_plot, ax_buttons) = plt.subplots(
     1, 2,
     figsize=(8, 4),
-    width_ratios=[4, 1],
+    width_ratios=[4, 1.4],
 )
 
 # Create initial plot
@@ -40,12 +40,8 @@
 ax_buttons.set_facecolor('lightgray')
 ax_buttons.set_title('Line Color', fontsize=12, pad=10)
 # Create a 2D grid of color options (3 rows x 2 columns)
-colors = [
-    ['red', 'yellow'],
-    ['green', 'purple'],
-    ['brown', 'gray'],
-]
-radio = RadioButtons(ax_buttons, colors, active=0)
+colors = ['red', 'yellow', 'green', 'purple', 'brown', 'gray']
+radio = RadioButtons(ax_buttons, colors, active=0, layout=(3, 2))
 
 def color_func(label):
     """Update the line color based on selected button."""
diff --git a/lib/matplotlib/widgets.py b/lib/matplotlib/widgets.py
@@ -1578,32 +1578,35 @@ class RadioButtons(AxesWidget):
     value_selected : str
         The label text of the currently selected button.
     index_selected : int
-        The index of the selected button in the flattened array. For 2D grids,
-        this is the index when reading left-to-right, top-to-bottom.
+        The index of the selected button.
     """
 
     def __init__(self, ax, labels, active=0, activecolor=None, *,
-                 useblit=True, label_props=None, radio_props=None):
+                 layout="vertical", useblit=True, label_props=None, radio_props=None):
         """
         Add radio buttons to an `~.axes.Axes`.
 
         Parameters
         ----------
         ax : `~matplotlib.axes.Axes`
             The Axes to add the buttons to.
-        labels : list of str or list of list of str
-            The button labels. If a list of strings, buttons are arranged
-            vertically. If a list of lists of strings, buttons are arranged
-            in a 2D grid where each inner list represents a row. For simple
-            horizontal radio buttons, use:
-            ``labels=[['button1', 'button2', 'button3']]``
+        labels : list of str
+            The button labels.
         active : int
-            The index of the initially selected button in the flattened array.
-            For 2D grids, this is the index when reading left-to-right,
-            top-to-bottom.
+            The index of the initially selected button.
         activecolor : :mpltype:`color`
             The color of the selected button. The default is ``'blue'`` if not
             specified here or in *radio_props*.
+        layout : {"vertical", "horizontal"} or (int, int), default: "vertical"
+            The layout of the radio buttons. Options are:
+
+            - ``"vertical"``: Arrange buttons in a single column (default).
+            - ``"horizontal"``: Arrange buttons in a single row.
+            - ``(rows, cols)`` tuple: Arrange buttons in a grid with the
+              specified number of rows and columns. Buttons are placed
+              left-to-right, top-to-bottom.
+
+            .. versionadded:: 3.11
         useblit : bool, default: True
             Use blitting for faster drawing if supported by the backend.
             See the tutorial :ref:`blitting` for details.
@@ -1613,8 +1616,8 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
         label_props : dict of lists, optional
             Dictionary of `.Text` properties to be used for the labels. Each
             dictionary value should be a list of at least a single element. If
-            the flat list of labels is of length M, its values are cycled such
-            that the Nth label gets the (N mod M) property.
+            the list is of length M, its values are cycled such that the Nth
+            label gets the (N mod M) property.
 
             .. versionadded:: 3.7
         radio_props : dict, optional
@@ -1634,13 +1637,33 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
         _api.check_isinstance((dict, None), label_props=label_props,
                               radio_props=radio_props)
 
-        # Check if labels is 2D (list of lists)
-        _is_2d = isinstance(labels[0], (list, tuple))
-
-        if _is_2d:
-            flat_labels = [item for row in labels for item in row]
+        labels = list(labels)
+        n_labels = len(labels)
+
+        bad_layout_raise_msg = \
+            "layout must be 'vertical', 'horizontal', or a (rows, cols) tuple; " \
+            f"got {layout!r}"
+        # Parse layout parameter
+        if isinstance(layout, str):
+            if layout == "vertical":
+                n_rows, n_cols = n_labels, 1
+            elif layout == "horizontal":
+                n_rows, n_cols = 1, n_labels
+            else:
+                raise ValueError(bad_layout_raise_msg)
+        elif isinstance(layout, tuple) and len(layout) == 2:
+            n_rows, n_cols = layout
+            if not (isinstance(n_rows, int) and isinstance(n_cols, int)):
+                raise TypeError(
+                    f"layout tuple must contain two integers; got {layout!r}"
+                )
+            if n_rows * n_cols < n_labels:
+                raise ValueError(
+                    f"layout {layout} has {n_rows * n_cols} positions but "
+                    f"{n_labels} labels were provided"
+                )
         else:
-            flat_labels = list(labels)
+            raise ValueError(bad_layout_raise_msg)
 
         radio_props = cbook.normalize_kwargs(radio_props,
                                              collections.PathCollection)
@@ -1655,7 +1678,7 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
 
         self._activecolor = activecolor
         self._initial_active = active
-        self.value_selected = flat_labels[active]
+        self.value_selected = labels[active]
         self.index_selected = active
 
         ax.set_xticks([])
@@ -1666,87 +1689,82 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
         self._background = None
 
         label_props = _expand_text_props(label_props)
-        # Calculate positions based on layout
-        text_x_offset = 0.10
-
-        if _is_2d:
-            n_rows = len(labels)
-            n_cols = max(len(row) for row in labels)
-            # Y positions with margins
-            y_margin = 0.05
-            y_spacing = (1 - 2 * y_margin) / max(1, n_rows - 1) if n_rows > 1 else 0
-
-            # Create temporary text objects to measure widths
-            flat_label_list = []
-            temp_texts = []
-            for i, row in enumerate(labels):
-                for j, label in enumerate(row):
-                    flat_label_list.append(label)
-            for label, props in zip(flat_label_list, label_props):
-                temp_texts.append(ax.text(
-                    0,
-                    0,
-                    label,
-                    transform=ax.transAxes,
-                    **props,
-                ))
-            # Force a draw to get accurate text measurements
-            ax.figure.canvas.draw()
-            # Calculate max text width per column (in axes coordinates)
-            col_widths = []
-            for col_idx in range(n_cols):
-                col_texts = []
-                for row_idx, row in enumerate(labels):
-                    if col_idx < len(row):
-                        col_texts.append(temp_texts[
-                            sum(len(labels[r]) for r in range(row_idx)) + col_idx
-                        ])
-                if col_texts:
-                    col_widths.append(
-                        max(
-                            text.get_window_extent(
-                                ax.figure.canvas.get_renderer()
-                            ).width
-                            for text in col_texts
-                        ) / ax.bbox.width
-                    )
-                else:
-                    col_widths.append(0)
-            # Remove temporary text objects
-            for text in temp_texts:
-                text.remove()
-            # Calculate x positions based on text widths
-            # TODO: Should these be arguments?
-            button_x_margin = 0.07  # Left margin for first button
-            col_spacing = 0.07  # Space between columns
-
-            col_x_positions = [button_x_margin]  # First column starts at left margin
-            for col_idx in range(n_cols - 1):
-                col_x_positions.append(sum([
-                    col_x_positions[-1],
-                    text_x_offset,
-                    col_widths[col_idx],
-                    col_spacing
-                ]))
-            # Create final positions
-            positions = []
-            for i, row in enumerate(labels):
-                y = 1 - y_margin - i * y_spacing
-                for j, label in enumerate(row):
-                    x = col_x_positions[j]
-                    positions.append((x, y))
-            xs = [pos[0] for pos in positions]
-            ys = [pos[1] for pos in positions]
-        else:
-            ys = np.linspace(1, 0, len(flat_labels) + 2)[1:-1]
-            xs = [0.15] * len(ys)
-            flat_label_list = flat_labels
+
+        # Define spacing in display units (pixels) for consistency
+        # across different axes sizes
+        axes_width_display = ax.bbox.width
+        left_margin_display = 15  # pixels
+        button_text_offset_display = 6.5  # pixels
+        col_spacing_display = 15  # pixels
+
+        # Convert to axes coordinates
+        left_margin = left_margin_display / axes_width_display
+        button_text_offset = button_text_offset_display / axes_width_display
+        col_spacing = col_spacing_display / axes_width_display
+
+        # Create temporary text objects to measure widths
+        temp_texts = []
+        for label, props in zip(labels, label_props):
+            temp_texts.append(ax.text(
+                0,
+                0,
+                label,
+                transform=ax.transAxes,
+                **props,
+            ))
+        # Force a draw to get accurate text measurements
+        ax.figure.canvas.draw()
+
+        # Calculate max text width per column (in axes coordinates)
+        col_widths = []
+        for col_idx in range(n_cols):
+            col_texts = []
+            for row_idx in range(n_rows):
+                label_idx = row_idx * n_cols + col_idx
+                if label_idx < n_labels:
+                    col_texts.append(temp_texts[label_idx])
+            if col_texts:
+                col_widths.append(
+                    max(
+                        text.get_window_extent(
+                            ax.figure.canvas.get_renderer()
+                        ).width
+                        for text in col_texts
+                    ) / axes_width_display
+                )
+            else:
+                col_widths.append(0)
+        # Remove temporary text objects
+        for text in temp_texts:
+            text.remove()
+
+        # Center rows vertically in the axes
+        ys_per_row = np.linspace(1, 0, n_rows + 2)[1:-1]
+        # Calculate x positions based on text widths
+        col_x_positions = [left_margin]  # First column starts at left margin
+        for col_idx in range(n_cols - 1):
+            col_x_positions.append(
+                col_x_positions[-1] +
+                button_text_offset +
+                col_widths[col_idx] +
+                col_spacing
+            )
+        # Create final positions (left-to-right, top-to-bottom)
+        xs = []
+        ys = []
+        for label_idx in range(n_labels):
+            row_idx = label_idx // n_cols
+            col_idx = label_idx % n_cols
+            x = col_x_positions[col_idx]
+            y = ys_per_row[row_idx]
+            xs.append(x)
+            ys.append(y)
 
         self.labels = [
-            ax.text(x + text_x_offset, y, label, transform=ax.transAxes,
+            ax.text(x + button_text_offset, y, label, transform=ax.transAxes,
                     horizontalalignment="left", verticalalignment="center",
                     **props)
-            for x, y, label, props in zip(xs, ys, flat_label_list, label_props)]
+            for x, y, label, props in zip(xs, ys, labels, label_props)]
         text_size = np.array([text.get_fontsize() for text in self.labels]) / 2
 
         radio_props = {
@@ -1765,7 +1783,7 @@ def __init__(self, ax, labels, active=0, activecolor=None, *,
         # the user set.
         self._active_colors = self._buttons.get_facecolor()
         if len(self._active_colors) == 1:
-            self._active_colors = np.repeat(self._active_colors, len(flat_labels),
+            self._active_colors = np.repeat(self._active_colors, n_labels,
                                             axis=0)
         self._buttons.set_facecolor(
             [activecolor if i == active else "none"
diff --git a/lib/matplotlib/widgets.pyi b/lib/matplotlib/widgets.pyi
@@ -206,10 +206,11 @@ class RadioButtons(AxesWidget):
     def __init__(
         self,
         ax: Axes,
-        labels: Iterable[str] | Iterable[Iterable[str]],
+        labels: Iterable[str],
         active: int = ...,
         activecolor: ColorType | None = ...,
         *,
+        layout: Literal["vertical", "horizontal"] | tuple[int, int] = ...,
         useblit: bool = ...,
         label_props: dict[str, Sequence[Any]] | None = ...,
         radio_props: dict[str, Any] | None = ...,
