DropSelect

class pygame_menu.widgets.DropSelect(title, items, dropselect_id='', default=- 1, onchange=None, onreturn=None, onselect=None, open_middle=False, placeholder='Select an option', placeholder_add_to_selection_box=True, selection_box_arrow_color=(150, 150, 150), selection_box_arrow_margin=(5, 5, 0), selection_box_bgcolor=(255, 255, 255), selection_box_border_color=(150, 150, 150), selection_box_border_width=1, selection_box_height=3, selection_box_inflate=(0, 0), selection_box_margin=(25, 0), selection_box_text_margin=5, selection_box_width=0, selection_infinite=False, selection_option_border_color=(220, 220, 220), selection_option_border_width=1, selection_option_cursor=None, selection_option_font=None, selection_option_font_color=(0, 0, 0), selection_option_font_size=None, selection_option_padding=5, selection_option_selected_bgcolor=(188, 227, 244), selection_option_selected_font_color=(0, 0, 0), *args, **kwargs)[source]

Bases: pygame_menu.widgets.core.widget.Widget

Drop select is a selector within a Frame. This drops a vertical frame if requested. Drop select can contain selectable items (options), only 1 can be selected.

The items of the DropSelect are:

items = [('Item1', a, b, c...), ('Item2', d, e, f...)]

The callbacks receive the current selected item, its index in the list, the associated arguments, and all unknown keyword arguments, where selected_item=widget.get_value() and selected_index=widget.get_index():

onchange((selected_item, selected_index), a, b, c..., **kwargs)
onreturn((selected_item, selected_index), a, b, c..., **kwargs)

For example, if selected_index=0 then selected_item=('Item1', a, b, c...).

Note

DropSelect only implements translation.

Parameters
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

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 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(*args)

Run onreturn callback when return event. The callback function receives the following arguments:

onreturn(value, *args, *widget._args, **widget._kwargs)
Where

Note

Not all widgets have an onreturn method.

Parameters

args – Extra arguments passed to the callback

Return type

Any

Returns

Callback return value

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

background_inflate_to_selection_effect()

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

This is a permanent change; for dynamic purposes, 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.

Return type

Widget

Returns

Self reference

change(*args)

Run onchange callback after change event is triggered. The callback function receives the following arguments:

onchange(value, *args, *widget._args, **widget._kwargs)
Where

Note

Not all widgets have an onchange method.

Parameters

args – Extra arguments passed to the callback

Return type

Any

Returns

Callback return value

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)[source]

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

DropSelect

Returns

Self reference

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

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

Note

Flip is only applied after Widget rendering. Thus, the changes are not immediate.

Note

Use pygame_menu.widgets.core.widget.Widget.render() method to force Widget rendering after calling this method.

Parameters
  • x – Flip on x-axis

  • y – Flip on y-axis

Return type

DropSelect

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()[source]

Return rect to be used in Widget focus.

Return type

Rect

Returns

Focus rect

get_font_color_status(check_selection=True)

Return the Widget font color based on the widget status.

Parameters

check_selection (bool) – If True font is also checked if selected

Return type

Union[Tuple[int, int, int], Tuple[int, int, int, int]]

Returns

Color by widget status

get_font_info()

Return a dict with the information of the widget font.

Return type

Dict[str, Any]

Returns

Font information dict

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_index()[source]

Get selected index.

Return type

int

Returns

Selected index

get_margin()

Return the Widget margin.

Return type

Tuple[int, int]

Returns

Widget margin (left, bottom)

get_menu()

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

Return type

Optional[Menu]

Returns

Menu reference

get_padding(transformed=True)

Return the Widget padding.

Parameters

transformed (bool) – If True, returns the scaled padding if widget is transformed (flip, scale)

Return type

Tuple

Returns

Widget padding (top, right, bottom, left)

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(inflate=None, apply_padding=True, use_transformed_padding=True, to_real_position=False, to_absolute_position=False, render=False, real_position_visible=True)

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 px

  • apply_padding (bool) – Apply widget padding

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

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

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

  • render (bool) – Force widget rendering

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

Return type

Rect

Returns

Widget rect object

get_scroll_value_percentage(orientation)[source]

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.

Parameters

orientation (str) – Orientation. See pygame_menu.locals

Return type

float

Returns

Value from 0 to 1

get_scrollarea()

Return the scrollarea object.

Return type

ScrollArea

Returns

ScrollArea object

get_selected_time()

Return time the Widget has been selected in milliseconds. If the Widget is not currently selected, return 0.

Return type

Union[int, float]

Returns

