ScrolledFrame

Bases: Frame

A widget container with a vertical scrollbar.

The ScrolledFrame fills the width with its container. The height is either set explicitly or is determined by the content frame's contents.

This widget behaves mostly like a normal frame other than the exceptions stated already. Another exception is when packing it into a Notebook or Panedwindow. In this case, you'll need to add the container instead of the content frame. For example, mynotebook.add(myscrolledframe.container).

The scrollbar has an autohide feature that can be turned on by setting autohide=True.

Examples:

```python
import ttkbootstrap as ttk
from ttkbootstrap.constants import *
from ttkbootstrap.scrolled import ScrolledFrame

app = ttk.Window()

sf = ScrolledFrame(app, autohide=True)
sf.pack(fill=BOTH, expand=YES, padx=10, pady=10)

# add a large number of checkbuttons into the scrolled frame
for x in range(20):
    ttk.Checkbutton(sf, text=f"Checkbutton {x}").pack(anchor=W)

app.mainloop()
```

Source code in src/ttkbootstrap/widgets/scrolled.py

class ScrolledFrame(ttk.Frame):
    """A widget container with a vertical scrollbar.

    The ScrolledFrame fills the width with its container. The height is
    either set explicitly or is determined by the content frame's
    contents.

    This widget behaves mostly like a normal frame other than the
    exceptions stated already. Another exception is when packing it
    into a Notebook or Panedwindow. In this case, you'll need to add
    the container instead of the content frame. For example,
    `mynotebook.add(myscrolledframe.container)`.

    The scrollbar has an autohide feature that can be turned on by
    setting `autohide=True`.

    Examples:

        ```python
        import ttkbootstrap as ttk
        from ttkbootstrap.constants import *
        from ttkbootstrap.scrolled import ScrolledFrame

        app = ttk.Window()

        sf = ScrolledFrame(app, autohide=True)
        sf.pack(fill=BOTH, expand=YES, padx=10, pady=10)

        # add a large number of checkbuttons into the scrolled frame
        for x in range(20):
            ttk.Checkbutton(sf, text=f"Checkbutton {x}").pack(anchor=W)

        app.mainloop()
        ```"""

    def __init__(
            self,
            master: Optional[tkinter.Misc] = None,
            padding: int = 2,
            bootstyle: str = DEFAULT,
            autohide: bool = False,
            height: int = 200,
            width: int = 300,
            scrollheight: Optional[int] = None,
            **kwargs: Any,
    ) -> None:
        """
        Parameters:

            master (Widget):
                The parent widget.

            padding (int):
                The amount of empty space to create on the outside of
                the widget.

            bootstyle (str):
                A style keyword used to set the color and style of the
                vertical scrollbar. Available options include -> primary,
                secondary, success, info, warning, danger, dark, light.

            autohide (bool):
                When **True**, the scrollbars will hide when the mouse
                is not within the frame bbox.

            height (int):
                The height of the container frame in screen units.

            width (int):
                The width of the container frame in screen units.

            scrollheight (int):
                The height of the content frame in screen units. If None,
                the height is determined by the frame contents.

            **kwargs (dict[str, Any]):
                Other keyword arguments passed to the content frame.
        """
        # content frame container
        self.container: ttk.Frame = ttk.Frame(
            master=master,
            relief=FLAT,
            borderwidth=0,
            width=width,
            height=height,
        )
        self.container.bind("<Configure>", lambda _: self.yview())
        self.container.propagate(False)

        # content frame
        super().__init__(
            master=self.container,
            padding=padding,
            bootstyle=bootstyle.replace('round', ''),
            width=width,
            height=height,
            **kwargs,
        )
        self.place(rely=0.0, relwidth=1.0, height=scrollheight)

        # vertical scrollbar
        self.vscroll: ttk.Scrollbar = ttk.Scrollbar(
            master=self.container,
            command=self.yview,
            orient=VERTICAL,
            bootstyle=bootstyle,
        )
        self.vscroll.pack(side=RIGHT, fill=Y)

        self.winsys: str = self.tk.call("tk", "windowingsystem")

        # setup autohide scrollbar
        self.autohide: bool = autohide
        if self.autohide:
            self.hide_scrollbars()

        # widget event binding
        self.container.bind("<Enter>", self._on_enter, "+")
        self.container.bind("<Leave>", self._on_leave, "+")
        self.container.bind("<Map>", self._on_map, "+")
        self.bind("<<MapChild>>", self._on_map_child, "+")

        # delegate content geometry methods to container frame
        _methods = vars(Pack).keys() | vars(Grid).keys() | vars(Place).keys()
        for method in _methods:
            if any(["pack" in method, "grid" in method, "place" in method]):
                # prefix content frame methods with 'content_'
                setattr(self, f"content_{method}", getattr(self, method))
                # overwrite content frame methods from container frame
                setattr(self, method, getattr(self.container, method))

    def yview(self, *args: Any) -> None:
        """Update the vertical position of the content frame within the
        container.

        Parameters:

            *args (list[Any, ...]):
                Optional arguments passed to yview in order to move the
                content frame within the container frame.
        """
        if not args:
            first, _ = self.vscroll.get()
            self.yview_moveto(fraction=first)
        elif args[0] == "moveto":
            self.yview_moveto(fraction=float(args[1]))
        elif args[0] == "scroll":
            self.yview_scroll(number=int(args[1]), what=args[2])
        else:
            return

    def yview_moveto(self, fraction: float) -> None:
        """Update the vertical position of the content frame within the
        container.

        Parameters:

            fraction (float):
                The relative position of the content frame within the
                container.
        """
        base, thumb = self._measures()
        if fraction < 0:
            first = 0.0
        elif (fraction + thumb) > 1:
            first = 1 - thumb
        else:
            first = fraction
        self.vscroll.set(first, first + thumb)
        self.content_place(rely=-first * base)

    def yview_scroll(self, number: int, what: str) -> None:
        """Update the vertical position of the content frame within the
        container.

        Parameters:

            number (int):
                The amount by which the content frame will be moved
                within the container frame by 'what' units.

            what (str):
                The type of units by which the number is to be interpeted.
                This parameter is currently not used and is assumed to be
                'units'.
        """
        first, _ = self.vscroll.get()
        fraction = (number / 100) + first
        self.yview_moveto(fraction)

    def _add_scroll_binding(self, parent: tkinter.Misc) -> None:
        """Recursive adding of scroll binding to all descendants."""
        children = parent.winfo_children()
        for widget in [parent, *children]:
            bindings = widget.bind()
            if self.winsys.lower() == "x11":
                if "<Button-4>" in bindings or "<Button-5>" in bindings:
                    continue
                else:
                    widget.bind("<Button-4>", self._on_mousewheel, "+")
                    widget.bind("<Button-5>", self._on_mousewheel, "+")
            else:
                if "<MouseWheel>" not in bindings:
                    widget.bind("<MouseWheel>", self._on_mousewheel, "+")
            if widget.winfo_children() and widget != parent:
                self._add_scroll_binding(widget)

    def _del_scroll_binding(self, parent: tkinter.Misc) -> None:
        """Recursive removal of scrolling binding for all descendants"""
        children = parent.winfo_children()
        for widget in [parent, *children]:
            if self.winsys.lower() == "x11":
                widget.unbind("<Button-4>")
                widget.unbind("<Button-5>")
            else:
                widget.unbind("<MouseWheel>")
            if widget.winfo_children() and widget != parent:
                self._del_scroll_binding(widget)

    def enable_scrolling(self) -> None:
        """Enable mousewheel scrolling on the frame and all of its
        children."""
        self._add_scroll_binding(self)

    def disable_scrolling(self) -> None:
        """Disable mousewheel scrolling on the frame and all of its
        children."""
        self._del_scroll_binding(self)

    def hide_scrollbars(self) -> None:
        """Hide the scrollbars."""
        self.vscroll.pack_forget()

    def show_scrollbars(self) -> None:
        """Show the scrollbars."""
        self.vscroll.pack(side=RIGHT, fill=Y)

    def autohide_scrollbar(self) -> None:
        """Toggle the autohide funtionality. Show the scrollbars when
        the mouse enters the widget frame, and hide when it leaves the
        frame."""
        self.autohide = not self.autohide

    def destroy(self) -> None:
        super().destroy()

    def _measures(self) -> Tuple[float, float]:
        """Measure the base size of the container and the thumb size
        for use in the yview methods"""
        outer = self.container.winfo_height()
        inner = max([self.winfo_height(), outer])
        base = inner / outer
        if inner == outer:
            thumb = 1.0
        else:
            thumb = outer / inner
        return base, thumb

    def _on_map_child(self, event: tkinter.Event) -> None:
        """Callback for when a widget is mapped to the content frame."""
        if self.container.winfo_ismapped():
            self.yview()

    def _on_enter(self, event: tkinter.Event) -> None:
        """Callback for when the mouse enters the widget."""
        self.enable_scrolling()
        if self.autohide:
            self.show_scrollbars()

    def _on_leave(self, event: tkinter.Event) -> None:
        """Callback for when the mouse leaves the widget."""
        self.disable_scrolling()
        if self.autohide:
            self.hide_scrollbars()

    def _on_configure(self, event: tkinter.Event) -> None:
        """Callback for when the widget is configured"""
        self.yview()

    def _on_map(self, event: tkinter.Event) -> None:
        self.yview()

    def _on_mousewheel(self, event: tkinter.Event) -> None:
        """Callback for when the mouse wheel is scrolled."""
        delta = 0
        if self.winsys.lower() == "win32":
            delta = -int(event.delta / 120)
        elif self.winsys.lower() == "aqua":
            delta = -event.delta
        elif event.num == 4:
            delta = -10
        elif event.num == 5:
            delta = 10
        self.yview_scroll(delta, UNITS)

    # Statically declare dynamically-assigned geometry helpers for type checkers
    content_pack: Callable[..., Any]
    content_grid: Callable[..., Any]
    content_place: Callable[..., Any]

