VMargin

class pygame_menu.widgets.VMargin(margin, widget_id='')[source]

Bases: pygame_menu.widgets.widget.none.NoneWidget

Vertical margin widget. VMargin only accepts margin, not padding.

Note

This widget does not implement any transformation.

Parameters
  • margin (Union[int, float]) – Vertical margin in px

  • widget_id (str) – ID of the widget

add_draw_callback(draw_callback)

Adds a function to the Widget to be executed each time the widget is drawn.

The function that this method receives 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.

Parameters

draw_callback (Callable[[Widget, Menu], Any]) – Function

Return type

str

Returns

Callback ID

add_self_to_kwargs(key='widget')

Adds the Widget object to kwargs, it helps to get the Widget reference for callbacks. It raises KeyError if key is duplicated.

Parameters

key (str) – Name of the parameter

Return type

Widget

Returns

Self reference

apply_draw_callbacks()

Apply callbacks on Widget draw.

Return type

Widget

Returns

Self reference

draw(surface)

Draw the Widget on a given surface.

Note

Widget drawing order:

  1. Background color

  2. prev decorator

  3. Widget selection effect (if prev)

  4. Widget surface

  5. Widget selection effect (if post)

  6. Widget border

  7. post decorator

Parameters

surface (Surface) – Surface to draw

Return type

Widget

Returns

Self reference

draw_after_if_selected(surface)

Draw Widget if selected after all widgets have been drawn. This method should also update last_surface; see pygame_menu.widgets.DropSelect widget example.

Parameters

surface (Optional[Surface]) – Surface to draw. None if frame is requesting the draw, as some widgets are drawn outside the frame surface

Return type

Widget

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

Widget

Returns

Self reference

force_menu_surface_update()

Forces menu surface update after next rendering call. This method automatically updates widget decoration cache as Menu render forces it to re-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

Widget

Returns

Self reference

get_alignment()

Return the Widget alignment.

Return type

str

Returns

Widget align

get_attribute(key, default=None)

Get an attribute value.

Parameters
  • key (str) – Key of the attribute

  • default (Optional[Any]) – Value if does not exists

Return type

Any

Returns

Attribute data

get_border()

Return the widget border properties.

Return type

Tuple[Union[Tuple[int, int, int], Tuple[int, int, int, int]], int, Union[str, List[str], Tuple[str, …]], Tuple[int, int]]

Returns

Color, width, position, and inflate

get_class_id()

Return the Class+ID as a string.

Return type

str

Returns

Class+ID format

get_col_row_index()

Get the Widget column/row position.

Return type

Tuple[int, int, int]

Returns

(column, row, index) tuple

get_counter_attribute(key, incr, default=0)

Get counter attribute.

Parameters
  • key (str) – Key of the attribute

  • incr (Any) – Increase value

  • default (Any) – Default vale to start with, by default it’s zero

Return type

Union[int, float]

Returns

New increase value

get_decorator()

Return the Widget decorator API.

Return type

Decorator

Returns

Decorator API

get_focus_rect()

Return rect to be used in Widget focus.

Return type

Rect

Returns

Focus rect

get_frame()

Get container frame of Widget. If Widget is not within a Frame, the method returns None.

Returns

Frame object

Return type

pygame_menu.widgets.Frame

get_frame_depth()

Get frame depth (If frame is packed within another frame).

Return type

int

Returns

Frame depth

get_height(apply_padding=True, apply_selection=False)

Return the Widget height.

Warning

If the widget is not rendered, this method will return 0.

Parameters
  • apply_padding (bool) – Apply padding

  • apply_selection (bool) – Apply selection

Return type

int

Returns

Widget height in px

get_id()

Return the object ID.

Return type

str

Returns

Object ID

get_menu()

Return the Menu reference, None if it has not been set.

Return type

Optional[Menu]

Returns

Menu reference

get_position(apply_padding=False, use_transformed_padding=True, to_real_position=False, to_absolute_position=False, real_position_visible=True)

Return the widget position tuple on x-axis and y-axis (x, y) in px.

Parameters
  • apply_padding (bool) – Apply widget padding to position

  • use_transformed_padding (bool) – Use scaled padding if the widget is scaled

  • to_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 positioning

  • real_position_visible (bool) – Return only the visible width/height if to_real_position=True

Return type

Tuple[int, int]

Returns

Widget position

get_rect(*args, **kwargs)[source]

Return the pygame.Rect object of the Widget. This method forces rendering.

