Source code for pygame_menu.widgets.core.widget

# coding=utf-8

Base class for widgets.

The MIT License (MIT)
Copyright 2017-2020 Pablo Pizarro R. @ppizarror

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the Software
is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.


import pygame
import pygame_menu.baseimage as _baseimage
import pygame_menu.font as _fonts
import pygame_menu.locals as _locals
from pygame_menu.widgets.core.selection import Selection
from pygame_menu.sound import Sound
from pygame_menu.utils import make_surface, assert_alignment, assert_color, assert_position, assert_vector2, to_string

from uuid import uuid4
import time

[docs]class Widget(object): """ Widget abstract class. :param title: Widget title :type title: str :param widget_id: Widget identifier :type widget_id: str :param onchange: Callback when changing the selector :type onchange: function, None :param onreturn: Callback when pressing return button :type onreturn: callable, None :param args: Optional arguments for callbacks :type args: any :param kwargs: Optional keyword-arguments for callbacks :type kwargs: dict """ def __init__(self, title='', widget_id='', onchange=None, onreturn=None, args=None, kwargs=None ): assert isinstance(widget_id, str) if onchange: assert callable(onchange), 'onchange must be callable or None' if onreturn: assert callable(onreturn), 'onreturn must be callable or None' # Store id, if None or empty create new ID based on UUID if widget_id is None or len(widget_id) == 0: widget_id = uuid4() self._attributes = {} # Stores widget attributes self._alignment = _locals.ALIGN_CENTER self._background_color = None self._background_inflate = (0, 0) self._events = [] # type: list self._id = str(widget_id) self._margin = (0.0, 0.0) # type: tuple self._max_width = None # type: (int,float) self._rect = pygame.Rect(0, 0, 0, 0) # type: (pygame.Rect,None) self._selected_rect = None # type: (pygame.rect.Rect,None) self._selection_time = 0 # type: float self._title = to_string(title) self._args = args or [] # type: list self._kwargs = kwargs or {} # type: dict self._on_change = onchange # type: callable self._on_return = onreturn # type: callable # Surface of the widget self._surface = None # type: (pygame.Surface,None) # Menu reference self._menu = None # If this is True then the widget forces the Menu to update because the # widget render has changed self._menu_surface_needs_update = False # Modified in set_font() method self._font = None # type: (pygame.font.Font,None) self._font_antialias = True # type: bool self._font_background_color = None # type: (tuple, None) self._font_color = (0, 0, 0) # type: tuple self._font_name = '' # type: str self._font_selected_color = (255, 255, 255) # type: tuple self._font_size = 0 # type: int # Text shadow self._shadow = False # type: bool self._shadow_color = (0, 0, 0) # type: tuple self._shadow_offset = 2.0 # type: float self._shadow_position = _locals.POSITION_NORTHWEST self._shadow_tuple = None # (x px offset, y px offset) self._create_shadow_tuple() # Rendering, this variable may be used by render() method # If the hash of the variables change respect to the last render hash # (hash computed using self._hash_variables() method) # then the widget should render and update the hash self._last_render_hash = 0 # type: int # Stores the last render surface size, updated by _check_render_size_changed() self._last_render_surface_size = (0, 0) self._selection_effect = None # type: Selection # Public attributes = False # Widget requests focus self.is_selectable = True # Some widgets cannot be selected like labels self.joystick_enabled = True self.mouse_enabled = True self.selected = False self.selection_effect_enabled = True # Some widgets cannot have selection effect self.sound = Sound() # type: Sound
[docs] def set_attribute(self, key, value): """ Set widget attribute. :param key: Key of the attribute :type key: str :param value: Value of the attribute :type value: any :return: None """ assert isinstance(key, str) self._attributes[key] = value
[docs] def get_attribute(self, key, default): """ Get attribute value. :param key: Key of the attribute :type key: str :param default: Value if does not exists :type default: any :return: Attribute data :rtype: any """ assert isinstance(key, str) if key not in self._attributes.keys(): return default return self._attributes[key]
@staticmethod def _hash_variables(*args): """ Compute hash from a series of variables. :param args: Variables to compute hash :type args: any :return: Hash data :rtype: int """ return hash(args) def _render_hash_changed(self, *args): """ This method checks if the widget must render because the inner variables changed. This method should include all the variables. If the render changed, :param args: Variables to check the hash :type args: any :return: Hash data :rtype: int """ _hash = self._hash_variables(*args) if _hash != self._last_render_hash: self._last_render_hash = _hash return True return False
[docs] def set_title(self, title): # lgtm [py/inheritance/incorrect-overridden-signature] """ Update the widget title. :param title: New title :type title: str :return: None """ self._title = to_string(title) self._apply_font() self._render() self._check_render_size_changed()
[docs] def get_title(self): """ Return the widget title. :return: Widget title :rtype: str """ return self._title
[docs] def set_background_color(self, color, inflate=(0, 0)): """ Set widget background color. :param color: Widget background color :type color: tuple, list, :py:class:`pygame_menu.baseimage.BaseImage`, None :param inflate: Inflate background in x,y :type inflate: tuple, list :return: None """ if color is not None: if isinstance(color, _baseimage.BaseImage): assert color.get_drawing_mode() == _baseimage.IMAGE_MODE_FILL, \ 'currently widget only support IMAGE_MODE_FILL drawing mode' else: assert_color(color) assert_vector2(inflate) assert inflate[0] >= 0 and inflate[1] >= 0, \ 'widget background inflate must be equal or greater than zero in both axis' self._background_color = color self._background_inflate = inflate
def _fill_background_color(self, surface): """ Fill a surface with the widget background color. :param surface: Surface to fill :type surface: :py:class:`pygame.Surface` :return: None """ if self._background_color is None: return if isinstance(self._background_color, _baseimage.BaseImage): self._background_color.draw( surface=surface, area=self._rect.inflate(*self._background_inflate), position=(self._rect.x - self._background_inflate[0] / 2, self._rect.y - self._background_inflate[1] / 2) ) else: surface.fill(self._background_color, self._rect.inflate(*self._background_inflate))
[docs] def get_selection_effect(self): """ Return the selection effect. :return: Selection effect :rtype: :py:class:`pygame_menu.widgets.core.Selection` """ return self._selection_effect
[docs] def set_selection_effect(self, selection): """ Set the selection effect handler. :param selection: Selection effect class :type selection: :py:class:`pygame_menu.widgets.core.Selection` :return: None """ assert isinstance(selection, Selection) self._selection_effect = selection
[docs] def apply(self, *args): """ Run ``on_return`` callback when return event. A callback function receives the following arguments: .. code-block:: python 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 :param args: Extra arguments passed to the callback :param args: any :return: None """ if self._on_return: args = list(args) + list(self._args) try: args.insert(0, self.get_value()) except ValueError: pass return self._on_return(*args, **self._kwargs)
[docs] def change(self, *args): """ Run ``on_change`` callback after change event is triggered. A callback function receives the following arguments: .. code-block:: python 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 :param args: Extra arguments passed to the callback :param args: any :return: None """ if self._on_change: args = list(args) + list(self._args) try: args.insert(0, self.get_value()) except ValueError: pass return self._on_change(*args, **self._kwargs)
[docs] def draw(self, surface): """ Draw the widget shape. :param surface: Surface to draw :type surface: :py:class:`pygame.Surface` :return: None """ raise NotImplementedError('override is mandatory')
[docs] def draw_selection(self, surface): """ Draw selection effect on widget. :param surface: Surface to draw :type surface: :py:class:`pygame.Surface` :return: None """ if not self.is_selectable or self._selection_effect is None or not self.selection_effect_enabled: return self._selection_effect.draw(surface, self)
[docs] def set_max_width(self, width): """ Set widget max width (column support) if force_fit_text is enabled. :param width: Width in px, None if max width is disabled :type width: int, float, None :return: None """ if width is not None: assert isinstance(width, (int, float)) self._max_width = width
[docs] def get_margin(self): """ Return the widget margin. :return: Widget margin :rtype: tuple """ return self._margin
[docs] def set_margin(self, x, y): """ Set Widget margin. :param x: Margin on x axis :type x: int, float :param y: Margin on y axis :type y: int, float :return: None """ assert isinstance(x, (int, float)) assert isinstance(y, (int, float)) self._margin = (x, y)
[docs] def get_rect(self): """ Return the Rect object, this forces the widget rendering. :return: Widget rect :rtype: :py:class:`pygame.Rect` """ self._render() return self._rect.copy()
[docs] def get_value(self): """ Return the value. If exception ``ValueError`` is raised, no value will be passed to the callbacks. :return: Widget data value :rtype: Object """ raise ValueError('{}({}) does not accept value'.format(self.__class__.__name__, self.get_id()))
[docs] def get_id(self): """ Return the widget ID. :return: Widget ID :rtype: str """ return self._id
def _render(self): """ Render the widget surface. This method shall update the attribute ``_surface`` with a pygame.Surface representing the outer borders of the widget. :return: None """ raise NotImplementedError('override is mandatory') def _font_render_string(self, text, color=(0, 0, 0), use_background_color=True): """ Render text. :param text: Text to render :type text: str :param color: Text color :type color: tuple :param use_background_color: Use default background color :type use_background_color: bool :return: Text surface :rtype: :py:class:`pygame.Surface` """ # assert isinstance(text, str) assert isinstance(color, tuple) assert isinstance(use_background_color, bool) bgcolor = self._font_background_color # Background color must be opaque, otherwise the results are quite bad if isinstance(bgcolor, (tuple, list)) and len(bgcolor) == 4 and bgcolor[3] != 255: bgcolor = None # Disable if not use_background_color: bgcolor = None return self._font.render(text, self._font_antialias, color, bgcolor) def _check_render_size_changed(self): """ Check the size changed after rendering. This method should be used only on widgets that can change in size, or if the size is changed during execution time (like set_title). The update status (needs update if render size changed) is returned by Widget.surface_needs_update() method. :return: Boolean, if True the size changed :rtype: bool """ if self._rect.size != self._last_render_surface_size: self._last_render_surface_size = self._rect.size self._menu_surface_needs_update = True return True return False def _render_string(self, string, color): """ Render text and turn it into a surface. :param string: Text to render :type string: str :param color: Text color :type color: tuple :return: Text surface :rtype: :py:class:`pygame.Surface` """ text = self._font_render_string(string, color) # Create surface surface = make_surface(width=text.get_width(), height=text.get_height(), alpha=True) # Draw shadow first if self._shadow: text_bg = self._font_render_string(string, self._shadow_color) surface.blit(text_bg, self._shadow_tuple) surface.blit(text, (0, 0)) new_width = surface.get_size()[0] new_height = surface.get_size()[1] if self._max_width is not None and new_width > self._max_width: surface = pygame.transform.smoothscale(surface, (self._max_width, new_height)) return surface
[docs] def surface_needs_update(self): """ 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. :return: True if the widget position has changed by events after the rendering. :rtype: bool """ if self._menu_surface_needs_update: self._menu_surface_needs_update = False return True return False
[docs] def set_font(self, font, font_size, color, selected_color, background_color, antialias=True): """ Set the text font. :param font: Name or list of names for font (see pygame.font.match_font for precise format) :type font: str, list :param font_size: Size of font in pixels :type font_size: int :param color: Text color :type color: tuple :param selected_color: Text color when widget is selected :type selected_color: tuple :param background_color: Font background color :type background_color: tuple :param antialias: Determines if antialias is applied to font (uses more processing power) :type antialias: bool :return: None """ assert isinstance(font, str) assert isinstance(font_size, int) assert isinstance(color, tuple) assert isinstance(selected_color, tuple) assert isinstance(background_color, (tuple, type(None))) assert isinstance(antialias, bool) self._font = _fonts.get_font(font, font_size) self._font_antialias = antialias self._font_background_color = background_color self._font_color = color self._font_name = font self._font_selected_color = selected_color self._font_size = font_size self._apply_font()
[docs] def get_font_info(self): """ Return a dict with the information of the widget font. :return: Dict, keys: size (int), name (str), color (tuple), selected_color (tuple), antialias (bool) :rtype: dict """ return { 'size': self._font_size, 'name': self._font_name, 'color': self._font_color, 'selected_color': self._font_selected_color, 'antialias': self._font_antialias, }
[docs] def set_menu(self, menu): """ Set the menu reference. :param menu: Menu object :type menu: :py:class:`pygame_menu.Menu` :return: None """ self._menu = menu
[docs] def get_menu(self): """ Return the menu reference (if exists). :return: Menu reference :rtype: :py:class:`pygame_menu.Menu` """ return self._menu
def _apply_font(self): """ Function triggered after a font is applied to the widget. :return: None """ raise NotImplementedError('override is mandatory')
[docs] def set_position(self, posx, posy): """ Set the position. :param posx: X position :type posx: int, float :param posy: Y position :type posy: int, float :return: None """ self._rect.x = posx self._rect.y = posy
[docs] def set_alignment(self, align): """ Set the alignment of the widget. :param align: Widget align, see locals :type align: str :return: None """ assert_alignment(align) self._alignment = align
[docs] def get_alignment(self): """ Return the widget alignment. :return: Widget align, see locals :rtype: str """ return self._alignment
[docs] def set_selected(self, selected=True): """ Mark the widget as selected. :param selected: Set item as selected :type selected: bool :return: None """ self.selected = selected = False if selected: self._focus() self._selection_time = time.time() else: self._blur() self._events = [] # Remove events self._render()
[docs] def get_selected_time(self): """ Return time the widget has been selected in miliseconds. If the widget is not currently selected, return 0. :return: Time in ms :rtype: float """ if not self.selected: return 0 return (time.time() - self._selection_time) * 1000
def _focus(self): """ Function that is executed when the widget receives a focus (is selected). :return: None """ pass def _blur(self): """ Function that is executed when the widget loses the focus. :return: None """ pass
[docs] def set_shadow(self, enabled=True, color=None, position=None, offset=None): """ Show text shadow. :param enabled: Shadow is enabled or not :type enabled: bool :param color: Shadow color :type color: list, None :param position: Shadow position :type position: str, None :param offset: Shadow offset :type offset: int, float, None :return: None """ self._shadow = enabled if color is not None: assert_color(color) self._shadow_color = color if position is not None: assert_position(position) self._shadow_position = position if offset is not None: assert isinstance(offset, (int, float)) if offset <= 0: raise ValueError('shadow offset must be greater than zero') self._shadow_offset = offset # Create shadow tuple position self._create_shadow_tuple()
[docs] def set_sound(self, sound): """ Set sound engine to the widget. :param sound: Sound object :type sound: :py:class:`pygame_menu.sound.Sound` :return: None """ self.sound = sound
def _create_shadow_tuple(self): """ Create shadow position tuple. :return: None """ x = 0 y = 0 if self._shadow_position == _locals.POSITION_NORTHWEST: x = -1 y = -1 elif self._shadow_position == _locals.POSITION_NORTH: y = -1 elif self._shadow_position == _locals.POSITION_NORTHEAST: x = 1 y = -1 elif self._shadow_position == _locals.POSITION_EAST: x = 1 elif self._shadow_position == _locals.POSITION_SOUTHEAST: x = 1 y = 1 elif self._shadow_position == _locals.POSITION_SOUTH: y = 1 elif self._shadow_position == _locals.POSITION_SOUTHWEST: x = -1 y = 1 elif self._shadow_position == _locals.POSITION_WEST: x = -1 self._shadow_tuple = (x * self._shadow_offset, y * self._shadow_offset)
[docs] def set_controls(self, joystick=True, mouse=True): """ Enable interfaces to control the widget. :param joystick: Use joystick :type joystick: bool :param mouse: Use mouse :type mouse: bool :return: None """ self.joystick_enabled = joystick self.mouse_enabled = mouse
[docs] def set_value(self, value): """ Set the value. .. warning:: This method does not fire the callbacks as it is called programmatically. This behavior is deliberately chosen to avoid infinite loops. :param value: Value to be set on the widget :type value: Object :return: None """ raise ValueError('{}({}) does not accept value'.format(self.__class__.__name__, self.get_id()))
[docs] def update(self, events): """ Update internal variable according to the given events list and fire the callbacks. :param events: List of pygame events :type events: list[:py:class:`pygame.event.Event`] :return: True if updated :rtype: bool """ raise NotImplementedError('override is mandatory')
def _add_event(self, event): """ Add a custom event to the widget for the next update(). :param event: Custom event :type event: :py:class:`pygame.event.Event` :return: None """ self._events.append(event) def _merge_events(self, events): """ Append widget events to events list. :param events: Event list :type events: list[:py:class:`pygame.event.Event`] :return: Augmented event list :rtype: list[:py:class:`pygame.event.Event`] """ if len(self._events) == 0: return events copy_events = [] for e in events: copy_events.append(e) for e in self._events: copy_events.append(e) self._events = [] return copy_events