Screen

Usage

An app will always have access to at least one screen. The toga.App.screens attribute will return the list of all available screens; the screen at index 0 will be the "primary" screen. Screen sizes and positions are given in CSS pixels.

# Print the size of the primary screen.
print(my_app.screens[0].size)

# Print the identifying name of the second screen
print(my_app.screens[1].name)

Notes

• When using the GTK backend under Wayland, the screen at index 0 may not be the primary screen. This because the separation of concerns enforced by Wayland makes determining the primary screen unreliable.

Reference

Source code in core/src/toga/screens.py

class Screen:
    def __init__(self, _impl: Any):
        self._impl = _impl
        self.factory = get_factory()

    @property
    def name(self) -> str:
        """Unique name of the screen."""
        return self._impl.get_name()

    @property
    def origin(self) -> Position:
        """
        The absolute coordinates of the screen's origin, in [CSS pixels][css-units].
        """
        return self._impl.get_origin()

    @property
    def size(self) -> Size:
        """The size of the screen, in [CSS pixels][css-units]."""
        return self._impl.get_size()

    def as_image(self, format: type[ImageT] = Image) -> ImageT:
        """Render the current contents of the screen as an image.

        :param format: Format to provide. Defaults to [`Image`][toga.images.Image]; also
            supports [`PIL.Image.Image`][] if Pillow is installed, as well as any image
            types defined by installed
            [image format plugins](/reference/api/resources/image/image-format-plugins.md).
        :returns: An image containing the screen content, in the format requested.
        """  # noqa: E501
        return Image(self._impl.get_image_data()).as_format(format)

name property

Unique name of the screen.

origin property

The absolute coordinates of the screen's origin, in CSS pixels.

size property

The size of the screen, in CSS pixels.

as_image(format=Image)

Render the current contents of the screen as an image.

:param format: Format to provide. Defaults to Image; also supports [PIL.Image.Image][] if Pillow is installed, as well as any image types defined by installed image format plugins. :returns: An image containing the screen content, in the format requested.

Source code in core/src/toga/screens.py

def as_image(self, format: type[ImageT] = Image) -> ImageT:
    """Render the current contents of the screen as an image.

    :param format: Format to provide. Defaults to [`Image`][toga.images.Image]; also
        supports [`PIL.Image.Image`][] if Pillow is installed, as well as any image
        types defined by installed
        [image format plugins](/reference/api/resources/image/image-format-plugins.md).
    :returns: An image containing the screen content, in the format requested.
    """  # noqa: E501
    return Image(self._impl.get_image_data()).as_format(format)