__init__(master=None, padding=2, bootstyle=DEFAULT, autohide=False, height=200, width=300, scrollheight=None, **kwargs)

Parameters:

master (Widget):
    The parent widget.

padding (int):
    The amount of empty space to create on the outside of
    the widget.

bootstyle (str):
    A style keyword used to set the color and style of the
    vertical scrollbar. Available options include -> primary,
    secondary, success, info, warning, danger, dark, light.

autohide (bool):
    When **True**, the scrollbars will hide when the mouse
    is not within the frame bbox.

height (int):
    The height of the container frame in screen units.

width (int):
    The width of the container frame in screen units.

scrollheight (int):
    The height of the content frame in screen units. If None,
    the height is determined by the frame contents.

**kwargs (dict[str, Any]):
    Other keyword arguments passed to the content frame.

Source code in src/ttkbootstrap/widgets/scrolled.py

def __init__(
        self,
        master: Optional[tkinter.Misc] = None,
        padding: int = 2,
        bootstyle: str = DEFAULT,
        autohide: bool = False,
        height: int = 200,
        width: int = 300,
        scrollheight: Optional[int] = None,
        **kwargs: Any,
) -> None:
    """
    Parameters:

        master (Widget):
            The parent widget.

        padding (int):
            The amount of empty space to create on the outside of
            the widget.

        bootstyle (str):
            A style keyword used to set the color and style of the
            vertical scrollbar. Available options include -> primary,
            secondary, success, info, warning, danger, dark, light.

        autohide (bool):
            When **True**, the scrollbars will hide when the mouse
            is not within the frame bbox.

        height (int):
            The height of the container frame in screen units.

        width (int):
            The width of the container frame in screen units.

        scrollheight (int):
            The height of the content frame in screen units. If None,
            the height is determined by the frame contents.

        **kwargs (dict[str, Any]):
            Other keyword arguments passed to the content frame.
    """
    # content frame container
    self.container: ttk.Frame = ttk.Frame(
        master=master,
        relief=FLAT,
        borderwidth=0,
        width=width,
        height=height,
    )
    self.container.bind("<Configure>", lambda _: self.yview())
    self.container.propagate(False)

    # content frame
    super().__init__(
        master=self.container,
        padding=padding,
        bootstyle=bootstyle.replace('round', ''),
        width=width,
        height=height,
        **kwargs,
    )
    self.place(rely=0.0, relwidth=1.0, height=scrollheight)

    # vertical scrollbar
    self.vscroll: ttk.Scrollbar = ttk.Scrollbar(
        master=self.container,
        command=self.yview,
        orient=VERTICAL,
        bootstyle=bootstyle,
    )
    self.vscroll.pack(side=RIGHT, fill=Y)

    self.winsys: str = self.tk.call("tk", "windowingsystem")

    # setup autohide scrollbar
    self.autohide: bool = autohide
    if self.autohide:
        self.hide_scrollbars()

    # widget event binding
    self.container.bind("<Enter>", self._on_enter, "+")
    self.container.bind("<Leave>", self._on_leave, "+")
    self.container.bind("<Map>", self._on_map, "+")
    self.bind("<<MapChild>>", self._on_map_child, "+")

    # delegate content geometry methods to container frame
    _methods = vars(Pack).keys() | vars(Grid).keys() | vars(Place).keys()
    for method in _methods:
        if any(["pack" in method, "grid" in method, "place" in method]):
            # prefix content frame methods with 'content_'
            setattr(self, f"content_{method}", getattr(self, method))
            # overwrite content frame methods from container frame
            setattr(self, method, getattr(self.container, method))