Parameters
  • inflate – Inflate rect on x-axis and y-axis (x, y) in px

  • apply_padding – Apply widget padding

  • use_transformed_padding – Use scaled padding if the widget is scaled

  • to_real_position – Transform the widget rect to real coordinates (if the Widget change the position if scrollbars move offsets). Used by events

  • to_absolute_position – Transform the widget rect to absolute coordinates (if the Widget does not change the position if scrollbars move offsets). Used by events

  • render – Force widget rendering

  • real_position_visible – Return only the visible width/height if to_real_position=True

Return type

Rect

Returns

Widget rect object

get_scrollarea()

Return the scrollarea object.

Return type

ScrollArea

Returns

ScrollArea object

get_size(apply_padding=True, apply_selection=False)

Return the Widget size.

Warning

If the widget is not rendered this method might return (0, 0).

Parameters
  • apply_padding (bool) – Apply padding

  • apply_selection (bool) – Apply selection

Return type

Tuple[int, int]

Returns

Widget width and height in px

get_translate(virtual=False)

Get Widget translate on x-axis and y-axis (x, y) in px.

Parameters

virtual (bool) – If True get virtual translation, usually applied within frame scrollarea

Return type

Tuple[int, int]

Returns

Translation on both axis

get_width(apply_padding=True, apply_selection=False)

Return the Widget width.

Warning

If the Widget is not rendered, this method will return 0.

Parameters
  • apply_padding (bool) – Apply padding

  • apply_selection (bool) – Apply selection

Return type

int

Returns

Widget width in px

has_attribute(key)

Return True if the object has the given attribute.

Parameters

key (str) – Key of the attribute

Return type

bool

Returns

True if exists

hide()

Hides the Widget.

Return type

Widget

Returns

Self reference

is_floating()

Return True if the Widget is floating.

Return type

bool

Returns

Float status

is_visible(check_frame=True)

Return True if the Widget is visible.

Parameters

check_frame (bool) – If True check frame and sub-frames if they’re opened as well

Return type

bool

Returns

Visible status

on_remove_from_menu()

Function executed if the Widget is removed from the Menu.

Return type

Widget

Returns

Self reference

remove_attribute(key)

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

remove_draw_callback(callback_id)

Removes draw callback from ID.

Parameters

callback_id (str) – Callback ID

Return type

Widget

Returns

Self reference

render()

Public rendering method.

Note

Unlike private _render method, public method forces widget rendering (calling pygame_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.

Return type

Optional[bool]

Returns

True if widget has rendered a new state, None if the widget has not changed, so render used a cache

scroll_to_widget(margin=(0, 0), scroll_parent=True)

Scroll to widget.

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

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

Return type

Widget

Returns

Self reference

set_attribute(key, value=None)

Set an attribute.

Parameters
  • key (str) – Key of the attribute

  • value (Optional[Any]) – Value of the attribute

Return type

Base

Returns

Self reference

set_col_row_index(col, row, index)

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).

Parameters
  • col (int) – Column

  • row (int) – Row

  • index (int) – Index in Menu widget list

Return type

Widget

Returns

Self reference

set_float(float_status=True, menu_render=False, origin_position=False)

Set the floating status. If True the Widget don’t contributes the 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 been set to the (0, 0) position, thus, the only way to move the Widget to a desired position is by translating it.

Parameters
  • float_status (bool) – Float status

  • menu_render (bool) – If True forces the Menu to render instantly; else, rendering is controlled by menu

  • origin_position (bool) – If True the widget position is set to the top-left position of the Menu if the widget is floating (updated by the Menu render phase)

Return type

Widget

Returns

None

set_font_shadow(*args, **kwargs)

Set the Widget font shadow.

Note

See pygame_menu.locals for valid position values.

Parameters
  • enabled – Shadow is enabled or not

  • color – Shadow color

  • position – Shadow position

  • offset – Shadow offset

Return type

NoneWidget

Returns

Self reference

set_frame(frame)

Set Widget frame.

Parameters

frame (Frame) – Frame object

Return type

Widget

Returns

Self reference

set_menu(menu)

Set the Widget menu reference.

Parameters

menu (Optional[Menu]) – Menu object

Return type

Widget

Returns

Self reference

set_position_relative_to_frame(index=- 1)

Set the Widget position relative to its frame.

Parameters

index (int) – Widget index

Return type

Widget

Returns

Self reference

set_scrollarea(scrollarea)

Set scrollarea reference. Mostly used for events.

Parameters

scrollarea (Optional[ScrollArea]) – Scrollarea object

Return type

None

Returns

None

set_tab_size(*args, **kwargs)

Set widget tab size.

Parameters

tab_size – Width of a tab character

Return type

NoneWidget

Returns

Self reference

show()

Set the Widget visible.

Return type

Widget

Returns

Self reference