diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/Font.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/Font.pod | 407 |
1 files changed, 0 insertions, 407 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Font.pod b/Master/tlpkg/tlperl/lib/Tk/Font.pod deleted file mode 100644 index 594efa58bca..00000000000 --- a/Master/tlpkg/tlperl/lib/Tk/Font.pod +++ /dev/null @@ -1,407 +0,0 @@ -# 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 - |