Frame
Bases:
Widget
Frame is a widget container, it can pack many widgets.
All widgets inside have a floating position. Widgets inside are placed using its margin + width/height.
(0, 0)
coordinate is the top-left position in frame.Frame modifies
translation
of widgets. Thus, if widget has a translation before it will be removed.Widget packing currently only supports LEFT, CENTER and RIGHT alignment in the same line, widgets cannot be packed in two different lines. For such purpose use several frames. If widget width or height exceeds Frame size
_FrameSizeException
will be raised.Note
Frame cannot be selected. Thus, it does not receive any selection effect.
Note
Frames should be appended to Menu scrollable frames if it’s scrollable, be careful when removing. Check
pygame_menu.widgets.DropSelect
as a complete example of Frame implementation within another Widgets.Note
Frame only accepts translation and resize transformations.
- Parameters:
Adds a function to the Widget to be executed each time the widget is drawn.
The function that this method receives two objects: the Widget itself and the Menu reference.
import math def draw_update_function(widget, menu): t = widget.get_attribute('t', 0) t += menu.get_clock().get_time() widget.set_padding(10*(1 + math.sin(t))) # Oscillating padding button = menu.add.button('This button updates its padding', None) button.set_draw_callback(draw_update_function)
After creating a new callback, this functions returns the ID of the call. It can be removed anytime using
pygame_menu.widgets.core.widget.Widget.remove_draw_callback()
.Note
If Menu surface cache is enabled this method may run only once. To force running the added method each time call
widget.force_menu_surface_update()
to force Menu update the cache status if the drawing callback does not make the Widget to render. Remember that rendering the Widget forces the Menu to update its surface, thus updating the cache too.
Adds the Widget object to kwargs, it helps to get the Widget reference for callbacks. It raises
KeyError
if key is duplicated.
Add predefined button to title. The button kwargs receive the
button
reference and the Frame reference inframe
argument, such as:onreturn_button_callback(*args, frame=Frame, button=Button, **kwargs)
- Parameters:
style (
Literal
['close'
,'maximize'
,'minimize'
]) – Style of the button (changes the symbol)callback (
Optional
[Callable
]) – Callback of the button if pressedbackground_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Button background colormargin (
Union
[Tuple
[Union
[int
,float
],Union
[int
,float
]],List
[Union
[int
,float
]]]) – Pack margin on x-axis and y-axis (x, y) in pxsymbol_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the symbolsymbol_height (
Union
[int
,float
]) – Symbol height factor, if1.0
uses 100% of the button heightsymbol_margin (
int
) – Symbol margin in px
- Return type:
- Returns:
Added button
Add button to title. Button kwargs receive the
button
reference and the Frame reference inframe
argument, such as:onreturn_button_callback(*args, frame=Frame, button=Button, **kwargs)
Adds a function to the Widget to be executed each time the Widget is updated.
The function that this method receives three objects: the events list, the Widget itself and the Menu reference. It is similar to
pygame_menu.widgets.core.widget.Widget.add_draw_callback()
.After creating a new callback, this functions returns the ID of the call. It can be removed anytime using
pygame_menu.widgets.core.widget.Widget.remove_update_callback()
.Note
Not all widgets are updated, so the provided function may never be executed in some widgets (for example, label or images).
Apply callbacks on Widget draw.
- Return type:
- Returns:
Self reference
Apply callbacks on Widget update.
Note
Readonly widgets or hidden widgets do not apply update callbacks.
Unpack all widgets within frame.
Return true if the frame contains the given widget.
Draw the Widget on a given surface.
Note
Widget drawing order:
Background color
prev
decoratorWidget selection effect (if prev)
Widget surface
Widget selection effect (if post)
Widget border
post
decorator
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. This method automatically updates widget decoration cache as Menu render forces it to re-render.
This method also should be aclled by each widget after render.
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 Widget alignment.
- Return type:
- Returns:
Widget align
Get an attribute value.
Return the widget border properties.
Return the Class+ID as a string.
- Return type:
- Returns:
Class+ID format
Get the Widget column/row position.
Return the widget controller. Each widget has their own controller object.
- Return type:
- Returns:
Controller object
Get counter attribute.
Frame decorator belongs to the scrollarea decorator if enabled.
- Return type:
- Returns:
ScrollArea decorator
Return rect to be used in Widget focus.
- Return type:
- Returns:
Focus rect
Return a dict with the information of the Widget font.
Get container frame of Widget. If Widget is not within a Frame, the method returns
None
.- Returns:
Frame object
- Return type:
Get frame depth (If frame is packed within another frame).
- Return type:
- Returns:
Frame depth
Return the Widget height.
Warning
If the widget is not rendered, this method will return
0
.
Return the object ID.
- Return type:
- Returns:
Object ID
Get index of the given widget within the widget list. Throws
IndexError
if widget does not exist.
Return first and last selectable indices tuple.
Return the Menu reference,
None
if it has not been set.
Return the Widget padding.
Return the widget position tuple on x-axis and y-axis (x, y) in px.
- Parameters:
apply_padding (
bool
) – Apply widget padding to positionuse_transformed_padding (
bool
) – Use scaled padding if the widget is scaledto_real_position (
bool
) – Get the real position within window (not the surface container)to_absolute_position (
bool
) – Get the absolute position within surface container, considering also the parent scrollarea positioningreal_position_visible (
bool
) – Return only the visible width/height ifto_real_position=True
- Return type:
- Returns:
Widget position
Return the
pygame.Rect
object of the Widget. This method forces rendering.- Parameters:
inflate (
Optional
[Tuple
[int
,int
]]) – Inflate rect on x-axis and y-axis (x, y) in pxapply_padding (
bool
) – Apply widget paddinguse_transformed_padding (
bool
) – Use scaled padding if the widget is scaledto_real_position (
bool
) – Transform the widget rect to real coordinates (if the Widget change the position if scrollbars move offsets). Used by eventsto_absolute_position (
bool
) – Transform the widget rect to absolute coordinates (if the Widget does not change the position if scrollbars move offsets). Used by eventsrender (
bool
) – Force widget renderingreal_position_visible (
bool
) – Return only the visible width/height ifto_real_position=True
- Return type:
- Returns:
Widget 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, or frame is not scrollable,
-1
is returned.
Return the scrollarea object.
- Parameters:
inner (
bool
) – IfTrue
return the inner scrollarea- Return type:
- Returns:
ScrollArea object
Return the Widget size.
Warning
If the widget is not rendered this method might return
(0, 0)
.
Return the Widget surface.
Warning
Use with caution.
- Return type:
- Returns:
Widget surface object
Return the Widget title.
Note
Not all widgets implements this method, for example, images don’t accept a title, and such widget would return an empty string if this method is called.
- Return type:
- Returns:
Widget title
Return the total number of packed widgets.
- Return type:
- Returns:
Number of packed widgets
Get Widget translation on x-axis and y-axis (x, y) in px.
Get widgets as a tuple.
Return the Widget width.
Warning
If the Widget is not rendered, this method will return
0
.
Return
True
if the object has the given attribute.
Hides the Widget.
- Return type:
- Returns:
Self reference
Return
True
if the Widget is floating.- Return type:
- Returns:
Float status
Return
True
if the Widget is visible.
Make the scrollarea of the frame.
- Parameters:
max_width (
Union
[int
,float
,None
]) – Maximum width of the scrollarea in pxmax_height (
Union
[int
,float
,None
]) – Maximum height of the scrollarea in pxscrollarea_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
,BaseImage
,None
]) – Scroll area color or image. IfNone
area is transparentscrollbar_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Scrollbar colorscrollbar_cursor (
Union
[int
,Cursor
,None
]) – Scrollbar cursorscrollbar_shadow (
bool
) – Indicate if a shadow is drawn on each scrollbarscrollbar_shadow_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the shadow of each scrollbarscrollbar_shadow_offset (
int
) – Offset of the scrollbar shadow in pxscrollbar_shadow_position (
str
) – Position of the scrollbar shadow. Seepygame_menu.locals
scrollbar_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 (
Union
[int
,float
]) – Scrollbar thickness in pxscrollbars (
Union
[str
,Tuple
[str
,...
]]) – Positions of the scrollbars. Seepygame_menu.locals
- Return type:
- Returns:
Self reference
Run the
onmouseleave
callback if the mouse is placed outside the Widget. The callback receive the Widget object reference and the mouse event:onmouseleave(widget, event) <or> onmouseleave()
Warning
This method does not evaluate if the mouse is placed over the Widget. Only executes the callback and updates the cursor if enabled.
Run the
onmouseover
if the mouse is placed over the Widget. The callback receive the Widget object reference and the mouse event:onmouseover(widget, event) <or> onmouseover()
Warning
This method does not evaluate if the mouse is placed over the Widget. Only executes the callback and updates the cursor if enabled.
Function executed if the Widget is removed from the Menu.
- Return type:
- Returns:
Self reference
Packs widget in the frame line. To pack a widget it has to be already appended to Menu, and the Menu must be the same as the frame.
Packing is added to the same line, for example if three LEFT widgets are added:
<frame horizontal> frame.pack(W1, alignment=ALIGN_LEFT, vertical_position=POSITION_NORTH) frame.pack(W2, alignment=ALIGN_LEFT, vertical_position=POSITION_CENTER) frame.pack(W3, alignment=ALIGN_LEFT, vertical_position=POSITION_SOUTH) ---------------- |W1 | | W2 | | W3 | ----------------
Another example:
<frame horizontal> frame.pack(W1, alignment=ALIGN_LEFT) frame.pack(W2, alignment=ALIGN_CENTER) frame.pack(W3, alignment=ALIGN_RIGHT) ---------------- |W1 W2 W3| ----------------
<frame vertical> frame.pack(W1, alignment=ALIGN_LEFT) frame.pack(W2, alignment=ALIGN_CENTER) frame.pack(W3, alignment=ALIGN_RIGHT) -------- |W1 | | W2 | | W3| --------
Note
Frame does not consider previous widget margin. For such purpose, use
margin
pack parameter.Note
It is recommended to force menu rendering after packing all widgets.
Note
Packing applies a virtual translation to the widget, previous translation is not modified.
Note
Widget floating is also considered within frames. If a widget is floating, it does not add any size to the respective positioning.
- Parameters:
widget (
Union
[Widget
,List
[Widget
],Tuple
[Widget
,...
]]) – Widget to be packedalign (
str
) – Widget alignment. Seepygame_menu.locals
vertical_position (
str
) – Vertical position of the widget within frame. Only valid: north, center, and south. Seepygame_menu.locals
margin (
Union
[Tuple
[Union
[int
,float
],Union
[int
,float
]],List
[Union
[int
,float
]]]) – (left, top) margin of added widget in px. It overrides the previous widget margin
- Return type:
- Returns:
Added widget references
Set relax status. If
True
Frame ignores sizing checks.
Removes the given attribute from the object. Throws
IndexError
if the given key does not exist.- Parameters:
key (
str
) – Key of the attribute- Return type:
Base
- Returns:
Self reference
Removes draw callback from ID.
Remove title from current Frame.
- Return type:
- Returns:
Self reference
Removes update callback from ID.
Public rendering method.
Note
Unlike private
_render
method, public method forces widget rendering (callingpygame_menu.widgets.core.widget.Widget._force_render()
). Use this method only if the widget has changed the state. Running this function many times may affect the performance.Note
Before rendering, check out if the widget font/title/values are set. If not, it is probable that a zero-size surface is set.
Resize the Frame.
- Parameters:
width (
Union
[int
,float
]) – New width in px. Horizontal padding will be subtractedheight (
Union
[int
,float
]) – New height in px. Vertical padding will be subtractedmax_width (
Union
[int
,float
,None
]) – Max frame width if the Frame is scrollable. IfNone
the same width will be usedmax_height (
Union
[int
,float
,None
]) – Max frame height if the Frame is scrollable. IfNone
the same height will be used
- Return type:
- Returns:
Self reference
The container ScrollArea scrolls to the Widget.
Scroll to horizontal value if frame is scrollable.
Scroll to vertical value if frame is scrollable.
Set the alignment of the Widget.
Note
Alignment is only applied when updating the widget position, done by Menu when rendering the surface. Thus, the alignment change is not immediate.
Note
Use
pygame_menu.widgets.core.widget.Widget.render()
method to force widget rendering after calling this method.Note
See
pygame_menu.locals
for validalign
values.
Set an attribute.
Set the Widget background color.
- Parameters:
- Return type:
- Returns:
Self reference
Set the Widget border.
Note
Inflate is added to the background inflate in drawing time.
- Parameters:
width (
int
) – Border width in pxcolor (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
,None
]) – Border colorinflate (
Tuple
[int
,int
]) – Inflate on x-axis and y-axis (x, y) in pxposition (
Union
[str
,List
[str
],Tuple
[str
,...
]]) – Border position. Valid only: north, south, east, and west. Seepygame_menu.locals
- Return type:
- Returns:
Self reference
Set the (column, row, index) position. If the column or row is
-1
then the widget is not assigned to a certain column/row (for example, if it’s hidden).
Set a new controller object.
- Parameters:
controller (
Controller
) – Controller- Return type:
- Returns:
Self reference
Enable interfaces to control the Widget.
Set the Widget cursor if user places the mouse over the Widget.
Set the floating status. If
True
the Widget don’t contribute its width/height to the Menu widget positioning computation (for example, the surface area or the column/row layout), and don’t add one unit to the rows (use the same vertical place as the previous widget).For example, before floating:
---------------------------- | wid1 | wid3 | | wid2 | wid4 | ----------------------------
After
wid3.set_float(True)
:---------------------------- | wid1 | wid4 | | wid2,wid3 | | ----------------------------
If the Widget is within a Frame, it does not contribute to the width/height of the layout. Also, it is being set to the (0, 0) position, thus, the only way to move the Widget to a desired position is by translating it.
- Parameters:
- Return type:
Set the Widget font.
- Parameters:
font (
Union
[str
,Font
,Path
]) – Font name (seepygame.font.match_font()
for precise format)font_size (
int
) – Size of font in pixelscolor (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Normal font colorselected_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Font color if widget is selectedreadonly_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Font color if widget is in readonly modereadonly_selected_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Font color if widget is selected and in readonly modebackground_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
,None
]) – Font background color. IfNone
no background color is usedantialias (
bool
) – Determines if antialias is applied to font (uses more processing power)
- Return type:
- Returns:
Self reference
Set the Widget font shadow.
Note
See
pygame_menu.locals
for validposition
values.
Set Widget frame.
Set the Widget margin (left, bottom).
Set the Widget menu reference.
Set
onmouseleave
callback. This method is executed inpygame_menu.widgets.core.widget.Widget.mouseleave()
method. The callback function receives the following arguments:onmouseleave(widget, event) <or> onmouseleave()
Set
onmouseover
callback. This method is executed inpygame_menu.widgets.core.widget.Widget.mouseover()
method. The callback function receives the following arguments:onmouseover(widget, event) <or> onmouseover()
Set the Widget padding according to CSS rules:
If an integer or float is provided: top, right, bottom and left values will be the same
If 2-item tuple is provided: top and bottom takes the first value, left and right the second
If 3-item tuple is provided: top will take the first value, left and right the second, and bottom the third
If 4-item tuple is provided: padding will be (top, right, bottom, left)
Note
See CSS W3Schools for more info about padding.
- Parameters:
padding (
Union
[int
,float
,List
[Union
[int
,float
]],Tuple
[Union
[int
,float
]],Tuple
[Union
[int
,float
],Union
[int
,float
]],Tuple
[Union
[int
,float
],Union
[int
,float
],Union
[int
,float
],Union
[int
,float
]],None
]) – Can be a single number, or a tuple of 2, 3 or 4 elements following CSS style- Return type:
- Returns:
Self reference
Set the Widget position relative to the Menu/Frame.
This method is executed by the Menu when updating the widget positioning. For moving the widget use
translate
method instead, as this position will be rewritten on next menu rendering phase.Note
Use
pygame_menu.widgets.core.widget.Widget.render()
method to force Widget rendering after calling this method.
Set scrollarea reference. Mostly used for events.
- Parameters:
scrollarea (
Optional
[ScrollArea
]) – Scrollarea object- Return type:
Set widget tab size.
Add a title to the frame.
- Parameters:
title (
str
) – New titlebackground_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
,Tuple
[Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
],Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
],bool
,bool
],BaseImage
,None
]) – Title background color. It can be a Color, a gradient, or an imagedraggable (
bool
) – IfTrue
the title accepts user drag using the mousepadding_inner (
Union
[int
,float
,List
[Union
[int
,float
]],Tuple
[Union
[int
,float
]],Tuple
[Union
[int
,float
],Union
[int
,float
]],Tuple
[Union
[int
,float
],Union
[int
,float
],Union
[int
,float
],Union
[int
,float
]],None
]) – Padding inside the titlepadding_outer (
Union
[int
,float
,List
[Union
[int
,float
]],Tuple
[Union
[int
,float
]],Tuple
[Union
[int
,float
],Union
[int
,float
]],Tuple
[Union
[int
,float
],Union
[int
,float
],Union
[int
,float
],Union
[int
,float
]],None
]) – Padding outside the title (respect to the Frame)title_alignment (
str
) – Alignment of the titletitle_buttons_alignment (
str
) – Alignment of the title buttons (if appended later)title_font (
Union
[str
,Font
,Path
,None
]) – Title font. IfNone
uses the same as the Frametitle_font_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
,None
]) – Title font color. IfNone
uses the same as the Frametitle_font_size (
Optional
[int
]) – Title font size in px. IfNone
uses the same as the Frame
- Return type:
- Returns:
Title frame object
Configure the widget shadow.
- Parameters:
shadow_type (
str
) – Shadow type, it can be rectangular or ellipseshadow_width (
int
) – Shadow width in px. If0
the shadow is disabledcorner_radius (
int
) – Shadow corner radius if rectangular in pxcolor (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Shadow coloraa_amount (
int
) – Antialiasing amout
- Return type:
- Returns:
Self reference
Set the Widget visible.
- Return type:
- Returns:
Self reference
Transformation: Translate to (+x, +y) according to the default position.
Note
Translate is only applied when updating the widget position (calling
pygame_menu.widgets.core.widget.Widget.set_position()
). This is done by Menu when rendering the surface. Thus, the position change is not immediate. To force translation update you may call Menu render method.Note
To revert changes, only set to
(0, 0)
.Note
Use
pygame_menu.widgets.core.widget.Widget.render()
method to force widget rendering after calling this method.
Disable float status for each subwidget.
- Return type:
- Returns:
Self reference
Unpack widget from Frame. If widget does not exist, raises
ValueError
. Unpacked widgets adopt a floating position and are moved to the last position of the widget list of Menu
Update according to the given events list and fire the callbacks. This method must return
True
if it updated (the internal variables changed during user input).Note
Update is not performed if the Widget is in
readonly
state, or it’s hidden. However,apply_update_callbacks
method is called in most widgets, exceptpygame_menu.widgets.NoneWidget
.
Updates the Widget font. This method receives a style dict (non-empty).
- Optional style keys
antialias
(bool) – Font antialiasbackground_color
(tuple) – Background colorcolor
(tuple) – Font colorname
(str) – Name of the fontreadonly_color
(tuple) – Readonly colorreadonly_selected_color
(tuple) – Readonly selected colorselected_color
(tuple) – Selected colorsize
(int) – Size of the font
Note
If a key is not defined it will be rewritten using current font style from
pygame_menu.widgets.core.widget.Widget.get_font_info()
method.
Update first and last selectable widget index.
- Return type:
- Returns:
Self reference
Update the widget from Menu. This method is the same as update(), however, it takes into account the value of
widget.receive_menu_update_events
.
Update the position of each widget.
- Return type:
- Returns:
Self reference