Time in milliseconds

get_selection_effect()

Return the selection effect.

Note

If no selection has been provided, _WidgetNullSelection class will be returned.

Note

For drawing, use pygame_menu.widgets.core.widget.Widget.draw_selection_effect().

Warning

Use with caution.

Return type

Selection

Returns

Selection effect

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

Return the Widget sound engine.

Return type

Sound

Returns

Sound API

get_surface()

Return the Widget surface.

Warning

Use with caution.

Return type

Surface

Returns

Widget surface object

get_title()

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

str

Returns

Widget title

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_value()[source]

Return the current value of the selected index.

Return type

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

Returns

Value and index as a tuple, (value, index)

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()[source]

Hides the Widget.

Return type

DropSelect

Returns

Self reference

is_floating()

Return True if the Widget is floating.

Return type

bool

Returns

Float status

is_selected()

Return True if the Widget is selected.

Return type

bool

Returns

Selected 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

make_selection_drop(**kwargs)[source]

Make selection drop box.

kwargs (Optional)
  • scrollbar_color (tuple, list, str, int, pygame.Color) – Scrollbar color

  • scrollbar_cursor (int, pygame.cursors.Cursor, None) – Cursor of the scrollbars if mouse is placed over. By default is None

  • scrollbar_shadow_color (tuple, list, str, int, pygame.Color) – Color of the shadow of each scrollbar

  • scrollbar_shadow_offset (int) – Offset of the scrollbar shadow in px

  • scrollbar_shadow_position (str) – Position of the scrollbar shadow. See pygame_menu.locals

  • scrollbar_shadow (bool) – Indicate if a shadow is drawn on each scrollbar

  • scrollbar_slider_color (tuple, list, str, int, pygame.Color) – Color of the sliders

  • scrollbar_slider_hover_color (tuple, list, str, int, pygame.Color) – Color of the slider if hovered or clicked

  • scrollbar_slider_pad (int, float) – Space between slider and scrollbars borders in px

  • scrollbar_thick (int) – Scrollbar thickness in px

  • scrollbars (str) – Scrollbar position. See pygame_menu.locals

Parameters

kwargs – Optional keyword arguments

Return type

DropSelect

Returns

Self reference

mouseleave(event, check_all_widget_mouseleave=True)

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.

Parameters
  • event (Event) – MOUSEMOVE pygame event

  • check_all_widget_mouseleave (bool) – Check widget leave statutes

Return type

Widget

Returns

Self reference

mouseover(event, check_all_widget_mouseleave=True)

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.

Parameters
  • event (Event) – MOUSEMOVE pygame event

  • check_all_widget_mouseleave (bool) – Check widget leave statutes

Return type

Widget

Returns

Self reference

on_remove_from_menu()[source]

Function executed if the Widget is removed from the Menu.

Return type

DropSelect

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

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

reset_value()

Reset the Widget value to the default one.

Return type

Widget

Returns

Self reference

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

Transformation: Set the Widget size to another size.

Note

This method calls pygame_menu.widgets.core.widget.Widget.scale() method; thus, some widgets may not support this transformation.

Note

The resize method uses the base Widget size, without any transformation, if a scaling factor is applied it unscales and then scales back to get the desired width/height.

Note

Resize is only applied after Widget rendering. Thus, the changes are not immediate.

Note

Use pygame_menu.widgets.core.widget.Widget.render() method to force widget rendering after calling this method.

Warning

Final Widget size may not be exactly the same as the desired (width, height) tuple due to rounding errors, expect ±2 px average.

Parameters
  • width – New width of the widget in px

  • height – New height of the widget in px

  • smooth – Smooth scaling

Return type

DropSelect

Returns

Self reference

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

Transformation: 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.

Note

Rotation is only applied after widget rendering. Thus, the changes are not immediate.

Note

Use pygame_menu.widgets.core.widget.Widget.render() method to force widget rendering after calling this method.

Parameters

angle – Rotation angle (degrees 0-360)

Return type

DropSelect

Returns

Self reference

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

Transformation: Scale the Widget to a desired width and height factor.

Note

Not all widgets are affected by scale.

Note

Scale considers widget padding.

Note

Scale is only applied after widget rendering. Thus, the changes are not immediate.

Note

Use pygame_menu.widgets.core.widget.Widget.render() method to force widget rendering after calling this method.

Parameters
  • width – Scale factor of the width

  • height – Scale factor of the height

  • smooth – Smooth scaling

Return type

DropSelect

Returns

Self reference

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

scrollh(value)[source]

Scroll to horizontal value.

Parameters

