mirror of
https://github.com/python/cpython.git
synced 2026-08-03 10:30:28 +08:00
fa5eafd19c
Explain the displayof argument of tkinter.font.Font.actual() and describe what Font.copy() returns, including for a wrapped font description. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
149 lines
5.4 KiB
ReStructuredText
149 lines
5.4 KiB
ReStructuredText
:mod:`!tkinter.font` --- Tkinter font wrapper
|
|
=============================================
|
|
|
|
.. module:: tkinter.font
|
|
:synopsis: Tkinter font-wrapping class
|
|
|
|
**Source code:** :source:`Lib/tkinter/font.py`
|
|
|
|
--------------
|
|
|
|
The :mod:`!tkinter.font` module provides the :class:`Font` class for creating
|
|
and using named fonts.
|
|
|
|
The different font weights and slants are:
|
|
|
|
.. data:: NORMAL
|
|
BOLD
|
|
ITALIC
|
|
ROMAN
|
|
|
|
.. class:: Font(root=None, font=None, name=None, exists=False, **options)
|
|
|
|
The :class:`Font` class represents a font used by Tk widgets.
|
|
It either creates a new *named font* or refers to an existing font.
|
|
A named font is Tk's way of identifying a font as a single object that can
|
|
be referred to by name and reconfigured in place,
|
|
rather than respecifying its attributes at each use.
|
|
|
|
With *exists* false (the default), a new named font is created.
|
|
Its attributes are taken from the font description *font* if it is given,
|
|
overridden by any keyword *options*.
|
|
The new font is named *name*, or a generated unique name if *name* is
|
|
omitted.
|
|
|
|
With *exists* true, an existing font is referred to instead of being
|
|
created.
|
|
If *name* is given, it is the name of the font,
|
|
which is reconfigured by *font* and *options* if either is given.
|
|
If *name* is omitted, the font description *font* is wrapped as is,
|
|
without creating a named font,
|
|
so that it is used without loss of precision by :meth:`actual`,
|
|
:meth:`measure` and :meth:`metrics`.
|
|
In this case no keyword options are accepted,
|
|
and the :attr:`!name` attribute is the description itself rather than a
|
|
string.
|
|
|
|
The font description *font* is a tuple of the family name, the size and
|
|
zero or more styles,
|
|
or any other form accepted by Tk, such as the name of a named font.
|
|
|
|
The keyword *options* are:
|
|
|
|
| *family* - font family, for example, Courier, Times
|
|
| *size* - font size
|
|
| If *size* is positive it is interpreted as size in points.
|
|
| If *size* is a negative number its absolute value is treated
|
|
| as size in pixels.
|
|
| *weight* - font emphasis (NORMAL, BOLD)
|
|
| *slant* - ROMAN, ITALIC
|
|
| *underline* - font underlining (0 - none, 1 - underline)
|
|
| *overstrike* - font strikeout (0 - none, 1 - strikeout)
|
|
|
|
.. versionchanged:: 3.10
|
|
Two fonts now compare equal (``==``) only when both are :class:`Font`
|
|
instances with the same name belonging to the same Tcl interpreter.
|
|
|
|
.. versionchanged:: next
|
|
A font description can now be wrapped without creating a new named font,
|
|
and keyword options now override the attributes of the specified *font*.
|
|
|
|
.. method:: actual(option=None, displayof=None)
|
|
|
|
Return the actual attributes of the font, which may differ from the
|
|
requested ones because of platform limitations.
|
|
With no *option*, return a dictionary of all the attributes; if *option*
|
|
is given, return the value of that single attribute.
|
|
The attributes are resolved on the display of the *displayof* widget,
|
|
or the main application window if it is not specified.
|
|
|
|
.. method:: cget(option)
|
|
|
|
Retrieve an attribute of the font.
|
|
|
|
.. note::
|
|
|
|
:meth:`!cget` and :meth:`configure` operate on a named font and raise
|
|
:exc:`~tkinter.TclError` for a wrapped font description.
|
|
Use :meth:`actual` to query the attributes of the latter.
|
|
|
|
.. method:: config(**options)
|
|
:no-typesetting:
|
|
|
|
.. method:: configure(**options)
|
|
|
|
Modify one or more attributes of the font.
|
|
With no arguments, return a dictionary of the current attributes.
|
|
|
|
:meth:`config` is an alias of :meth:`!configure`.
|
|
|
|
.. method:: copy()
|
|
|
|
Return a distinct copy of the current font:
|
|
a new named font with the same attributes but a different name,
|
|
which can be reconfigured independently of the original.
|
|
If the current font wraps a font description,
|
|
the copy is instead a named font with its resolved attributes.
|
|
|
|
.. method:: measure(text, displayof=None)
|
|
|
|
Return amount of space the text would occupy on the specified display
|
|
when formatted in the current font, as an integer number of pixels.
|
|
If no display is specified then the main application window is assumed.
|
|
|
|
.. method:: metrics(*options, **kw)
|
|
|
|
Return font-specific data.
|
|
With no options, return a dictionary mapping each metric name to its
|
|
integer value; if one option name is given, return that metric's value as
|
|
an integer.
|
|
Options include:
|
|
|
|
*ascent* - distance between baseline and highest point that a
|
|
character of the font can occupy
|
|
|
|
*descent* - distance between baseline and lowest point that a
|
|
character of the font can occupy
|
|
|
|
*linespace* - minimum vertical separation necessary between any two
|
|
characters of the font that ensures no vertical overlap between lines.
|
|
|
|
*fixed* - 1 if font is fixed-width else 0
|
|
|
|
.. function:: families(root=None, displayof=None)
|
|
|
|
Return a tuple of the names of the available font families.
|
|
|
|
.. function:: names(root=None)
|
|
|
|
Return a tuple of the names of all the defined fonts.
|
|
|
|
.. function:: nametofont(name, root=None)
|
|
|
|
Return a :class:`Font` representation of the existing named font *name*.
|
|
*root* is the widget whose Tcl interpreter owns the font; if omitted, the
|
|
default root window is used.
|
|
|
|
.. versionchanged:: 3.10
|
|
The *root* parameter was added.
|