autohide_scrollbar()

Toggle the autohide funtionality. Show the scrollbars when the mouse enters the widget frame, and hide when it leaves the frame.

Source code in src/ttkbootstrap/widgets/scrolled.py

def autohide_scrollbar(self) -> None:
    """Toggle the autohide funtionality. Show the scrollbars when
    the mouse enters the widget frame, and hide when it leaves the
    frame."""
    self.autohide = not self.autohide

disable_scrolling()

Disable mousewheel scrolling on the frame and all of its children.

Source code in src/ttkbootstrap/widgets/scrolled.py

def disable_scrolling(self) -> None:
    """Disable mousewheel scrolling on the frame and all of its
    children."""
    self._del_scroll_binding(self)

enable_scrolling()

Enable mousewheel scrolling on the frame and all of its children.

Source code in src/ttkbootstrap/widgets/scrolled.py

def enable_scrolling(self) -> None:
    """Enable mousewheel scrolling on the frame and all of its
    children."""
    self._add_scroll_binding(self)

hide_scrollbars()

Hide the scrollbars.

Source code in src/ttkbootstrap/widgets/scrolled.py

def hide_scrollbars(self) -> None:
    """Hide the scrollbars."""
    self.vscroll.pack_forget()

show_scrollbars()

Show the scrollbars.

