Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1996 Sun Microsystems, Inc. |
2 | # See the file "license.terms" for information on usage and redistribution | |
3 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
4 | # | |
5 | # | |
6 | ||
7 | =head1 NAME | |
8 | ||
9 | font - Create and inspect fonts. | |
10 | ||
11 | =for category Tk Generic Methods | |
12 | ||
13 | =head1 SYNOPSIS | |
14 | ||
15 | S< >I<$widget>->B<Font>(I<option>?, I<arg, arg, ...>?) | |
16 | ||
17 | S< >I<$font>->I<Option>?(I<arg, arg, ...>)? | |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | The B<Font> method provides several facilities for dealing with | |
22 | fonts, such as defining named fonts and inspecting the actual attributes of | |
23 | a font. The command has several different forms, determined by the | |
24 | first argument. The following forms are currently supported: | |
25 | ||
26 | =over 4 | |
27 | ||
28 | =item I<$font>-E<gt>B<actual>(I<-option>?) | |
29 | ||
30 | =item I<$widget>-E<gt>B<fontActual>(I<font>?, I<-option>?) | |
31 | ||
32 | Returns information about the actual attributes that are obtained when | |
33 | I<font> is used on I<$font>'s display; the actual attributes obtained | |
34 | may differ from the attributes requested due to platform-dependant | |
35 | limitations, such as the availability of font families and pointsizes. | |
36 | I<font> is a font description; see L<"FONT DESCRIPTION"> below. If | |
37 | I<option> is specified, returns the value of that attribute; if it is | |
38 | omitted, the return value is a list of all the attributes and their values. | |
39 | See L<"FONT OPTIONS"> below for a list of the possible attributes. | |
40 | ||
41 | =item I<$font>-E<gt>B<configure>(I<-option>??=>I<value>, I<-option>=>I<value>, ...?) | |
42 | ||
43 | Query or modify the desired attributes for I<$font>. | |
44 | If no I<-option> is specified, returns a list describing | |
45 | all the options and their values for I<fontname>. If a single I<-option> | |
46 | is specified with no I<value>, then returns the current value of that | |
47 | attribute. If one or more I<option-value> pairs are specified, | |
48 | then the method modifies the given named font to have the given values; in | |
49 | this case, all widgets using that font will redisplay themselves using the | |
50 | new attributes for the font. See L<"FONT OPTIONS"> below for a list of the | |
51 | possible attributes. | |
52 | ||
53 | Note: the above behaviour differs in detail to B<configure> on widgets, | |
54 | images etc. | |
55 | ||
56 | =item I<$font> = I<$widget>-E<gt>B<Font>(I<-option>=>I<value>, ...>?) | |
57 | ||
58 | =item I<$font> = I<$widget>-E<gt>B<fontCreate>(?I<fontname>??, I<-option>=>I<value>, ...>?) | |
59 | ||
60 | Creates a new font object and returns a reference to it. | |
61 | I<fontname> specifies the name for the font; if it is omitted, then Tk generates | |
62 | a new name of the form B<font>I<x>, where I<x> is an integer. There may be any | |
63 | number of I<option-value> pairs, which provide the desired attributes for | |
64 | the new named font. See L<"FONT OPTIONS"> below for a list of the possible | |
65 | attributes. | |
66 | ||
67 | Note: the created font is I<not> shared between widgets of different | |
68 | L<MainWindow|Tk::MainWindow>s. | |
69 | ||
70 | =item I<$font>-E<gt>B<delete> | |
71 | ||
72 | =item I<$widget>-E<gt>B<fontDelete>(I<fontname>?, I<fontname>, ...?) | |
73 | ||
74 | Delete the specified named fonts. If there are widgets using the named font, | |
75 | the named font won't actually be deleted until all the instances are | |
76 | released. Those widgets will continue to display using the last known values | |
77 | for the named font. If a deleted named font is subsequently recreated with | |
78 | another call to B<fontCreate>, the widgets will use the new named font | |
79 | and redisplay themselves using the new attributes of that font. | |
80 | ||
81 | =item I<$widget>-E<gt>B<fontFamilies> | |
82 | ||
83 | The return value is a list of the case-insensitive names of all font families | |
84 | that exist on I<$widget>'s display. | |
85 | ||
86 | =item I<$font>-E<gt>B<measure>(I<text>) | |
87 | ||
88 | =item I<$widget>-E<gt>B<fontMeasure>(I<font>, I<text>) | |
89 | ||
90 | Measures the amount of space the string I<text> would use in the given | |
91 | I<font> when displayed in I<$widget>. I<font> is a font description; | |
92 | see L<"FONT DESCRIPTION"> below. | |
93 | The return value is the total width in pixels | |
94 | of I<text>, not including the extra pixels used by highly exagerrated | |
95 | characters such as cursive ``I<f>''. If the string contains newlines or tabs, | |
96 | those characters are not expanded or treated specially when measuring the | |
97 | string. | |
98 | ||
99 | =item I<$font>-E<gt>B<metrics>(I<-option>?) | |
100 | ||
101 | =item I<$widget>-E<gt>B<fontMetrics>(I<font>?, I<-option>?) | |
102 | ||
103 | Returns information about the metrics (the font-specific data), for | |
104 | I<font> when it is used on I<$widget>'s display. I<font> is a font | |
105 | description; see L<"FONT DESCRIPTION"> below. | |
106 | If I<option> is specified, | |
107 | returns the value of that metric; if it is omitted, the return value is a | |
108 | list of all the metrics and their values. See L<"FONT METRICS"> below for a list | |
109 | of the possible metrics. | |
110 | ||
111 | =item I<$widget>-E<gt>B<fontNames> | |
112 | ||
113 | The return value is a list of all font objects that are currently defined for | |
114 | I<$widget>'s MainWindow. | |
115 | ||
116 | =back | |
117 | ||
118 | =head1 FONT DESCRIPTION | |
119 | ||
120 | The following formats are accepted as a font description anywhere | |
121 | I<font> is specified as an argument above; these same forms are also | |
122 | permitted when specifying the B<-font> option for widgets. | |
123 | ||
124 | =over 4 | |
125 | ||
126 | =item [1] I<fontname> | |
127 | ||
128 | The name of a named font, created using the B<fontCreate> method. When | |
129 | a widget uses a named font, it is guaranteed that this will never cause an | |
130 | error, as long as the named font exists, no matter what potentially invalid | |
131 | or meaningless set of attributes the named font has. If the named font | |
132 | cannot be displayed with exactly the specified attributes, some other close | |
133 | font will be substituted automatically. | |
134 | ||
135 | =item [1a] I<$font> | |
136 | ||
137 | A font object created using the B<Font> method. This is essentially the same | |
138 | as using a named font. The object is a reference to the name, and carries | |
139 | additional information e.g. which MainWindow it relates to in an manner peculiar | |
140 | to perl/Tk. | |
141 | ||
142 | =item [3] I<systemfont> | |
143 | ||
144 | The platform-specific name of a font, interpreted by the graphics server. | |
145 | This also includes, under X, an XLFD (see L<[4]|/[4]>) for which a single ``B<*>'' | |
146 | character was used to elide more than one field in the middle of the | |
147 | name. See L<"PLATFORM-SPECIFIC ISSUES"> for a list of the system fonts. | |
148 | ||
149 | =item [3] [I<family>,?I<size>,??I<style>,??I<style ...>?] | |
150 | ||
151 | A properly formed list whose first element is the desired font | |
152 | I<family> and whose optional second element is the desired I<size>. | |
153 | The interpretation of the I<size> attribute follows the same rules | |
154 | described for L<-size|/-size> in L<"FONT OPTIONS"> below. Any additional optional | |
155 | arguments following the I<size> are font I<style>s. Possible values | |
156 | for the I<style> arguments are as follows: | |
157 | ||
158 | normal bold roman italic | |
159 | underline overstrike | |
160 | ||
161 | =item [4] X-font names (XLFD) | |
162 | ||
163 | A Unix-centric font name of the form | |
164 | I<-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding>. | |
165 | The ``B<*>'' character may be used to skip individual fields that the | |
166 | user does not care about. There must be exactly one ``B<*>'' for each | |
167 | field skipped, except that a ``B<*>'' at the end of the XLFD skips any | |
168 | remaining fields; the shortest valid XLFD is simply ``B<*>'', signifying | |
169 | all fields as defaults. Any fields that were skipped are given default | |
170 | values. For compatibility, an XLFD always chooses a font of the specified | |
171 | pixel size (not point size); although this interpretation is not strictly | |
172 | correct, all existing applications using XLFDs assumed that one ``point'' | |
173 | was in fact one pixel and would display incorrectly (generally larger) if | |
174 | the correct size font were actually used. | |
175 | ||
176 | =item [5] I<option value >?I<option value ...>? | |
177 | ||
178 | A properly formed list of I<option-value> pairs that specify | |
179 | the desired attributes of the font, in the same format used when defining | |
180 | a named font; see L<"FONT OPTIONS"> below. | |
181 | ||
182 | =back | |
183 | ||
184 | When font description I<font> is used, the system attempts to parse the | |
185 | description according to each of the above five rules, in the order specified. | |
186 | Cases [1] and [2] must match the name of an existing named font or of a | |
187 | system font. Cases [3], [4], and [5] are accepted on all | |
188 | platforms and the closest available font will be used. In some situations | |
189 | it may not be possible to find any close font (e.g., the font family was | |
190 | a garbage value); in that case, some system-dependant default font is | |
191 | chosen. If the font description does not match any of the above patterns, | |
192 | an error is generated. | |
193 | ||
194 | =head1 FONT METRICS | |
195 | ||
196 | The following options are used by the B<metrics>/B<fontMetrics> method to query | |
197 | font-specific data determined when the font was created. These properties are | |
198 | for the whole font itself and not for individual characters drawn in that | |
199 | font. In the following definitions, the ``baseline'' of a font is the | |
200 | horizontal line where the bottom of most letters line up; certain letters, | |
201 | such as lower-case ``g'' stick below the baseline. | |
202 | ||
203 | =over 4 | |
204 | ||
205 | =item B<-ascent> | |
206 | ||
207 | The amount in pixels that the tallest letter sticks up above the baseline of | |
208 | the font, plus any extra blank space added by the designer of the font. | |
209 | (I<$font>-<gt>B<ascent> is provided for compatibility.) | |
210 | ||
211 | =item B<-descent> | |
212 | ||
213 | The largest amount in pixels that any letter sticks down below the baseline | |
214 | of the font, plus any extra blank space added by the designer of the font. | |
215 | (I<$font>-<gt>B<descent> is provided for compatibility.) | |
216 | ||
217 | =item B<-linespace> | |
218 | ||
219 | Returns how far apart vertically in pixels two lines of text using the same | |
220 | font should be placed so that none of the characters in one line overlap any | |
221 | of the characters in the other line. This is generally the sum of the ascent | |
222 | above the baseline line plus the descent below the baseline. | |
223 | ||
224 | =item B<-fixed> | |
225 | ||
226 | Returns a boolean flag that is ``B<1>'' if this is a fixed-width font, | |
227 | where each normal character is the the same width as all the other | |
228 | characters, or is ``B<0>'' if this is a proportionally-spaced font, where | |
229 | individual characters have different widths. The widths of control | |
230 | characters, tab characters, and other non-printing characters are not | |
231 | included when calculating this value. | |
232 | ||
233 | =back | |
234 | ||
235 | =head1 FONT OPTIONS | |
236 | ||
237 | The following options are supported on all platforms, and are used when | |
238 | constructing a named font or when specifying a font using style [5] as | |
239 | above: | |
240 | ||
241 | =over 4 | |
242 | ||
243 | =item B<-family> => I<name> | |
244 | ||
245 | The case-insensitive font family name. Tk guarantees to support the font | |
246 | families named B<Courier> (a monospaced ``typewriter'' font), B<Times> | |
247 | (a serifed ``newspaper'' font), and B<Helvetica> (a sans-serif | |
248 | ``European'' font). The most closely matching native font family will | |
249 | automatically be substituted when one of the above font families is used. | |
250 | The I<name> may also be the name of a native, platform-specific font | |
251 | family; in that case it will work as desired on one platform but may not | |
252 | display correctly on other platforms. If the family is unspecified or | |
253 | unrecognized, a platform-specific default font will be chosen. | |
254 | ||
255 | =item B<-size> => I<size> | |
256 | ||
257 | The desired size of the font. If the I<size> argument is a positive | |
258 | number, it is interpreted as a size in points. If I<size> is a negative | |
259 | number, its absolute value is interpreted as a size in pixels. If a | |
260 | font cannot be displayed at the specified size, a nearby size will be | |
261 | chosen. If I<size> is unspecified or zero, a platform-dependent default | |
262 | size will be chosen. | |
263 | ||
264 | The original Tcl/Tk authors believe sizes should normally be specified in points | |
265 | so the application will remain the same ruler size on the screen, even when | |
266 | changing screen resolutions or moving scripts across platforms. While this is an | |
267 | admirable goal it does not work as well in practice as they hoped. | |
268 | The mapping between points and pixels is set when the application starts, based | |
269 | on alleged properties of the installed monitor, but it can be overridden by | |
270 | calling the L<scaling|Tk::Widget/scaling> command. However this can be | |
271 | problematic when system has no way of telling if (say) an 11" or 22" monitor is | |
272 | attached, also if it I<can> tell then some monitor sizes may result in poorer | |
273 | quality scaled fonts being used rather than a "tuned" bitmap font. | |
274 | In addition specifying pixels is useful in certain circumstances such as when a piece of text | |
275 | must line up with respect to a fixed-size bitmap. | |
276 | ||
277 | At present the Tcl/Tk scheme is used unchanged, with "point" size being returned | |
278 | by I<actual> (as an integer), and used internally. Suggestions for work-rounds | |
279 | to undesirable behaviour welcome. | |
280 | ||
281 | =item B<-weight> => I<weight> | |
282 | ||
283 | The nominal thickness of the characters in the font. The value | |
284 | B<normal> specifies a normal weight font, while B<bold> specifies a | |
285 | bold font. The closest available weight to the one specified will | |
286 | be chosen. The default weight is B<normal>. | |
287 | ||
288 | =item B<-slant> => I<slant> | |
289 | ||
290 | The amount the characters in the font are slanted away from the | |
291 | vertical. Valid values for slant are B<roman> and B<italic>. | |
292 | A roman font is the normal, upright appearance of a font, while | |
293 | an italic font is one that is tilted some number of degrees from upright. | |
294 | The closest available slant to the one specified will be chosen. | |
295 | The default slant is B<roman>. | |
296 | ||
297 | =item B<-underline> => I<boolean> | |
298 | ||
299 | The value is a boolean flag that specifies whether characters in this | |
300 | font should be underlined. The default value for underline is B<false>. | |
301 | ||
302 | =item B<-overstrike> => I<boolean> | |
303 | ||
304 | The value is a boolean flag that specifies whether a horizontal line should | |
305 | be drawn through the middle of characters in this font. The default value | |
306 | for overstrike is B<false>. | |
307 | ||
308 | =back | |
309 | ||
310 | =head1 PLATFORM-SPECIFIC ISSUES | |
311 | ||
312 | The following named system fonts are supported: | |
313 | ||
314 | =over 4 | |
315 | ||
316 | =item X Windows: | |
317 | ||
318 | All valid X font names, including those listed by xlsfonts(1), are available. | |
319 | ||
320 | =item MS Windows: | |
321 | ||
322 | system ansi device | |
323 | systemfixed ansifixed oemfixed | |
324 | ||
325 | =item Macintosh: | |
326 | ||
327 | system application | |
328 | ||
329 | =back | |
330 | ||
331 | =head1 COMPATIBILITY WITH PREVIOUS VERSIONS | |
332 | ||
333 | In prior versions of perl/Tk the I<$widget>-E<gt>B<Font> method was a perl | |
334 | wrapper on the original "[4] X-font names (XLFD)" style as described above | |
335 | (which was the only form supported by versions of core tk prior to version | |
336 | tk8.0). | |
337 | This module is provided in its original form (it has just been renamed) | |
338 | via: | |
339 | ||
340 | use Tk::X11Font; | |
341 | I<$widget>-E<gt>B<X11Font>(...) | |
342 | ||
343 | However the methods of the old scheme have been mimiced as closely as possible | |
344 | with the new scheme. It is intended that code should work without modification, | |
345 | except for the case of using : | |
346 | ||
347 | @names = $font->Name; | |
348 | ||
349 | i.e. the I<Name> method in an array/list context. This now returns one element | |
350 | on all platforms (as it did on Win32), while previously on X systems it returned | |
351 | a list of fonts that matched an under-specified pattern. | |
352 | ||
353 | Briefly the methods supported for compatibilty are as follows: | |
354 | ||
355 | =over 4 | |
356 | ||
357 | =item $newfont = I<$font>-E<gt>B<Clone>(I<-option>=>I<value>, ...>?) | |
358 | ||
359 | Returns a new font object I<$newfont> related to the original I<$font> by | |
360 | changing the values of the specified I<-option>s. | |
361 | ||
362 | =item I<$font>-E<gt>Family - maps to -family | |
363 | ||
364 | =item I<$font>-E<gt>Weight - maps to -weight | |
365 | ||
366 | =item I<$font>-E<gt>Slant - maps to -slant | |
367 | ||
368 | =item I<$font>-E<gt>Pixel and Point - map to -size | |
369 | ||
370 | =back | |
371 | ||
372 | New code should use I<$font>-E<gt>B<configure> to achieve same effect as last | |
373 | four items above. | |
374 | ||
375 | =over 4 | |
376 | ||
377 | =item Foundry, Swidth, Adstyle, Xres, Yres, Space, Avgwidth, Registry, Encoding | |
378 | ||
379 | Are all ignored if set, and return '*' if queried. | |
380 | ||
381 | =item I<$font>-E<gt>B<Name> | |
382 | ||
383 | Returns the name of a named font, or a string representation of an unnamed | |
384 | font. Using I<$font> in a scalar context does the same. Note this is distinctly | |
385 | different from behaviour of L<X11Font's Name|Tk::X11Font/Name( [ $max ] )> in | |
386 | a list context. | |
387 | ||
388 | =item I<$font>-E<gt>B<Pattern> | |
389 | ||
390 | Returns a XLFD string for the font based on I<actual> values, and some heuristics | |
391 | to map Tk's forms to the "standard" X conventions. | |
392 | ||
393 | =back | |
394 | ||
395 | ||
396 | =head1 SEE ALSO | |
397 | ||
398 | L<Tk::options|Tk::options> | |
399 | ||
400 | L<Tk::X11Font|Tk::X11Font> | |
401 | ||
402 | =head1 KEYWORDS | |
403 | ||
404 | font | |
405 | ||
406 | =cut | |
407 |