Add pdfioContentTextNewLineShow/f functions (Issue #24)

CHANGES.md

@@ -6,6 +6,9 @@ v1.2.0 (Month DD, YYYY)
 -----------------------
 
 - Added `pdfioContentTextMeasure` function (Issue #17)
+- Added `pdfioContentTextNewLineShow` and `pdfioContentTextNewLineShowf`
+  functions (Issue #24)
+- Renamed `pdfioContentTextNextLine` to `pdfioContentTextNewLine`.
 - Now use autoconf to configure the PDFio sources (Issue #54)
 
 

doc/pdfio.3

@@ -1,4 +1,4 @@
-.TH pdfio 3 "pdf read/write library" "2023-12-04" "pdf read/write library"
+.TH pdfio 3 "pdf read/write library" "2023-12-05" "pdf read/write library"
 .SH NAME
 pdfio \- pdf read/write library
 .SH Introduction
@@ -1808,14 +1808,49 @@ bool  pdfioContentTextMoveTo (
     double ty
 );
 .fi
-.SS pdfioContentTextNextLine
+.SS pdfioContentTextNewLine
 Move to the next line.
 .PP
 .nf
-bool  pdfioContentTextNextLine (
+bool  pdfioContentTextNewLine (
     pdfio_stream_t *st
 );
 .fi
+.SS pdfioContentTextNewLineShow
+Move to the next line and show text.
+.PP
+.nf
+bool  pdfioContentTextNewLineShow (
+    pdfio_stream_t *st,
+    double ws,
+    double cs,
+    bool unicode,
+    const char *s
+);
+.fi
+.PP
+This function moves to the next line and then shows some text with optional
+word and character spacing in a PDF content stream. The "unicode" argument
+specifies that the current font maps to full Unicode.  The "s" argument
+specifies a UTF-8 encoded string.
+.SS pdfioContentTextNewLineShowf
+Show formatted text.
+.PP
+.nf
+bool  pdfioContentTextNewLineShowf (
+    pdfio_stream_t *st,
+    double ws,
+    double cs,
+    bool unicode,
+    const char *format,
+    ...
+);
+.fi
+.PP
+This function moves to the next line and shows some formatted text with
+optional word and character spacing in a PDF content stream. The "unicode"
+argument specifies that the current font maps to full Unicode.  The "format"
+argument specifies a UTF-8 encoded \fBprintf\fR-style format string.
 .SS pdfioContentTextShow
 Show text.
 .PP

doc/pdfio.html

@@ -345,7 +345,9 @@ span.string {
 <li><a href="#pdfioContentTextMeasure">pdfioContentTextMeasure</a></li>
 <li><a href="#pdfioContentTextMoveLine">pdfioContentTextMoveLine</a></li>
 <li><a href="#pdfioContentTextMoveTo">pdfioContentTextMoveTo</a></li>
-<li><a href="#pdfioContentTextNextLine">pdfioContentTextNextLine</a></li>
+<li><a href="#pdfioContentTextNewLine">pdfioContentTextNewLine</a></li>
+<li><a href="#pdfioContentTextNewLineShow">pdfioContentTextNewLineShow</a></li>
+<li><a href="#pdfioContentTextNewLineShowf">pdfioContentTextNewLineShowf</a></li>
 <li><a href="#pdfioContentTextShow">pdfioContentTextShow</a></li>
 <li><a href="#pdfioContentTextShowJustified">pdfioContentTextShowJustified</a></li>
 <li><a href="#pdfioContentTextShowf">pdfioContentTextShowf</a></li>
@@ -2055,10 +2057,10 @@ bool pdfioContentTextMoveTo(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st, do
 </tbody></table>
 <h4 class="returnvalue">Return Value</h4>
 <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
-<h3 class="function"><a id="pdfioContentTextNextLine">pdfioContentTextNextLine</a></h3>
+<h3 class="function"><a id="pdfioContentTextNewLine">pdfioContentTextNewLine</a></h3>
 <p class="description">Move to the next line.</p>
 <p class="code">
-bool pdfioContentTextNextLine(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st);</p>
+bool pdfioContentTextNewLine(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st);</p>
 <h4 class="parameters">Parameters</h4>
 <table class="list"><tbody>
 <tr><th>st</th>
@@ -2066,6 +2068,56 @@ bool pdfioContentTextNextLine(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st);
 </tbody></table>
 <h4 class="returnvalue">Return Value</h4>
 <p class="description"><code>true</code> on success, <code>false</code> on failure</p>
+<h3 class="function"><a id="pdfioContentTextNewLineShow">pdfioContentTextNewLineShow</a></h3>
+<p class="description">Move to the next line and show text.</p>
+<p class="code">
+bool pdfioContentTextNewLineShow(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st, double ws, double cs, bool unicode, const char *s);</p>
+<h4 class="parameters">Parameters</h4>
+<table class="list"><tbody>
+<tr><th>st</th>
+<td class="description">Stream</td></tr>
+<tr><th>ws</th>
+<td class="description">Word spacing or <code>0.0</code> for none</td></tr>
+<tr><th>cs</th>
+<td class="description">Character spacing or <code>0.0</code> for none</td></tr>
+<tr><th>unicode</th>
+<td class="description">Unicode text?</td></tr>
+<tr><th>s</th>
+<td class="description">String to show</td></tr>
+</tbody></table>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function moves to the next line and then shows some text with optional
+word and character spacing in a PDF content stream. The &quot;unicode&quot; argument
+specifies that the current font maps to full Unicode.  The &quot;s&quot; argument
+specifies a UTF-8 encoded string.</p>
+<h3 class="function"><a id="pdfioContentTextNewLineShowf">pdfioContentTextNewLineShowf</a></h3>
+<p class="description">Show formatted text.</p>
+<p class="code">
+bool pdfioContentTextNewLineShowf(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st, double ws, double cs, bool unicode, const char *format, ...);</p>
+<h4 class="parameters">Parameters</h4>
+<table class="list"><tbody>
+<tr><th>st</th>
+<td class="description">Stream</td></tr>
+<tr><th>ws</th>
+<td class="description">Word spacing or <code>0.0</code> for none</td></tr>
+<tr><th>cs</th>
+<td class="description">Character spacing or <code>0.0</code> for none</td></tr>
+<tr><th>unicode</th>
+<td class="description">Unicode text?</td></tr>
+<tr><th>format</th>
+<td class="description"><code>printf</code>-style format string</td></tr>
+<tr><th>...</th>
+<td class="description">Additional arguments as needed</td></tr>
+</tbody></table>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description"><code>true</code> on success, <code>false</code> on failure</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function moves to the next line and shows some formatted text with
+optional word and character spacing in a PDF content stream. The &quot;unicode&quot;
+argument specifies that the current font maps to full Unicode.  The &quot;format&quot;
+argument specifies a UTF-8 encoded <code>printf</code>-style format string.</p>
 <h3 class="function"><a id="pdfioContentTextShow">pdfioContentTextShow</a></h3>
 <p class="description">Show text.</p>
 <p class="code">
@@ -2125,9 +2177,9 @@ bool pdfioContentTextShowf(<a href="#pdfio_stream_t">pdfio_stream_t</a> *st, boo
 </tbody></table>
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">Show formatted text.</p>
-<p class="discussion">This function shows some text in a PDF content stream. The &quot;unicode&quot; argument
+<p class="discussion">This function shows some formatted text in a PDF content stream. The
-specifies that the current font maps to full Unicode.  The &quot;format&quot; argument
+&quot;unicode&quot; argument specifies that the current font maps to full Unicode.
-specifies a UTF-8 encoded <code>printf</code>-style format string.</p>
+The &quot;format&quot; argument specifies a UTF-8 encoded <code>printf</code>-style format string.</p>
 <h3 class="function"><a id="pdfioDictCopy">pdfioDictCopy</a></h3>
 <p class="description">Copy a dictionary to a PDF file.</p>
 <p class="code">

pdfio-content.c

@@ -1187,17 +1187,97 @@ pdfioContentTextMoveTo(
 
 
 //
-// 'pdfioContentTextNextLine()' - Move to the next line.
+// 'pdfioContentTextNewLine()' - Move to the next line.
 //
 
 bool					// O - `true` on success, `false` on failure
-pdfioContentTextNextLine(
+pdfioContentTextNewLine(
     pdfio_stream_t *st)			// I - Stream
 {
   return (pdfioStreamPuts(st, "T*\n"));
 }
 
 
+//
+// 'pdfioContentTextNewLineShow()' - Move to the next line and show text.
+//
+// This function moves to the next line and then shows some text with optional
+// word and character spacing in a PDF content stream. The "unicode" argument
+// specifies that the current font maps to full Unicode.  The "s" argument
+// specifies a UTF-8 encoded string.
+//
+
+bool					// O - `true` on success, `false` on failure
+pdfioContentTextNewLineShow(
+    pdfio_stream_t *st,			// I - Stream
+    double         ws,			// I - Word spacing or `0.0` for none
+    double         cs,			// I - Character spacing or `0.0` for none
+    bool           unicode,		// I - Unicode text?
+    const char     *s)			// I - String to show
+{
+  bool	newline = false;		// New line?
+  char	op;				// Text operator
+
+
+  // Write word and/or character spacing as needed...
+  if (ws > 0.0 || cs > 0.0)
+  {
+    // Use " operator to show text with word and character spacing...
+    if (!pdfioStreamPrintf(st, "%g %g", ws, cs))
+      return (false);
+
+    op = '\"';
+  }
+  else
+  {
+    // Use ' operator to show text with the defaults...
+    op = '\'';
+  }
+
+  // Write the string...
+  if (!write_string(st, unicode, s, &newline))
+    return (false);
+
+  // Draw it...
+  if (newline)
+    return (pdfioStreamPrintf(st, "%c T*\n", op));
+  else
+    return (pdfioStreamPrintf(st, "%c\n", op));
+}
+
+
+//
+// 'pdfioContentTextNewLineShowf()' - Show formatted text.
+//
+// This function moves to the next line and shows some formatted text with
+// optional word and character spacing in a PDF content stream. The "unicode"
+// argument specifies that the current font maps to full Unicode.  The "format"
+// argument specifies a UTF-8 encoded `printf`-style format string.
+//
+
+bool					// O - `true` on success, `false` on failure
+pdfioContentTextNewLineShowf(
+    pdfio_stream_t *st,			// I - Stream
+    double         ws,			// I - Word spacing or `0.0` for none
+    double         cs,			// I - Character spacing or `0.0` for none
+    bool           unicode,		// I - Unicode text?
+    const char     *format,		// I - `printf`-style format string
+    ...)				// I - Additional arguments as needed
+{
+  char		buffer[8192];		// Text buffer
+  va_list	ap;			// Argument pointer
+
+
+  // Format the string...
+  va_start(ap, format);
+  vsnprintf(buffer, sizeof(buffer), format, ap);
+  va_end(ap);
+
+  // Show it...
+  return (pdfioContentTextNewLineShow(st, ws, cs, unicode, buffer));
+}
+
+
 //
 // 'pdfioContentTextShow()' - Show text.
 //
@@ -1230,9 +1310,9 @@ pdfioContentTextShow(
 //
 // 'pdfioContentTextShowf()' - Show formatted text.
 //
-// This function shows some text in a PDF content stream. The "unicode" argument
+// This function shows some formatted text in a PDF content stream. The
-// specifies that the current font maps to full Unicode.  The "format" argument
+// "unicode" argument specifies that the current font maps to full Unicode.
-// specifies a UTF-8 encoded `printf`-style format string.
+// The "format" argument specifies a UTF-8 encoded `printf`-style format string.
 //
 
 bool

pdfio-content.h

@@ -118,7 +118,9 @@ extern bool		pdfioContentTextEnd(pdfio_stream_t *st) _PDFIO_PUBLIC;
 extern double		pdfioContentTextMeasure(pdfio_obj_t *font, const char *s, double size) _PDFIO_PUBLIC;
 extern bool		pdfioContentTextMoveLine(pdfio_stream_t *st, double tx, double ty) _PDFIO_PUBLIC;
 extern bool		pdfioContentTextMoveTo(pdfio_stream_t *st, double tx, double ty) _PDFIO_PUBLIC;
-extern bool		pdfioContentTextNextLine(pdfio_stream_t *st) _PDFIO_PUBLIC;
+extern bool		pdfioContentTextNewLine(pdfio_stream_t *st) _PDFIO_PUBLIC;
+extern bool		pdfioContentTextNewLineShow(pdfio_stream_t *st, double ws, double cs, bool unicode, const char *s) _PDFIO_PUBLIC;
+extern bool		pdfioContentTextNewLineShowf(pdfio_stream_t *st, double ws, double cs, bool unicode, const char *format, ...) _PDFIO_PUBLIC _PDFIO_FORMAT(5,6);
 extern bool		pdfioContentTextShow(pdfio_stream_t *st, bool unicode, const char *s) _PDFIO_PUBLIC;
 extern bool		pdfioContentTextShowf(pdfio_stream_t *st, bool unicode, const char *format, ...) _PDFIO_PUBLIC _PDFIO_FORMAT(3,4);
 extern bool		pdfioContentTextShowJustified(pdfio_stream_t *st, bool unicode, size_t num_fragments, const double *offsets, const char * const *fragments) _PDFIO_PUBLIC;

pdfio1.def

@@ -141,7 +141,9 @@ pdfioContentTextEnd
 pdfioContentTextMeasure
 pdfioContentTextMoveLine
 pdfioContentTextMoveTo
-pdfioContentTextNextLine
+pdfioContentTextNewLine
+pdfioContentTextNewLineShow
+pdfioContentTextNewLineShowf
 pdfioContentTextShow
 pdfioContentTextShowJustified
 pdfioContentTextShowf