font(3)

NAME

font - Create and inspect fonts.

SYNOPSIS

$widget->Font(option?, arg, arg, ...?)
$font->Option?(arg, arg, ...)?

DESCRIPTION

The Font method 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:

$font->actual(-option?)
$widget->fontActual(font?, -option?): Returns information about the actual attributes that
are obtained when font is used on $font's display; the actual attributes obtained may differ from the
attributes requested due to platform-dependant limita
tions, such as the availability of font families and
pointsizes. font is a font description; see "FONT
DESCRIPTION" below. If option 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.
$font->configure(-option??=>value, -option=>value, ...?): Query or modify the desired attributes for $font. If
no -option is specified, returns a list describing all the options and their values for fontname. If a sin gle -option is specified with no value, then returns the current value of that attribute. If one or more
option-value pairs are specified, then the method mod ifies the given named font to have the given values;
in this case, all widgets using that font will redis
play themselves using the new attributes for the font.
See "FONT OPTIONS" below for a list of the possible
attributes.; Note: the above behaviour differs in detail to config
ure on widgets, images etc.
$font = $widget->Font(-option=>value, ...>?) $font = $widget->fontCreate(?fontname??, -option=>value, ...>?): Creates a new font object and returns a reference to
it. fontname specifies the name for the font; if it is omitted, then Tk generates a new name of the form
fontx, where x is an integer. There may be any number of option-value pairs, which provide the desired attributes for the new named font. See "FONT OPTIONS"
below for a list of the possible attributes.; Note: the created font is not shared between widgets
of different MainWindows.
$font->delete
$widget->fontDelete(fontname?, fontname, ...?): 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 fontCreate, the widgets will use the new named font and redisplay themselves using the new
attributes of that font.
$widget->fontFamilies: The return value is a list of the case-insensitive
names of all font families that exist on $widget's
display.
$font->measure(text)
$widget->fontMeasure(font, text): Measures the amount of space the string text would use
in the given font when displayed in $widget. font is a font description; see "FONT DESCRIPTION" below. The
return value is the total width in pixels of text, not
including the extra pixels used by highly exagerrated
characters such as cursive ``f''. If the string con
tains newlines or tabs, those characters are not
expanded or treated specially when measuring the
string.
$font->metrics(-option?)
$widget->fontMetrics(font?, -option?): Returns information about the metrics (the font-spe
cific data), for font when it is used on $widget's display. font is a font description; see "FONT
DESCRIPTION" below. If option 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.
$widget->fontNames: The return value is a list of all font objects that
are currently defined for $widget's MainWindow.

FONT DESCRIPTION

The following formats are accepted as a font description
anywhere font is specified as an argument above; these
same forms are also permitted when specifying the -font
option for widgets.

[1] fontname: The name of a named font, created using the fontCreate method. When a widget uses a named font, it is guar
anteed 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.
[1a] $font: A font object created using the Font method. This is
essentially the same as using a named font. The object
is a reference to the name, and carries additional
information e.g. which MainWindow it relates to in an
manner peculiar to perl/Tk.
[3] systemfont: 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 ``*'' 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.
[3] [family,?size,??style,??style ...?]: A properly formed list whose first element is the
desired font family and whose optional second element
is the desired size. The interpretation of the size attribute follows the same rules described for -size
in "FONT OPTIONS" below. Any additional optional
arguments following the size are font styles. Possi ble values for the style arguments are as follows:

normal bold roman italic
underline overstrike
[4] X-font names (XLFD): A Unix-centric font name of the form -foundry-fam_ ily-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spac_ ing-width-charset-encoding. The ``*'' character may be used to skip individual fields that the user does
not care about. There must be exactly one ``*'' for
each field skipped, except that a ``*'' at the end of
the XLFD skips any remaining fields; the shortest
valid XLFD is simply ``*'', 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.
[5] option value ?option value ...?: A properly formed list of option-value pairs that specify the desired attributes of the font, in the
same format used when defining a named font; see "FONT
OPTIONS" below.
When font description font 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 plat forms 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 pat terns, an error is generated.

FONT METRICS

The following options are used by the metrics/fontMetrics method 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 let
ters line up; certain letters, such as lower-case ``g''
stick below the baseline.

