adjust: 将ege_前缀的文本输出函数的坐标参数类型由 int 改为 float (#259)

wysaid · Feb 4, 2025 · b7abf8f · b7abf8f
1 parent d1aebb1
commit b7abf8f
Show file tree

Hide file tree

Showing 14 changed files with 118 additions and 79 deletions.
diff --git a/include/ege.h b/include/ege.h
@@ -1262,12 +1262,12 @@ int  EGEAPI textheight(const wchar_t* text, PIMAGE pimg = NULL);
 int  EGEAPI textheight(char    c, PIMAGE pimg = NULL);
 int  EGEAPI textheight(wchar_t c, PIMAGE pimg = NULL);
 
-void EGEAPI ege_outtextxy(int x, int y, const char*    text, PIMAGE pimg = NULL);
-void EGEAPI ege_outtextxy(int x, int y, const wchar_t* text, PIMAGE pimg = NULL);
-void EGEAPI ege_outtextxy(int x, int y, char    c, PIMAGE pimg = NULL);
-void EGEAPI ege_outtextxy(int x, int y, wchar_t c, PIMAGE pimg = NULL);
-void EGEAPI ege_xyprintf (int x, int y, const char*    format, ...);
-void EGEAPI ege_xyprintf (int x, int y, const wchar_t* format, ...);
+void EGEAPI ege_outtextxy(float x, float y, const char*    text, PIMAGE pimg = NULL);
+void EGEAPI ege_outtextxy(float x, float y, const wchar_t* text, PIMAGE pimg = NULL);
+void EGEAPI ege_outtextxy(float x, float y, char    c, PIMAGE pimg = NULL);
+void EGEAPI ege_outtextxy(float x, float y, wchar_t c, PIMAGE pimg = NULL);
+void EGEAPI ege_xyprintf (float x, float y, const char*    format, ...);
+void EGEAPI ege_xyprintf (float x, float y, const wchar_t* format, ...);
 
 void EGEAPI settextjustify(int horiz, int vert, PIMAGE pimg = NULL);
 

diff --git a/man/api/font/ege_drawtext.htm b/man/api/font/ege_drawtext.htm
@@ -9,20 +9,20 @@
 <font size="4">
 <font size="4" color="#0000FF"><strong>功能：</strong></font>
 
-在指定位置格式化输出字符串。文本颜色使用 ARGB 颜色，由 setcolor() 指定。
+在指定位置格式化输出文本（使用 ARGB 颜色，由 setcolor() 或 settextcolor() 指定）。
 
 <font size="4" color="#0000FF"><strong>声明：</strong></font>
 <pre><font color=#0000FF>void </font><font color=#008080>ege_drawtext</font>(
     <font color=#800080>const char* </font>format,
-    <font color=#0000FF>int </font>x,
-    <font color=#0000FF>int </font>y,
-    ...
+    <font color=#0000FF>float </font>x,
+    <font color=#0000FF>float </font>y,
+    <font color=#800080>PIMAGE</font> pimg = <font color=#800080>NULL</font>
 );
 <font color=#0000FF>void </font><font color=#008080>ege_drawtext</font>(
     <font color=#800080>const wchar_t* </font>format,
-    <font color=#0000FF>int </font>x,
-    <font color=#0000FF>int </font>y,
-    ...
+    <font color=#0000FF>float </font>x,
+    <font color=#0000FF>float </font>y,
+    <font color=#800080>PIMAGE</font> pimg = <font color=#800080>NULL</font>
 );
 </pre>
 <font size="4" color="#0000FF"><strong>参数：</strong></font>
@@ -31,20 +31,20 @@
 格式字符串。
 
 x
-字符串输出时头字母的 x 轴的坐标值
+文本输出位置的 x 坐标(文本实际位置与文本对齐方式、文本倾斜角度等相关)。
 
 y
-字符串输出时头字母的 y 轴的坐标值。
+文本输出位置的 y 坐标(文本实际位置与文本对齐方式、文本倾斜角度等相关)。
 
-...
-要输出的内容的参数，类似 printf。
+pimg
+要输出文本的目标图像（如果为 NULL，则输出到窗口）。
 
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>
 
 （无）
 
 <font size="4" color="#0000FF"><strong>示例：</strong></font>
-无
+<font color=#008080>ege_drawtext</font>(<font color=#FF00FF>"text"</font>, 10.0f, 60.5f);
 
 </font>
 </pre>

