font.py

"""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, eastAsia: bool | False, cs: bool | False) -> None:
        rPr = self._element.get_or_add_rPr()
        rPr.rFonts_ascii = value
        rPr.rFonts_hAnsi = value

        if eastAsia:
            self._element.rPr.rFonts.set(qn('w:eastAsia'), value)
        if cs:
            self._element.rPr.rFonts.set(qn('w:cs'), 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]