Button

class pygame_menu.widgets.Button(title, button_id='', onreturn=None, *args, **kwargs)[source]

Bases: pygame_menu.widgets.core.widget.Widget

Button widget.

Parameters:
  • title (str) – Button title
  • button_id (str) – Button ID
  • onreturn (callable, None) – Callback when pressing the button
  • args (any) – Optional arguments for callbacks
  • kwargs (dict) – Optional keyword arguments
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 widget.remove_draw_callback(id).

Parameters:draw_callback (callable) – Function
Returns:Callback ID
Return type:str
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 receives two objects: the widget itself and the menu reference. It is similar to add_draw_callback.

After creating a new callback, this functions returns the ID of the call. It can be removed anytime using widget.remove_update_callback(id).

Note

Not all widgets are updated, so the provided function may never be executed.

Parameters:update_callback (callable) – Function
Returns:Callback ID
Return type:str
apply(*args)

Run on_return callback when return event. A callback function receives the following arguments:

callback_func(value, *args, *widget._args, **widget._kwargs)
with:
  • value (if something is returned by get_value())
  • args given to this method
  • args of the widget
  • kwargs of the widget
Parameters:
  • args – Extra arguments passed to the callback
  • args – any
Returns:

None

apply_draw_callbacks()

Apply callbacks on widget draw.

Returns:None
apply_update_callbacks()

Apply callbacks on widget update.

Returns:None
change(*args)

Run on_change callback after change event is triggered. A callback function receives the following arguments:

callback_func(value, *args, *widget._args, **widget._kwargs)
with:
  • value (if something is returned by get_value())
  • args given to this method
  • args of the widget
  • kwargs of the widget
Parameters:
  • args – Extra arguments passed to the callback
  • args – any
Returns:

None

change_id(widget_id)

Change widget id.

Parameters:widget_id (str) – Widget ID
Returns:None
draw(surface)[source]

Draw the widget shape.

Parameters:surface (pygame.Surface) – Surface to draw
Returns:None
draw_selection(surface)

Draw selection effect on widget.

Parameters:surface (pygame.Surface) – Surface to draw
Returns:None
flip(x, y)

This method can flip the widget either vertically, horizontally, or both. Flipping a widget is non-destructive and does not change the dimensions.

Parameters:
  • x (bool) – Flip in x axis
  • y (bool) – Flip on y axis
Returns:

None

get_alignment()

Return the widget alignment.

Returns:Widget align, see locals
Return type:str
get_attribute(key, default=None)

Get attribute value.

Parameters:
  • key (str) – Key of the attribute
  • default (any) – Value if does not exists
Returns:

Attribute data

Return type:

any

get_font_info()

Return a dict with the information of the widget font.

Dict values:

  • antialias Font antialias (bool)
  • background_color Background color (tuple)
  • color Font color (tuple)
  • name Name of the font (str)
  • selected_color Selected color (tuple)
  • size Size of the font (int)
Returns:Dict
Return type:dict
get_id()

Return the widget ID.

Returns:Widget ID
Return type:str
get_margin()

Return the widget margin.

Returns:Widget margin (left, top)
Return type:tuple
get_menu()

Return the menu reference (if exists).

Warning

Use with caution.

Returns:Menu reference
Return type:pygame_menu.Menu, None
get_padding()

Return the widget padding.

Returns:Widget padding (top,right,bottom,left)
Return type:tuple
get_rect(inflate=None)

Return the Rect object, this forces the widget rendering.

Note

This is the only method that returns the rect with the padding applied. If widget._rect is used, the padding has not been applied.

Parameters:inflate (None, tuple, list) – Inflate rect (x,y) in px
Returns:Widget rect
Return type:pygame.Rect
get_selected_time()

Return time the widget has been selected in miliseconds. If the widget is not currently selected, return 0.

Returns:Time in ms
Return type:float
get_selection_effect()

Return the selection effect.

Warning

Use with caution.

Returns:Selection effect
Return type:pygame_menu.widgets.core.Selection
get_surface()

Return widget surface.

Warning

Use with caution.

Returns:Widget surface
Return type:pygame.Surface
get_title()

Return the widget title.

Returns:Widget title
Return type:str
get_value()

Return the value. If exception ValueError is raised, no value will be passed to the callbacks.

Returns:Widget data value
Return type:Object
has_attribute(key)

Returns true if widget has the given attribute.

Parameters:key (str) – Key of the attribute
Returns:True if exists
Return type:bool
hide()

Hides widget.

Returns:None
remove_attribute(key)

Removes the given attribute from the widget. Throws IndexError if given key does not exist.

Parameters:key (str) – Key of the attribute
Returns:None
remove_draw_callback(callback_id)

Removes draw callback from ID.

Parameters:callback_id (str) – Callback ID
Returns:None
remove_update_callback(callback_id)

Removes update callback from ID.

Parameters:callback_id (str) – Callback ID
Returns:None
resize(width, height, smooth=False)

Set the widget size to another size.

Note

This method calls widget.scale method; thus, some widgets may not support this transformation.

