Toplevel

Bases: Toplevel

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

Examples:

```python
app = Toplevel(title="My Toplevel")
app.mainloop()
```

Source code in src/ttkbootstrap/window.py

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

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

    Examples:

        ```python
        app = Toplevel(title="My Toplevel")
        app.mainloop()
        ```
    """

    def __init__(
            self,
            title: str = "ttkbootstrap",
            iconphoto: 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,
            transient: Optional[tkinter.Misc] = None,
            overrideredirect: bool = False,
            windowtype: Optional[str] = None,
            topmost: bool = False,
            toolwindow: bool = False,
            alpha: float = 1.0,
            **kwargs: Any,
    ) -> None:
        """
        Parameters:

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

            iconphoto (str):
                A path to the image used for the titlebar icon.
                Internally this is passed to the `Tk.iconphoto` method.
                By default the application icon is used.

            size (tuple[int, int]):
                The width and height of the application window.
                Internally, this argument is passed to the
                `Toplevel.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 `Toplevel.geometry`
                method.

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

            maxsize (tuple[int, int]):
                Specifies the maximum permissible dimensions for the
                window. Internally, this argument is passed to the
                `Toplevel.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 `Toplevel.resizable` method.

            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 `Toplevel.transient` method.

            overrideredirect (bool):
                Instructs the window manager to ignore this widget if
                True. Internally, this argument is processed as
                `Toplevel.overrideredirect(1)`.

            windowtype (str):
                On X11, requests that the window should be interpreted by
                the window manager as being of the specified type. Internally,
                this is passed to the `Toplevel.attributes('-type', windowtype)`.

                See the [-type option](https://tcl.tk/man/tcl8.6/TkCmd/wm.htm#M64)
                for a list of available options.

            topmost (bool):
                Specifies whether this is a topmost window (displays above all
                other windows). Internally, this processed by the window as
                `Toplevel.attributes('-topmost', 1)`.

            toolwindow (bool):
                On Windows, specifies a toolwindow style. Internally, this is
                processed as `Toplevel.attributes('-toolwindow', 1)`.

            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 (Dict):
                Other optional keyword arguments.
        """
        if 'iconify' in kwargs:
            iconify = kwargs.pop('iconify')
        else:
            iconify = None

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

        if iconphoto != '':
            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.')
                pass

        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 iconify:
            self.iconify()

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

        if overrideredirect:
            self.overrideredirect(1)

        if windowtype is not None:
            if self.winsys == 'x11':
                self.attributes("-type", windowtype)

        if topmost:
            self.attributes("-topmost", 1)

        if toolwindow:
            if self.winsys == 'win32':
                self.attributes("-toolwindow", 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)

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

    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', iconphoto='', size=None, position=None, minsize=None, maxsize=None, resizable=None, transient=None, overrideredirect=False, windowtype=None, topmost=False, toolwindow=False, alpha=1.0, **kwargs)

Parameters:

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

iconphoto (str):
    A path to the image used for the titlebar icon.
    Internally this is passed to the `Tk.iconphoto` method.
    By default the application icon is used.

size (tuple[int, int]):
    The width and height of the application window.
    Internally, this argument is passed to the
    `Toplevel.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 `Toplevel.geometry`
    method.

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

maxsize (tuple[int, int]):
    Specifies the maximum permissible dimensions for the
    window. Internally, this argument is passed to the
    `Toplevel.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 `Toplevel.resizable` method.

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 `Toplevel.transient` method.

overrideredirect (bool):
    Instructs the window manager to ignore this widget if
    True. Internally, this argument is processed as
    `Toplevel.overrideredirect(1)`.

windowtype (str):
    On X11, requests that the window should be interpreted by
    the window manager as being of the specified type. Internally,
    this is passed to the `Toplevel.attributes('-type', windowtype)`.

    See the [-type option](https://tcl.tk/man/tcl8.6/TkCmd/wm.htm#M64)
    for a list of available options.

topmost (bool):
    Specifies whether this is a topmost window (displays above all
    other windows). Internally, this processed by the window as
    `Toplevel.attributes('-topmost', 1)`.

toolwindow (bool):
    On Windows, specifies a toolwindow style. Internally, this is
    processed as `Toplevel.attributes('-toolwindow', 1)`.

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 (Dict):
    Other optional keyword arguments.

Source code in src/ttkbootstrap/window.py

def __init__(
        self,
        title: str = "ttkbootstrap",
        iconphoto: 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,
        transient: Optional[tkinter.Misc] = None,
        overrideredirect: bool = False,
        windowtype: Optional[str] = None,
        topmost: bool = False,
        toolwindow: bool = False,
        alpha: float = 1.0,
        **kwargs: Any,
) -> None:
    """
    Parameters:

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

        iconphoto (str):
            A path to the image used for the titlebar icon.
            Internally this is passed to the `Tk.iconphoto` method.
            By default the application icon is used.

        size (tuple[int, int]):
            The width and height of the application window.
            Internally, this argument is passed to the
            `Toplevel.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 `Toplevel.geometry`
            method.

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

        maxsize (tuple[int, int]):
            Specifies the maximum permissible dimensions for the
            window. Internally, this argument is passed to the
            `Toplevel.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 `Toplevel.resizable` method.

        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 `Toplevel.transient` method.

        overrideredirect (bool):
            Instructs the window manager to ignore this widget if
            True. Internally, this argument is processed as
            `Toplevel.overrideredirect(1)`.

        windowtype (str):
            On X11, requests that the window should be interpreted by
            the window manager as being of the specified type. Internally,
            this is passed to the `Toplevel.attributes('-type', windowtype)`.

            See the [-type option](https://tcl.tk/man/tcl8.6/TkCmd/wm.htm#M64)
            for a list of available options.

        topmost (bool):
            Specifies whether this is a topmost window (displays above all
            other windows). Internally, this processed by the window as
            `Toplevel.attributes('-topmost', 1)`.

        toolwindow (bool):
            On Windows, specifies a toolwindow style. Internally, this is
            processed as `Toplevel.attributes('-toolwindow', 1)`.

        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 (Dict):
            Other optional keyword arguments.
    """
    if 'iconify' in kwargs:
        iconify = kwargs.pop('iconify')
    else:
        iconify = None

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

    if iconphoto != '':
        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.')
            pass

    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 iconify:
        self.iconify()

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

    if overrideredirect:
        self.overrideredirect(1)

    if windowtype is not None:
        if self.winsys == 'x11':
            self.attributes("-type", windowtype)

    if topmost:
        self.attributes("-topmost", 1)

    if toolwindow:
        if self.winsys == 'win32':
            self.attributes("-toolwindow", 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)

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}')