summaryrefslogtreecommitdiff
path: root/html/en/func/text.html
blob: 12a54cdbb15ddc400e2e14066500f2c6f78e8808 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
<!doctype HTML PUBLIC "-//IETF//DTD HTML//EN">
<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">

<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Text</title>
<link rel="stylesheet" type="text/css" href="../../style.css">
</head>

<body>

<h2 align="center">Text</h2>

  <p>A raster text using a font with styles. The position the text is drawn depends on the text alignment attribute. </p>
  <p>The library has at least 4 standard typefaces: &quot;System&quot; (which depends on the driver and platform), 
  &quot;Courier&quot; (mono spaced 
  with serif), &quot;Times&quot; (proportional with serif) and &quot;Helvetica&quot; (proportional without serif). Each typeface can have 
  some styles: Plain, <strong>Bold</strong>, <em>Italic</em> and a combination of <em><strong>Bold and Italic</strong></em>. 
  As an alternative to the standard typefaces, you can use other typefaces or native driver typefaces with the function
  <strong>NativeFont</strong>, but they may work in a reduced set of drivers.
  </p>
  <p>You may retrieve the dimensions of the selected font with function <font>
  <strong>GetFontDim</strong></font>. Also you 
  may retrieve the bounding box of a specific text before drawing by using the 
  <font><strong>GetTextSize</strong></font> 
  and <font><strong>GetTextBox</strong></font> functions. </p>
  <p>The text is drawn using a reference point; you can change the alignment relative to this point using the
  <font><strong>TextAligment</strong></font> function. </p>

<hr>
<pre class="function"><span class="mainFunction">void <a name="cdText">cdCanvasText</a>(cdCanvas* canvas, int x, int y, const char* text); [in C]</span>
void cdfCanvasText(cdCanvas* canvas, double x, double y, const char* text); [in C]
void wdCanvasText(cdCanvas* canvas, double x, double y, const char* text); (WC) [in C]

canvas:Text(x, y: number, text: string) [in Lua]
canvas:fText(x, y: number, text: string) [in Lua]
canvas:wText(x, y: number, text: string) (WC) [in Lua]</pre>

  <p>Draws a text in the position <b><tt>(x,y)</tt></b> according to the current font and 
  text alignment. It expects an ANSI string. Can have line breaks.</p>

<h3>Attributes</h3>
<pre class="function"><span class="mainFunction">void <a name="cdFont">cdCanvasFont</a>(cdCanvas* canvas, const char* typeface, int style, int size); [in C]</span>
void wdCanvasFont(cdCanvas* canvas, const char* typeface, int style, double size); (WD) [in C]

canvas:Font(typeface, style, size: number) [in Lua]
canvas:wFont(typeface, style, size: number) (WD) [in Lua]</pre>

  <p>Selects a text font. The font type can be one of the standard type faces or 
  other driver dependent type face. Since font face names are not a standard 
	between drivers, a few names are specially handled to improve application 
	portability. If you want to use names that work for all systems we recommend 
	using: &quot;<strong>Courier</strong>&quot;, &quot;<strong>Times</strong>&quot; and &quot;<strong>Helvetica</strong>&quot;.</p>
<p>The style can be a combination of: <strong>CD_PLAIN</strong>, 
  <strong>CD_BOLD</strong>, <strong>CD_ITALIC</strong>, <strong>CD_UNDERLINE</strong> 
  or <strong>CD_STRIKEOUT</strong>. Only the Windows and PDF drivers support underline and 
  strikeout. The size is provided in points (1/72 inch) or in pixels (using 
  negative values). </p>
  <p>Default values: &quot;<strong>System</strong>&quot;, <b>CD_PLAIN</b>, 12. </p>
  <p>You can specify partial parameters using NULL, -1 and 0 for typeface, style 
  and size. When these parameters are specified the current font parameter is 
  used. For example: <b>CanvasFont(NULL, -1, 10)</b> will only change the font 
  size.</p>
  <p>To convert between pixels and points use the function <strong>
  <font>cdPixel2MM</font>
  </strong>to convert from pixels to millimeters and use the formula &quot;<strong>(value in <em>points</em>) = CD_MM2PT * 
  (value in millimeters)</strong>&quot;.</p>
  <p>In WC, the size is specified in millimeters, but is internally converted to points.</p>
