Window

Bases: Tk

A class that wraps the tkinter.Tk class in order to provide a more convenient api with additional bells and whistles. For more information on how to use the inherited Tk methods, see the tcl/tk documentation and the Python documentation.

Examples:

```python
app = Window(title="My Application", themename="superhero")
app.mainloop()
```

Source code in src/ttkbootstrap/window.py

class Window(tkinter.Tk):
    """A class that wraps the tkinter.Tk class in order to provide a
    more convenient api with additional bells and whistles. For more
    information on how to use the inherited `Tk` methods, see the
    [tcl/tk documentation](https://tcl.tk/man/tcl8.6/TkCmd/wm.htm)
    and the [Python documentation](https://docs.python.org/3/library/tkinter.html#tkinter.Tk).

    ![](../../assets/window/window-toplevel.png)

    Examples:

        ```python
        app = Window(title="My Application", themename="superhero")
        app.mainloop()
        ```
    """

    def __init__(
            self,
            title: str = "ttkbootstrap",
            themename: str = "litera",
            iconphoto: Optional[str] = '',
            size: Optional[Tuple[int, int]] = None,
            position: Optional[Tuple[int, int]] = None,
            minsize: Optional[Tuple[int, int]] = None,
            maxsize: Optional[Tuple[int, int]] = None,
            resizable: Optional[Tuple[bool, bool]] = None,
            hdpi: bool = True,
            scaling: Optional[float] = None,
            transient: Optional[tkinter.Misc] = None,
            overrideredirect: bool = False,
            alpha: float = 1.0,
            **kwargs: Any,
    ) -> None:
        """
        Parameters:

            title (str):
                The title that appears on the application titlebar.

            themename (str):
                The name of the ttkbootstrap theme to apply to the
                application.

            iconphoto (str):
                A path to the image used for the titlebar icon.
                Internally this is passed to the `Tk.iconphoto` method
                and the image will be the default icon for all windows.
                A ttkbootstrap image is used by default. To disable
                this default behavior, set the value to `None` and use
                the `Tk.iconphoto` or `Tk.iconbitmap` methods directly.

            size (tuple[int, int]):
                The width and height of the application window.
                Internally, this argument is passed to the
                `Window.geometry` method.

            position (tuple[int, int]):
                The horizontal and vertical position of the window on
                the screen relative to the top-left coordinate.
                Internally this is passed to the `Window.geometry`
                method.

            minsize (tuple[int, int]):
                Specifies the minimum permissible dimensions for the
                window. Internally, this argument is passed to the
                `Window.minsize` method.

            maxsize (tuple[int, int]):
                Specifies the maximum permissible dimensions for the
                window. Internally, this argument is passed to the
                `Window.maxsize` method.

            resizable (tuple[bool, bool]):
                Specifies whether the user may interactively resize the
                toplevel window. Must pass in two arguments that specify
                this flag for _horizontal_ and _vertical_ dimensions.
                This can be adjusted after the window is created by using
                the `Window.resizable` method.

            hdpi (bool):
                Enable high-dpi support for Windows OS. This option is
                enabled by default.

            scaling (float):
                Sets the current scaling factor used by Tk to convert
                between physical units (for example, points, inches, or
                millimeters) and pixels. The number argument is a
                floating point number that specifies the number of pixels
                per point on window's display.

            transient (Union[Tk, Widget]):
                Instructs the window manager that this widget is
                transient with regard to the widget master. Internally
                this is passed to the `Window.transient` method.

            overrideredirect (bool):
                Instructs the window manager to ignore this widget if
                True. Internally, this argument is passed to the
                `Window.overrideredirect(1)` method.

            alpha (float):
                On Windows, specifies the alpha transparency level of the
                toplevel. Where not supported, alpha remains at 1.0. Internally,
                this is processed as `Toplevel.attributes('-alpha', alpha)`.

            **kwargs:
                Any other keyword arguments that are passed through to tkinter.Tk() constructor
                List of available keywords available at: https://docs.python.org/3/library/tkinter.html#tkinter.Tk
        """
        if hdpi:
            utility.enable_high_dpi_awareness()

        super().__init__(**kwargs)
        self.winsys: str = self.tk.call('tk', 'windowingsystem')

        if scaling is not None:
            utility.enable_high_dpi_awareness(self, scaling)

        if iconphoto is not None:
            if iconphoto == '':
                # the default ttkbootstrap icon
                self._icon = tkinter.PhotoImage(master=self, data=Icon.icon)
                self.iconphoto(True, self._icon)
            else:
                try:
                    # the user provided an image path
                    self._icon = tkinter.PhotoImage(file=iconphoto, master=self)
                    self.iconphoto(True, self._icon)
                except tkinter.TclError:
                    # The fallback icon if the user icon fails.
                    print('iconphoto path is bad; using default image.')
                    self._icon = tkinter.PhotoImage(data=Icon.icon, master=self)
                    self.iconphoto(True, self._icon)

        self.title(title)

        if size is not None:
            width, height = size
            self.geometry(f"{width}x{height}")

        if position is not None:
            xpos, ypos = position
            self.geometry(f"+{xpos}+{ypos}")

        if minsize is not None:
            width, height = minsize
            self.minsize(width, height)

        if maxsize is not None:
            width, height = maxsize
            self.maxsize(width, height)

        if resizable is not None:
            width, height = resizable
            self.resizable(width, height)

        if transient is not None:
            self.transient(transient)

        if overrideredirect:
            self.overrideredirect(1)

        if alpha is not None:
            if self.winsys == 'x11':
                self.alpha = alpha
                self.alpha_bind = self.bind("<Visibility>", on_visibility, '+')
            else:
                self.attributes("-alpha", alpha)

        apply_class_bindings(self)
        apply_all_bindings(self)
        self._style = Style(themename)

    @property
    def style(self) -> Style:
        """Return a reference to the `ttkbootstrap.style.Style` object."""
        return self._style

    def destroy(self) -> None:
        """Destroy the window and all its children."""
        self._style.instance = None
        super().destroy()

    def place_window_center(self) -> None:
        """Position the toplevel in the center of the screen. Does not
        account for titlebar height."""
        self.update_idletasks()
        w_height = self.winfo_height()
        w_width = self.winfo_width()
        s_height = self.winfo_screenheight()
        s_width = self.winfo_screenwidth()
        xpos = (s_width - w_width) // 2
        ypos = (s_height - w_height) // 2
        self.geometry(f'+{xpos}+{ypos}')

    position_center = place_window_center  # alias

