From 0b29b1cc12e1e8f95a618d611391aa87418b383d Mon Sep 17 00:00:00 2001
From: "Darryl L. Miles" <darryl.miles@darrylmiles.org>
Date: Thu, 17 Jul 2025 22:19:16 +0100
Subject: [PATCH] fix GrTextSizePtr API interface return type consistency

commit 86b5d591d from 20241004 by me, modified return type of
GrTextSize API in the graphics from 'void' to 'int' to convey
and error scenario to indicate when 'r' was not filled in for
the caller, but this is a multi graphics driver API interface
so requires all downstream graphics engines to also support
the return type change.

This API can error and indicates when 'Rect *r' was
successfully updated.
---
 graphics/grMain.c      | 2 +-
 graphics/grNull.c      | 5 +++--
 graphics/grOGL3.c      | 2 +-
 graphics/grOGLInt.h    | 2 +-
 graphics/grTCairo3.c   | 9 +++++----
 graphics/grTCairoInt.h | 2 +-
 graphics/grTOGL3.c     | 9 +++++----
 graphics/grTOGLInt.h   | 2 +-
 graphics/grTk3.c       | 9 +++++----
 graphics/grTkInt.h     | 2 +-
 graphics/grX11Int.h    | 2 +-
 graphics/grX11su3.c    | 9 +++++----
 graphics/graphics.h    | 2 +-
 13 files changed, 31 insertions(+), 26 deletions(-)

diff --git a/graphics/grMain.c b/graphics/grMain.c
index 404b4e30..8d98ef0b 100644
--- a/graphics/grMain.c
+++ b/graphics/grMain.c
@@ -160,7 +160,7 @@ void (*GrClosePtr)()		= NULL;
 void (*GrSetCMapPtr)()		= NULL;
 
 void (*GrSetCursorPtr)()	= NULL;
-void (*GrTextSizePtr)()		= NULL;
+int  (*GrTextSizePtr)()		= NULL;
 void (*GrDrawGlyphPtr)()	= NULL;
 void (*GrBitBltPtr)()		= NULL;
 int  (*GrReadPixelPtr)()	= NULL;
diff --git a/graphics/grNull.c b/graphics/grNull.c
index 7a30db4c..a4d64519 100644
--- a/graphics/grNull.c
+++ b/graphics/grNull.c
@@ -136,7 +136,7 @@ NullInit()
  *	Determine the size of a text string.
  *
  * Results:
- *	None.
+ *	Returns 0 indicating 'r' has been updated.
  *
  * Side effects:
  *	A rectangle is filled in that is the size of the text in pixels.
@@ -146,7 +146,7 @@ NullInit()
  * ----------------------------------------------------------------------------
  */
 
-void
+int
 NullTextSize(text, size, r)
     char *text;
     int size;
@@ -157,6 +157,7 @@ NullTextSize(text, size, r)
     r->r_xtop = strlen(text);
     r->r_ybot = 0;
     r->r_ytop = 1;
+    return 0;
 }
 
 /*
diff --git a/graphics/grOGL3.c b/graphics/grOGL3.c
index e1b5b093..28b28c77 100644
--- a/graphics/grOGL3.c
+++ b/graphics/grOGL3.c
@@ -257,7 +257,7 @@ groglSetCharSize (size)
  *	Determine the size of a text string.
  *
  * Results:
- *	0 on success.  -1 on error (no side-effects).
+ *	Returns 0 when 'r' updated, otherwise -1 on error (no side-effects).
  *
  * Side effects:
  *	A rectangle is filled in that is the size of the text in pixels.
diff --git a/graphics/grOGLInt.h b/graphics/grOGLInt.h
index ff290aaf..7efa2cdb 100644
--- a/graphics/grOGLInt.h
+++ b/graphics/grOGLInt.h
@@ -63,7 +63,7 @@ extern void groglFontText();
 extern void groglDefineCursor();
 extern void GrOGLSetCursor();
 extern void GrOGLSetWindow();
-extern void GrOGLTextSize();
+extern int  GrOGLTextSize();
 extern void GrOGLDrawGlyph();
 extern void GrOGLBitBlt();
 extern void NullBitBlt();
diff --git a/graphics/grTCairo3.c b/graphics/grTCairo3.c
index 5ebfa8d2..c5bfc9e7 100644
--- a/graphics/grTCairo3.c
+++ b/graphics/grTCairo3.c
@@ -173,7 +173,7 @@ int size;       /* Width of characters, in pixels (6 or 8). */
  *  Determine the size of a text string.
  *
  * Results:
- *  None.
+ *  Return 0 when 'r' updated, otherwise -1 on error (no side-effects).
  *
  * Side effects:
  *  A rectangle is filled in that is the size of the text in pixels.
@@ -182,7 +182,7 @@ int size;       /* Width of characters, in pixels (6 or 8). */
  * ----------------------------------------------------------------------------
  */
 
