modals.py

Unified overlay, tooltip, notification, and dialog UI primitives.

class Overlay

Description

Base class for UI overlays with lifecycle, fade, positioning, and cleanup.

Methods
def __init__(self: Any, x: int = 0, y: int = 0, width: int = 1, height: int = 1, pivot: Any = (0, 0), element_id: Optional[str] = None, layer: LayerType = LayerType.POPUP, fade_duration: float = 0.15) -> Any
No documentation
def opacity(self: Any) -> float
No documentation
def show(self: Any) -> None
No documentation
def hide(self: Any) -> None
No documentation
def set_position(self: Any, x: int, y: int) -> None
No documentation
def cleanup_on_hide(self: Any) -> None
Hook for subclasses to release transient overlay state.
def update_overlay_fade(self: Any, dt: float) -> None
No documentation
def update(self: Any, dt: float, input_state: InputState) -> None
No documentation

class TooltipConfig

Description

Configuration class for tooltip appearance and behavior.
Allows easy customization of tooltips without passing multiple parameters.

Methods
def __init__(self: Any, text: str = '', font_size: int = 14, padding: int = 8, corner_radius: int = 4, offset_x: int = 10, offset_y: int = 10, show_delay: float = 0.5, max_width: int = 300, theme: ThemeType = None) -> Any
Initialize tooltip configuration.

Args:
   text (str): Tooltip text content
   font_size (int): Font size for tooltip text
   padding (int): Padding around text
   corner_radius (int): Border radius for rounded corners
   offset_x (int): Horizontal offset from target element
   offset_y (int): Vertical offset from target element
   show_delay (float): Delay in seconds before showing tooltip
   max_width (int): Maximum width before text wraps
   theme (ThemeType): Custom theme for tooltip

class Tooltip

Description

Tooltip element that displays helpful information when hovering over UI elements.
Automatically adjusts position to stay within screen boundaries.

Methods
def __init__(self: Any, config: TooltipConfig = None, element_id: Optional[str] = None) -> Any
Initialize a tooltip with configuration.

Args:
   config (TooltipConfig): Configuration object for tooltip appearance
   element_id (Optional[str]): Custom element ID
def _calculate_size(self: Any) -> Any
Calculate tooltip size based on text and configuration.
def _wrap_text(self: Any, text: str, font: Any) -> List[str]
Wrap text to fit within max width.

Args:
   text (str): Text to wrap
   font: Font object for size calculation
   
Returns:
   List[str]: List of wrapped lines
def set_text(self: Any, text: str) -> Any
Update tooltip text and recalculate size.

Args:
   text (str): New tooltip text
def set_config(self: Any, config: TooltipConfig) -> Any
Update tooltip configuration.

Args:
   config (TooltipConfig): New configuration
def set_target(self: Any, element: UIElement) -> Any
Set the target element for this tooltip.

Args:
   element (UIElement): Element to attach tooltip to
def update_tooltip(self: Any, inputState: InputState, dt: float, screen_width: int, screen_height: int) -> bool
Update tooltip state and position.

Args:
   mouse_pos (Tuple[int, int]): Current mouse position
   dt (float): Delta time in seconds
   screen_width (int): Screen width for boundary checking
   screen_height (int): Screen height for boundary checking
   
Returns:
   bool: True if tooltip should be visible, False otherwise
def _update_position(self: Any, screen_width: int, screen_height: int, mouse_pos: Tuple[int, int]) -> Any
Update tooltip position to follow mouse and stay within screen bounds.

Args:
   screen_width (int): Screen width for boundary checking
   screen_height (int): Screen height for boundary checking
   mouse_pos (Tuple[int, int]): Current mouse position
def update_theme(self: Any, theme_type: ThemeType) -> Any
Update the tooltip's theme.
def render(self: Any, renderer: Any) -> Any
Render tooltip using OpenGL backend
def _render_wrapped_text(self: Any, renderer: Any, x: int, y: int, theme: Any) -> Any
Render wrapped text inside tooltip.

class UITooltipManager

Description

Manages tooltips globally to ensure proper display and positioning.
Supports multiple tooltips for different UI elements.