style property

Return a reference to the ttkbootstrap.style.Style object.

__init__(title='ttkbootstrap', themename='litera', iconphoto='', size=None, position=None, minsize=None, maxsize=None, resizable=None, hdpi=True, scaling=None, transient=None, overrideredirect=False, alpha=1.0, **kwargs)

Parameters:

title (str):
    The title that appears on the application titlebar.

themename (str):
    The name of the ttkbootstrap theme to apply to the
    application.

iconphoto (str):
    A path to the image used for the titlebar icon.
    Internally this is passed to the `Tk.iconphoto` method
    and the image will be the default icon for all windows.
    A ttkbootstrap image is used by default. To disable
    this default behavior, set the value to `None` and use
    the `Tk.iconphoto` or `Tk.iconbitmap` methods directly.

size (tuple[int, int]):
    The width and height of the application window.
    Internally, this argument is passed to the
    `Window.geometry` method.

position (tuple[int, int]):
    The horizontal and vertical position of the window on
    the screen relative to the top-left coordinate.
    Internally this is passed to the `Window.geometry`
    method.

minsize (tuple[int, int]):
    Specifies the minimum permissible dimensions for the
    window. Internally, this argument is passed to the
    `Window.minsize` method.

maxsize (tuple[int, int]):
    Specifies the maximum permissible dimensions for the
    window. Internally, this argument is passed to the
    `Window.maxsize` method.

resizable (tuple[bool, bool]):
    Specifies whether the user may interactively resize the
    toplevel window. Must pass in two arguments that specify
    this flag for _horizontal_ and _vertical_ dimensions.
    This can be adjusted after the window is created by using
    the `Window.resizable` method.

hdpi (bool):
    Enable high-dpi support for Windows OS. This option is
    enabled by default.

scaling (float):
    Sets the current scaling factor used by Tk to convert
    between physical units (for example, points, inches, or
    millimeters) and pixels. The number argument is a
    floating point number that specifies the number of pixels
    per point on window's display.

transient (Union[Tk, Widget]):
    Instructs the window manager that this widget is
    transient with regard to the widget master. Internally
    this is passed to the `Window.transient` method.

overrideredirect (bool):
    Instructs the window manager to ignore this widget if
    True. Internally, this argument is passed to the
    `Window.overrideredirect(1)` method.

alpha (float):
    On Windows, specifies the alpha transparency level of the
    toplevel. Where not supported, alpha remains at 1.0. Internally,
    this is processed as `Toplevel.attributes('-alpha', alpha)`.

**kwargs:
    Any other keyword arguments that are passed through to tkinter.Tk() constructor
    List of available keywords available at: https://docs.python.org/3/library/tkinter.html#tkinter.Tk

Source code in src/ttkbootstrap/window.py

