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
If user event collides a widget within the ScrollArea respect to the relative position.
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
- 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
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.
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
- 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 the world rect.
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.
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.