Attributes
_instance: Any = None
_tooltips: Dict[str, Tooltip] = {}
_active_tooltip: Optional[Tooltip] = None
Methods
def __new__(cls: Any) -> Any
No documentation
def register_tooltip(cls: Any, element: UIElement, tooltip: Tooltip) -> Any
Register a tooltip for a UI element.

Args:
   element (UIElement): The UI element that triggers the tooltip
   tooltip (Tooltip): The tooltip to show
def unregister_tooltip(cls: Any, element: UIElement) -> Any
Unregister tooltip for a UI element.

Args:
   element (UIElement): The UI element to remove tooltip from
def update_all_themes(cls: Any, theme_type: ThemeType | ThemeKey) -> Any
Update all registered tooltips to the new theme.
def update(cls: Any, engine: 'LunaEngine', dt: float) -> Any
Update all tooltips and determine which one should be active.

Args:
   engine (LunaEngine): The main engine instance
   dt (float): Delta time in seconds
def get_tooltip_to_render(cls: Any, engine: 'LunaEngine') -> List[Tooltip]
Get the currently active tooltip to render.

Args:
   engine (LunaEngine): The main engine instance
   
Returns:
   List[Tooltip]: List containing the active tooltip, or empty if none
def render(cls: Any, renderer: Any) -> Any
Render the active tooltip.
def clear_all(cls: Any) -> Any
Clear all registered tooltips.

class NotificationType

Description

Types of notifications with different visual styles.

Attributes
SUCCESS: Any = auto()
INFO: Any = auto()
WARNING: Any = auto()
ERROR: Any = auto()
CUSTOM: Any = auto()
Methods

No methods defined.

class NotificationPosition

Description

Pre-defined notification positions.

Attributes
TOP_LEFT: Any = 'top_left'
TOP_CENTER: Any = 'top_center'
TOP_RIGHT: Any = 'top_right'
CENTER_LEFT: Any = 'center_left'
CENTER: Any = 'center'
CENTER_RIGHT: Any = 'center_right'
BOTTOM_LEFT: Any = 'bottom_left'
BOTTOM_CENTER: Any = 'bottom_center'
BOTTOM_RIGHT: Any = 'bottom_right'
CUSTOM: Any = 'custom'
Methods

No methods defined.

class NotificationStyle

Description

Style configuration for different notification types.

Methods
def __init__(self: Any, bg_color: Tuple[int, int, int], border_color: Tuple[int, int, int], text_color: Tuple[int, int, int], icon_type: Optional[Icon] = None, duration: float = 5.0, show_icon: bool = True) -> Any
Initialize notification style.

Args:
   bg_color: Background color (RGB)
   border_color: Border color (RGB)
   text_color: Text color (RGB)
   icon_type: Optional icon type from Icons enum
   duration: Default duration in seconds
   show_icon: Whether to show icon

class NotificationConfig

Description

No documentation

Methods
def __init__(self: Any, text: str, notification_type: NotificationType = NotificationType.INFO, duration: Optional[float] = None, position: Union[NotificationPosition, Tuple[int, int]] = NotificationPosition.TOP_RIGHT, width: int = 300, height: int = 60, show_close_button: bool = True, auto_close: bool = True, animation_speed: float = 0.3, show_progress_bar: bool = False, on_close: Optional[Callable] = None, on_click: Optional[Callable] = None, metadata: Any = None, custom_icon: Optional[Icon] = None) -> Any
Initialize notification configuration.

Args:
   text: Notification text
   notification_type: Type of notification
   duration: Display duration in seconds (None for default based on type)
   position: Position (NotificationPosition enum or custom (x, y) tuple)
   width: Width of notification
   height: Height of notification
   show_close_button: Whether to show close button
   auto_close: Whether notification auto-closes after duration
   animation_speed: Speed of slide/fade animations in seconds
   show_progress_bar: Whether to show progress bar for remaining time
   on_close: Callback when notification is closed
   on_click: Callback when notification is clicked
   metadata: Optional metadata attached to notification
   custom_icon: Optional custom icon

class Notification

Description

Single notification element with advanced positioning and animations.

