diff options
Diffstat (limited to 'tk/doc/font.n')
| -rw-r--r-- | tk/doc/font.n | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/tk/doc/font.n b/tk/doc/font.n new file mode 100644 index 00000000000..b7d4b94c340 --- /dev/null +++ b/tk/doc/font.n @@ -0,0 +1,285 @@ +'\" +'\" Copyright (c) 1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH font n 8.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +font \- Create and inspect fonts. +.SH SYNOPSIS +\fBfont\fI option \fR?\fIarg arg ...\fR? +.BE +.SH DESCRIPTION +.PP +The \fBfont\fR command provides several facilities for dealing with +fonts, such as defining named fonts and inspecting the actual attributes of +a font. The command has several different forms, determined by the +first argument. The following forms are currently supported: +.TP +\fBfont actual \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? +. +Returns information about the the actual attributes that are obtained when +\fIfont\fR is used on \fIwindow\fR's display; the actual attributes obtained +may differ from the attributes requested due to platform-dependant +limitations, such as the availability of font families and pointsizes. +\fIfont\fR is a font description; see FONT DESCRIPTIONS below. If the +\fIwindow\fR argument is omitted, it defaults to the main window. If +\fIoption\fR is specified, returns the value of that attribute; if it is +omitted, the return value is a list of all the attributes and their values. +See FONT OPTIONS below for a list of the possible attributes. +.TP +\fBfont configure \fIfontname\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +. +Query or modify the desired attributes for the named font called +\fIfontname\fR. If no \fIoption\fR is specified, returns a list describing +all the options and their values for \fIfontname\fR. If a single \fIoption\fR +is specified with no \fIvalue\fR, then returns the current value of that +attribute. If one or more \fIoption\fR\-\fIvalue\fR pairs are specified, +then the command modifies the given named font to have the given values; in +this case, all widgets using that font will redisplay themselves using the +new attributes for the font. See FONT OPTIONS below for a list of the +possible attributes. +.TP +\fBfont create\fR ?\fIfontname\fR? ?\fIoption value ...\fR? +. +Creates a new named font and returns its name. \fIfontname\fR specifies the +name for the font; if it is omitted, then Tk generates a new name of the +form \fBfont\fIx\fR, where \fIx\fR is an integer. There may be any number +of \fIoption\fR\-\fIvalue\fR pairs, which provide the desired attributes for +the new named font. See FONT OPTIONS below for a list of the possible +attributes. +.TP +\fBfont delete\fR \fIfontname\fR ?\fIfontname ...\fR? +. +Delete the specified named fonts. If there are widgets using the named font, +the named font won't actually be deleted until all the instances are +released. Those widgets will continue to display using the last known values +for the named font. If a deleted named font is subsequently recreated with +another call to \fBfont create\fR, the widgets will use the new named font +and redisplay themselves using the new attributes of that font. +.TP +\fBfont families\fR ?\fB\-displayof \fIwindow\fR? +. +The return value is a list of the case-insensitive names of all font families +that exist on \fIwindow\fR's display. If the \fIwindow\fR argument is +omitted, it defaults to the main window. +.TP +\fBfont measure \fIfont\fR ?\fB\-displayof \fIwindow\fR? \fItext\fR +. +Measures the amount of space the string \fItext\fR would use in the given +\fIfont\fR when displayed in \fIwindow\fR. \fIfont\fR is a font description; +see FONT DESCRIPTIONS below. If the \fIwindow\fR argument is omitted, it +defaults to the main window. The return value is the total width in pixels +of \fItext\fR, not including the extra pixels used by highly exagerrated +characters such as cursive ``f''. If the string contains newlines or tabs, +those characters are not expanded or treated specially when measuring the +string. +.TP +\fBfont metrics \fIfont\fR ?\fB\-displayof \fIwindow\fR? ?\fIoption\fR? +. +Returns information about the metrics (the font-specific data), for +\fIfont\fR when it is used on \fIwindow\fR's display. \fIfont\fR is a font +description; see FONT DESCRIPTIONS below. If the \fIwindow\fR argument is +omitted, it defaults to the main window. If \fIoption\fR is specified, +returns the value of that metric; if it is omitted, the return value is a +list of all the metrics and their values. See FONT METRICS below for a list +of the possible metrics. +.TP +\fBfont names\fR +The return value is a list of all the named fonts that are currently defined. +.SH "FONT DESCRIPTION" +.PP +The following formats are accepted as a font description anywhere +\fIfont\fR is specified as an argument above; these same forms are also +permitted when specifying the \fB\-font\fR option for widgets. +.TP +[1] \fIfontname\fR +. +The name of a named font, created using the \fBfont create\fR command. When +a widget uses a named font, it is guaranteed that this will never cause an +error, as long as the named font exists, no matter what potentially invalid +or meaningless set of attributes the named font has. If the named font +cannot be displayed with exactly the specified attributes, some other close +font will be substituted automatically. +.TP +[2] \fIsystemfont\fR +. +The platform-specific name of a font, interpreted by the graphics server. +This also includes, under X, an XLFD (see [4]) for which a single ``\fB*\fR'' +character was used to elide more than one field in the middle of the +name. See PLATFORM-SPECIFIC issues for a list of the system fonts. +.VS 8.0 br +.TP +[3] \fIfamily \fR?\fIsize\fR? ?\fIstyle\fR? ?\fIstyle ...\fR? +. +A properly formed list whose first element is the desired font +\fIfamily\fR and whose optional second element is the desired \fIsize\fR. +The interpretation of the \fIsize\fR attribute follows the same rules +described for \fB\-size\fR in FONT OPTIONS below. Any additional optional +arguments following the \fIsize\fR are font \fIstyle\fRs. Possible values +for the \fIstyle\fR arguments are as follows: +.RS +.DS +.ta 3c 6c 9c +\fBnormal bold roman italic +underline overstrike\fR +.DE +.RE +.TP +[4] X-font names (XLFD) +. +A Unix-centric font name of the form +\fI-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding\fR. +The ``\fB*\fR'' character may be used to skip individual fields that the +user does not care about. There must be exactly one ``\fB*\fR'' for each +field skipped, except that a ``\fB*\fR'' at the end of the XLFD skips any +remaining fields; the shortest valid XLFD is simply ``\fB*\fR'', signifying +all fields as defaults. Any fields that were skipped are given default +values. For compatibility, an XLFD always chooses a font of the specified +pixel size (not point size); although this interpretation is not strictly +correct, all existing applications using XLFDs assumed that one ``point'' +was in fact one pixel and would display incorrectly (generally larger) if +the correct size font were actually used. +.VE +.TP +[5] \fIoption value \fR?\fIoption value ...\fR? +. +A properly formed list of \fIoption\fR\-\fIvalue\fR pairs that specify +the desired attributes of the font, in the same format used when defining +a named font; see FONT OPTIONS below. +.LP +When font description \fIfont\fR is used, the system attempts to parse the +description according to each of the above five rules, in the order specified. +Cases [1] and [2] must match the name of an existing named font or of a +system font. Cases [3], [4], and [5] are accepted on all +platforms and the closest available font will be used. In some situations +it may not be possible to find any close font (e.g., the font family was +a garbage value); in that case, some system-dependant default font is +chosen. If the font description does not match any of the above patterns, +an error is generated. +.SH "FONT METRICS" +. +The following options are used by the \fBfont metrics\fR command to query +font-specific data determined when the font was created. These properties are +for the whole font itself and not for individual characters drawn in that +font. In the following definitions, the ``baseline'' of a font is the +horizontal line where the bottom of most letters line up; certain letters, +such as lower-case ``g'' stick below the baseline. +.TP +\fB\-ascent \0\fR +. +The amount in pixels that the tallest letter sticks up above the baseline of +the font, plus any extra blank space added by the designer of the font. +.TP +\fB\-descent \0\fR +. +The largest amount in pixels that any letter sticks down below the baseline +of the font, plus any extra blank space added by the designer of the font. +.TP +\fB\-linespace\fR +. +Returns how far apart vertically in pixels two lines of text using the same +font should be placed so that none of the characters in one line overlap any +of the characters in the other line. This is generally the sum of the ascent +above the baseline line plus the descent below the baseline. +.TP +\fB\-fixed \0\fR +. +Returns a boolean flag that is ``\fB1\fR'' if this is a fixed-width font, +where each normal character is the the same width as all the other +characters, or is ``\fB0\fR'' if this is a proportionally-spaced font, where +individual characters have different widths. The widths of control +characters, tab characters, and other non-printing characters are not +included when calculating this value. +.SH "FONT OPTIONS" +The following options are supported on all platforms, and are used when +constructing a named font or when specifying a font using style [5] as +above: +.TP +\fB\-family \fIname\fR +. +The case-insensitive font family name. Tk guarantees to support the font +families named \fBCourier\fR (a monospaced ``typewriter'' font), \fBTimes\fR +(a serifed ``newspaper'' font), and \fBHelvetica\fR (a sans-serif +``European'' font). The most closely matching native font family will +automatically be substituted when one of the above font families is used. +The \fIname\fR may also be the name of a native, platform-specific font +family; in that case it will work as desired on one platform but may not +display correctly on other platforms. If the family is unspecified or +unrecognized, a platform-specific default font will be chosen. +.VS +.TP +\fB\-size \fIsize\fR +. +The desired size of the font. If the \fIsize\fR argument is a positive +number, it is interpreted as a size in points. If \fIsize\fR is a negative +number, its absolute value is interpreted as a size in pixels. If a +font cannot be displayed at the specified size, a nearby size will be +chosen. If \fIsize\fR is unspecified or zero, a platform-dependent default +size will be chosen. +.RS +.PP +Sizes should normally be specified in points so the application will remain +the same ruler size on the screen, even when changing screen resolutions or +moving scripts across platforms. However, specifying pixels is useful in +certain circumstances such as when a piece of text must line up with respect +to a fixed-size bitmap. The mapping between points and pixels is set when +the application starts, based on properties of the installed monitor, but it +can be overridden by calling the \fBtk scaling\fR command. +.RE +.VE +.TP +\fB\-weight \fIweight\fR +. +The nominal thickness of the characters in the font. The value +\fBnormal\fR specifies a normal weight font, while \fBbold\fR specifies a +bold font. The closest available weight to the one specified will +be chosen. The default weight is \fBnormal\fR. +.TP +\fB\-slant \fIslant\fR +The amount the characters in the font are slanted away from the +vertical. Valid values for slant are \fBroman\fR and \fBitalic\fR. +A roman font is the normal, upright appearance of a font, while +an italic font is one that is tilted some number of degrees from upright. +The closest available slant to the one specified will be chosen. +The default slant is \fBroman\fR. +.TP +\fB\-underline \fIboolean\fR +The value is a boolean flag that specifies whether characters in this +font should be underlined. The default value for underline is \fBfalse\fR. +.TP +\fB\-overstrike \fIboolean\fR +The value is a boolean flag that specifies whether a horizontal line should +be drawn through the middle of characters in this font. The default value +for overstrike is \fBfalse\fR. + +.SH "PLATFORM-SPECIFIC ISSUES" +.LP +The following named system fonts are supported: +.RS +.TP +X Windows: +All valid X font names, including those listed by xlsfonts(1), are available. +.TP +MS Windows: +.DS +\fBsystem ansi device +systemfixed ansifixed oemfixed\fR +.DE +.TP +Macintosh: +.DS +\fBsystem application\fR +.DE +.RE +.SH "SEE ALSO" +options + +.SH KEYWORDS +font |