"""Font-related proxy objects."""
from __future__ import annotations
from typing import TYPE_CHECKING, Any
from docx.dml.color import ColorFormat
from docx.enum.text import WD_UNDERLINE
from docx.shared import ElementProxy, Emu
if TYPE_CHECKING:
from docx.enum.text import WD_COLOR_INDEX
from docx.oxml.text.run import CT_R
from docx.shared import Length
[文档]
class Font(ElementProxy):
"""Proxy object for parent of a `<w:rPr>` element and providing access to
character properties such as font name, font size, bold, and subscript."""
def __init__(self, r: CT_R, parent: Any | None = None):
super().__init__(r, parent)
self._element = r
self._r = r
@property
def all_caps(self) -> bool | None:
"""Read/write.
Causes text in this font to appear in capital letters.
"""
return self._get_bool_prop("caps")
@all_caps.setter
def all_caps(self, value: bool | None) -> None:
self._set_bool_prop("caps", value)
@property
def bold(self) -> bool | None:
"""Read/write.
Causes text in this font to appear in bold.
"""
return self._get_bool_prop("b")
@bold.setter
def bold(self, value: bool | None) -> None:
self._set_bool_prop("b", value)
@property
def color(self):
"""A |ColorFormat| object providing a way to get and set the text color for this
font."""
return ColorFormat(self._element)
@property
def complex_script(self) -> bool | None:
"""Read/write tri-state value.
When |True|, causes the characters in the run to be treated as complex script
regardless of their Unicode values.
"""
return self._get_bool_prop("cs")
@complex_script.setter
def complex_script(self, value: bool | None) -> None:
self._set_bool_prop("cs", value)
@property
def cs_bold(self) -> bool | None:
"""Read/write tri-state value.
When |True|, causes the complex script characters in the run to be displayed in
bold typeface.
"""
return self._get_bool_prop("bCs")
@cs_bold.setter
def cs_bold(self, value: bool | None) -> None:
self._set_bool_prop("bCs", value)
@property
def cs_italic(self) -> bool | None:
"""Read/write tri-state value.
When |True|, causes the complex script characters in the run to be displayed in
italic typeface.
"""
return self._get_bool_prop("iCs")
@cs_italic.setter
def cs_italic(self, value: bool | None) -> None:
self._set_bool_prop("iCs", value)
@property
def double_strike(self) -> bool | None:
"""Read/write tri-state value.
When |True|, causes the text in the run to appear with double strikethrough.
"""
return self._get_bool_prop("dstrike")
@double_strike.setter
def double_strike(self, value: bool | None) -> None:
self._set_bool_prop("dstrike", value)
@property
def emboss(self) -> bool | None:
"""Read/write tri-state value.
When |True|, causes the text in the run to appear as if raised off the page in
relief.
"""
return self._get_bool_prop("emboss")
@emboss.setter
def emboss(self, value: bool | None) -> None:
self._set_bool_prop("emboss", value)
@property
def hidden(self) -> bool | None:
"""Read/write tri-state value.
When |True|, causes the text in the run to be hidden from display, unless
applications settings force hidden text to be shown.
"""
return self._get_bool_prop("vanish")
@hidden.setter
def hidden(self, value: bool | None) -> None:
self._set_bool_prop("vanish", value)
@property
def highlight_color(self) -> WD_COLOR_INDEX | None:
"""Color of highlighing applied or |None| if not highlighted."""
rPr = self._element.rPr
if rPr is None:
return None
return rPr.highlight_val
@highlight_color.setter
def highlight_color(self, value: WD_COLOR_INDEX | None):
rPr = self._element.get_or_add_rPr()
rPr.highlight_val = value
@property
def italic(self) -> bool | None:
"""Read/write tri-state value.
When |True|, causes the text of the run to appear in italics. |None| indicates
the effective value is inherited from the style hierarchy.
"""
return self._get_bool_prop("i")
@italic.setter
def italic(self, value: bool | None) -> None:
self._set_bool_prop("i", value)
@property
def imprint(self) -> bool | None:
"""Read/write tri-state value.
When |True|, causes the text in the run to appear as if pressed into the page.
"""
return self._get_bool_prop("imprint")
@imprint.setter
def imprint(self, value: bool | None) -> None:
self._set_bool_prop("imprint", value)
@property
def math(self) -> bool | None:
"""Read/write tri-state value.
When |True|, specifies this run contains WML that should be handled as though it
was Office Open XML Math.
"""
return self._get_bool_prop("oMath")
@math.setter
def math(self, value: bool | None) -> None:
self._set_bool_prop("oMath", value)
@property
def name(self) -> str | None:
"""The typeface name for this |Font|.
Causes the text it controls to appear in the named font, if a matching font is
found. |None| indicates the typeface is inherited from the style hierarchy.
"""
rPr = self._element.rPr
if rPr is None:
return None
return rPr.rFonts_ascii
@name.setter
def name(self, value: str | None) -> None:
rPr = self._element.get_or_add_rPr()
rPr.rFonts_ascii = value
rPr.rFonts_hAnsi = value
@property
def no_proof(self) -> bool | None:
"""Read/write tri-state value.
When |True|, specifies that the contents of this run should not report any
errors when the document is scanned for spelling and grammar.
"""
return self._get_bool_prop("noProof")
@no_proof.setter
def no_proof(self, value: bool | None) -> None:
self._set_bool_prop("noProof", value)
@property
def outline(self) -> bool | None:
"""Read/write tri-state value.
When |True| causes the characters in the run to appear as if they have an
outline, by drawing a one pixel wide border around the inside and outside
borders of each character glyph.
"""
return self._get_bool_prop("outline")
@outline.setter
def outline(self, value: bool | None) -> None:
self._set_bool_prop("outline", value)
@property
def rtl(self) -> bool | None:
"""Read/write tri-state value.
When |True| causes the text in the run to have right-to-left characteristics.
"""
return self._get_bool_prop("rtl")
@rtl.setter
def rtl(self, value: bool | None) -> None:
self._set_bool_prop("rtl", value)
@property
def shadow(self) -> bool | None:
"""Read/write tri-state value.
When |True| causes the text in the run to appear as if each character has a
shadow.
"""
return self._get_bool_prop("shadow")
@shadow.setter
def shadow(self, value: bool | None) -> None:
self._set_bool_prop("shadow", value)
@property
def size(self) -> Length | None:
"""Font height in English Metric Units (EMU).
|None| indicates the font size should be inherited from the style hierarchy.
|Length| is a subclass of |int| having properties for convenient conversion into
points or other length units. The :class:`docx.shared.Pt` class allows
convenient specification of point values::
>>> font.size = Pt(24)
>>> font.size
304800
>>> font.size.pt
24.0
"""
rPr = self._element.rPr
if rPr is None:
return None
return rPr.sz_val
@size.setter
def size(self, emu: int | Length | None) -> None:
rPr = self._element.get_or_add_rPr()
rPr.sz_val = None if emu is None else Emu(emu)
@property
def small_caps(self) -> bool | None:
"""Read/write tri-state value.
When |True| causes the lowercase characters in the run to appear as capital
letters two points smaller than the font size specified for the run.
"""
return self._get_bool_prop("smallCaps")
@small_caps.setter
def small_caps(self, value: bool | None) -> None:
self._set_bool_prop("smallCaps", value)
@property
def snap_to_grid(self) -> bool | None:
"""Read/write tri-state value.
When |True| causes the run to use the document grid characters per line settings
defined in the docGrid element when laying out the characters in this run.
"""
return self._get_bool_prop("snapToGrid")
@snap_to_grid.setter
def snap_to_grid(self, value: bool | None) -> None:
self._set_bool_prop("snapToGrid", value)
@property
def spec_vanish(self) -> bool | None:
"""Read/write tri-state value.
When |True|, specifies that the given run shall always behave as if it is
hidden, even when hidden text is being displayed in the current document. The
property has a very narrow, specialized use related to the table of contents.
Consult the spec (§17.3.2.36) for more details.
"""
return self._get_bool_prop("specVanish")
@spec_vanish.setter
def spec_vanish(self, value: bool | None) -> None:
self._set_bool_prop("specVanish", value)
@property
def strike(self) -> bool | None:
"""Read/write tri-state value.
When |True| causes the text in the run to appear with a single horizontal line
through the center of the line.
"""
return self._get_bool_prop("strike")
@strike.setter
def strike(self, value: bool | None) -> None:
self._set_bool_prop("strike", value)
@property
def subscript(self) -> bool | None:
"""Boolean indicating whether the characters in this |Font| appear as subscript.
|None| indicates the subscript/subscript value is inherited from the style
hierarchy.
"""
rPr = self._element.rPr
if rPr is None:
return None
return rPr.subscript
@subscript.setter
def subscript(self, value: bool | None) -> None:
rPr = self._element.get_or_add_rPr()
rPr.subscript = value
@property
def superscript(self) -> bool | None:
"""Boolean indicating whether the characters in this |Font| appear as
superscript.
|None| indicates the subscript/superscript value is inherited from the style
hierarchy.
"""
rPr = self._element.rPr
if rPr is None:
return None
return rPr.superscript
@superscript.setter
def superscript(self, value: bool | None) -> None:
rPr = self._element.get_or_add_rPr()
rPr.superscript = value
@property
def underline(self) -> bool | WD_UNDERLINE | None:
"""The underline style for this |Font|.
The value is one of |None|, |True|, |False|, or a member of :ref:`WdUnderline`.
|None| indicates the font inherits its underline value from the style hierarchy.
|False| indicates no underline. |True| indicates single underline. The values
from :ref:`WdUnderline` are used to specify other outline styles such as double,
wavy, and dotted.
"""
rPr = self._element.rPr
if rPr is None:
return None
val = rPr.u_val
return (
None
if val == WD_UNDERLINE.INHERITED
else True
if val == WD_UNDERLINE.SINGLE
else False
if val == WD_UNDERLINE.NONE
else val
)
@underline.setter
def underline(self, value: bool | WD_UNDERLINE | None) -> None:
rPr = self._element.get_or_add_rPr()
# -- works fine without these two mappings, but only because True == 1 and
# -- False == 0, which happen to match the mapping for WD_UNDERLINE.SINGLE
# -- and .NONE respectively.
val = (
WD_UNDERLINE.SINGLE
if value is True
else WD_UNDERLINE.NONE
if value is False
else value
)
rPr.u_val = val
@property
def web_hidden(self) -> bool | None:
"""Read/write tri-state value.
When |True|, specifies that the contents of this run shall be hidden when the
document is displayed in web page view.
"""
return self._get_bool_prop("webHidden")
@web_hidden.setter
def web_hidden(self, value: bool | None) -> None:
self._set_bool_prop("webHidden", value)
def _get_bool_prop(self, name: str) -> bool | None:
"""Return the value of boolean child of `w:rPr` having `name`."""
rPr = self._element.rPr
if rPr is None:
return None
return rPr._get_bool_val(name) # pyright: ignore[reportPrivateUsage]
def _set_bool_prop(self, name: str, value: bool | None):
"""Assign `value` to the boolean child `name` of `w:rPr`."""
rPr = self._element.get_or_add_rPr()
rPr._set_bool_val(name, value) # pyright: ignore[reportPrivateUsage]