diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Font.pod')
| -rwxr-xr-x | Master/tlpkg/tlperl/lib/Tk/Font.pod | 407 |
1 files changed, 407 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Font.pod b/Master/tlpkg/tlperl/lib/Tk/Font.pod new file mode 100755 index 00000000000..594efa58bca --- /dev/null +++ b/Master/tlpkg/tlperl/lib/Tk/Font.pod @@ -0,0 +1,407 @@ +# 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. +# +# + +=head1 NAME + +font - Create and inspect fonts. + +=for category Tk Generic Methods + +=head1 SYNOPSIS + +S< >I<$widget>->B<Font>(I<option>?, I<arg, arg, ...>?) + +S< >I<$font>->I<Option>?(I<arg, arg, ...>)? + +=head1 DESCRIPTION + +The B<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: + +=over 4 + +=item I<$font>-E<gt>B<actual>(I<-option>?) + +=item I<$widget>-E<gt>B<fontActual>(I<font>?, I<-option>?) + +Returns information about the actual attributes that are obtained when +I<font> is used on I<$font>'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. +I<font> is a font description; see L<"FONT DESCRIPTION"> below. If +I<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 L<"FONT OPTIONS"> below for a list of the possible attributes. + +=item I<$font>-E<gt>B<configure>(I<-option>??=>I<value>, I<-option>=>I<value>, ...?) + +Query or modify the desired attributes for I<$font>. +If no I<-option> is specified, returns a list describing +all the options and their values for I<fontname>. If a single I<-option> +is specified with no I<value>, then returns the current value of that +attribute. If one or more I<option-value> pairs are specified, +then the method 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 L<"FONT OPTIONS"> below for a list of the +possible attributes. + +Note: the above behaviour differs in detail to B<configure> on widgets, +images etc. + +=item I<$font> = I<$widget>-E<gt>B<Font>(I<-option>=>I<value>, ...>?) + +=item I<$font> = I<$widget>-E<gt>B<fontCreate>(?I<fontname>??, I<-option>=>I<value>, ...>?) + +Creates a new font object and returns a reference to it. +I<fontname> specifies the name for the font; if it is omitted, then Tk generates +a new name of the form B<font>I<x>, where I<x> is an integer. There may be any +number of I<option-value> pairs, which provide the desired attributes for +the new named font. See L<"FONT OPTIONS"> below for a list of the possible +attributes. + +Note: the created font is I<not> shared between widgets of different +L<MainWindow|Tk::MainWindow>s. + +=item I<$font>-E<gt>B<delete> + +=item I<$widget>-E<gt>B<fontDelete>(I<fontname>?, I<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 B<fontCreate>, the widgets will use the new named font +and redisplay themselves using the new attributes of that font. + +=item I<$widget>-E<gt>B<fontFamilies> + +The return value is a list of the case-insensitive names of all font families +that exist on I<$widget>'s display. + +=item I<$font>-E<gt>B<measure>(I<text>) + +=item I<$widget>-E<gt>B<fontMeasure>(I<font>, I<text>) + +Measures the amount of space the string I<text> would use in the given +I<font> when displayed in I<$widget>. I<font> is a font description; +see L<"FONT DESCRIPTION"> below. +The return value is the total width in pixels +of I<text>, not including the extra pixels used by highly exagerrated +characters such as cursive ``I<f>''. If the string contains newlines or tabs, +those characters are not expanded or treated specially when measuring the +string. + +=item I<$font>-E<gt>B<metrics>(I<-option>?) + +=item I<$widget>-E<gt>B<fontMetrics>(I<font>?, I<-option>?) + +Returns information about the metrics (the font-specific data), for +I<font> when it is used on I<$widget>'s display. I<font> is a font +description; see L<"FONT DESCRIPTION"> below. +If I<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 L<"FONT METRICS"> below for a list +of the possible metrics. + +=item I<$widget>-E<gt>B<fontNames> + +The return value is a list of all font objects that are currently defined for +I<$widget>'s MainWindow. + +=back + +=head1 FONT DESCRIPTION + +The following formats are accepted as a font description anywhere +I<font> is specified as an argument above; these same forms are also +permitted when specifying the B<-font> option for widgets. + +=over 4 + +=item [1] I<fontname> + +The name of a named font, created using the B<fontCreate> method. 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. + +=item [1a] I<$font> + +A font object created using the B<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. + +=item [3] I<systemfont> + +The platform-specific name of a font, interpreted by the graphics server. +This also includes, under X, an XLFD (see L<[4]|/[4]>) for which a single ``B<*>'' +character was used to elide more than one field in the middle of the +name. See L<"PLATFORM-SPECIFIC ISSUES"> for a list of the system fonts. + +=item [3] [I<family>,?I<size>,??I<style>,??I<style ...>?] + +A properly formed list whose first element is the desired font +I<family> and whose optional second element is the desired I<size>. +The interpretation of the I<size> attribute follows the same rules +described for L<-size|/-size> in L<"FONT OPTIONS"> below. Any additional optional +arguments following the I<size> are font I<style>s. Possible values +for the I<style> arguments are as follows: + + normal bold roman italic + underline overstrike + +=item [4] X-font names (XLFD) + +A Unix-centric font name of the form +I<-foundry-family-weight-slant-setwidth-addstyle-pixel-point-resx-resy-spacing-width-charset-encoding>. +The ``B<*>'' character may be used to skip individual fields that the +user does not care about. There must be exactly one ``B<*>'' for each +field skipped, except that a ``B<*>'' at the end of the XLFD skips any +remaining fields; the shortest valid XLFD is simply ``B<*>'', 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. + +=item [5] I<option value >?I<option value ...>? + +A properly formed list of I<option-value> pairs that specify +the desired attributes of the font, in the same format used when defining +a named font; see L<"FONT OPTIONS"> below. + +=back + +When font description I<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 +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. + +=head1 FONT METRICS + +The following options are used by the B<metrics>/B<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 letters line up; certain letters, +such as lower-case ``g'' stick below the baseline. + +=over 4 + +=item B<-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. +(I<$font>-E<gt>B<ascent> is provided for compatibility.) + +=item B<-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. +(I<$font>-E<gt>B<descent> is provided for compatibility.) + +=item B<-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. + +=item B<-fixed> + +Returns a boolean flag that is ``B<1>'' if this is a fixed-width font, +where each normal character is the the same width as all the other +characters, or is ``B<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. + +=back + +=head1 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: + +=over 4 + +=item B<-family> => I<name> + +The case-insensitive font family name. Tk guarantees to support the font +families named B<Courier> (a monospaced ``typewriter'' font), B<Times> +(a serifed ``newspaper'' font), and B<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 I<name> 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. + +=item B<-size> => I<size> + +The desired size of the font. If the I<size> argument is a positive +number, it is interpreted as a size in points. If I<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 I<size> is unspecified or zero, a platform-dependent default +size will be chosen. + +The original Tcl/Tk authors believe 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. 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 L<scaling|Tk::Widget/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 I<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 I<actual> (as an integer), and used internally. Suggestions for work-rounds +to undesirable behaviour welcome. + +=item B<-weight> => I<weight> + +The nominal thickness of the characters in the font. The value +B<normal> specifies a normal weight font, while B<bold> specifies a +bold font. The closest available weight to the one specified will +be chosen. The default weight is B<normal>. + +=item B<-slant> => I<slant> + +The amount the characters in the font are slanted away from the +vertical. Valid values for slant are B<roman> and B<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 B<roman>. + +=item B<-underline> => I<boolean> + +The value is a boolean flag that specifies whether characters in this +font should be underlined. The default value for underline is B<false>. + +=item B<-overstrike> => I<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 overstrike is B<false>. + +=back + +=head1 PLATFORM-SPECIFIC ISSUES + +The following named system fonts are supported: + +=over 4 + +=item X Windows: + +All valid X font names, including those listed by xlsfonts(1), are available. + +=item MS Windows: + + system ansi device + systemfixed ansifixed oemfixed + +=item Macintosh: + + system application + +=back + +=head1 COMPATIBILITY WITH PREVIOUS VERSIONS + +In prior versions of perl/Tk the I<$widget>-E<gt>B<Font> method was a perl +wrapper on the original "[4] X-font names (XLFD)" style as described above +(which was the only form supported 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 I<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 follows: + +=over 4 + +=item $newfont = I<$font>-E<gt>B<Clone>(I<-option>=>I<value>, ...>?) + +Returns a new font object I<$newfont> related to the original I<$font> by +changing the values of the specified I<-option>s. + +=item I<$font>-E<gt>Family - maps to -family + +=item I<$font>-E<gt>Weight - maps to -weight + +=item I<$font>-E<gt>Slant - maps to -slant + +=item I<$font>-E<gt>Pixel and Point - map to -size + +=back + +New code should use I<$font>-E<gt>B<configure> to achieve same effect as last +four items above. + +=over 4 + +=item Foundry, Swidth, Adstyle, Xres, Yres, Space, Avgwidth, Registry, Encoding + +Are all ignored if set, and return '*' if queried. + +=item I<$font>-E<gt>B<Name> + +Returns the name of a named font, or a string representation of an unnamed +font. Using I<$font> in a scalar context does the same. Note this is distinctly +different from behaviour of L<X11Font's Name|Tk::X11Font/Name( [ $max ] )> in +a list context. + +=item I<$font>-E<gt>B<Pattern> + +Returns a XLFD string for the font based on I<actual> values, and some heuristics +to map Tk's forms to the "standard" X conventions. + +=back + + +=head1 SEE ALSO + +L<Tk::options|Tk::options> + +L<Tk::X11Font|Tk::X11Font> + +=head1 KEYWORDS + +font + +=cut + |