RangeSlider
Bases:
pygame_menu.widgets.core.widget.Widget
Range slider widget. Offers 1 or 2 sliders for defining a unique value or a range of numeric ones.
If the state of the widget changes the
onchange
callback is called. The state can change by pressing LEFT/RIGHT, or by mouse/touch events.onchange(range_value, **kwargs)
If pressing return key on the widget:
onreturn(range_value, **kwargs)
Note
RangeSlider only accepts translation transformation.
- Parameters
title (
Any
) – Range slider titlerangeslider_id (
str
) – RangeSlider IDdefault_value (
Union
[int
,float
,Tuple
[Union
[int
,float
],Union
[int
,float
]],List
[Union
[int
,float
]]]) – Default range value, can accept a number or a tuple/list of 2 elements (min, max). If a single number is provided the rangeslider only accepts 1 value, if 2 are provided, the range is enabled (2 values)range_values (
Union
[Tuple
[Union
[int
,float
],Union
[int
,float
]],List
[Union
[int
,float
]],Tuple
[Union
[int
,float
], …]]) – Tuple/list of 2 elements of min/max values of the range slider. Also range can accept a list of numbers, in which case the values of the range slider will be discrete. List must be sortedrange_width (
int
) – Width of the range in pxincrement (
Union
[int
,float
]) – Increment of the value if using left/right keys; used only if the range values are not discreteonchange (
Optional
[Callable
]) – Callback when changing the value of the range slideronreturn (
Optional
[Callable
]) – Callback when pressing return on the range slideronselect (
Optional
[Callable
]) – Function when selecting the widgetrange_box_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the range box between the slidersrange_box_color_readonly (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the range box if widget in readonly staterange_box_enabled (
bool
) – Enables a range box between two slidersrange_box_height_factor (
Union
[int
,float
]) – Height of the range box (factor of the range title height)range_box_single_slider (
bool
) – Enables range box if there’s only 1 slider instead of 2range_line_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the range linerange_line_height (
int
) – Height of the range line in pxrange_margin (
Tuple
[int
,int
]) – Range margin on x-axis and y-axis (x, y) from title in pxrange_text_value_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the range values textrange_text_value_enabled (
bool
) – Enables the range values textrange_text_value_font (
Union
[str
,Font
,Path
,None
]) – Font of the ranges value. IfNone
the same font as the widget is usedrange_text_value_font_height (
Union
[int
,float
]) – Height factor of the range value font (factor of the range title height)range_text_value_margin_f (
Union
[int
,float
]) – Margin of the range text values (factor of the range title height)range_text_value_position (
str
) – Position of the range text values, can be NORTH or SOUTH. Seepygame_menu.locals
range_text_value_tick_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the range text value tickrange_text_value_tick_enabled (
bool
) – Range text value tick enabledrange_text_value_tick_hfactor (
Union
[int
,float
]) – Height factor of the range text value tick (factor of the range title height)range_text_value_tick_number (
int
) – Number of range value text, the values are placed uniformly distributedrange_text_value_tick_thick (
int
) – Thickness of the range text value tick in pxrepeat_keys_initial_ms (
Union
[int
,float
]) – Time in ms before keys are repeated when held in msrepeat_keys_interval_ms (
Union
[int
,float
]) – Interval between key press repetition when held in msslider_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Slider colorslider_height_factor (
Union
[int
,float
]) – Height of the slider (factor of the range title height)slider_sel_highlight_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of the selected slider highlight box effectslider_sel_highlight_enabled (
bool
) – Selected slider is highlightedslider_sel_highlight_thick (
int
) – Thickness of the selected slider highlightslider_selected_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Selected slider colorslider_text_value_bgcolor (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Background color of the value text on each sliderslider_text_value_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Color of value text on each sliderslider_text_value_enabled (
bool
) – Enables a value text on each sliderslider_text_value_font (
Union
[str
,Font
,Path
,None
]) – Font of the slider value. IfNone
the same font as the widget is usedslider_text_value_font_height (
Union
[int
,float
]) – Height factor of the slider font (factor of the range title height)slider_text_value_margin_f (
Union
[int
,float
]) – Margin of the slider text values (factor of the range title height)slider_text_value_padding (
Union
[int
,float
,List
[Union
[int
,float
]],Tuple
[Union
[int
,float
]],Tuple
[Union
[int
,float
],Union
[int
,float
]],Tuple
[Union
[int
,float
],Union
[int
,float
],Union
[int
,float
],Union
[int
,float
]],None
]) – Padding of the slider text valuesslider_text_value_position (
str
) – Position of the slider text values, can be NORTH or SOUTH. Seepygame_menu.locals
slider_text_value_triangle (
bool
) – Draws a triangle between slider text value and sliderslider_thickness (
int
) – Slider thickness in pxslider_vmargin (
Union
[int
,float
]) – Vertical margin of the slider (factor of the range title height)value_format (
Callable
[[Union
[int
,float
]],str
]) – Function that format the value and returns a string that is used in the range and slider textargs – Optional arguments for callbacks
kwargs – Optional keyword arguments
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.
Adds the Widget object to kwargs, it helps to get the Widget reference for callbacks. It raises
KeyError
if key is duplicated.
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).
Run
onreturn
callback when return event. The callback function receives the following arguments:onreturn(value, *args, *widget._args, **widget._kwargs)
- Where
value
if something is returned bypygame_menu.widgets.core.widget.Widget.get_value()
args
given to this methodargs
of the widgetkwargs
of the widget
Note
Not all widgets have an
onreturn
method.- Parameters
args – Extra arguments passed to the callback
- Return type
- Returns
Callback return value
Apply callbacks on Widget draw.
- Return type
- Returns
Self reference
Apply callbacks on Widget update.
Note
Readonly widgets or hidden widgets do not apply update callbacks.
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
toTrue
may help.Note
This method may have unexpected results with certain selection effects.
- Return type
- Returns
Self reference
Run
onchange
callback after change event is triggered. The callback function receives the following arguments:onchange(value, *args, *widget._args, **widget._kwargs)
- Where
value
if something is returned bypygame_menu.widgets.core.widget.Widget.get_value()
args
given to this methodargs
of the widgetkwargs
of the widget
Note
Not all widgets have an
onchange
method.- Parameters
args – Extra arguments passed to the callback
- Return type
- Returns
Callback return value
Draw the Widget on a given surface.
Note
Widget drawing order:
Background color
prev
decoratorWidget selection effect (if prev)
Widget surface
Widget selection effect (if post)
Widget border
post
decorator
Draw Widget if selected after all widgets have been drawn. This method should also update
last_surface
; seepygame_menu.widgets.DropSelect
widget example orpygame_menu.widgets.RangeSlider
.
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
- Returns
Self reference
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 aclled 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
- Returns
Self reference
Return the Widget alignment.
- Return type
- Returns
Widget align
Get an attribute value.
Return the widget border properties.
Return the Class+ID as a string.
- Return type
- Returns
Class+ID format
Get the Widget column/row position.
Get counter attribute.
Return the Widget decorator API.
- Return type
- Returns
Decorator API
Return rect to be used in Widget focus.
- Return type
- Returns
Focus rect
Return the Widget font color based on the widget status.
Return a dict with the information of the Widget font.
Get container frame of Widget. If Widget is not within a Frame, the method returns
None
.- Returns
Frame object
- Return type
Get frame depth (If frame is packed within another frame).
- Return type
- Returns
Frame depth
Return the Widget height.
Warning
If the widget is not rendered, this method will return
0
.
Return the object ID.
- Return type
- Returns
Object ID
Return the Menu reference,
None
if it has not been set.
Return the Widget padding.
Return the widget position tuple on x-axis and y-axis (x, y) in px.
- Parameters
apply_padding (
bool
) – Apply widget padding to positionuse_transformed_padding (
bool
) – Use scaled padding if the widget is scaledto_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 positioningreal_position_visible (
bool
) – Return only the visible width/height ifto_real_position=True
- Return type
- Returns
Widget position
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 pxapply_padding (
bool
) – Apply widget paddinguse_transformed_padding (
bool
) – Use scaled padding if the widget is scaledto_real_position (
bool
) – Transform the widget rect to real coordinates (if the Widget change the position if scrollbars move offsets). Used by eventsto_absolute_position (
bool
) – Transform the widget rect to absolute coordinates (if the Widget does not change the position if scrollbars move offsets). Used by eventsrender (
bool
) – Force widget renderingreal_position_visible (
bool
) – Return only the visible width/height ifto_real_position=True
- Return type
- Returns
Widget rect object
Return the scrollarea object.
- Return type
- Returns
ScrollArea object
Return time the Widget has been selected in milliseconds. If the Widget is not currently selected, return
0
.
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
- Returns
Selection effect
Return the Widget size.
Warning
If the widget is not rendered this method might return
(0, 0)
.
Return the Widget sound engine.
- Return type
- Returns
Sound API
Return the Widget surface.
Warning
Use with caution.
- Return type
- Returns
Widget surface object
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
- Returns
Widget title
Get Widget translation on x-axis and y-axis (x, y) in px.
Return the Widget value. If exception
ValueError
is raised, no value will be passed to the callbacks.Warning
Not all widgets return a value.
Return the Widget width.
Warning
If the Widget is not rendered, this method will return
0
.
Return
True
if the object has the given attribute.
Hides the Widget.
- Return type
- Returns
Self reference
Return
True
if the Widget is floating.- Return type
- Returns
Float status
Return
True
if the Widget is selected.- Return type
- Returns
Selected status
Return
True
if the Widget is visible.
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.
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.
Function executed if the Widget is removed from the Menu.
- Return type
- Returns
Self reference
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
Removes draw callback from ID.
Removes update callback from ID.
Public rendering method.
Note
Unlike private
_render
method, public method forces widget rendering (callingpygame_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.
Reset the Widget value to the default one.
- Return type
- Returns
Self reference
The container ScrollArea scrolls to the Widget.
Mark the Widget as selected and execute the
onselect
callback function as follows:onselect(selected, widget, menu) <or> onselect()
If Widget
is_selectable
isFalse
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.
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 validalign
values.
Set an attribute.
Set the Widget background color.
- Parameters
- Return type
- Returns
Self reference
Set the Widget border.
Note
Inflate is added to the background inflate in drawing time.
- Parameters
width (
int
) – Border width in pxcolor (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
,None
]) – Border colorinflate (
Tuple
[int
,int
]) – Inflate on x-axis and y-axis (x, y) in pxposition (
Union
[str
,List
[str
],Tuple
[str
, …]]) – Border position. Valid only: north, south, east, and west. Seepygame_menu.locals
- Return type
- Returns
Self reference
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).
Enable interfaces to control the Widget.
Set the Widget cursor if user places the mouse over the Widget.
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.
Set the floating status. If
True
the Widget don’t contributes 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 been set to the (0, 0) position, thus, the only way to move the Widget to a desired position is by translating it.
- Parameters
- Return type
- Returns
None
Set the Widget font.
- Parameters
font (
Union
[str
,Font
,Path
]) – Font name (seepygame.font.match_font()
for precise format)font_size (
int
) – Size of font in pixelscolor (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Normal font colorselected_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Font color if widget is selectedreadonly_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Font color if widget is in readonly modereadonly_selected_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Font color if widget is selected and in readonly modebackground_color (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
,None
]) – Font background color. IfNone
no background color is usedantialias (
bool
) – Determines if antialias is applied to font (uses more processing power)
- Return type
- Returns
Self reference
Set the Widget font shadow.
Note
See
pygame_menu.locals
for validposition
values.
Set the Widget margin (left, bottom).
Set the Widget menu reference.
Set
onchange
callback. This method is executed inpygame_menu.widgets.core.widget.Widget.change()
method. The callback function receives the following arguments:onchange(value, *args, *widget._args, **widget._kwargs)
Set
onmouseleave
callback. This method is executed inpygame_menu.widgets.core.widget.Widget.mouseleave()
method. The callback function receives the following arguments:onmouseleave(widget, event) <or> onmouseleave()
Set
onmouseover
callback. This method is executed inpygame_menu.widgets.core.widget.Widget.mouseover()
method. The callback function receives the following arguments:onmouseover(widget, event) <or> onmouseover()
Set
onreturn
callback. This method is executed inpygame_menu.widgets.core.widget.Widget.apply()
method. The callback function receives the following arguments:onreturn(value, *args, *widget._args, **widget._kwargs)
Set
onselect
callback. This method is executed inpygame_menu.widgets.core.widget.Widget.select()
method. The callback function receives the following arguments:onselect(selected, widget, menu) <or> onselect()
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
]],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
- Returns
Self reference
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.
Set scrollarea reference. Mostly used for events.
- Parameters
scrollarea (
Optional
[ScrollArea
]) – Scrollarea object- Return type
- Returns
None
Set the selection effect handler.
Note
If
selection=None
the selection effect will be established to_WidgetNullSelection
class.
Set sound engine to the Widget.
Set widget tab size.
Update the Widget title.
Note
Not all widgets implements this method, for example, images don’t accept a title.
Set the Widget value.
Note
Not all widgets accepts a value, for example the image widget.
Warning
This method does not fire the callbacks as it is called programmatically. This behavior is deliberately chosen to avoid infinite loops.
Configure the widget shadow.
- Parameters
shadow_type (
str
) – Shadow type, it can be rectangular or ellipseshadow_width (
int
) – Shadow width in px. If0
the shadow is disabledcorner_radius (
int
) – Shadow corner radius if rectangular in pxcolor (
Union
[Tuple
[int
,int
,int
],Tuple
[int
,int
,int
,int
],str
,int
,Color
]) – Shadow coloraa_amount (
int
) – Antialiasing amout
- Return type
- Returns
Self reference
Set the Widget visible.
- Return type
- Returns
Self reference
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.
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. However,apply_update_callbacks
method is called in most widgets, exceptpygame_menu.widgets.NoneWidget
.
Updates the Widget font. This method receives a style dict (non empty).
- Optional style keys
antialias
(bool) – Font antialiasbackground_color
(tuple) – Background colorcolor
(tuple) – Font colorname
(str) – Name of the fontreadonly_color
(tuple) – Readonly colorreadonly_selected_color
(tuple) – Readonly selected colorselected_color
(tuple) – Selected colorsize
(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.
Return
True
if the Widget’s value changed from the default value.- Return type
- Returns
True
if changed