<p>Fonts can heavily benefit from the ANTIALIAS attribute where available in the 
driver.</p>
  <div align="center">
    <center>
    <table border="0" cellpadding="5" cellspacing="8" style="border-collapse: collapse" bordercolor="#111111">
      <tr>
        <td>
        <p align="center"><font size="4">Type Faces</font><br>
        <img src="../../img/fonts.gif" border="2" width="140" height="125"> </td>
        <td>
        <p align="center"><font size="4">Font Styles</font><br>
        <img src="../../img/font_style.gif" border="2" width="135" height="122"> </td>
      </tr>
    </table>
    </center>
  </div>

<pre class="function"><span class="mainFunction">void <a name="cdGetFont">cdCanvasGetFont</a>(cdCanvas* canvas, char* typeface, int *style, int *size); [in C]</span>
void wdCanvasGetFont(cdCanvas* canvas, char* typeface, int *style, double *size); (WC) [in C]

canvas:GetFont() -&gt; (typeface: string, style, size: number) [in Lua]
canvas:wGetFont() -&gt; (typeface: string, style, size: number) (WC) [in Lua]</pre>

  <p>Returns the values of the current font. It is not necessary to provide all 
  return pointers; you can provide only the desired values.</p>
  <p>In WC, the size is returned in millimeters.</p>

<pre class="function"><span class="mainFunction">char* <a name="cdNativeFont">cdCanvasNativeFont</a>(cdCanvas* canvas, const char* nativefont); [in C]</span>

canvas:NativeFont(font: string) -&gt; (old_font: string) [in Lua]</pre>

  <p>Selects a font based on a string description. The description can depend on the driver 
  and the platform, but a common definition is available for all drivers. It 
  does not need to be stored by the application, as it is internally replicated 
  by the library. The string is case sensitive. It returns the previous string. </p>
<p>The string is parsed and the font typeface, style and size are set according 
to the parsed values, as if <strong>cdCanvasFont</strong> was called. The native font string is 
cleared when a font is set 
using <strong>cdCanvasFont</strong>.</p>
<p>The common format definition is similar to the the <a href="http://www.pango.org/">
Pango</a> library Font Description, used by GTK+2. It is defined as having 3 parts: &lt;font 
family&gt;, &lt;font styles&gt; &lt;font size&gt;. For ex: &quot;Times, Bold 18&quot;, or 
&quot;Arial,Helvetica, Italic Underline -24&quot;. The supported styles include: 
Bold, Italic, Underline and Strikeout. Underline, Strikeout, and negative 
pixel values are not supported by the standard Pango Font Description. The Pango 
format include many other definitions not supported by the CD format, they are 
just ignored.</p>
<p>The IUP &quot;FONT&quot; attribute internal formats are also accepted in all drivers 
and platforms.</p>
  <p>Using &quot;NULL&quot; as a parameter, it only returns the previous string and does not change the font. The value returned 
  is the last attributed value, which may not correspond exactly to the font selected by the driver.</p>

  <p>Using &quot;(char*)CD_QUERY&quot; as a parameter, it returns the current selected 
  font in the common format definition.</p>

<pre class="function"><span class="mainFunction">int <a name="cdTextAlignment">cdCanvasTextAlignment</a>(cdCanvas* canvas, int alignment); [in C]</span>

canvas:TextAlignment(alignment: number) -&gt; (old_alignment: number) [in Lua]</pre>

  <p>Defines the vertical and horizontal alignment of a text as: <b><tt>CD_NORTH</tt></b>, <b><tt>CD_SOUTH</tt></b>, <b>
  <tt>CD_EAST</tt></b>, <b><tt>CD_WEST</tt></b>, <b><tt>CD_NORTH_EAST</tt></b>, <b><tt>CD_NORTH_WEST</tt></b>, <b><tt>
  CD_SOUTH_EAST</tt></b>, <b><tt>CD_SOUTH_WEST</tt></b>, <b><tt>CD_CENTER</tt></b>, <b><tt>CD_BASE_LEFT</tt></b>, <b>
  <tt>CD_BASE_CENTER</tt></b>, or <b><tt>CD_BASE_RIGHT</tt></b>. Returns the previous value. Default value: <b><tt>
  CD_BASE_LEFT</tt></b>. Value <tt><b>CD_QUERY</b> </tt>simply returns the current value.</p>
  <p align="center"><font size="4">Text Alignment</font><br>
  <img src="../../img/align.gif" border="2" width="273" height="227"></p>