Attributes
STYLES: Any = {NotificationType.SUCCESS: NotificationStyle(bg_color=(46, 204, 113), border_color=(39, 174, 96), text_color=(255, 255, 255), icon_type=Icons.SUCCESS, duration=3.0, show_icon=True), NotificationType.INFO: NotificationStyle(bg_color=(52, 152, 219), border_color=(41, 128, 185), text_color=(255, 255, 255), icon_type=Icons.INFO, duration=5.0, show_icon=True), NotificationType.WARNING: NotificationStyle(bg_color=(241, 196, 15), border_color=(243, 156, 18), text_color=(0, 0, 0), icon_type=Icons.WARN, duration=7.0, show_icon=True), NotificationType.ERROR: NotificationStyle(bg_color=(231, 76, 60), border_color=(192, 57, 43), text_color=(255, 255, 255), icon_type=Icons.ERROR, duration=10.0, show_icon=True), NotificationType.CUSTOM: NotificationStyle(bg_color=(149, 165, 166), border_color=(127, 140, 141), text_color=(255, 255, 255), icon_type=Icons.INFO, duration=5.0, show_icon=True)}
Methods
def __init__(self: Any, config: NotificationConfig, engine: 'LunaEngine', theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a notification.

Args:
   config: Notification configuration
   engine: Reference to the engine for screen size
   theme: Theme to use
   element_id: Custom element ID
def _get_theme_based_style(self: Any) -> NotificationStyle
Get notification style based on current theme.
def _calculate_target_position(self: Any) -> Tuple[int, int]
Calculate target position based on configuration.
def _calculate_start_position(self: Any) -> Tuple[int, int]
Calculate start position for slide animation based on target position.
def _create_ui(self: Any) -> Any
Create the notification UI elements.
def _apply_custom_style(self: Any) -> Any
Apply custom styling if provided in config.
def show(self: Any) -> Any
Start showing the notification.
def close(self: Any) -> Any
Close the notification with animation.
def force_close(self: Any) -> Any
Force close without animation.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update notification state and animations.
def _ease_out(self: Any, t: float) -> float
Ease out cubic function for smooth animation.
def _ease_in(self: Any, t: float) -> float
Ease in cubic function for smooth animation.
def should_remove(self: Any) -> bool
Check if notification should be removed.
def get_opacity(self: Any) -> float
Get current opacity for fade animations.
def render(self: Any, renderer: Any) -> Any
Render notification with icon.

class NotificationManager

Description

Manages all notifications globally with queue support.
Handles positioning, stacking, and lifecycle of notifications.

Attributes
_instance: Any = None
Methods
def __new__(cls: Any) -> Any
No documentation
def _initialize(self: Any) -> Any
Initialize the notification manager.
def set_engine(self: Any, engine: 'LunaEngine') -> Any
Set the engine reference for screen size calculations.
def show_notification(self: Any, config: NotificationConfig) -> Notification
Show a new notification immediately or add to queue.

Args:
   config: Notification configuration
   
Returns:
   The created Notification object
def _show_notification_immediate(self: Any, notification: Notification) -> Any
Show a notification immediately.
def _update_notification_positions(self: Any, position: NotificationPosition) -> Any
Update positions for stacked notifications in a position group.
def show_simple_notification(self: Any, text: str, notification_type: NotificationType = NotificationType.INFO, duration: Optional[float] = None, position: Union[NotificationPosition, Tuple[int, int]] = NotificationPosition.TOP_RIGHT) -> Notification
Show a simple notification with minimal configuration.

Args:
   text: Notification text
   notification_type: Type of notification
   duration: Optional custom duration
   position: Position for notification
   
Returns:
   The created Notification object
def remove_notification(self: Any, notification: Notification) -> Any
Remove a specific notification.
def clear_all(self: Any) -> Any
Clear all notifications immediately.
def clear_by_type(self: Any, notification_type: NotificationType) -> Any
Clear all notifications of a specific type.
def _process_queue(self: Any) -> Any
Process the notification queue.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update all notifications and process queue.
def render(self: Any, renderer: Any) -> Any
Render all notifications.
def get_notification_count(self: Any) -> int
Get the current number of active notifications.
def get_queue_length(self: Any) -> int
Get the current queue length.
def has_notifications(self: Any) -> bool
Check if there are any active notifications.
def has_queued_notifications(self: Any) -> bool
Check if there are any queued notifications.
def set_max_concurrent(self: Any, max_count: int) -> Any
Set maximum concurrent notifications.
def set_default_margin(self: Any, margin: int) -> Any
Set default margin for notifications.
def set_spacing(self: Any, spacing: int) -> Any
Set spacing between notifications.

class DialogBox

Description

RPG-style dialog box with multiple display styles and text animations.
Supports typewriter effect, fade-in, and character-by-character display.

Internal metrics (padding, name_padding, corner radius, indicator size,
shadow distance, and the hard-coded font sizes) scale with the current
ratio because the user cannot change them.

Attributes
_properties: Dict[str, Dict[str, Any]] = {**UIElement._properties, 'dialog_style': {'name': 'Dialog style', 'key': 'dialog_style', 'type': str, 'editable': True, 'description': 'Visual style: "default", "rpg", "pokemon", "modern".', 'options': ['default', 'rpg', 'pokemon', 'modern']}, 'text': {'name': 'text', 'key': 'text', 'type': str, 'editable': True, 'description': 'The dialog text content.'}, 'speaker_name': {'name': 'speaker name', 'key': 'speaker_name', 'type': str, 'editable': True, 'description': 'Name of the speaker displayed above the box.'}, 'animation_type': {'name': 'animation type', 'key': 'animation_type', 'type': str, 'editable': True, 'description': 'Type of text animation: "typewriter".'}, 'animation_speed': {'name': 'animation speed', 'key': 'animation_speed', 'type': int, 'editable': True, 'description': 'Characters per second for typewriter effect.'}}
Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, dialog_style: Literal['default', 'rpg', 'pokemon', 'modern'] = 'default', theme: Optional[ThemeType] = None, element_id: Optional[str] = None) -> None
No documentation
def _sm(self: Any) -> float
No documentation
def font_size(self: Any) -> int
No documentation
def name_font_size(self: Any) -> int
No documentation
def padding(self: Any) -> int
No documentation
def name_padding(self: Any) -> int
No documentation
def corner_radius(self: Any) -> int
No documentation
def corner_radius(self: Any, value: int) -> Any
No documentation
def font(self: Any) -> pygame.font.Font
No documentation
def name_font(self: Any) -> pygame.font.Font
No documentation
def _get_init_args(self: Any) -> Dict[str, Any]
No documentation
def set_text(self: Any, text: str, speaker_name: str = '', instant: bool = False) -> None
No documentation
def set_animation(self: Any, animation_type: str, speed: int = 30) -> None
No documentation
def skip_animation(self: Any) -> None
No documentation
def advance(self: Any) -> bool
No documentation
def set_on_complete(self: Any, callback: Callable[[], None]) -> None
No documentation
def set_on_advance(self: Any, callback: Callable[[], None]) -> None
No documentation
def update(self: Any, dt: float, inputState: InputState) -> None
No documentation
def render(self: Any, renderer: OpenGLRenderer) -> None
No documentation
def _render_wrapped_text(self: Any, renderer: OpenGLRenderer, x: int, y: int, width: int, height: int, theme: Any) -> None
No documentation

