Initial revision

1 files changed, 285 insertions, 0 deletions

diff --git a/doc/font.n b/doc/font.n
new file mode 100644
index 0000000..d3e5878
--- /dev/null
+++ b/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.
+'\" 
+'\" SCCS: @(#) font.n 1.10 97/08/22 18:52:18
+'\" 
+.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