<pre class="function"><span class="mainFunction">double <a name="cdTextOrientation">cdCanvasTextOrientation</a>(cdCanvas* canvas, double angle); [in C]</span>

canvas:TextOrientation(angle: number) -&gt; (old_angle: number) [in Lua]</pre>

  <p>Defines the text orientation, which is an angle provided in degrees relative to the horizontal line according to 
  which the text is drawn. Returns the previous value. Value <tt><b>CD_QUERY</b> </tt>simply returns the current value. 
  The default value is 0.</p>

<h3>Properties</h3>
<pre class="function"><span class="mainFunction">void <a name="cdFontDim">cdCanvasGetFontDim</a>(cdCanvas* canvas, int *max_width, int *height, int *ascent, int *descent); [in C]</span>
void wdCanvasGetFontDim(cdCanvas* canvas, double *max_width, double *height, double *ascent, double *descent); (WC) [in C]

canvas:GetFontDim() -&gt; (max_width, height, ascent, descent: number) [in Lua]
canvas:wGetFontDim() -&gt; (max_width, height, ascent, descent: number) (WC) [in Lua]</pre>

  <p>Returns the maximum width of a character, the line's height, the <i>ascent</i> and <i>descent</i> of the 
  characters of the currently selected font. The line's height is the sum of the <i>
  ascent</i> and <i>descent</i> of a 
  given additional space (if this is the case). All values are given in pixels 
  and are positive. It is not necessary to provide all return pointers, you can provide only 
  the desired values and <i><tt>NULL</tt></i> for the others.</p>
  <p align="center"><font size="4">Font Dimension Attributes<br>
  </font><img src="../../img/font_dim.gif" border="2" width="300" height="139"></p>

<pre class="function"><span class="mainFunction">void <a name="cdTextSize">cdCanvasGetTextSize</a>(cdCanvas* canvas, const char* text, int *width, int *height); [in C]</span>
void wdCanvasGetTextSize(cdCanvas* canvas, const char* text, double *width, double *height); (WC) [in C]

canvas:GetTextSize(text: string) -&gt; (width, heigth: number) [in Lua]
canvas:wGetTextSize(text: string) -&gt; (width, heigth: number) (WC) [in Lua]</pre>

    <p>Returns the text size independent from orientation. It is 
      not necessary to provide all return pointers, you can provide only the desired 
      values and <font>NULL</font> for the others.</p>

<pre class="function"><span class="mainFunction">void <a name="cdTextBounds">cdCanvasGetTextBounds</a>(cdCanvas* canvas, int x, int y, const char *text, int *rect); [in C]</span>
void wdCanvasGetTextBounds(cdCanvas* canvas, double x, double y, const char* text, double *rect); (WC) [in C]

canvas:GetTextBounds(x, y: number, text: string) -&gt; (rect: table) [in Lua]
canvas:wGetTextBounds(x, y: number, text: string) -&gt; (rect: table) (WC) [in Lua]</pre>

  <p>Returns the oriented bounding rectangle occupied by a text at a given 
	position. The rectangle has the same dimentions returned by <strong>
	GetTextSize</strong>. The rectangle corners are returned in counter-clock wise 
  order starting with the bottom left corner, arranged (x0,y0,x1,y1,x2,y2,x3,y3).</p>


<pre class="function"><span class="mainFunction">void <a name="cdTextBox">cdCanvasGetTextBox</a>(cdCanvas* canvas, int x, int y, const char* text, int *xmin, int *xmax, int *ymin, int *ymax); [in C]</span>
void wdCanvasGetTextBox(cdCanvas* canvas, double x, double y, const char* text, double *xmin, double *xmax, double *ymin, double *ymax); (WC) [in C]

canvas:GetTextBox(x, y: number, text: string) -&gt; (xmin, xmax, ymin, ymax: number) [in Lua]
canvas:wGetTextBox(x, y: number, text: string) -&gt; (xmin, xmax, ymin, ymax: number) (WC) [in Lua]</pre>

  <p>Returns the horizontal bounding rectangle occupied by a text at a given 
	position. If orientation is not 0 then its area is always larger than the 
	area of the rectangle returned by <strong>GetTextBounds</strong>. It is not necessary 
  to provide all return pointers, you can provide only the desired values and <i><tt>NULL</tt></i> for the others.</p>


</body>

</html>