Parameters:
  • width (int, float) – New width of the widget in px
  • height (int, float) – New height of the widget in px
  • smooth (bool) – Smooth scaling
Returns:

None

rotate(angle)

Unfiltered counterclockwise rotation. The angle argument represents degrees and can be any floating point value. Negative angle amounts will rotate clockwise.

Note

Not all widgets accepts rotation. Also this rotation only affects the text or images, the selection or background is not rotated.

Parameters:angle (int, float) – Rotation angle (degrees 0-360)
Returns:None
scale(width, height, smooth=True)

Scale the widget to a desired width and height factor.

Note

Not all widgets are affected by scale.

Parameters:
  • width (int, float) – Scale factor of the width
  • height (int, float) – Scale factor of the height
  • smooth (bool) – Smooth scaling
Returns:

None

set_alignment(align)

Set the alignment of the widget.

Parameters:align (str) – Widget align, see locals
Returns:None
set_attribute(key, value)

Set widget attribute.

Parameters:
  • key (str) – Key of the attribute
  • value (any) – Value of the attribute
Returns:

None

set_background_color(color, inflate=(0, 0))

Set widget background color.

Parameters:
Returns:

None

set_controls(joystick=True, mouse=True, touchscreen=True)

Enable interfaces to control the widget.

Parameters:
  • joystick (bool) – Use joystick
  • mouse (bool) – Use mouse
  • touchscreen (bool) – Use touchscreen
Returns:

None

set_font(font, font_size, color, selected_color, background_color, antialias=True)

Set the text font.

Parameters:
  • font (str) – Font name (see pygame.font.match_font for precise format)
  • font_size (int) – Size of font in pixels
  • color (tuple) – Text color
  • selected_color (tuple) – Text color when widget is selected
  • background_color (tuple) – Font background color
  • antialias (bool) – Determines if antialias is applied to font (uses more processing power)
Returns:

None

set_margin(x, y)

Set Widget margin (left, top).

Parameters:
  • x (int, float) – Margin on x axis (left)
  • y (int, float) – Margin on y axis (top)
Returns:

None

set_max_width(width)

Set widget max width (column support) if force_fit_text is enabled.

Parameters:width (int, float, None) – Width in px, None if max width is disabled
Returns:None
set_menu(menu)

Set the menu reference.

Parameters:menu (pygame_menu.Menu) – Menu object
Returns:None
set_padding(padding)

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 (int, float, tuple, list) – Can be a single number, or a tuple of 2, 3 or 4 elements following CSS style
Returns:None
set_position(posx, posy)

Set the widget position.

Parameters:
Returns:

None

set_selected(selected=True)

Mark the widget as selected.

Parameters:selected (bool) – Set item as selected
Returns:None
set_selection_effect(selection)

Set the selection effect handler.

Parameters:selection (pygame_menu.widgets.core.Selection) – Selection effect class
Returns:None
set_shadow(enabled=True, color=None, position=None, offset=None)

Show text shadow.

Parameters:
  • enabled (bool) – Shadow is enabled or not
  • color (list, None) – Shadow color
  • position (str, None) – Shadow position
  • offset (int, float, None) – Shadow offset
Returns:

None

set_sound(sound)

Set sound engine to the widget.

Parameters:sound (pygame_menu.sound.Sound) – Sound object
Returns:None
set_title(title)

Update the widget title.

Parameters:title (str) – New title
Returns:None
set_value(value)

Set the widget value.

Warning

This method does not fire the callbacks as it is called programmatically. This behavior is deliberately chosen to avoid infinite loops.

Parameters:value (Object) – Value to be set on the widget
Returns:None
show()

Set widget visible.

Returns:None
surface_needs_update()

Checks if the widget width/height has changed because events. If so, return true and set the status of the widget (menu widget position needs update) as false. This method is used by Menu.update().

Returns:True if the widget position has changed by events after the rendering.
Return type:bool
translate(x, y)

Translate to (+x,+y) according to default position.

Note

To revert changes, only set to (0,0).

Parameters:
Returns:

None

update(events)[source]

Update internal variable according to the given events list and fire the callbacks.

Parameters:events (list[pygame.event.Event]) – List of pygame events
Returns:True if updated
Return type:bool
update_callback(callback, *args)[source]

Update function triggered by the button; callback cannot point to a Menu, that behaviour is only valid using Menu.add_button() method.

Note

If button points to a submenu, and the callback is changed to a function, the submenu will be removed from the parent menu. Thus preserving the structure.

Parameters:
  • callback (callable) – Function
  • args (any) – Arguments used by the function once triggered
Returns:

None

update_font(style)

Updates font. This method receives a style dict (non empty) containing the following keys:

  • antialias Font antialias (bool)
  • background_color Background color (tuple)
  • color Font color (tuple)
  • name Name of the font (str)
  • selected_color Selected color (tuple)
  • size Size of the font (int)

Note

If a key is not defined it will be rewritten using current font style from Widget.get_font_info() method.

Parameters:style (dict) – Font style dict
Returns:None