def __init__(
        self,
        title: str = "ttkbootstrap",
        themename: str = "litera",
        iconphoto: Optional[str] = '',
        size: Optional[Tuple[int, int]] = None,
        position: Optional[Tuple[int, int]] = None,
        minsize: Optional[Tuple[int, int]] = None,
        maxsize: Optional[Tuple[int, int]] = None,
        resizable: Optional[Tuple[bool, bool]] = None,
        hdpi: bool = True,
        scaling: Optional[float] = None,
        transient: Optional[tkinter.Misc] = None,
        overrideredirect: bool = False,
        alpha: float = 1.0,
        **kwargs: Any,
) -> None:
    """
    Parameters:

        title (str):
            The title that appears on the application titlebar.

        themename (str):
            The name of the ttkbootstrap theme to apply to the
            application.

        iconphoto (str):
            A path to the image used for the titlebar icon.
            Internally this is passed to the `Tk.iconphoto` method
            and the image will be the default icon for all windows.
            A ttkbootstrap image is used by default. To disable
            this default behavior, set the value to `None` and use
            the `Tk.iconphoto` or `Tk.iconbitmap` methods directly.

        size (tuple[int, int]):
            The width and height of the application window.
            Internally, this argument is passed to the
            `Window.geometry` method.

        position (tuple[int, int]):
            The horizontal and vertical position of the window on
            the screen relative to the top-left coordinate.
            Internally this is passed to the `Window.geometry`
            method.

        minsize (tuple[int, int]):
            Specifies the minimum permissible dimensions for the
            window. Internally, this argument is passed to the
            `Window.minsize` method.

        maxsize (tuple[int, int]):
            Specifies the maximum permissible dimensions for the
            window. Internally, this argument is passed to the
            `Window.maxsize` method.

        resizable (tuple[bool, bool]):
            Specifies whether the user may interactively resize the
            toplevel window. Must pass in two arguments that specify
            this flag for _horizontal_ and _vertical_ dimensions.
            This can be adjusted after the window is created by using
            the `Window.resizable` method.

        hdpi (bool):
            Enable high-dpi support for Windows OS. This option is
            enabled by default.

        scaling (float):
            Sets the current scaling factor used by Tk to convert
            between physical units (for example, points, inches, or
            millimeters) and pixels. The number argument is a
            floating point number that specifies the number of pixels
            per point on window's display.

        transient (Union[Tk, Widget]):
            Instructs the window manager that this widget is
            transient with regard to the widget master. Internally
            this is passed to the `Window.transient` method.

        overrideredirect (bool):
            Instructs the window manager to ignore this widget if
            True. Internally, this argument is passed to the
            `Window.overrideredirect(1)` method.

        alpha (float):
            On Windows, specifies the alpha transparency level of the
            toplevel. Where not supported, alpha remains at 1.0. Internally,
            this is processed as `Toplevel.attributes('-alpha', alpha)`.

        **kwargs:
            Any other keyword arguments that are passed through to tkinter.Tk() constructor
            List of available keywords available at: https://docs.python.org/3/library/tkinter.html#tkinter.Tk
    """
    if hdpi:
        utility.enable_high_dpi_awareness()

    super().__init__(**kwargs)
    self.winsys: str = self.tk.call('tk', 'windowingsystem')

    if scaling is not None:
        utility.enable_high_dpi_awareness(self, scaling)

    if iconphoto is not None:
        if iconphoto == '':
            # the default ttkbootstrap icon
            self._icon = tkinter.PhotoImage(master=self, data=Icon.icon)
            self.iconphoto(True, self._icon)
        else:
            try:
                # the user provided an image path
                self._icon = tkinter.PhotoImage(file=iconphoto, master=self)
                self.iconphoto(True, self._icon)
            except tkinter.TclError:
                # The fallback icon if the user icon fails.
                print('iconphoto path is bad; using default image.')
                self._icon = tkinter.PhotoImage(data=Icon.icon, master=self)
                self.iconphoto(True, self._icon)

    self.title(title)

    if size is not None:
        width, height = size
        self.geometry(f"{width}x{height}")

    if position is not None:
        xpos, ypos = position
        self.geometry(f"+{xpos}+{ypos}")

    if minsize is not None:
        width, height = minsize
        self.minsize(width, height)

    if maxsize is not None:
        width, height = maxsize
        self.maxsize(width, height)

    if resizable is not None:
        width, height = resizable
        self.resizable(width, height)

    if transient is not None:
        self.transient(transient)

    if overrideredirect:
        self.overrideredirect(1)

    if alpha is not None:
        if self.winsys == 'x11':
            self.alpha = alpha
            self.alpha_bind = self.bind("<Visibility>", on_visibility, '+')
        else:
            self.attributes("-alpha", alpha)

    apply_class_bindings(self)
    apply_all_bindings(self)
    self._style = Style(themename)

destroy()

Destroy the window and all its children.

Source code in src/ttkbootstrap/window.py

def destroy(self) -> None:
    """Destroy the window and all its children."""
    self._style.instance = None
    super().destroy()

place_window_center()

Position the toplevel in the center of the screen. Does not account for titlebar height.

Source code in src/ttkbootstrap/window.py

def place_window_center(self) -> None:
    """Position the toplevel in the center of the screen. Does not
    account for titlebar height."""
    self.update_idletasks()
    w_height = self.winfo_height()
    w_width = self.winfo_width()
    s_height = self.winfo_screenheight()
    s_width = self.winfo_screenwidth()
    xpos = (s_width - w_width) // 2
    ypos = (s_height - w_height) // 2
    self.geometry(f'+{xpos}+{ypos}')