ScrollArea

class pygame_menu._scrollarea.ScrollArea(area_width, area_height, area_color=None, border_color=None, border_width=0, controls_joystick=True, controls_keyboard=True, controls_mouse=True, controls_touchscreen=True, extend_x=0, extend_y=0, menubar=None, parent_scrollarea=None, scrollarea_id='', scrollbar_color=(235, 235, 235), scrollbar_cursor=None, scrollbar_slider_color=(200, 200, 200), scrollbar_slider_hover_color=(180, 180, 180), scrollbar_slider_pad=0, scrollbar_thick=20, scrollbars=('position-south', 'position-east'), shadow=False, shadow_color=(0, 0, 0), shadow_offset=2, shadow_position='position-southeast', world=None)

The ScrollArea class provides a scrolling view managing up to 4 scroll bars.

A scroll area is used to display the contents of a child surface (world). If the surface exceeds the size of the drawing surface, the view provide scroll bars so that the entire area of the child surface can be viewed.

Note

See pygame_menu.locals for valid scrollbars and shadow_position values.

Note

ScrollArea cannot be copied or deep-copied.

Parameters:

• area_width (int) – Width of scrollable area in px

• area_height (int) – Height of scrollable area in px

• area_color (ColorInputType | pygame_menu.BaseImage | None) – Background color, it can be a color or an image

• border_color (ColorInputType | pygame_menu.BaseImage | None) – Border color

• border_width (int) – Border width in px

• controls_joystick (bool) – Use joystick events

• controls_keyboard (bool) – Use keyboard events

• controls_mouse (bool) – Use mouse events

• controls_touchscreen (bool) – Use touchscreen events

• extend_x (int) – Px to extend the surface on x-axis in px from left. Recommended use only within Menus

• extend_y (int) – Px to extend the surface on y-axis in px from top. Recommended use only within Menus

• menubar (pygame_menu.widgets.MenuBar | None) – Menubar for style compatibility. None if ScrollArea is not used within a Menu (for example, in Frames)

• parent_scrollarea (ScrollArea | None) – Parent ScrollArea if the new one is added within another area

• scrollarea_id (str) – Scrollarea ID

• scrollbar_color (ColorInputType) – Scrollbars color

• scrollbar_cursor (CursorInputType) – Scrollbar cursor

• scrollbar_slider_color (ColorInputType) – Color of the sliders

• scrollbar_slider_hover_color (ColorInputType) – Color of the slider if hovered or clicked

• scrollbar_slider_pad (NumberType) – Space between slider and scrollbars borders in px

• scrollbar_thick (int) – Scrollbar thickness in px

• scrollbars (StringVector) – Positions of the scrollbars. See pygame_menu.locals

• shadow (bool) – Indicate if a shadow is drawn on each scrollbar

• shadow_color (ColorInputType) – Color of the shadow of each scrollbar

• shadow_offset (int) – Offset of the scrollbar shadow in px

• shadow_position (str) – Position of the scrollbar shadow. See pygame_menu.locals

• world (pygame.Surface | None) – Surface to draw and scroll

collide(widget, event)

If user event collides a widget within the ScrollArea respect to the relative position.

Parameters:

• widget (pygame_menu.widgets.Widget | pygame.Rect) – Widget or rect

• event (EventType) – Pygame event

Return type:

bool

Returns:

True if collide

create_rect(width, height)

Create rect object.

Parameters:

• width (int) – Area width

• height (int) – Area height

Return type:

None

draw(surface)

Draw the ScrollArea.

Parameters:

surface (Surface) – Surface to render the area

Return type:

ScrollArea

Returns:

Self reference

force_menu_surface_cache_update()

Forces menu surface cache to update after next drawing call. This also updates widget decoration.

Note

This method only updates the surface cache, without forcing re-rendering of all Menu widgets as pygame_menu.widgets.core.widget.Widget.force_menu_surface_update() does.

Return type:

ScrollArea

Returns:

Self reference

force_menu_surface_update()

Forces menu surface update after next rendering call.

Note

This method is expensive, as menu surface update forces re-rendering of all widgets (because them can change in size, position, etc…).

Return type:

ScrollArea

Returns:

Self reference

get_absolute_view_rect()

Return the ScrollArea absolute view rect clipped if it is not visible by its parent ScrollArea.