diff --git a/man/api/font/ege_outtextxy.htm b/man/api/font/ege_outtextxy.htm
@@ -9,65 +9,74 @@
 <font size="4">
 <font size="4" color="#0000FF"><strong>功能：</strong></font>
 
-在指定位置输出字符串，支持 ARGB 颜色。
+在指定位置输出字符串（使用 ARGB 颜色，由 setcolor() 或 settextcolor() 指定）。
 
 <font size="4" color="#0000FF"><strong>声明：</strong></font>
 <pre><font color=#0000FF>void </font><font color=#008080>ege_outtextxy</font>(
-    <font color=#0000FF>int </font>x,
-    <font color=#0000FF>int </font>y,
+    <font color=#0000FF>float </font>x,
+    <font color=#0000FF>float </font>y,
     <font color=#800080>const char* </font>text,
     <font color=#800080>PIMAGE</font> pimg = <font color=#800080>NULL
 </font>);
 
 <font color=#0000FF>void </font><font color=#008080>ege_outtextxy</font>(
-    <font color=#0000FF>int </font>x,
-    <font color=#0000FF>int </font>y,
+    <font color=#0000FF>float </font>x,
+    <font color=#0000FF>float </font>y,
     <font color=#800080>CHAR </font>c,
     <font color=#800080>PIMAGE</font> pimg = <font color=#800080>NULL
 </font>);
 
 <font color=#0000FF>void </font><font color=#008080>ege_outtextxy</font>(
-    <font color=#0000FF>int </font>x,
-    <font color=#0000FF>int </font>y,
+    <font color=#0000FF>float </font>x,
+    <font color=#0000FF>float </font>y,
     <font color=#800080>const wchar_t* </font>text,
     <font color=#800080>PIMAGE</font> pimg = <font color=#800080>NULL
 </font>);
 
 <font color=#0000FF>void </font><font color=#008080>ege_outtextxy</font>(
-    <font color=#0000FF>int </font>x,
-    <font color=#0000FF>int </font>y,
+    <font color=#0000FF>float </font>x,
+    <font color=#0000FF>float </font>y,
     <font color=#800080>wchar_t </font>c,
     <font color=#800080>PIMAGE</font> pimg = <font color=#800080>NULL
 </font>);</pre>
 <font size="4" color="#0000FF"><strong>参数：</strong></font>
 
 x
-字符串输出时头字母的 x 轴的坐标值
+文本输出位置的 x 坐标(文本实际位置与文本对齐方式、文本倾斜角度等相关)。
 
 y
-字符串输出时头字母的 y 轴的坐标值。
+文本输出位置的 y 坐标(文本实际位置与文本对齐方式、文本倾斜角度等相关)。
 
 text
 要输出的文本内容。
 
 c
 要输出的字符。
 
+pimg
+要输出文本的目标图像（如果为 NULL，则输出到窗口）。
+
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>
 
 （无）
 
 <font size="4" color="#0000FF"><strong>示例：</strong></font>
-<pre><font color=#008000>// 输出字符串
-</font><font color=#0000FF>char </font>s[] = <font color=#FF00FF>"Hello World"</font>;
+<pre><font color=#008000>// 示例1：输出固定内容的字符串
+</font><font color=#0000FF>const char* </font>s = <font color=#FF00FF>"Hello World"</font>;
 <font color=#008080>ege_outtextxy</font>(10, 20, s);
-<font color=#008000>// 输出字符
+
+<font color=#008000>// 示例2：输出字符
 </font><font color=#0000FF>char </font>c = <font color=#FF00FF>'A'</font>;
 <font color=#008080>ege_outtextxy</font>(10, 40, c);
-<font color=#008000>// 输出数值，先将数字格式化输出为字符串
+
+<font color=#008000>// 示例3：输出数值，先将数字格式化输出为字符串
 </font><font color=#0000FF>char </font>s[5];
-<font color=#008080>sprintf</font>(s, <font color=#FF00FF>"%d"</font>, 1024);
-<font color=#008080>ege_outtextxy</font>(10, 60, s);</pre>
+<font color=#008080>sprintf</font>(s, <font color=#FF00FF>"value:%d"</font>, 1024);
+<font color=#008080>ege_outtextxy</font>(10.0f, 60.5f,  s);
+
+<font color=#008000>// 示例3 可以直接用 ege_xyprintf 代替</font>
+<font color=#008080>ege_xyprintf</font>(10.0f, 60.5f, <font color=#FF00FF>"value:%d"</font>, 1024);
+</pre>
 
 </font>
 </pre>

