Source code for docx.text.font

"""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


[docs]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]