-ascent: 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.
($font-<gt>ascent is provided for compatibility.)
-descent: 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.
($font-<gt>descent is provided for compatibility.)
-linespace: 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.
-fixed: Returns a boolean flag that is ``1'' if this is a
fixed-width font, where each normal character is the
the same width as all the other characters, or is
``0'' 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.

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:

-family => name: The case-insensitive font family name. Tk guarantees
to support the font families named Courier (a
monospaced ``typewriter'' font), Times (a serifed
``newspaper'' font), and Helvetica (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 name may also
be the name of a native, platform-specific font fam
ily; in that case it will work as desired on one plat
form but may not display correctly on other platforms.
If the family is unspecified or unrecognized, a plat
form-specific default font will be chosen.
-size => size: The desired size of the font. If the size argument is
a positive number, it is interpreted as a size in
points. If size 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 size is unspecified or zero,
a platform-dependent default size will be chosen.; The original Tcl/Tk authors believe sizes should nor
mally 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. While this is an admirable goal it does not
work as well in practice as they hoped. The mapping
between points and pixels is set when the application
starts, based on alleged properties of the installed
monitor, but it can be overridden by calling the
scaling command. However this can be problematic when
system has no way of telling if (say) an 11" or 22"
monitor is attached, also if it can tell then some
monitor sizes may result in poorer quality scaled
fonts being used rather than a "tuned" bitmap font.
In addition specifying pixels is useful in certain
circumstances such as when a piece of text must line
up with respect to a fixed-size bitmap.; At present the Tcl/Tk scheme is used unchanged, with
"point" size being returned by actual (as an integer), and used internally. Suggestions for work-rounds to
undesirable behaviour welcome.
-weight => weight: The nominal thickness of the characters in the font.
The value normal specifies a normal weight font, while bold specifies a bold font. The closest available
weight to the one specified will be chosen. The
default weight is normal.
-slant => slant: The amount the characters in the font are slanted away
from the vertical. Valid values for slant are roman
and italic. 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 roman.
-underline => boolean: The value is a boolean flag that specifies whether
characters in this font should be underlined. The
default value for underline is false.
-overstrike => boolean: 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 over
strike is false.

PLATFORM-SPECIFIC ISSUES

The following named system fonts are supported:

X Windows:: All valid X font names, including those listed by xls_
fonts(1), are available.
MS Windows:: system ansi device
systemfixed ansifixed oemfixed
Macintosh:: system application

COMPATIBILITY WITH PREVIOUS VERSIONS

In prior versions of perl/Tk the $widget->Font method was a perl wrapper on the original "[4] X-font names (XLFD)"
style as described above (which was the only form sup
ported by versions of core tk prior to version tk8.0).
This module is provided in its original form (it has just
been renamed) via:: use Tk::X11Font;
I<$widget>-E<gt>B<X11Font>(...)
However the methods of the old scheme have been mimiced as closely as possible with the new scheme. It is intended that code should work without modification, except for the case of using :: @names = $font->Name;
i.e. the Name method in an array/list context. This now returns one element on all platforms (as it did on Win32), while previously on X systems it returned a list of fonts that matched an under-specified pattern.
Briefly the methods supported for compatibilty are as fol lows:
$newfont = $font->Clone(-option=>value, ...>?): Returns a new font object $newfont related to the
original $font by changing the values of the specified
-options.
$font->Family - maps to -family $font->Weight - maps to -weight $font->Slant - maps to -slant $font->Pixel and Point - map to -size
New code should use $font->configure to achieve same effect as last four items above.
Foundry, Swidth, Adstyle, Xres, Yres, Space, Avgwidth, Registry, Encoding: Are all ignored if set, and return '*' if queried.
$font->Name: Returns the name of a named font, or a string repre
sentation of an unnamed font. Using $font in a scalar
context does the same. Note this is distinctly differ
ent from behaviour of X11Font's Name in a list con
text.
$font->Pattern: Returns a XLFD string for the font based on actual
values, and some heuristics to map Tk's forms to the
"standard" X conventions.

KEYWORDS

font

docs.sk

comprehensive documentation repository

In section