Source code for

Module for managing paragraph breaks.

.. versionadded:: 0.9.0

# region Imports
from __future__ import annotations
from typing import Any, Dict, Tuple, overload, Type, TypeVar

from import BreakType

from import CancelEventArgs
from ooodev.exceptions import ex as mEx
from ooodev.loader import lo as mLo
from ooodev.utils import props as mProps
from ooodev.format.inner.kind.format_kind import FormatKind
from ooodev.format.inner.style_base import StyleBase

# endregion Imports

_TBreaks = TypeVar(name="_TBreaks", bound="Breaks")

[docs]class Breaks(StyleBase): """ Paragraph Breaks Any properties starting with ``prop_`` set or get current instance values. .. seealso:: - :ref:`help_writer_format_direct_para_text_flow` .. versionadded:: 0.9.0 """ # region init
[docs] def __init__(self, *, type: BreakType | None = None, style: str | None = None, num: int | None = None) -> None: """ Constructor Args: type (BreakType, optional): Break type. style (str, optional): Style to apply to break. num (int, optional): Page number to apply to break. Returns: None: Note: If argument ``type`` is ``None`` then all other argument are ignored See Also: - :ref:`help_writer_format_direct_para_text_flow` """ # sourcery skip: merge-nested-ifs # # Default for writer is BreakType.NONE # BreakType controls the dialog insert checkbox # pg_style only applies # Dialog position is set by the type: e.g. BreakType.PAGE_AFTER Type is Page and Position is After # When BreakType.PAGE_AFTER or COLUMN_AFTER page style is not used. if type is None: # everything depends on a BreakType super().__init__() return init_vals: Dict[str, Any] = {"BreakType": type} if style is not None: if type in (BreakType.PAGE_BEFORE, BreakType.COLUMN_BEFORE, BreakType.COLUMN_BOTH, BreakType.PAGE_BOTH): # # pg_style is only valid when BreakType.COLUMN_BEFORE or BreakType.PAGE_BEFORE # LibreOffice Dev Tools report this property as readonly. # api does not. # PageStyleName: contains the name of the current page style. # init_vals["PageStyleName"] = pg_style # PageDescName: If this property is set, it creates a page break before the paragraph # it belongs to and assigns the value as the name of the new page style sheet to use. init_vals["PageDescName"] = style if "PageDescName" in init_vals and num is not None: # pg_num is only valid when BreakType.COLUMN_BEFORE or BreakType.PAGE_BEFORE AND # page style is set (pg_style) init_vals["PageNumberOffset"] = num super().__init__(**init_vals)
# endregion init # region methods def _supported_services(self) -> Tuple[str, ...]: try: return self._supported_services_values except AttributeError: self._supported_services_values = ( "", "", ) return self._supported_services_values def _on_modifying(self, source: Any, event: CancelEventArgs) -> None: if self._is_default_inst: raise ValueError("Modifying a default instance is not allowed") return super()._on_modifying(source, event) # region apply() @overload def apply(self, obj: Any) -> None: ... @overload def apply(self, obj: Any, **kwargs) -> None: ...
[docs] def apply(self, obj: Any, **kwargs) -> None: """ Applies break properties to ``obj`` Args: obj (object): UNO object that supports ```` service. Returns: None: """ try: super().apply(obj, **kwargs) except mEx.MultiError as e: mLo.Lo.print(f"{self.__class__.__name__}.apply(): Unable to set Property") for err in e.errors: mLo.Lo.print(f" {err}")
# endregion apply() # region from_obj() @overload @classmethod def from_obj(cls: Type[_TBreaks], obj: Any) -> _TBreaks: ... @overload @classmethod def from_obj(cls: Type[_TBreaks], obj: Any, **kwargs) -> _TBreaks: ...
[docs] @classmethod def from_obj(cls: Type[_TBreaks], obj: Any, **kwargs) -> _TBreaks: """ Gets instance from object Args: obj (object): UNO object. Raises: NotSupportedError: If ``obj`` is not supported. Returns: Breaks: ``Breaks`` instance that represents ``obj`` break properties. """ # pylint: disable=protected-access nu = cls(**kwargs) if not nu._is_valid_obj(obj): raise mEx.NotSupportedError(f'Object is not supported for conversion to "{cls.__name__}"') t = mProps.Props.get(obj, "BreakType", None) style = mProps.Props.get(obj, "PageDescName", None) num = mProps.Props.get(obj, "PageNumberOffset", None) result = cls(type=t, style=style, num=num, **kwargs) result.set_update_obj(obj) return result
# endregion from_obj() # endregion methods # region properties @property def prop_format_kind(self) -> FormatKind: """Gets the kind of style""" try: return self._format_kind_prop except AttributeError: self._format_kind_prop = FormatKind.PARA return self._format_kind_prop @property def prop_type(self) -> BreakType | None: """Gets break type""" return self._get("BreakType") @property def prop_style(self) -> str | None: """Gets Break Style""" return self._get("PageDescName") @property def prop_num(self) -> int | None: """Gets Page number to apply to break""" return self._get("PageNumberOffset") @property def default(self: _TBreaks) -> _TBreaks: """Gets ``Breaks`` default.""" # pylint: disable=protected-access # pylint: disable=unexpected-keyword-arg try: return self._default_inst except AttributeError: self._default_inst = self.__class__(type=BreakType.NONE, _cattribs=self._get_internal_cattribs()) self._default_inst._is_default_inst = True return self._default_inst
# endregion properties