ScrollArea
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 validscrollbars
andshadow_position
values.Note
ScrollArea cannot be copied or deep-copied.
- Parameters:
area_width (
int
) – Width of scrollable area in pxarea_height (
int
) – Height of scrollable area in pxarea_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 imageborder_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
,BaseImage
,None
]) – Border colorborder_width (
int
) – Border width in pxcontrols_joystick (
bool
) – Use joystick eventscontrols_keyboard (
bool
) – Use keyboard eventscontrols_mouse (
bool
) – Use mouse eventscontrols_touchscreen (
bool
) – Use touchscreen eventsextend_x (
int
) – Px to extend the surface on x-axis in px from left. Recommended use only within Menusextend_y (
int
) – Px to extend the surface on y-axis in px from top. Recommended use only within Menusmenubar (
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 areascrollarea_id (
str
) – Scrollarea IDscrollbar_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Scrollbars colorscrollbar_cursor (
Union
[int
,Cursor
,None
]) – Scrollbar cursorscrollbar_slider_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the slidersscrollbar_slider_hover_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the slider if hovered or clickedscrollbar_slider_pad (
Union
[int
,float
]) – Space between slider and scrollbars borders in pxscrollbar_thick (
int
) – Scrollbar thickness in pxscrollbars (
Union
[str
,Tuple
[str
,...
],List
[str
]]) – Positions of the scrollbars. Seepygame_menu.locals
shadow (
bool
) – Indicate if a shadow is drawn on each scrollbarshadow_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the shadow of each scrollbarshadow_offset (
int
) – Offset of the scrollbar shadow in pxshadow_position (
str
) – Position of the scrollbar shadow. Seepygame_menu.locals
world (
Optional
[Surface
]) – Surface to draw and scroll
If user event collides a widget within the ScrollArea respect to the relative position.
Create rect object.
Draw the ScrollArea.
- Parameters:
surface (
Surface
) – Surface to render the area- Return type:
- Returns:
Self reference
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:
- Returns:
Self reference
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:
- Returns:
Self reference
Return the ScrollArea absolute view rect clipped if it is not visible by its parent ScrollArea.
- Return type:
Rect
- Returns:
Clipped absolute view rect
Return the border size (width, height) in px.
Return the ScrollArea decorator API.
Note
Menu drawing order:
Menu background color/image
Menu
prev
decoratorMenu ScrollArea
prev
decoratorMenu ScrollArea widgets
Menu ScrollArea
post
decoratorMenu title
Menu
post
decorator
- Return type:
- Returns:
Decorator API
Return the depth of the ScrollArea (how many parents do it has recursively).
- Return type:
- Returns:
Depth’s number
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:
- Returns:
Hidden height in px
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:
- Returns:
Hidden width in px
Return the offset introduced by the scrollbars in the world.
Return the parent ScrollArea.
- Return type:
- Returns:
Parent ScrollArea object
Return parent ScrollArea position.
Get percentage scroll values of scroll and parents; if
0
the scroll is at top/left,1
bottom/right.
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 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.
Return the scroll thickness of the area. If it’s hidden return zero.
Return the area size.
Get object translation on both axis.
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 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.
Return the world surface area.
Warning
Use with caution.
- Return type:
Optional
[Surface
]- Returns:
World surface.
None
if it has not been set yet
Return the world rect.
- Parameters:
absolute (
bool
) – To absolute position- Return type:
Rect
- Returns:
World rect object
Hide scrollbar from given orientation.
- Parameters:
- Return type:
- Returns:
Self reference
Return
True
if the user is scrolling.- Return type:
- Returns:
True
if user scrolls
Return
True
if the mouse is placed over the ScrollArea.
Scroll to position in terms of the percentage.
- Parameters:
- Return type:
- Returns:
Self reference
Ensure that the given rect is in the viewable area.
- Parameters:
- Return type:
- Returns:
Scrollarea scrolled to rect. If
False
the rect was already inside the visible area
Set the Menu reference.
- Parameters:
menu (
Menu
) – Menu object- Return type:
- Returns:
Self reference
Set parent ScrollArea.
- Parameters:
parent (
Optional
[ScrollArea
]) – Parent ScrollArea- Return type:
Set the position.
- Parameters:
- Return type:
- Returns:
Self reference
Update the scrolled surface.
- Parameters:
surface (
Surface
) – New world surface- Return type:
- Returns:
Self reference
Hide scrollbar from given orientation.
- Parameters:
- Return type:
- Returns:
Self reference
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
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.
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.
Translate on x-axis and y-axis (x, y) in px.
Called by end user to update scroll state.