Page Layout

Classes related to “style:page-layout”.

Classes:

Name	Description
`StylePageLayout`	The “style:page-layout” element represents the styles that specify the

StylePageLayout

Bases: StyleProps

The “style:page-layout” element represents the styles that specify the formatting properties of a page.

The “style:page-layout” element is usable within the following element: “office:automatic-styles”.

Methods:

Name	Description
`__init__`	Initialize a StylePageLayout element.
`__repr__`
`del_properties`	Delete specific properties from the page-layout.
`get_footer_style`	Get the `style:footer-style` element within the page layout.
`get_header_style`	Get the `style:header-style` element within the page layout.
`get_properties`	Retrieve the page-layout properties of the `StylePageLayout`.
`set_background`	Set the background properties for the page layout.
`set_footer_style`	Set or replace the `style:footer-style` element within the page layout.
`set_header_style`	Set or replace the `style:header-style` element within the page layout.
`set_properties`	Set the properties for the page-layout.

Attributes:

Name	Type	Description
`PAGE_USAGE`	`ClassVar`
`family`	`str \| None`	Get the family of the style.
`name`
`page_usage`	`str`	Get the `style:page-usage` attribute.

Source code in odfdo/page_layout.py

class StylePageLayout(StyleProps):
    """The "style:page-layout" element represents the styles that specify the
    formatting properties of a page.

    The "style:page-layout" element is usable within the following element:
    "office:automatic-styles".
    """

    # The "style:page-layout" element has the following attributes:
    # style:name
    # style:page-usage

    _tag: str = "style:page-layout"
    _properties: tuple[PropDef | PropDefBool, ...] = (PropDef("name", "style:name"),)
    PAGE_USAGE: ClassVar = {"all", "left", "right", "mirrored"}

    def __init__(
        self,
        name: str | None = None,
        page_usage: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Initialize a StylePageLayout element.

        The `name` is not mandatory at creation but becomes required when
        inserting into a document as an automatic style.

        Args:
            name: The name of the page layout style.
            page_usage: The type of pages the layout applies to.
                Allowed values are "all" (default), "left", "mirrored", "right".
            **kwargs: Additional keyword arguments for the parent `Element` class.
        """
        self._family = "page-layout"
        tag_or_elem = kwargs.get("tag_or_elem")
        if tag_or_elem is None:
            kwargs["tag"] = "style:page-layout"
        Element.__init__(self, **kwargs)
        if self._do_init:
            kwargs.pop("tag", None)
            kwargs.pop("tag_or_elem", None)
            if name:
                self.name = name
            if page_usage:
                self.page_usage = page_usage

    @property
    def family(self) -> str | None:
        """Get the family of the style.

        For `StylePageLayout`, this is always "page-layout".

        Returns:
            str | None: The family name.
        """
        return self._family

    @family.setter
    def family(self, family: str | None) -> None:
        """Setter for the family property (no-op as family is fixed)."""
        pass

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} family={self.family} name={self.name}>"

    @property
    def page_usage(self) -> str:
        """Get the `style:page-usage` attribute.

        Specifies the type of pages that a page master should generate.

        Returns:
            str: The page usage type. Defaults to "all".
        """
        return self._get_attribute_str_default("style:page-usage", "all")

    @page_usage.setter
    def page_usage(self, page_usage: str | None) -> None:
        """Set the `style:page-usage` attribute.

        Args:
            page_usage: The page usage type. Allowed values are
                "all", "left", "right", "mirrored". Invalid values default to "all".
        """
        if page_usage not in self.PAGE_USAGE:
            page_usage = "all"
        self._set_attribute_str_default("style:page-usage", page_usage, "all")

    def get_properties(self, area: str | None = "page-layout") -> PropDict | None:
        """Retrieve the page-layout properties of the `StylePageLayout`.

        Args:
            area: The area for which to retrieve properties.
                (Parameter is kept for compatibility but internally fixed to "page-layout").

        Returns:
            dict[str, str | dict] | None: A dictionary mapping property names to their values.
        """
        return super().get_properties(area="page-layout")

    def set_properties(
        self,
        properties: PropDict | None = None,
        style: StyleBase | None = None,
        area: str | None = None,
        **kwargs: Any,
    ) -> None:
        """Set the properties for the page-layout.

        Properties can be provided either as a dictionary, as a `StyleBase` object,
        or as keyword arguments. The `area` is internally fixed to "page-layout".

        Args:
            properties: A dictionary of properties to set.
            style: A `StyleBase` object from which to copy properties.
            area: The area for which to set properties.
                (Parameter is kept for compatibility but internally fixed to "page-layout").
            **kwargs: Additional keyword arguments for properties to set.
        """
        return super().set_properties(
            properties=properties, style=style, area="page-layout", **kwargs
        )

    def del_properties(
        self,
        properties: list[str] | None = None,
        area: str | None = None,
    ) -> None:
        """Delete specific properties from the page-layout.

        Args:
            properties: A list of property names to delete.
            area: The area from which to delete properties.
                (Parameter is kept for compatibility but internally fixed to "page-layout").
        """
        return super().del_properties(properties=properties, area="page-layout")

    def set_background(
        self,
        color: str | None = None,
        url: str | None = None,
        position: str | None = "center",
        repeat: str | None = None,
        opacity: str | int | None = None,
        filter: str | None = None,  # noqa: A002
    ) -> None:
        """Set the background properties for the page layout.

        This can configure a background color or an image. If no arguments are
        provided, any existing background is removed.

        Args:
            color: The background color in '#RRGGBB' format.
            url: The URL of a background image.
            position: The position of the background image. Can be
                "left", "center", "right", "top", "bottom", or a combination
                of two (e.g., "top center"). Defaults to "center".
            repeat: How the background image repeats. Can be
                "no-repeat", "repeat", or "stretch".
            opacity: The opacity of the background image as
                a percentage integer (0-100).
            filter: An application-specific filter name for the background image.
        """
        _set_background(self, color, url, position, repeat, opacity, filter)

    def get_header_style(self) -> StyleBase | None:
        """Get the `style:header-style` element within the page layout.

        Returns:
            StyleBase | None: The `StyleBase` instance representing the header
                style, or `None` if no header style is defined.
        """
        return cast(None | StyleBase, self.get_element("style:header-style"))

    def set_header_style(self, new_style: StyleBase) -> None:
        """Set or replace the `style:header-style` element within the page layout.

        Args:
            new_style: The new header style to set.
        """
        header_style = self.get_header_style()
        if header_style is not None:
            self.delete(header_style)
        self.append(new_style)

    def get_footer_style(self) -> StyleBase | None:
        """Get the `style:footer-style` element within the page layout.

        Returns:
            StyleBase | None: The `StyleBase` instance representing the footer
                style, or `None` if no footer style is defined.
        """
        return cast(None | StyleBase, self.get_element("style:footer-style"))

    def set_footer_style(self, new_style: StyleBase) -> None:
        """Set or replace the `style:footer-style` element within the page layout.

        Args:
            new_style: The new footer style to set.
        """
        footer_style = self.get_footer_style()
        if footer_style is not None:
            self.delete(footer_style)
        self.append(new_style)

PAGE_USAGE `class-attribute` `instance-attribute`

PAGE_USAGE: ClassVar = {'all', 'left', 'right', 'mirrored'}

_family `instance-attribute`

_family = 'page-layout'

_properties `class-attribute` `instance-attribute`

_properties: tuple[PropDef | PropDefBool, ...] = (
    PropDef("name", "style:name"),
)

_tag `class-attribute` `instance-attribute`

_tag: str = 'style:page-layout'

family `property` `writable`

family: str | None

Get the family of the style.

For StylePageLayout, this is always “page-layout”.

Returns:

Type	Description
`str \| None`	str \| None: The family name.

name `instance-attribute`

name = name

page_usage `property` `writable`

page_usage: str

Get the style:page-usage attribute.

Specifies the type of pages that a page master should generate.

Returns:

Name	Type	Description
`str`	`str`	The page usage type. Defaults to “all”.

init

__init__(
    name: str | None = None,
    page_usage: str | None = None,
    **kwargs: Any,
) -> None

Initialize a StylePageLayout element.

The name is not mandatory at creation but becomes required when inserting into a document as an automatic style.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	The name of the page layout style.	`None`
`page_usage`	`str \| None`	The type of pages the layout applies to. Allowed values are “all” (default), “left”, “mirrored”, “right”.	`None`
`**kwargs`	`Any`	Additional keyword arguments for the parent `Element` class.	`{}`

Source code in odfdo/page_layout.py

def __init__(
    self,
    name: str | None = None,
    page_usage: str | None = None,
    **kwargs: Any,
) -> None:
    """Initialize a StylePageLayout element.

    The `name` is not mandatory at creation but becomes required when
    inserting into a document as an automatic style.

    Args:
        name: The name of the page layout style.
        page_usage: The type of pages the layout applies to.
            Allowed values are "all" (default), "left", "mirrored", "right".
        **kwargs: Additional keyword arguments for the parent `Element` class.
    """
    self._family = "page-layout"
    tag_or_elem = kwargs.get("tag_or_elem")
    if tag_or_elem is None:
        kwargs["tag"] = "style:page-layout"
    Element.__init__(self, **kwargs)
    if self._do_init:
        kwargs.pop("tag", None)
        kwargs.pop("tag_or_elem", None)
        if name:
            self.name = name
        if page_usage:
            self.page_usage = page_usage

repr

__repr__() -> str

Source code in odfdo/page_layout.py

def __repr__(self) -> str:
    return f"<{self.__class__.__name__} family={self.family} name={self.name}>"

del_properties

del_properties(
    properties: list[str] | None = None,
    area: str | None = None,
) -> None

Delete specific properties from the page-layout.

Parameters:

Name	Type	Description	Default
`properties`	`list[str] \| None`	A list of property names to delete.	`None`
`area`	`str \| None`	The area from which to delete properties. (Parameter is kept for compatibility but internally fixed to “page-layout”).	`None`

Source code in odfdo/page_layout.py

def del_properties(
    self,
    properties: list[str] | None = None,
    area: str | None = None,
) -> None:
    """Delete specific properties from the page-layout.

    Args:
        properties: A list of property names to delete.
        area: The area from which to delete properties.
            (Parameter is kept for compatibility but internally fixed to "page-layout").
    """
    return super().del_properties(properties=properties, area="page-layout")

get_footer_style

get_footer_style() -> StyleBase | None

Get the style:footer-style element within the page layout.

Returns:

Type	Description
`StyleBase \| None`	StyleBase \| None: The `StyleBase` instance representing the footer style, or `None` if no footer style is defined.

Source code in odfdo/page_layout.py

def get_footer_style(self) -> StyleBase | None:
    """Get the `style:footer-style` element within the page layout.

    Returns:
        StyleBase | None: The `StyleBase` instance representing the footer
            style, or `None` if no footer style is defined.
    """
    return cast(None | StyleBase, self.get_element("style:footer-style"))

get_header_style

get_header_style() -> StyleBase | None

Get the style:header-style element within the page layout.

Returns:

Type	Description
`StyleBase \| None`	StyleBase \| None: The `StyleBase` instance representing the header style, or `None` if no header style is defined.

Source code in odfdo/page_layout.py

def get_header_style(self) -> StyleBase | None:
    """Get the `style:header-style` element within the page layout.

    Returns:
        StyleBase | None: The `StyleBase` instance representing the header
            style, or `None` if no header style is defined.
    """
    return cast(None | StyleBase, self.get_element("style:header-style"))

get_properties

get_properties(
    area: str | None = "page-layout",
) -> PropDict | None

Retrieve the page-layout properties of the StylePageLayout.

Parameters:

Name	Type	Description	Default
`area`	`str \| None`	The area for which to retrieve properties. (Parameter is kept for compatibility but internally fixed to “page-layout”).	`'page-layout'`

Returns:

Type	Description
`PropDict \| None`	dict[str, str \| dict] \| None: A dictionary mapping property names to their values.

Source code in odfdo/page_layout.py

def get_properties(self, area: str | None = "page-layout") -> PropDict | None:
    """Retrieve the page-layout properties of the `StylePageLayout`.

    Args:
        area: The area for which to retrieve properties.
            (Parameter is kept for compatibility but internally fixed to "page-layout").

    Returns:
        dict[str, str | dict] | None: A dictionary mapping property names to their values.
    """
    return super().get_properties(area="page-layout")

set_background

set_background(
    color: str | None = None,
    url: str | None = None,
    position: str | None = "center",
    repeat: str | None = None,
    opacity: str | int | None = None,
    filter: str | None = None,
) -> None

Set the background properties for the page layout.

This can configure a background color or an image. If no arguments are provided, any existing background is removed.

Parameters:

Name	Type	Description	Default
`color`	`str \| None`	The background color in ‘#RRGGBB’ format.	`None`
`url`	`str \| None`	The URL of a background image.	`None`
`position`	`str \| None`	The position of the background image. Can be “left”, “center”, “right”, “top”, “bottom”, or a combination of two (e.g., “top center”). Defaults to “center”.	`'center'`
`repeat`	`str \| None`	How the background image repeats. Can be “no-repeat”, “repeat”, or “stretch”.	`None`
`opacity`	`str \| int \| None`	The opacity of the background image as a percentage integer (0-100).	`None`
`filter`	`str \| None`	An application-specific filter name for the background image.	`None`

Source code in odfdo/page_layout.py

def set_background(
    self,
    color: str | None = None,
    url: str | None = None,
    position: str | None = "center",
    repeat: str | None = None,
    opacity: str | int | None = None,
    filter: str | None = None,  # noqa: A002
) -> None:
    """Set the background properties for the page layout.

    This can configure a background color or an image. If no arguments are
    provided, any existing background is removed.

    Args:
        color: The background color in '#RRGGBB' format.
        url: The URL of a background image.
        position: The position of the background image. Can be
            "left", "center", "right", "top", "bottom", or a combination
            of two (e.g., "top center"). Defaults to "center".
        repeat: How the background image repeats. Can be
            "no-repeat", "repeat", or "stretch".
        opacity: The opacity of the background image as
            a percentage integer (0-100).
        filter: An application-specific filter name for the background image.
    """
    _set_background(self, color, url, position, repeat, opacity, filter)

set_footer_style

set_footer_style(new_style: StyleBase) -> None

Set or replace the style:footer-style element within the page layout.

Parameters:

Name	Type	Description	Default
`new_style`	`StyleBase`	The new footer style to set.	required

Source code in odfdo/page_layout.py

def set_footer_style(self, new_style: StyleBase) -> None:
    """Set or replace the `style:footer-style` element within the page layout.

    Args:
        new_style: The new footer style to set.
    """
    footer_style = self.get_footer_style()
    if footer_style is not None:
        self.delete(footer_style)
    self.append(new_style)

set_header_style

set_header_style(new_style: StyleBase) -> None

Set or replace the style:header-style element within the page layout.

Parameters:

Name	Type	Description	Default
`new_style`	`StyleBase`	The new header style to set.	required

Source code in odfdo/page_layout.py

def set_header_style(self, new_style: StyleBase) -> None:
    """Set or replace the `style:header-style` element within the page layout.

    Args:
        new_style: The new header style to set.
    """
    header_style = self.get_header_style()
    if header_style is not None:
        self.delete(header_style)
    self.append(new_style)

set_properties

set_properties(
    properties: PropDict | None = None,
    style: StyleBase | None = None,
    area: str | None = None,
    **kwargs: Any,
) -> None

Set the properties for the page-layout.

Properties can be provided either as a dictionary, as a StyleBase object, or as keyword arguments. The area is internally fixed to “page-layout”.

Parameters:

Name	Type	Description	Default
`properties`	`PropDict \| None`	A dictionary of properties to set.	`None`
`style`	`StyleBase \| None`	A `StyleBase` object from which to copy properties.	`None`
`area`	`str \| None`	The area for which to set properties. (Parameter is kept for compatibility but internally fixed to “page-layout”).	`None`
`**kwargs`	`Any`	Additional keyword arguments for properties to set.	`{}`

Source code in odfdo/page_layout.py

def set_properties(
    self,
    properties: PropDict | None = None,
    style: StyleBase | None = None,
    area: str | None = None,
    **kwargs: Any,
) -> None:
    """Set the properties for the page-layout.

    Properties can be provided either as a dictionary, as a `StyleBase` object,
    or as keyword arguments. The `area` is internally fixed to "page-layout".

    Args:
        properties: A dictionary of properties to set.
        style: A `StyleBase` object from which to copy properties.
        area: The area for which to set properties.
            (Parameter is kept for compatibility but internally fixed to "page-layout").
        **kwargs: Additional keyword arguments for properties to set.
    """
    return super().set_properties(
        properties=properties, style=style, area="page-layout", **kwargs
    )

Page Layout

StylePageLayout

PAGE_USAGE class-attribute instance-attribute

_family instance-attribute

_properties class-attribute instance-attribute

_tag class-attribute instance-attribute

family property writable

name instance-attribute

page_usage property writable

__init__

__repr__

del_properties

get_footer_style

get_header_style

get_properties

set_background

set_footer_style

set_header_style

set_properties

PAGE_USAGE `class-attribute` `instance-attribute`

_family `instance-attribute`

_properties `class-attribute` `instance-attribute`

_tag `class-attribute` `instance-attribute`

family `property` `writable`

name `instance-attribute`

page_usage `property` `writable`

init

repr