value (Union[int, float]) – Horizontal scroll value, if 0 scroll to left; 1 scroll to right

Return type

DropSelect

Returns

Self reference

scrollv(value)[source]

Scroll to vertical value.

Parameters

value (Union[int, float]) – Vertical scroll value, if 0 scroll to top; 1 scroll to bottom

Return type

DropSelect

Returns

Self reference

select(status=True, update_menu=False)

Mark the Widget as selected and execute the onselect callback function as follows:

onselect(selected, widget, menu) <or> onselect()

If Widget is_selectable is False this function is not executed.

Note

Use pygame_menu.widgets.core.widget.Widget.render() method to force Widget rendering after calling this method.

Warning

This method should only be used by the menu.

Parameters
  • status (bool) – Selection status

  • update_menu (bool) – If True this status is also applied on the menu that contains this 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_background_color(color, inflate=(0, 0))

Set the Widget background color.

Parameters
Return type

Widget

Returns

Self reference

set_border(width, color, inflate=(0, 0), position=('position-north', 'position-south', 'position-east', 'position-west'))

Set the Widget border.

Note

Inflate is added to the background inflate in drawing time.

Parameters
Return type

Widget

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_controls(joystick=True, mouse=True, touchscreen=True, keyboard=True)

Enable interfaces to control the Widget.

Parameters
  • joystick (bool) – Use joystick events

  • mouse (bool) – Use mouse events

  • touchscreen (bool) – Use touchscreen events

  • keyboard (bool) – Use keyboard events

Return type

Widget

Returns

Self reference

set_cursor(cursor)

Set the Widget cursor if user places the mouse over the Widget.

Parameters

cursor (Union[int, Cursor, None]) – Pygame cursor

Return type

Widget

Returns

Self reference

set_default_value(index)[source]

Set the Widget value, and then make it as default.

Note

This method is intended to be used along pygame_menu.widgets.core.widget.Widget.reset_value() method that sets the Widget value back to the default set with this method.

Note

Not all widgets accepts a value, for example the image widget.

Parameters

value – Default widget value

Return type

DropSelect

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(font, font_size, color, selected_color, readonly_color, readonly_selected_color, background_color, antialias=True)

Set the Widget font.

Parameters
Return type

Widget

Returns

Self reference

set_font_shadow(enabled=True, color=None, position=None, offset=2)

Set the Widget font shadow.

Note

See pygame_menu.locals for valid position values.

Parameters
Return type

Widget

Returns

Self reference

set_frame(frame)[source]

Set Widget frame.

Parameters

frame (Frame) – Frame object

Return type

DropSelect

Returns

Self reference

set_margin(x, y)

Set the Widget margin (left, bottom).

Parameters
Return type

Widget

Returns

Self reference

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

Transformation: Set the Widget max height, it applies a scaling factor if the widget height is greater than the limit.

Note

Max height considers padding.

Note

Max height is only applied after Widget rendering. Thus, the changes are not immediate.

Note

Use pygame_menu.widgets.core.widget.Widget.render() method to force widget rendering after calling this method.

Warning

Final Widget size may not be exactly the same as the desired (width, height) tuple due to rounding errors, expect ±2 px average.

Parameters
  • height – Height in px, None if max height is disabled

  • scale_width – If True the width is also scaled if the height exceeds the limit

  • smooth – Smooth scaling

Return type

DropSelect

Returns

Self reference

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

Transformation: Set the Widget max width, it applies a scaling factor if the widget width is greater than the limit.

Note

If width=0 the widget will use the max column width of the Menu (using the column the widget belongs to).

Note

Max width considers padding.

Note

Max width is only applied after widget rendering. Thus, the changes are not immediate.

Note

Use pygame_menu.widgets.core.widget.Widget.render() method to force widget rendering after calling this method.

Warning

Final Widget size may not be exactly the same as the desired (width, height) tuple due to rounding errors, expect ±2 px average.

Parameters
  • width – Width in px, None if max width is disabled

  • scale_height – If True the height is also scaled if the width exceeds the limit

  • smooth – Smooth scaling

Return type

DropSelect

Returns

Self reference

set_menu(menu)

Set the Widget menu reference.

Parameters

menu (Optional[Menu]) – Menu object

Return type

Widget

Returns

Self reference

set_onchange(onchange)

Set onchange callback. This method is executed in pygame_menu.widgets.core.widget.Widget.change() method. The callback function receives the following arguments:

onchange(value, *args, *widget._args, **widget._kwargs)
Parameters

onchange (Optional[Callable]) – Callback executed if the Widget changes its value; it can be a function or None

