Debian Codegraph @

Doc/library/tkinter.font.rst

raw
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.