From f8a7e299b03365a5526f787f7e5504cd09ec83e0 Mon Sep 17 00:00:00 2001
From: Greg Ercolano <erco@seriss.com>
Date: Fri, 9 May 2025 09:29:10 -0700
Subject: Fl_Terminal doc fixes, private->protected for utf8_char_at_*()

---
 FL/Fl_Terminal.H                  |  2 ++
 documentation/src/Fl_Terminal.dox |  8 +++---
 src/Fl_Terminal.cxx               | 59 ++++++++++++++++++++++++++++++---------
 3 files changed, 52 insertions(+), 17 deletions(-)

diff --git a/FL/Fl_Terminal.H b/FL/Fl_Terminal.H
index 6ab67be29..7752ece28 100644
--- a/FL/Fl_Terminal.H
+++ b/FL/Fl_Terminal.H
@@ -1012,8 +1012,10 @@ private:
   void display_modified(void);
   void display_modified_clear(void);
   void clear_char_at_disp(int drow, int dcol);
+protected:
   const Utf8Char* utf8_char_at_disp(int drow, int dcol) const;
   const Utf8Char* utf8_char_at_glob(int grow, int gcol) const;
+private:
   void repeat_char(char c, int rep);
   void utf8_cache_clear(void);
   void utf8_cache_flush(void);
diff --git a/documentation/src/Fl_Terminal.dox b/documentation/src/Fl_Terminal.dox
index 01ba6fafb..92460f067 100644
--- a/documentation/src/Fl_Terminal.dox
+++ b/documentation/src/Fl_Terminal.dox
@@ -194,10 +194,10 @@ into the history, all without moving memory around.
 In fact the only time screen memory is moved around is during these infrequent
 operations:
 