diff --git a/man/api/font/ege_xyprintf.htm b/man/api/font/ege_xyprintf.htm
@@ -9,41 +9,43 @@
 <font size="4">
 <font size="4" color="#0000FF"><strong>功能：</strong></font>
 
-在指定位置格式化输出字符串，使用 ARGB 颜色。
+在指定位置格式化输出文本（使用 ARGB 颜色，由 setcolor() 或 settextcolor() 指定）。
 
 <font size="4" color="#0000FF"><strong>声明：</strong></font>
 <pre><font color=#0000FF>void </font><font color=#008080>ege_xyprintf</font>(
-    <font color=#0000FF>int </font>x,
-    <font color=#0000FF>int </font>y,
+    <font color=#0000FF>float </font>x,
+    <font color=#0000FF>float </font>y,
     <font color=#800080>const char* </font>format,
     ...
 );
 <font color=#0000FF>void </font><font color=#008080>ege_xyprintf</font>(
-    <font color=#0000FF>int </font>x,
-    <font color=#0000FF>int </font>y,
+    <font color=#0000FF>float </font>x,
+    <font color=#0000FF>float </font>y,
     <font color=#800080>const wchar_t* </font>format,
     ...
 );
 </pre>
 <font size="4" color="#0000FF"><strong>参数：</strong></font>
 
 x
-字符串输出时头字母的 x 轴的坐标值
+文本输出位置的 x 坐标(文本实际位置与文本对齐方式、文本倾斜角度等相关)。
 
 y
-字符串输出时头字母的 y 轴的坐标值。
+文本输出位置的 y 坐标(文本实际位置与文本对齐方式、文本倾斜角度等相关)。
 
 format
 格式字符串。
+
 ...
-要输出的内容的参数，类似 printf。
+要输出的内容的参数（支持多个参数，类似 printf）。
 
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>
 
 （无）
 
 <font size="4" color="#0000FF"><strong>示例：</strong></font>
-无
+
+<font color=#008080>ege_xyprintf</font>(10.0f, 60.5f, <font color=#FF00FF>"value:%d"</font>, 1024);
 
 </font>
 </pre>

diff --git a/man/api/font/getfont.htm b/man/api/font/getfont.htm
@@ -9,7 +9,7 @@
 <font size="4">
 <font size="4" color="#0000FF"><strong>功能：</strong></font>
 
-获取当前字体样式
+获取图像(窗口)所设置的字体样式。
 
 <font size="4" color="#0000FF"><strong>声明：</strong></font>
 <pre><font color=#0000FF>void </font><font color=#008080>getfont</font>(
@@ -20,6 +20,9 @@
 font
 指向 LOGFONT 结构体的指针。
 
+pimg
+要获取字体样式的目标图像（ 如果参数为 NULL，则表示窗口）。
+
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>
 
 （无）

diff --git a/man/api/font/outtext.htm b/man/api/font/outtext.htm
@@ -33,11 +33,14 @@
 </font>);</pre>
 <font size="4" color="#0000FF"><strong>参数：</strong></font>
 text
-要输出的字符串。
+要输出的文本内容。
 
 c
 要输出的字符。
 
+pimg
+要输出文本的目标图像（如果为 NULL，则输出到窗口）。
+
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>
 
 （无）

diff --git a/man/api/font/outtextrect.htm b/man/api/font/outtextrect.htm
@@ -9,7 +9,7 @@
 <font size="4">
 <font size="4" color="#0000FF"><strong>功能：</strong></font>
 
-在指定矩形范围内输出字符串。
+在指定矩形范围内输出文本。
 
 <font size="4" color="#0000FF"><strong>声明：</strong></font>
 <pre><font color=#0000FF>void </font><font color=#008080>outtextrect</font>(
@@ -30,10 +30,13 @@
 </font>);</pre>
 <font size="4" color="#0000FF"><strong>参数：</strong></font>
 x, y, w, h
-要输出字符串所在的矩形区域
+指定文本所在的矩形区域
 
 text
-要输出的字符串。
+要输出的文本内容。
+
+pimg
+要输出文本的目标图像（如果为 NULL，则输出到窗口）。
 
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>
 

diff --git a/man/api/font/outtextxy.htm b/man/api/font/outtextxy.htm
@@ -9,7 +9,7 @@
 <font size="4">
 <font size="4" color="#0000FF"><strong>功能：</strong></font>
 