Global Functions

def show_notification(text: str, notification_type: NotificationType = NotificationType.INFO, duration: Optional[float] = None, position: Union[NotificationPosition, Tuple[int, int]] = NotificationPosition.TOP_RIGHT) -> Notification

Convenience function to show a simple notification.

Args:
   text: Notification text
   notification_type: Type of notification
   duration: Optional custom duration
   position: Position for notification
   
Returns:
   The created Notification object

def show_error(text: str, duration: Optional[float] = None, position: Union[NotificationPosition, Tuple[int, int]] = NotificationPosition.TOP_RIGHT) -> Notification

Show an error notification.

def show_warning(text: str, duration: Optional[float] = None, position: Union[NotificationPosition, Tuple[int, int]] = NotificationPosition.TOP_RIGHT) -> Notification

Show a warning notification.

def show_success(text: str, duration: Optional[float] = None, position: Union[NotificationPosition, Tuple[int, int]] = NotificationPosition.TOP_RIGHT) -> Notification

Show a success notification.

def show_info(text: str, duration: Optional[float] = None, position: Union[NotificationPosition, Tuple[int, int]] = NotificationPosition.TOP_RIGHT) -> Notification

Show an info notification.

def clear_all_notifications() -> Any

Clear all notifications.

def get_notification_count() -> int

Get the current number of active notifications.

def get_queue_length() -> int

Get the current queue length.

Back to Ui Module