Return type:

Rect

Returns:

Clipped absolute view rect

get_border_size()

Return the border size (width, height) in px.

Return type:

tuple[int, int]

Returns:

Border width, height

get_decorator()

Return the ScrollArea decorator API.

Note

Menu drawing order:

1. Menu background color/image

2. Menu prev decorator

3. Menu ScrollArea prev decorator

4. Menu ScrollArea widgets

5. Menu ScrollArea post decorator

6. Menu title

7. Menu post decorator

Return type:

Decorator

Returns:

Decorator API

get_depth()

Return the depth of the ScrollArea (how many parents do it has recursively).

Return type:

int

Returns:

Depth’s number

get_hidden_height()

Return the total height out of the bounds of the viewable area. Zero is returned if the world height is lower than the viewable area.

Return type:

int

Returns:

Hidden height in px

get_hidden_width()

Return the total width out of the bounds of the viewable area. Zero is returned if the world width is lower than the viewable area.

Return type:

int

Returns:

Hidden width in px

get_menu()

Return the Menu reference (if exists).

Return type:

pygame_menu.Menu | None

Returns:

Menu reference

get_offsets()

Return the offset introduced by the scrollbars in the world.

Return type:

tuple[int, int]

Returns:

ScrollArea offset on x-axis and y-axis (x, y)

get_parent()

Return the parent ScrollArea.

Return type:

ScrollArea | None

Returns:

Parent ScrollArea object

get_parent_position()

Return parent ScrollArea position.

Return type:

tuple[int, int]

Returns:

Position on x, y-axis in px

get_parent_scroll_value_percentage(orientation)

Get percentage scroll values of scroll and parents; if 0 the scroll is at top/left, 1 bottom/right.

Parameters:

orientation (str) – Orientation. See pygame_menu.locals

Return type:

tuple[float, ...]

Returns:

Value from 0 to 1 as a tuple; first item is the current scrollarea

get_position()

Return the ScrollArea position.

Return type:

tuple[int, int]

Returns:

X, Y position in px

get_rect(to_real_position=False)

Return the pygame.Rect object of the ScrollArea.

Parameters:

to_real_position (bool) – Get real position fof the scroll area

Return type:

Rect

Returns:

Pygame.Rect object

get_scroll_value_percentage(orientation)

Get the scroll value in percentage; if 0 the scroll is at top/left, 1 bottom/right.

Note

If ScrollArea does not contain such orientation scroll, -1 is returned.

Parameters:

orientation (str) – Orientation. See pygame_menu.locals

Return type:

float

Returns:

Value from 0 to 1

get_scrollbar(position)

Returns the scrollbar at the given position, or None if not present. :type position: str :param position: The position of the scrollbar (e.g., POSITION_NORTH, POSITION_EAST). :rtype: ScrollBar | None :return: The ScrollBar object or None.

get_scrollbar_thickness(orientation, visible=True)

Return the scroll thickness of the area. If it’s hidden return zero.

Parameters:

• orientation (str) – Orientation of the scroll. See pygame_menu.locals

• visible (bool) – If True returns the real thickness depending on if it is visible or not

Return type:

int

Returns:

Thickness in px

get_size(inner=False)

Return the area size.

Parameters:

inner (bool) – If True returns the rect view area

Return type:

tuple[int, int]

Returns:

Width, height in pixels

get_translate()

Get object translation on both axis.

Return type:

tuple[int, int]

Returns:

Translation on x-axis and y-axis (x, y) in px

get_view_rect()

Subtract width of scrollbars from area with the given size and return the viewable area.

The viewable area depends on the world size, because scroll bars may or may not be displayed.

Return type:

Rect

Returns:

View rect object

get_widget_position_relative_to_view_rect(widget)

Get widget position relative to view rect on x-axis and y-axis. On each axis, the relative position goes from -inf to +inf. If between (0, 1) the widget is inside the view rect.

Note

Only top-left widget position is checked.

Parameters:

widget (Widget) – Widget to check the position

Return type:

tuple[Union[int, float], Union[int, float]]

Returns:

Relative position to view rect on x-axis and y-axis

get_world()

Return the world surface area.

Warning

Use with caution.

Return type:

pygame.Surface | None

Returns:

World surface. None if it has not been set yet

get_world_rect(absolute=False)

