| 1 |
:mod:`!tkinter.font` --- Tkinter font wrapper |
| 2 |
============================================= |
| 3 |
|
| 4 |
.. module:: tkinter.font |
| 5 |
:synopsis: Tkinter font-wrapping class |
| 6 |
|
| 7 |
**Source code:** :source:`Lib/tkinter/font.py` |
| 8 |
|
| 9 |
-------------- |
| 10 |
|
| 11 |
The :mod:`tkinter.font` module provides the :class:`Font` class for creating |
| 12 |
and using named fonts. |
| 13 |
|
| 14 |
The different font weights and slants are: |
| 15 |
|
| 16 |
.. data:: NORMAL |
| 17 |
BOLD |
| 18 |
ITALIC |
| 19 |
ROMAN |
| 20 |
|
| 21 |
.. class:: Font(root=None, font=None, name=None, exists=False, **options) |
| 22 |
|
| 23 |
The :class:`Font` class represents a named font. *Font* instances are given |
| 24 |
unique names and can be specified by their family, size, and style |
| 25 |
configuration. Named fonts are Tk's method of creating and identifying |
| 26 |
fonts as a single object, rather than specifying a font by its attributes |
| 27 |
with each occurrence. |
| 28 |
|
| 29 |
.. versionchanged:: 3.10 |
| 30 |
Two fonts now compare equal (``==``) only when both are :class:`Font` |
| 31 |
instances with the same name belonging to the same Tcl interpreter. |
| 32 |
|
| 33 |
arguments: |
| 34 |
|
| 35 |
| *font* - font specifier tuple (family, size, options) |
| 36 |
| *name* - unique font name |
| 37 |
| *exists* - self points to existing named font if true |
| 38 |
|
| 39 |
additional keyword options (ignored if *font* is specified): |
| 40 |
|
| 41 |
| *family* - font family, for example, Courier, Times |
| 42 |
| *size* - font size |
| 43 |
| If *size* is positive it is interpreted as size in points. |
| 44 |
| If *size* is a negative number its absolute value is treated |
| 45 |
| as size in pixels. |
| 46 |
| *weight* - font emphasis (NORMAL, BOLD) |
| 47 |
| *slant* - ROMAN, ITALIC |
| 48 |
| *underline* - font underlining (0 - none, 1 - underline) |
| 49 |
| *overstrike* - font strikeout (0 - none, 1 - strikeout) |
| 50 |
|
| 51 |
.. method:: actual(option=None, displayof=None) |
| 52 |
|
| 53 |
Return the actual attributes of the font, which may differ from the |
| 54 |
requested ones because of platform limitations. |
| 55 |
With no *option*, return a dictionary of all the attributes; if *option* |
| 56 |
is given, return the value of that single attribute. |
| 57 |
The attributes are resolved on the display of the *displayof* widget, |
| 58 |
or the main application window if it is not specified. |
| 59 |
|
| 60 |
.. method:: cget(option) |
| 61 |
|
| 62 |
Retrieve an attribute of the font. |
| 63 |
|
| 64 |
.. method:: config(**options) |
| 65 |
:no-typesetting: |
| 66 |
|
| 67 |
.. method:: configure(**options) |
| 68 |
|
| 69 |
Modify one or more attributes of the font. |
| 70 |
With no arguments, return a dictionary of the current attributes. |
| 71 |
|
| 72 |
:meth:`config` is an alias of :meth:`!configure`. |
| 73 |
|
| 74 |
.. method:: copy() |
| 75 |
|
| 76 |
Return a distinct copy of the current font: |
| 77 |
a new named font with the same attributes but a different name, |
| 78 |
which can be reconfigured independently of the original. |
| 79 |
If the current font wraps a font description, |
| 80 |
the copy is instead a named font with its resolved attributes. |
| 81 |
|
| 82 |
.. method:: measure(text, displayof=None) |
| 83 |
|
| 84 |
Return amount of space the text would occupy on the specified display |
| 85 |
when formatted in the current font, as an integer number of pixels. |
| 86 |
If no display is specified then the main application window is assumed. |
| 87 |
|
| 88 |
.. method:: metrics(*options, **kw) |
| 89 |
|
| 90 |
Return font-specific data. |
| 91 |
With no options, return a dictionary mapping each metric name to its |
| 92 |
integer value; if one option name is given, return that metric's value as |
| 93 |
an integer. |
| 94 |
Options include: |
| 95 |
|
| 96 |
*ascent* - distance between baseline and highest point that a |
| 97 |
character of the font can occupy |
| 98 |
|
| 99 |
*descent* - distance between baseline and lowest point that a |
| 100 |
character of the font can occupy |
| 101 |
|
| 102 |
*linespace* - minimum vertical separation necessary between any two |
| 103 |
characters of the font that ensures no vertical overlap between lines. |
| 104 |
|
| 105 |
*fixed* - 1 if font is fixed-width else 0 |
| 106 |
|
| 107 |
.. function:: families(root=None, displayof=None) |
| 108 |
|
| 109 |
Return a tuple of the names of the available font families. |
| 110 |
|
| 111 |
.. function:: names(root=None) |
| 112 |
|
| 113 |
Return a tuple of the names of all the defined fonts. |
| 114 |
|
| 115 |
.. function:: nametofont(name, root=None) |
| 116 |
|
| 117 |
Return a :class:`Font` representation of the existing named font *name*. |
| 118 |
*root* is the widget whose Tcl interpreter owns the font; if omitted, the |
| 119 |
default root window is used. |
| 120 |
|
| 121 |
.. versionchanged:: 3.10 |
| 122 |
The *root* parameter was added. |