Selector

class pygame_menu.widgets.Selector(title, elements, selector_id='', default=0, onchange=None, onreturn=None, *args, **kwargs)[source]

Bases: pygame_menu.widgets.core.widget.Widget

Selector widget: several items with values and two functions that are executed when changing the selector (left/right) and pressing return button on the selected item.

The values of the selector are like:

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

The callbacks receive the current text, its index in the list, the associated arguments and all unknown keyword arguments:

onchange((current_text, index), a, b, c..., **kwargs)
onreturn((current_text, index), a, b, c..., **kwargs)
Parameters:
  • title (str) – Selector title
  • elements (list) – Elements of the selector
  • selector_id (str) – ID of the selector
  • default (int) – Index of default element to display
  • onchange (callable, None) – Callback when changing the selector
  • onreturn (callable, None) – Callback when pressing return on the selector
  • kwargs (dict) – Optional keyword arguments
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

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

Return the widget alignment.

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

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

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

Return the Rect object, this forces the widget rendering.

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.

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

Return the widget title.

Returns:Widget title
Return type:str
get_value()[source]

Return the current value of the selector at the selected index.

Returns:Value and index as a tuple, (value, index)
Return type:tuple
hide()

Hides widget.

Returns:None
left()[source]

Move selector to left.

Returns:None
right()[source]

Move selector to right.

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

Set the current value of the widget, selecting the element that matches the text if item is a string, or the index of the position of item is an integer.

For example, if selector is [[‘a’,0],[‘b’,1],[‘a’,2]]:

  • widget.set_value(‘a’) -> Widget selects 0 (first match)
  • widget.set_value(2) -> Widget selects 2.
Parameters:item (str, int) – Item to select, can be a string or an integer.
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 .update() from Menu class.

Returns:True if the widget position has changed by events after the rendering.
Return type:bool
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_elements(elements)[source]

Update selector elements.

Parameters:elements (Object) – Elements of the selector
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 .get_font_info() method.

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