Show reserved toolbar truncation and clip lines without wrapping

Author: tleonhardt

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## 4.3.0 (TBD)
 
+- Bug Fixes
+    - Reserved bottom toolbars now indicate clipped content with a right-edge ellipsis (`…`). Long
+      lines are truncated without wrapping, and newlines beyond the reserved row are indicated
+      instead of silently hiding content, including when the first line is empty.
+
 - Breaking Changes
     - Replaced `enable_bottom_toolbar` with `bottom_toolbar_mode` in `Cmd.__init__()`. The default,
       `cmd2.ToolbarMode.OFF`, disables the toolbar. Use `cmd2.ToolbarMode.AUTO` where you previously

cmd2/cmd2.py

@@ -2132,6 +2132,10 @@ def get_bottom_toolbar(self) -> AnyFormattedText:
         your application. This could be information like the application name, current state,
         or even a real-time clock.
 
+        Reserved rendering uses one row and clips each logical line without wrapping. An
+        ellipsis in the rightmost column indicates omitted text or lines after a newline.
+        Widths are measured in terminal columns; wide characters are never split.
+
         During command execution this callback runs in a background UI thread. Protect shared
         state with a lock when necessary. The built-in pager shares this toolbar. It is suspended
         while another prompt, external pager, or interactive shell owns the terminal.

cmd2/toolbar_painter.py

@@ -21,6 +21,9 @@
 mouse map, so a handler here would never be called; rendering the visible part is the honest
 subset rather than advertising support that does not exist.
 
+**Lines are clipped with an ellipsis.** Newlines advance to the next reserved row;
+horizontal overflow never wraps. Omitted columns or rows are indicated at the right edge.
+
 **Carriage returns are dropped and tabs are expanded.** Both are cursor motion in a context
 where the painter owns the cursor.
 """
@@ -104,8 +107,9 @@ def build(
 
         Content that does not fill the frame is padded with default-styled spaces: the pad is
         what overwrites a longer previous frame, so it is content rather than absence of it.
-        Content taller than the band is truncated here -- growing the toolbar is a geometry
-        transition, and writing the extra rows would put them outside the reservation.
+        Each logical line is clipped to the terminal width without wrapping. A right-edge
+        ellipsis marks omitted columns, or omitted lines on the last reserved row. Growing
+        the toolbar is a geometry transition, never a consequence of content overflow.
 
         :param content: the formatted text to lay out
         :param width: the terminal width in columns
@@ -120,6 +124,8 @@ def build(
             raise ValueError(f"a frame needs a positive height, got {height}")
 
         rows = _layout(content, width, default_style)
+        if len(rows) > height:
+            _mark_truncated(rows[height - 1], default_style)
         blank = tuple(Cell(" ", default_style) for _ in range(width))
         while len(rows) < height:
             rows.append(list(blank))
@@ -129,9 +135,9 @@ def build(
 def measure_toolbar_height(content: "AnyFormattedText", width: int) -> int:
     """Measure how many rows content needs at a given width.
 
-    This is what sizes the reservation, so it counts wrapping and explicit newlines the same
-    way :meth:`ToolbarFrame.build` lays them out. Empty content still measures one row: an
-    empty toolbar is an intentional visibility change, not a request for no reservation.
+    Only explicit newlines add rows; horizontal overflow is clipped, as in
+    :meth:`ToolbarFrame.build`. Empty content still measures one row. This helper does not
+    change the reservation, whose height is chosen by its owner.
 
     :param content: the formatted text to measure
     :param width: the terminal width in columns
@@ -143,22 +149,38 @@ def measure_toolbar_height(content: "AnyFormattedText", width: int) -> int:
     return max(1, len(_layout(content, width, "")))
 
 
+def _mark_truncated(row: list[Cell], default_style: str) -> None:
+    """Mark omitted content in the rightmost column without splitting a wide character.
+
+    :param row: a padded, nonempty row to modify
+    :param default_style: the style for the indicator and any cleared wide-character cell
+    """
+    if row[-1].is_continuation:
+        row[-2] = Cell(" ", default_style)
+    row[-1] = Cell("…", default_style)
+
+
 def _layout(content: "AnyFormattedText", width: int, default_style: str) -> list[list[Cell]]:
-    """Lay content out into as many full-width rows as it needs.
+    """Clip each logical line to one padded row, marking horizontal overflow.
 
     :param content: the formatted text to lay out
     :param width: the terminal width in columns
-    :param default_style: the style for padding cells
+    :param default_style: the style for padding and truncation indicators
     :return: the rows, each padded to ``width`` cells
     """
     rows: list[list[Cell]] = []
     row: list[Cell] = []
+    clipped = False
 
     def finish_row() -> None:
-        """Pad the row in progress and start a new one."""
+        """Pad and mark the row in progress, then start the next logical line."""
+        nonlocal clipped
         row.extend(Cell(" ", default_style) for _ in range(width - len(row)))
+        if clipped:
+            _mark_truncated(row, default_style)
         rows.append(list(row))
         row.clear()
+        clipped = False
 
     for fragment in to_formatted_text(content):
         style, text = fragment[0], fragment[1]
@@ -168,24 +190,19 @@ def finish_row() -> None:
             if char == "\n":
                 finish_row()
                 continue
-            if char == "\r":
+            if char == "\r" or clipped:
                 continue
             if char == "\t":
                 spaces = TAB_WIDTH - (len(row) % TAB_WIDTH)
-                for _ in range(spaces):
-                    if len(row) == width:
-                        finish_row()
-                    row.append(Cell(" ", style))
+                available = width - len(row)
+                row.extend(Cell(" ", style) for _ in range(min(spaces, available)))
+                clipped = spaces > available
                 continue
 
             char_width = get_cwidth(char)
             if char_width == 0 and row:
-                # A combining mark belongs to the character it follows; it occupies no column
-                # of its own, so it joins that cell rather than becoming one. After a wide
-                # character the cell to the left is that character's right half, and the mark
-                # belongs to the half that carries the text -- attaching it to the
-                # continuation cell would give the mark a column of its own and shift every
-                # later cell one place right of where it is on the screen.
+                # Combining marks still belong to a retained character at the right edge.
+                # Once a character is clipped, its marks must be discarded with it.
                 base = len(row) - 1
                 if row[base].is_continuation:
                     base -= 1
@@ -194,16 +211,14 @@ def finish_row() -> None:
                 continue
             columns = max(1, char_width)
             if len(row) + columns > width:
-                # Padding rather than splitting: half a wide character at the right edge is
-                # what makes the terminal wrap the row itself, which would put toolbar cells
-                # in a row the frame does not own.
-                finish_row()
+                clipped = True
+                continue
             row.append(Cell(char, style))
             if columns == 2:
                 row.append(Cell("", style, is_continuation=True))
 
-    if row:
-        finish_row()
+    # An empty string is one empty line; a trailing newline introduces another one.
+    finish_row()
     return rows
 
 

docs/features/prompt.md

@@ -96,6 +96,24 @@ def get_bottom_toolbar(self) -> AnyFormattedText:
     ]
 ```
 
+### Reserved Toolbar Overflow
+
+Reserved rendering currently reserves one terminal row. Each logical line is clipped to the terminal
+width; long lines do not wrap. A newline starts another logical line, which is omitted when there is
+no reserved row available. A leading newline therefore leaves an empty first line.
+
+Whenever content is omitted, an ellipsis (`…`) appears in the rightmost column of the affected row.
+Omitted lines are indicated on the last reserved row. The indicator uses the toolbar's default
+style. For example, at a width of eight columns, `abcdefgh` fits unchanged, `abcdefghi` becomes
+`abcdefg…`, and `Ready\nDetails` becomes `Ready  …`. A leading newline displays spaces followed by
+`…`, rather than a completely blank toolbar.
+
+Widths are measured in terminal display columns, including wide and combining characters. Truncation
+never splits a wide character; it may leave a space before the ellipsis. Tabs expand to eight-column
+tab stops, and carriage returns are ignored. These rules apply to `RESERVED` and to `AUTO` when it
+selects reserved rendering. `LEGACY` retains prompt-toolkit's layout. The number of reserved rows is
+not yet configurable through `Cmd`.
+
 ### Refreshing the Toolbar
 
 The toolbar is rendered by `prompt-toolkit` and is naturally redrawn whenever the prompt is

tests/test_reserved_terminal.py

@@ -72,7 +72,7 @@ def terminal_harness(request):
         harness.close()
 
 
-def read_prompt(harness, terminal) -> None:
+def read_prompt(harness, terminal, expected_toolbar="STATUS") -> None:
     """Use the real input reader and CPR binding, then accept a prompt with known height."""
     ui = harness.app.main_session.app
     sent = False
@@ -92,13 +92,39 @@ def ready(app):
         assert sent
         assert terminal.reports
         assert all(row < terminal.screen.lines for row in terminal.reports)
-        assert terminal.screen.display[-1].startswith("STATUS")
+        assert terminal.screen.display[-1].startswith(expected_toolbar)
     finally:
         watchdog.cancel()
         watchdog.join()
         ui.after_render -= ready
 
 
+@pytest.mark.parametrize(
+    ("content", "expected"),
+    [
+        ("STATUS\nsecond line", "STATUS" + " " * 73 + "…"),
+        ("\nSTATUS", " " * 79 + "…"),
+        ("S" * 81, "S" * 79 + "…"),
+        ("S" * 78 + "广x", "S" * 78 + " …"),
+    ],
+)
+def test_clipped_toolbar_survives_commands_and_prompt_refresh(terminal_harness, content, expected) -> None:
+    harness, terminal = terminal_harness
+    harness.app.main_session.bottom_toolbar = content
+    with harness.app._reserved_toolbar_context():
+        assert terminal.screen.display[-1] == expected
+        with harness.app._command_toolbar_context():
+            harness.app.poutput("ordinary output")
+        assert terminal.screen.display[-1] == expected
+        read_prompt(harness, terminal, expected_toolbar=expected)
+        # A shorter dynamic replacement must remove the old text and indicator.
+        harness.app.main_session.bottom_toolbar = "OK"
+        assert harness.app.reserved_toolbar.refresh()
+        assert terminal.screen.display[-1] == "OK" + " " * 78
+    assert terminal.screen.margins is None
+    assert terminal.screen.display[-1].strip() == ""
+
+
 @pytest.mark.parametrize("row", [1, 22, 23, 24])
 @pytest.mark.parametrize("reserved", [1, 2])
 def test_acquisition_keeps_existing_output_and_cursor_above_the_band(terminal_harness, row, reserved) -> None:

tests/test_toolbar_painter.py

@@ -34,6 +34,29 @@ def styles_of(frame: ToolbarFrame, row: int = 0) -> list[str]:
 
 
 class TestShape:
+    @pytest.mark.parametrize(
+        ("content", "width", "height", "expected"),
+        [
+            ("\nSTATUS", 8, 1, ["       …"]),
+            ("STATUS\nnext", 8, 1, ["STATUS …"]),
+            ("abcd", 4, 1, ["abcd"]),
+            ("abcde", 4, 1, ["abc…"]),
+            ("abcdef\nxy", 4, 2, ["abc…", "xy  "]),
+            ("a\nb\nc\nd", 4, 3, ["a   ", "b   ", "c  …"]),
+            ("abc\n", 4, 1, ["abc…"]),
+            ("广", 1, 1, ["…"]),
+            ("a广x", 3, 1, ["a …"]),
+            ("e\u0301abc", 3, 1, ["e\u0301a…"]),
+            ("abx\u0301", 3, 1, ["abx\u0301"]),
+            ("abcde\u0301\nz", 4, 2, ["abc…", "z   "]),
+            ("\tX\ny", 4, 2, ["   …", "y   "]),
+        ],
+    )
+    def test_truncation_is_visible_and_does_not_wrap(self, content, width, height, expected) -> None:
+        frame = ToolbarFrame.build(content, width=width, height=height)
+        assert [text_of(frame, row) for row in range(height)] == expected
+        assert all(len(row) == width for row in frame.rows)
+
     def test_a_frame_is_always_exactly_its_declared_size(self) -> None:
         frame = ToolbarFrame.build("hi", width=10, height=2)
         assert len(frame.rows) == 2
@@ -45,16 +68,16 @@ def test_short_content_is_padded_with_default_style_spaces(self) -> None:
         assert text_of(frame) == "hi   "
         assert styles_of(frame) == ["class:toolbar"] * 5
 
-    def test_content_wider_than_the_terminal_wraps(self) -> None:
+    def test_content_wider_than_the_terminal_is_clipped(self) -> None:
         frame = ToolbarFrame.build("abcdef", width=3, height=2)
-        assert text_of(frame, 0) == "abc"
-        assert text_of(frame, 1) == "def"
+        assert text_of(frame, 0) == "ab…"
+        assert text_of(frame, 1) == "   "
 
     def test_content_taller_than_the_band_is_truncated(self) -> None:
         """Growing past the band is a geometry transition, never a write outside it."""
         frame = ToolbarFrame.build("one\ntwo\nthree", width=10, height=2)
         assert text_of(frame, 0) == "one       "
-        assert text_of(frame, 1) == "two       "
+        assert text_of(frame, 1) == "two      …"
 
     def test_an_explicit_newline_starts_a_row(self) -> None:
         frame = ToolbarFrame.build("a\nb", width=3, height=2)
@@ -105,10 +128,10 @@ def test_a_wide_character_occupies_two_cells(self) -> None:
     def test_a_wide_character_is_never_split_at_the_right_edge(self) -> None:
         """Half a wide character at the edge is what wraps a row into the one below it."""
         frame = ToolbarFrame.build("a广", width=2, height=2)
-        assert text_of(frame, 0) == "a "
-        assert frame.rows[1][0].char == "广"
+        assert text_of(frame, 0) == "a…"
+        assert text_of(frame, 1) == "  "
 
-    def test_the_pad_before_a_wrapped_wide_character_uses_the_default_style(self) -> None:
+    def test_the_truncation_indicator_uses_the_default_style(self) -> None:
         frame = ToolbarFrame.build([("bold", "a广")], width=2, height=2, default_style="base")
         assert styles_of(frame, 0) == ["bold", "base"]
 
@@ -137,8 +160,8 @@ class TestMeasurement:
     def test_a_short_toolbar_is_one_row(self) -> None:
         assert measure_toolbar_height("hi", width=10) == 1
 
-    def test_wrapping_is_counted(self) -> None:
-        assert measure_toolbar_height("abcdef", width=3) == 2
+    def test_horizontal_overflow_does_not_add_rows(self) -> None:
+        assert measure_toolbar_height("abcdef", width=3) == 1
 
     def test_newlines_are_counted(self) -> None:
         assert measure_toolbar_height("a\nb\nc", width=10) == 3
@@ -148,10 +171,10 @@ def test_empty_content_still_measures_one_row(self) -> None:
         assert measure_toolbar_height("", width=10) == 1
 
     def test_measurement_matches_the_frame_it_would_build(self) -> None:
-        content = [("bold", "wide 广 content that wraps around")]
+        content = [("bold", "wide 广 content that is clipped\nlast row")]
         height = measure_toolbar_height(content, width=12)
         frame = ToolbarFrame.build(content, width=12, height=height)
-        # Nothing was truncated: the last row is where the content ended.
+        # Horizontal clipping does not move content onto the last logical line.
         assert measure_toolbar_height(content, width=12) == len(frame.rows)
         assert text_of(frame, height - 1).strip() != ""
 
@@ -181,12 +204,12 @@ def test_a_frame_reports_its_own_size(self) -> None:
     def test_an_empty_frame_reports_zero_width(self) -> None:
         assert ToolbarFrame(rows=()).width == 0
 
-    def test_a_tab_wraps_when_it_reaches_the_edge(self) -> None:
-        """The expansion is cells, so it wraps like any other run of them."""
+    def test_a_tab_is_clipped_when_it_reaches_the_edge(self) -> None:
+        """Tab expansion cannot spill into the next reserved row."""
         frame = ToolbarFrame.build("a\tb", width=4, height=3)
-        assert text_of(frame, 0) == "a   "
+        assert text_of(frame, 0) == "a  …"
         assert text_of(frame, 1) == "    "
-        assert text_of(frame, 2) == "b   "
+        assert text_of(frame, 2) == "    "
 
     def test_a_combining_mark_after_a_wide_character_joins_that_character(self) -> None:
         """Attaching it to the continuation cell instead shifts every later column."""