-void
+int
 GrTCairoTextSize(text, size, r)
 char *text;
 int size;
@@ -195,7 +195,7 @@ Rect *r;
 	/* Note:  size is ignored, as it is passed the current value;	*/
 	/* but the font size in cairo has already been set.		*/
 
-	if (tcairoCurrent.mw == 0) return;
+	if (tcairoCurrent.mw == 0) return -1;
 
 	tcairodata = (TCairoData *)tcairoCurrent.mw->w_grdata2;
 	cairo_text_extents(tcairodata->context, text, &extents);
@@ -204,6 +204,7 @@ Rect *r;
 	r->r_ybot = -(extents.height + extents.y_bearing);
 	r->r_xtop = extents.width + extents.x_bearing;
 	r->r_xbot = extents.x_bearing;
+	return 0;
 }
 
 /* Cairo backing store functions (now removed from the X11-based ones) */
@@ -598,7 +599,7 @@ LinkedRect *obscure;    /* A list of obscuring rectangles */
 	float tscale;
 	TCairoData *tcairodata = (TCairoData *)tcairoCurrent.mw->w_grdata2;
 
-	GrTCairoTextSize(text, tcairoCurrent.fontSize, &textrect);
+	if (GrTCairoTextSize(text, tcairoCurrent.fontSize, &textrect) < 0) return;
 
 	location.r_xbot = pos->p_x + textrect.r_xbot;
 	location.r_xtop = pos->p_x + textrect.r_xtop;
diff --git a/graphics/grTCairoInt.h b/graphics/grTCairoInt.h
index f613ab06..4188ffe6 100644
--- a/graphics/grTCairoInt.h
+++ b/graphics/grTCairoInt.h
@@ -63,7 +63,7 @@ extern void grtcairoPutText();
 extern void grtcairoFontText();
 #endif
 extern void GrTCairoSetCursor();
-extern void GrTCairoTextSize();
+extern int GrTCairoTextSize();
 extern void GrTCairoDrawGlyph();
 extern void GrTCairoBitBlt();
 extern void NullBitBlt();
diff --git a/graphics/grTOGL3.c b/graphics/grTOGL3.c
index 3414f3a4..877d2df3 100644
--- a/graphics/grTOGL3.c
+++ b/graphics/grTOGL3.c
@@ -194,7 +194,7 @@ grtoglSetCharSize (size)
  *	Determine the size of a text string.
  *
  * Results:
- *	None.
+ *	Returns 0 when 'r' updated, otherwise -1 on error (no side-effects).
  *
  * Side effects:
  *	A rectangle is filled in that is the size of the text in pixels.
@@ -203,7 +203,7 @@ grtoglSetCharSize (size)
  * ----------------------------------------------------------------------------
  */
 
-void
+int
 GrTOGLTextSize(text, size, r)
     char *text;
     int size;
@@ -233,7 +233,7 @@ GrTOGLTextSize(text, size, r)
 		size );
 	break;
     }
-    if (font == NULL) return;
+    if (font == NULL) return -1;
     Tk_GetFontMetrics(font, &overall);
     width = Tk_TextWidth(font, text, strlen(text));
     /* Hack alert!  Tk_TextWidth returns values too small! */
@@ -242,6 +242,7 @@ GrTOGLTextSize(text, size, r)
     r->r_ybot = -overall.descent;
     r->r_xtop = width;
     r->r_xbot = 0;
+    return 0;
 }
 
 /* OpenGL backing store functions (now removed from the X11-based ones) */
@@ -682,7 +683,7 @@ grtoglPutText (text, pos, clip, obscure)
     int i;
     float tscale;
 
-    GrTOGLTextSize(text, toglCurrent.fontSize, &textrect);
+    if (GrTOGLTextSize(text, toglCurrent.fontSize, &textrect) < 0) return;
 
     location.r_xbot = pos->p_x + textrect.r_xbot;
     location.r_xtop = pos->p_x + textrect.r_xtop;
diff --git a/graphics/grTOGLInt.h b/graphics/grTOGLInt.h
index e67af2df..5292dea9 100644
--- a/graphics/grTOGLInt.h
+++ b/graphics/grTOGLInt.h
@@ -60,7 +60,7 @@ extern void grtoglPutText();
 extern void grtoglFontText();
 #endif
 extern void GrTOGLSetCursor();
-extern void GrTOGLTextSize();
+extern int  GrTOGLTextSize();
 extern void GrTOGLDrawGlyph();
 extern void GrTOGLBitBlt();
 extern void NullBitBlt();
diff --git a/graphics/grTk3.c b/graphics/grTk3.c
index 889ef98d..16c9f0b5 100644
--- a/graphics/grTk3.c
+++ b/graphics/grTk3.c
@@ -167,7 +167,7 @@ grtkSetCharSize (size)
  *	Determine the size of a text string.
  *
  * Results:
- *	None.
+ *	Returns 0 when 'r' updated, otherwise -1 on error (no side-effects).
  *
  * Side effects:
  *	A rectangle is filled in that is the size of the text in pixels.
@@ -176,7 +176,7 @@ grtkSetCharSize (size)
  * ----------------------------------------------------------------------------
  */
 
-void
+int
 GrTkTextSize(text, size, r)
     char *text;
     int size;
@@ -206,13 +206,14 @@ GrTkTextSize(text, size, r)
 		size );
 	break;
     }
-    if (font == NULL) return;
+    if (font == NULL) return -1;
     Tk_GetFontMetrics(font, &overall);
     width = Tk_TextWidth(font, text, strlen(text));
     r->r_ytop = overall.ascent;
     r->r_ybot = -overall.descent;
     r->r_xtop = width;
     r->r_xbot = 0;
+    return 0;
 }
 
 
@@ -493,7 +494,7 @@ grtkPutText (text, pos, clip, obscure)
 
     if (grCurrent.font == NULL) return;
 
-    GrTkTextSize(text, grCurrent.fontSize, &textrect);
+    if (GrTkTextSize(text, grCurrent.fontSize, &textrect) < 0) return;
 
     location.r_xbot = pos->p_x + textrect.r_xbot;
     location.r_xtop = pos->p_x + textrect.r_xtop;
diff --git a/graphics/grTkInt.h b/graphics/grTkInt.h
index 3bee9f8a..9ffca5e8 100644
--- a/graphics/grTkInt.h
+++ b/graphics/grTkInt.h
@@ -66,7 +66,7 @@ extern void GrTkSetCMap();
 extern void grtkPutText();
 extern void grtkFontText();
 extern void GrTkSetCursor();
-extern void GrTkTextSize();
+extern int  GrTkTextSize();
 extern void GrTkDrawGlyph();
 extern void GrTkBitBlt();
 extern void NullBitBlt();
diff --git a/graphics/grX11Int.h b/graphics/grX11Int.h
index 51094c93..052eea79 100644
--- a/graphics/grX11Int.h
+++ b/graphics/grX11Int.h
@@ -87,7 +87,7 @@ extern void grx11PutText();
 extern void grx11FontText();
 extern void grx11DefineCursor();
 extern void GrX11SetCursor();
-extern void GrX11TextSize();
+extern int  GrX11TextSize();
 extern void GrX11DrawGlyph();
 extern void GrX11BitBlt();
 extern void NullBitBlt();
diff --git a/graphics/grX11su3.c b/graphics/grX11su3.c
index 7416bdd9..f46a2961 100644
--- a/graphics/grX11su3.c
+++ b/graphics/grX11su3.c
@@ -228,7 +228,7 @@ grx11SetCharSize (size)
  *	Determine the size of a text string.
  *
  * Results:
- *	None.
+ *	Returns 0 when 'r' updated, otherwise -1 on error (no side-effects).
  *
  * Side effects:
  *	A rectangle is filled in that is the size of the text in pixels.
@@ -237,7 +237,7 @@ grx11SetCharSize (size)
  * ----------------------------------------------------------------------------
  */
 
-void
+int
 GrX11TextSize(text, size, r)
     char *text;
     int size;
@@ -266,12 +266,13 @@ GrX11TextSize(text, size, r)
 		size );
 	break;
     }
-    if (font == NULL) return;
+    if (font == NULL) return -1;
     XTextExtents(font, text, strlen(text), &dir, &fa, &fd, &overall);
     r->r_ytop = overall.ascent;
     r->r_ybot = -overall.descent;
     r->r_xtop = overall.width - overall.lbearing;
     r->r_xbot = -overall.lbearing - 1;
+    return 0;
 }
 
 
@@ -790,7 +791,7 @@ grx11PutText (text, pos, clip, obscure)
 
     if (grCurrent.font == NULL) return;
 
-    GrX11TextSize(text, grCurrent.fontSize, &textrect);
+    if (GrX11TextSize(text, grCurrent.fontSize, &textrect) < 0) return;
 
     location.r_xbot = pos->p_x + textrect.r_xbot;
     location.r_xtop = pos->p_x + textrect.r_xtop;
diff --git a/graphics/graphics.h b/graphics/graphics.h
index 474f9fb2..1dc8486b 100644
--- a/graphics/graphics.h
+++ b/graphics/graphics.h
@@ -42,7 +42,7 @@ typedef struct {	/* Colormap table entry */
 /* Housekeeping and initialization routines */
 extern bool (*GrInitPtr)();
 extern void (*GrClosePtr)();
-extern void (*GrTextSizePtr)();
+extern int (*GrTextSizePtr)();
 
 /*
  * Display painting and text routines