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, any) – 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

Callback return value

Return type

any

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

Callback return value

Return type

any

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

expand_background_inflate_to_selection_effect()

Expand background inflate to match the selection effect (the widget don’t require to be selected).

This is a permanent change; for dynamic purpuoses, depending if the widget is selected or not, setting widget.selection_expand_background to True may help.

Note

This method may have unexpected results with certain selection effects.

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_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

Returns

Widget height (px)

Return type

float

get_id()

Return the widget ID.

Returns

Widget ID

Return type

str

get_margin()

Return the widget margin.

Returns

Widget margin (left,bottom)

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

Return the widget position tuple (x, y).

Returns

Widget position

Return type

tuple

get_rect(apply_padding=True, 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
  • apply_padding (bool) – Apply widget padding

  • 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 milliseconds. 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_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

Returns

Widget (width, height)

Return type

tuple

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

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

Returns

Widget width (px)

Return type

float

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, None) – 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, bottom).

Parameters
  • x (int, float) – Margin on x axis (left)

  • y (int, float) – Margin on y axis (bottom)

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, None) – 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=2)

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], tuple[pygame.event.Event]) – List/Tuple 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