Return type

Widget

Returns

Self reference

set_onmouseleave(onmouseleave)

Set onmouseleave callback. This method is executed in pygame_menu.widgets.core.widget.Widget.mouseleave() method. The callback function receives the following arguments:

onmouseleave(widget, event) <or> onmouseleave()
Parameters

onmouseleave (Union[Callable[[Widget, Event], Any], Callable[[], Any], None]) – Callback executed if user leaves the Widget with the mouse; it can be a function or None

Return type

Widget

Returns

Self reference

set_onmouseover(onmouseover)

Set onmouseover callback. This method is executed in pygame_menu.widgets.core.widget.Widget.mouseover() method. The callback function receives the following arguments:

onmouseover(widget, event) <or> onmouseover()
Parameters

onmouseover (Union[Callable[[Widget, Event], Any], Callable[[], Any], None]) – Callback executed if user enters the Widget with the mouse; it can be a function or None

Return type

Widget

Returns

Self reference

set_onreturn(onreturn)

Set onreturn callback. This method is executed in pygame_menu.widgets.core.widget.Widget.apply() method. The callback function receives the following arguments:

onreturn(value, *args, *widget._args, **widget._kwargs)
Parameters

onreturn (Optional[Callable]) – Callback executed if user applies on Widget; it can be a function or None

Return type

Widget

Returns

Self reference

set_onselect(onselect)

Set onselect callback. This method is executed in pygame_menu.widgets.core.widget.Widget.select() method. The callback function receives the following arguments:

onselect(selected, widget, menu) <or> onselect()
Parameters

onselect (Union[Callable[[bool, Widget, Menu], Any], Callable[[], Any], None]) – Callback executed if user selects the Widget; it can be a function or None

Return type

Widget

Returns

Self reference

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 (Union[int, float, List[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

Widget

Returns

Self reference

set_position(x, y)[source]

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.

Parameters
Return type

DropSelect

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)[source]

Set scrollarea reference. Mostly used for events.

Parameters

scrollarea (ScrollArea) – Scrollarea object

Return type

None

Returns

None

set_selection_effect(selection)

Set the selection effect handler.

Note

If selection=None the selection effect will be established to _WidgetNullSelection class.

Parameters

selection (Optional[Selection]) – Selection effect class

Return type

Widget

Returns

Self reference

set_sound(sound)

Set sound engine to the Widget.

Parameters

sound (Sound) – Sound object

Return type

Widget

Returns

Self reference

set_tab_size(tab_size)

Set widget tab size.

Parameters

tab_size (int) – Width of a tab character

Return type

Widget

Returns

Self reference

set_theme(theme)[source]

Set object theme.

Parameters

theme (Theme) – Theme

Return type

DropSelect

Returns

Self reference

set_title(title)

Update the Widget title.

Note

Not all widgets implements this method, for example, images don’t accept a title.

Parameters

title (str) – New title

Return type

Widget

Returns

Self reference

set_value(item)[source]

Set the current value of the widget, selecting the item that matches the text if item is a string, or the index if item is an integer. This method raises ValueError if no item found.

For example, if widget item list is [['a',0],['b',1],['a',2]]:

  • widget.set_value(‘a’) -> Widget selects the first item (index 0)

  • widget.set_value(2) -> Widget selects the third item (index 2)

Note

This method does not trigger any event (change).

Parameters

item (Union[str, int]) – Item to select, can be a string or an integer

Return type

None

Returns

None

show()[source]

Set the Widget visible.

Return type

DropSelect

Returns

Self reference

translate(x, y)[source]

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.

Parameters
Return type

DropSelect

Returns

None

update(events)[source]

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.

Parameters

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

Return type

bool

Returns

True if updated

update_font(style)

Updates the Widget font. This method receives a style dict (non empty).

Optional style keys
  • antialias (bool) – Font antialias

  • background_color (tuple) – Background color

  • color (tuple) – Font color

  • name (str) – Name of the font

  • readonly_color (tuple) – Readonly color

  • readonly_selected_color (tuple) – Readonly selected color

  • selected_color (tuple) – Selected color

  • size (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.

Parameters

style (Dict[str, Any]) – Font style dict

Return type

Widget

Returns

Self reference

update_items(items)[source]

Update drop select items.

Note

If the length of the list is different than the previous one, the new index of the select will be the first item of the list.

Parameters

items (Union[List[Tuple[Any, …]], List[str]]) – New drop select items; format [('Item1', a, b, c...), ('Item2', d, e, f...)]

Return type

None

Returns

None