-- during scrolling "down"
-- character insert/delete operations within a line
-- changing the display size
-- changing the history size
+- during "scroll down" escape sequences, e.g. ESC[\#T
+- character insert/delete operations within a line, e.g. ESC[\#@, ESC[\#P
+- changing the display size e.g. Fl_Terminal::resize()
+- changing the history size e.g. Fl_Terminal::history_lines()
 
 So a class "RingBuffer" is defined to manage the ring, and accessing its various
 parts, either as the entire entity ring, just the history, or just the display.
diff --git a/src/Fl_Terminal.cxx b/src/Fl_Terminal.cxx
index f68668b1e..74aa02161 100644
--- a/src/Fl_Terminal.cxx
+++ b/src/Fl_Terminal.cxx
@@ -911,8 +911,8 @@ void Fl_Terminal::RingBuffer::scroll(int rows, const CharStyle& style) {
 //
 // Example:
 //   // Walk ALL rows in the ring buffer..
-//   for (int row=0; row<ring.rows(); row++) {
-//     Utf8Char *u8c = ring.u8c_ring_row(row);
+//   for (int row=0; row<ring_rows(); row++) {
+//     Utf8Char *u8c = u8c_ring_row(row);
 //     ..
 //   }
 //
@@ -925,7 +925,7 @@ const Fl_Terminal::Utf8Char* Fl_Terminal::RingBuffer::u8c_ring_row(int row) cons
 // Return UTF-8 char for beginning of 'row' in the history buffer.
 //   Example:
 //     // Walk ALL rows in history..
-//     for (int hrow=0; hrow<ring.hrows(); hrow++) {
+//     for (int hrow=0; hrow<hist_rows(); hrow++) {
 //       Utf8Char *u8c = u8c_hist_row(hrow);
 //       ..
 //     }
@@ -940,7 +940,7 @@ const Fl_Terminal::Utf8Char* Fl_Terminal::RingBuffer::u8c_hist_row(int hrow) con
 // Special case to walk the "in use" rows of the history
 //   Example:
 //     // Walk the "in use" rows of history..
-//     for (int hrow=0; hrow<ring.hist_use(); hrow++) {
+//     for (int hrow=0; hrow<hist_use(); hrow++) {
 //       Utf8Char *u8c = u8c_hist_use_row(hrow);
 //       ..
 //     }
@@ -957,7 +957,7 @@ const Fl_Terminal::Utf8Char* Fl_Terminal::RingBuffer::u8c_hist_use_row(int hurow
 // Return UTF-8 char for beginning of 'row' in the display buffer
 //   Example:
 //     // Walk ALL rows in display..
-//     for (int drow=0; drow<ring.drows(); drow++) {
+//     for (int drow=0; drow<disp_rows(); drow++) {
 //         Utf8Char *u8c = u8c_disp_row(drow);
 //         ..
 //     }
@@ -975,8 +975,8 @@ const Fl_Terminal::Utf8Char* Fl_Terminal::RingBuffer::u8c_disp_row(int drow) con
 // Scrolling offset is NOT applied; this is raw access to the ring's rows.
 // Example:
 //   // Walk ALL rows in the ring buffer..
-//   for (int row=0; row<ring.rows(); row++) {
-//     Utf8Char *u8c = ring.u8c_ring_row(row);
+//   for (int row=0; row<ring_rows(); row++) {
+//     Utf8Char *u8c = u8c_ring_row(row);
 //     ..
 //   }
 //
@@ -992,7 +992,7 @@ Fl_Terminal::Utf8Char* Fl_Terminal::RingBuffer::u8c_hist_use_row(int hurow)
 // Return UTF-8 char for beginning of 'row' in the display buffer
 // Example:
 //   // Walk ALL rows in display..
-//   for (int drow=0; drow<ring.drows(); drow++) {
+//   for (int drow=0; drow<disp_rows(); drow++) {
 //     Utf8Char *u8c = u8c_disp_row(drow);
 //     ..
 //   }
@@ -1081,10 +1081,15 @@ const Fl_Terminal::Utf8Char* Fl_Terminal::u8c_disp_row(int drow) const
 
   Example:
   \code
-  // Walk ALL rows and cols in the ring buffer..
-  for (int row=0; row<ring.rows(); row++) {
-      Utf8Char *u8c = ring.u8c_ring_row(row);
-      for (int col=0; col<ring.cols(); col++,u8c++) {
+  // Walk ALL rows and cols in the raw ring buffer..
+  //    These will not necessarily be in order as they appear
+  //    on-screen.
+  //    For walking the terminal lines in order, see examples
+  //    for u8c_hist_use_row() and u8c_disp_row().
+  //
+  for (int row=0; row<ring_rows(); row++) {
+      Utf8Char *u8c = u8c_ring_row(row);
+      for (int col=0; col<ring_cols(); col++,u8c++) {
           ..make use of u8c->xxx() methods..
       }
   }
@@ -1111,6 +1116,19 @@ Fl_Terminal::Utf8Char* Fl_Terminal::u8c_hist_row(int hrow)
   aren't many (or any) rows in the history buffer that have been
   populated with scrollback text yet.
 
+  Example to walk all "in use" lines of the history buffer:
+  \code
+  // Walk the entire screen history ("in use") and display to stdout
+  for (int row=0; row<hist_use(); row++) {
+      const Utf8Char *u8c = u8c_hist_use_row(row);            // first char in row
+      for (int col=0; col<=hist_cols(); col++,u8c++) {        // walk columns left-to-right
+          // ..Do things here with each u8c char..
+          ::printf("%.*s", u8c->length(), u8c->text_utf8());  // show each utf8 char to stdout
+      }
+      ::printf("\n"); // end of each line
+  }
+  \endcode
+
   \see u8c_disp_row(int) for example use.
 */
 Fl_Terminal::Utf8Char* Fl_Terminal::u8c_hist_use_row(int hurow)
@@ -1130,6 +1148,21 @@ Fl_Terminal::Utf8Char* Fl_Terminal::u8c_hist_use_row(int hurow)
         ::printf("<%.*s>", len, text);          // print potentially multibyte char
     }
     \endcode
+
+  - This can also be used to walk all rows on the display screen up to the cursor row, e.g.
+    \code
+    // Write all chars in display up to cursor row to stdout
+    for (int row=0; row<disp_rows() && row<=cursor_row(); row++) {
+        const Utf8Char *u8c = u8c_disp_row(row);                // first char in row
+        for (int col=0; col<=display_cols(); col++,u8c++) {     // walk columns left-to-right
+            // ..Do things here with each u8c char..
+            ::printf("%.*s", u8c->text_utf8(), u8c->length());  // write each utf8 char to stdout
+        }
+        ::printf("\n");
+    }
+    \endcode
+
+  \see u8c_hist_use_row() for examples of walking the screen history
 */
 Fl_Terminal::Utf8Char* Fl_Terminal::u8c_disp_row(int drow)
   { return const_cast<Utf8Char*>(const_cast<const Fl_Terminal*>(this)->u8c_disp_row(drow)); }
@@ -3925,7 +3958,7 @@ int Fl_Terminal::handle(int e) {
 
 /**
   Return a string copy of all lines in the terminal (including history).
-  The returned string is allocated with strdup(3), which the caller must free.
+  The returned string is allocated with `strdup(3)`, which the caller must `free(3)`.
 
   If \p 'lines_below_cursor' is false (default), lines below the cursor on down
   to the bottom of the display are ignored, and not included in the returned string.
-- 
cgit v1.2.3