ScrollArea

class pygame_menu._scrollarea.ScrollArea(area_width, area_height, area_color=None, 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)[source]

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 (Union[Tuple[int, int, int], Tuple[int, int, int, int], str, int, Color, BaseImage, None]) – Background color, it can be a color or an image

  • 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 (Optional[MenuBar]) – Menubar for style compatibility. None if ScrollArea is not used within a Menu (for example, in Frames)

  • parent_scrollarea (Optional[ScrollArea]) – Parent ScrollArea if the new one is added within another area

  • scrollarea_id (str) – Scrollarea ID

  • scrollbar_color (Union[Tuple[int, int, int], Tuple[int, int, int, int], str, int, Color]) – Scrollbars color

  • scrollbar_cursor (Union[int, Cursor, None]) – Scrollbar cursor

  • scrollbar_slider_color (Union[Tuple[int, int, int], Tuple[int, int, int, int], str, int, Color]) – Color of the sliders

  • scrollbar_slider_hover_color (Union[Tuple[int, int, int], Tuple[int, int, int, int], str, int, Color]) – Color of the slider if hovered or clicked

  • scrollbar_slider_pad (Union[int, float]) – Space between slider and scrollbars borders in px

  • scrollbar_thick (int) – Scrollbar thickness in px

  • scrollbars (Union[str, Tuple[str, …], List[str]]) – Positions of the scrollbars. See pygame_menu.locals

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

  • shadow_color (Union[Tuple[int, int, int], Tuple[int, int, int, int], str, int, Color]) – 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 (Optional[Surface]) – Surface to draw and scroll

collide(widget, event)[source]

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

Parameters
  • widget (Union[Widget, Rect]) – Widget or rect

  • event (Event) – Pygame event

Return type

bool

Returns

True if collide

draw(surface)[source]

Draw the ScrollArea.

Parameters

surface (Surface) – Surface to render the area

Return type

ScrollArea

Returns

Self reference

force_menu_surface_cache_update()[source]

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()[source]

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()[source]

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

Return type

Rect

Returns

Clipped absolute view rect

get_decorator()[source]

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()[source]

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

Return type

int

Returns

Depth’s number

get_hidden_height()[source]

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()[source]

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()[source]

Return the Menu reference (if exists).

Return type

Optional[Menu]

Returns

Menu reference

get_offsets()[source]

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()[source]

Return the parent ScrollArea.

Return type

Optional[ScrollArea]

Returns

Parent ScrollArea object

get_parent_position()[source]

Return parent ScrollArea position.

Return type

Tuple[int, int]

Returns

Position on x, y axis in px

get_parent_scroll_value_percentage(orientation)[source]

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()[source]

Return the ScrollArea position.

Return type

Tuple[int, int]

Returns

X, Y position in px

get_rect(to_real_position=False)[source]

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)[source]

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_thickness(orientation, visible=True)[source]

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 if it is visible or not

Return type

int

Returns

Thickness in px

get_size(inner=False)[source]

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()[source]

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()[source]

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)[source]

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()[source]

Return the world surface area.

Warning

Use with caution.

Return type

Optional[Surface]

Returns

World surface. None if it has not been set yet

get_world_rect(absolute=False)[source]

Return the world rect.

Parameters

absolute (bool) – To absolute position

Return type

Rect

Returns

World rect object

get_world_size()[source]

Return the world size.

Return type

Tuple[int, int]

Returns

Width, height in pixels

hide_scrollbars(orientation)[source]

Hide scrollbar from given orientation.

Parameters

orientation (str) – Orientation. See pygame_menu.locals

Return type

ScrollArea

Returns

Self reference

is_scrolling()[source]

Return True if the user is scrolling.

Return type

bool

Returns

True if user scrolls

mouse_is_over(view=False)[source]

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)[source]

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)[source]

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)[source]

Set the Menu reference.

Parameters

menu (Menu) – Menu object

Return type

ScrollArea

Returns

Self reference

set_parent_scrollarea(parent)[source]

Set parent ScrollArea.

Parameters

parent (Optional[ScrollArea]) – Parent ScrollArea

Return type

None

Returns

None

set_position(x, y)[source]

Set the position.

Parameters
  • x (int) – X position

  • y (int) – Y position

Return type

ScrollArea

Returns

Self reference

set_world(surface)[source]

Update the scrolled surface.

Parameters

surface (Surface) – New world surface

Return type

ScrollArea

Returns

Self reference

show_scrollbars(orientation)[source]

Hide scrollbar from given orientation.

Parameters

orientation (str) – Orientation. See pygame_menu.locals

Return type

ScrollArea

Returns

Self reference

to_absolute_position(virtual)[source]

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)[source]

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
Return type

Union[Rect, Tuple[int, int]]

Returns

Real rect or real position

to_world_position(real)[source]

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 (Union[Rect, Tuple[Union[int, float], Union[int, float]]]) – Position/Rect according ScrollArea origin

Return type

Union[Rect, Tuple[int, int]]

Returns

Rect in world or position in world

translate(x, y)[source]

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

Parameters
Return type

ScrollArea

Returns

Self reference

update(events)[source]

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