-在指定位置输出字符串。
+在指定位置输出文本。
 
 <font size="4" color="#0000FF"><strong>声明：</strong></font>
 <pre><font color=#0000FF>void </font><font color=#008080>outtextxy</font>(
@@ -42,32 +42,40 @@
 <font size="4" color="#0000FF"><strong>参数：</strong></font>
 
 x
-字符串输出时头字母的 x 轴的坐标值
+文本输出位置的 x 坐标(文本实际位置与文本对齐方式、文本倾斜角度等相关)。
 
 y
-字符串输出时头字母的 y 轴的坐标值。
+文本输出位置的 y 坐标(文本实际位置与文本对齐方式、文本倾斜角度等相关)。
 
 text
-要输出的字符串。
+要输出的文本内容。
 
 c
 要输出的字符。
 
+pimg
+要输出文本的目标图像（如果为 NULL，则输出到窗口）。
+
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>
 
 （无）
 
 <font size="4" color="#0000FF"><strong>示例：</strong></font>
-<pre><font color=#008000>// 输出字符串
-</font><font color=#0000FF>char </font>s[] = <font color=#FF00FF>"Hello World"</font>;
+<pre><font color=#008000>// 示例1：输出固定内容的字符串
+</font><font color=#0000FF>const char* </font>s = <font color=#FF00FF>"Hello World"</font>;
 <font color=#008080>outtextxy</font>(10, 20, s);
-<font color=#008000>// 输出字符
+
+<font color=#008000>// 示例2：输出字符
 </font><font color=#0000FF>char </font>c = <font color=#FF00FF>'A'</font>;
 <font color=#008080>outtextxy</font>(10, 40, c);
-<font color=#008000>// 输出数值，先将数字格式化输出为字符串
+
+<font color=#008000>// 示例3：输出格式化字符串。先将数字格式化输出成字符串再输出。
 </font><font color=#0000FF>char </font>s[5];
-<font color=#008080>sprintf</font>(s, <font color=#FF00FF>"%d"</font>, 1024);
-<font color=#008080>outtextxy</font>(10, 60, s);</pre>
+<font color=#008080>sprintf</font>(s, <font color=#FF00FF>"value:%d"</font>, 1024);
+<font color=#008080>outtextxy</font>(10, 60, s);
+
+<font color=#008000>// 示例3 可以直接用 xyprintf 代替</font>
+<font color=#008080>xyprintf</font>(10, 60, <font color=#FF00FF>"value:%d"</font>, 1024);</pre>
 
 </font>
 </pre>

diff --git a/man/api/font/setfont.htm b/man/api/font/setfont.htm
@@ -9,7 +9,7 @@
 <font size="4">
 <font size="4" color="#0000FF"><strong>功能：</strong></font>
 
-设置当前字体样式,字体颜色另外由setcolor() 或 settextcolor() 设置。
+设置图像(窗口)的字体样式,字体颜色另外由setcolor() 或 settextcolor() 设置。
 
 <font size="4" color="#0000FF"><strong>备注：</strong></font>
 另有接收类型为 const wchar_t* 的 typeface 参数的重载。
@@ -123,6 +123,9 @@
 font
 指向 LOGFONT 结构体的指针。
 
+pimg
+要设置字体样式的目标图像（ 如果参数为 NULL，则表示窗口）。
+
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>
 
 （无）

diff --git a/man/api/font/settextjustify.htm b/man/api/font/settextjustify.htm
@@ -9,7 +9,7 @@
 <font size="4">
 <font size="4" color="#0000FF"><strong>功能：</strong></font>
 
-设置文字对齐方式。
+设置文本对齐方式。
 
 <font size="4" color="#0000FF"><strong>声明：</strong></font>
 <pre><font color=#0000FF>void </font><font color=#008080>settextjustify</font>(
@@ -30,8 +30,9 @@
 	<tr align="center"><td>CENTER_TEXT</td><td>居中对齐</td><td>CENTER_TEXT</td><td>居中对齐</td></tr>
 	<tr align="center"><td>RIGHT_TEXT</td><td>右对齐</td><td>BOTTOM_TEXT</td><td>底部对齐</td></tr>
 </table>
-text
-要输出的字符串的指针。
+
+pimg
+要设置的图像（如果参数为 NULL，则表示窗口）。
 
 <font size="4" color="#0000FF"><strong>返回值：</strong></font>