Source code in src/ttkbootstrap/widgets/scrolled.py

def show_scrollbars(self) -> None:
    """Show the scrollbars."""
    self.vscroll.pack(side=RIGHT, fill=Y)

yview(*args)

Update the vertical position of the content frame within the container.

Parameters:

*args (list[Any, ...]):
    Optional arguments passed to yview in order to move the
    content frame within the container frame.

Source code in src/ttkbootstrap/widgets/scrolled.py

def yview(self, *args: Any) -> None:
    """Update the vertical position of the content frame within the
    container.

    Parameters:

        *args (list[Any, ...]):
            Optional arguments passed to yview in order to move the
            content frame within the container frame.
    """
    if not args:
        first, _ = self.vscroll.get()
        self.yview_moveto(fraction=first)
    elif args[0] == "moveto":
        self.yview_moveto(fraction=float(args[1]))
    elif args[0] == "scroll":
        self.yview_scroll(number=int(args[1]), what=args[2])
    else:
        return

yview_moveto(fraction)

Update the vertical position of the content frame within the container.

Parameters:

fraction (float):
    The relative position of the content frame within the
    container.

Source code in src/ttkbootstrap/widgets/scrolled.py

def yview_moveto(self, fraction: float) -> None:
    """Update the vertical position of the content frame within the
    container.

    Parameters:

        fraction (float):
            The relative position of the content frame within the
            container.
    """
    base, thumb = self._measures()
    if fraction < 0:
        first = 0.0
    elif (fraction + thumb) > 1:
        first = 1 - thumb
    else:
        first = fraction
    self.vscroll.set(first, first + thumb)
    self.content_place(rely=-first * base)

yview_scroll(number, what)

Update the vertical position of the content frame within the container.

Parameters:

number (int):
    The amount by which the content frame will be moved
    within the container frame by 'what' units.

what (str):
    The type of units by which the number is to be interpeted.
    This parameter is currently not used and is assumed to be
    'units'.

Source code in src/ttkbootstrap/widgets/scrolled.py

def yview_scroll(self, number: int, what: str) -> None:
    """Update the vertical position of the content frame within the
    container.

    Parameters:

        number (int):
            The amount by which the content frame will be moved
            within the container frame by 'what' units.

        what (str):
            The type of units by which the number is to be interpeted.
            This parameter is currently not used and is assumed to be
            'units'.
    """
    first, _ = self.vscroll.get()
    fraction = (number / 100) + first
    self.yview_moveto(fraction)