Return the world rect.

Parameters:

absolute (bool) – To absolute position

Return type:

Rect

Returns:

World rect object

get_world_size()

Return the world size.

Return type:

tuple[int, int]

Returns:

Width, height in pixels

hide_scrollbars(orientation, force=True)

Hide scrollbar from given orientation.

Parameters:

• orientation (str) – Orientation. See pygame_menu.locals

• force (bool) – Force hide

Return type:

ScrollArea

Returns:

Self reference

is_scrolling()

Return True if the user is scrolling.

Return type:

bool

Returns:

True if user scrolls

mouse_is_over(view=False)

Return True if the mouse is placed over the ScrollArea.

Parameters:

view (bool) – If True uses “view rect” instead of “rect”

Return type:

bool

Returns:

True if the mouse is over the object

scroll_to(orientation, value)

Scroll to position in terms of the percentage.

Parameters:

• orientation (str) – Orientation. See pygame_menu.locals

• value (Union[int, float]) – If 0 scrolls to top/left, 1 to bottom/right

Return type:

ScrollArea

Returns:

Self reference

scroll_to_rect(rect, margin=(0, 0), scroll_parent=True)

Ensure that the given rect is in the viewable area.

Parameters:

• rect (Rect) – Rect in the world surface reference

• margin (tuple[Union[int, float], Union[int, float]]) – Extra margin around the rect on x-axis and y-axis in px

• scroll_parent (bool) – If True parent scroll also scrolls to rect

Return type:

bool

Returns:

Scrollarea scrolled to rect. If False the rect was already inside the visible area

set_menu(menu)

Set the Menu reference.

Parameters:

menu (Menu) – Menu object

Return type:

ScrollArea

Returns:

Self reference

set_parent_scrollarea(parent)

Set parent ScrollArea.

Parameters:

parent (ScrollArea | None) – Parent ScrollArea

Return type:

ScrollArea

set_position(x, y)

Set the position.

Parameters:

• x (int) – X position

• y (int) – Y position

Return type:

ScrollArea

Returns:

Self reference

set_world(surface)

Update the scrolled surface.

Parameters:

surface (Surface) – New world surface

Return type:

ScrollArea

Returns:

Self reference

show_scrollbars(orientation, force=True)

Hide scrollbar from given orientation.

Parameters:

• orientation (str) – Orientation. See pygame_menu.locals

• force (bool) – Force show

Return type:

ScrollArea

Returns:

Self reference

to_absolute_position(virtual)

Return the absolute position of a rect within the ScrollArea. Absolute position is concerning the parent ScrollArea. If None, the rect is not changed at all.

Note

Absolute position must be used if desired to get the widget position outside a scrolled area status, for example the view rect, or the scrollbars.

Parameters:

virtual (Rect) – Rect in the world surface reference

Return type:

Rect

Returns:

Rect in absolute position

to_real_position(virtual, visible=False)

Return the real position/Rect according to the ScrollArea origin of a position/Rect in the world surface reference.

Note

Real position must be used if desired to get the widget position within a scrolled area status.

Parameters:

• virtual (pygame.Rect | Tuple2NumberType) – Position/Rect in the world surface reference

• visible (bool) – If a virtual is Rect object, return only the visible width/height

Return type:

pygame.Rect | Tuple2IntType

Returns:

Real rect or real position

to_world_position(real)

Return the position/Rect in the world surface reference of a real position/Rect according to the ScrollArea origin.

Note

Virtual position must be used if desired to get the widget position within a scrolled area status.

Parameters:

real (pygame.Rect | Tuple2NumberType) – Position/Rect according ScrollArea origin

Return type:

pygame.Rect | Tuple2IntType

Returns:

Rect in world or position in world

translate(x, y)

Translate on x-axis and y-axis (x, y) in px.

Parameters:

• x (Union[int, float]) – X translation in px

• y (Union[int, float]) – Y translation in px

Return type:

ScrollArea

Returns:

Self reference

update(events)

Called by end user to update scroll state.

Parameters:

events (Union[list[Event], tuple[Event]]) – List of pygame events

Return type:

bool

Returns:

True if updated

update_area_color(color)

Updates area color (background).

Parameters:

color (ColorInputType | pygame_menu.BaseImage | None) – Color

Return type:

ScrollArea

Returns:

Self reference