VMargin

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

Bases: NoneWidget

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

Note

VMargin does not accept 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 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_update_callback(update_callback)

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

Parameters:

update_callback (Callable[[List[Event], Widget, Menu], Any]) – Function

Return type:

str

Returns:

Callback ID

apply_draw_callbacks()

Apply callbacks on Widget draw.

Return type:

Widget

Returns:

Self reference

apply_update_callbacks(events)

Apply callbacks on Widget update.

Note

Readonly widgets or hidden widgets do not apply update callbacks.

Parameters:

events (List[Event]) – Events list

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

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.

This method also should be called 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:

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 it does not exist

Return type:

Any

Returns:

Attribute data

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_controller()

Return the widget controller. Each widget has their own controller object.

Return type:

Controller

Returns:

Controller object

get_counter_attribute(key, incr=0, 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_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_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_scrollarea()

Return the scrollarea object.

Return type:

ScrollArea

Returns:

ScrollArea object

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

remove_update_callback(callback_id)

Removes update callback from ID.

Parameters:

callback_id (str) – Callback ID

Return type:

Widget

Returns:

Self reference

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

The container ScrollArea scrolls to the 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_alignment(align)

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 valid align values.

Parameters:

align (str) – Widget align

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_controller(controller)

Set a new controller object.

Parameters:

controller (Controller) – Controller

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 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:
  • 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

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_scrollarea(scrollarea)

Set scrollarea reference. Mostly used for events.

Parameters:

scrollarea (Optional[ScrollArea]) – Scrollarea object

Return type:

None

show()

Set the Widget visible.

Return type:

Widget

Returns:

Self reference

update_menu(events)

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.

Parameters:

events (Union[List[Event], Tuple[Event]]) – List/Tuple of pygame events

Return type:

bool

Returns:

True if updated