elements.py

elements.py - UI Elements Module for LunaEngine

ENGINE PATH:
lunaengine -> ui -> elements.py

DESCRIPTION:
This module provides a comprehensive collection of user interface (UI) elements
for creating interactive graphical interfaces in Pygame. It includes basic components
like buttons, labels, and text fields, as well as more complex elements like dropdown
menus, progress bars, and scrollable containers.

LIBRARIES USED:
- pygame: For graphical rendering and event handling
- numpy: For mathematical calculations (primarily in gradients)
- typing: For type hints and type annotations
- enum: For enum definitions (UI states)
- time: For animation timing

MAIN CLASSES (in order of appearance):

1. UIState (Enum):
  - Defines possible UI element states (NORMAL, HOVERED, PRESSED, DISABLED)

2. FontManager:
  - Manages Pygame fonts with lazy loading and caching
  - Ensures proper font system initialization

3. UIElement:
  - Base class for all UI elements providing common functionality
  - Handles positioning, theming, mouse interaction, and rendering

4. TextLabel:
  - Displays static or dynamic text with theme support
  - Supports custom fonts and colors

5. ImageLabel:
  - Displays images with optional scaling
  - Supports various image formats

6. Button:
  - Interactive button with hover, press, and disabled states
  - Supports text and theme-based styling

7. ImageButton:
  - Button that uses images instead of text
  - Includes state-based visual feedback

8. TextBox:
  - Interactive text input field with cursor
  - Supports keyboard input and text editing

9. DialogBox:
  - RPG-style dialog boxes with multiple styles and animations
  - Supports multiple lines of text and custom themes

10. ProgressBar:
   - Visual progress indicator for loading or value display
   - Shows percentage and customizable range

11. UIDraggable:
   - UI element that can be dragged around the screen
   - Provides visual feedback during dragging

12. UIGradient:
   - UI element with gradient background
   - Supports horizontal and vertical gradients with multiple colors

13. Select:
   - Selection element with arrow buttons to cycle through options
   - Compact alternative to dropdowns

14. Switch:
   - Toggle switch element with sliding animation
   - Alternative to checkboxes with smooth transitions

15. Slider:
   - Interactive slider for selecting numeric values
   - Draggable thumb with value display

16. Dropdown:
   - Dropdown menu for selecting from a list of options
   - Supports scrolling for long lists and custom themes

17. UiFrame:
   - Container element for grouping UI elements
   - Supports nested frames and theme-based styling

18. NumberSelector:
   - Numeric input control with increment/decrement buttons
   - Supports min/max values and digit padding

19. Checkbox:
   - Binary state control with optional label
   - Supports theme-based styling and toggle callbacks

20. ScrollingFrame:
   - Frame with scrollable content area
   - Supports both vertical and horizontal scrolling with scrollbars

21. Tabination:
   - Tabbed container for organizing content into multiple pages
   - Supports clickable tabs and alternating background colors

22. Clock:
   - Real‑time or custom time display (analog/digital)
   - Supports 12/24‑hour formats and extensive styling

23. AudioVisualizer:
   - Real‑time audio visualization (bars, waveform, circle, particles, spectrum)
   - Connects to audio sources and supports animated transitions

24. Pagination:
   - Page navigation control for paged content
   - Shows page numbers with ellipsis and navigation buttons

25. TextArea:
   - Multi‑line text input area with word wrapping, line numbers, and scrollbars
   - Supports selection, copy/paste, undo/redo, and read‑only mode

26. FileFinder:
   - File selection element with text field and browse button
   - Integrates with system file dialog and supports file filtering

27. ChartVisualizer:
   - Versatile data visualization component (bar, pie, line, scatter)
   - Includes animations, legends, and customizable colors

This module forms the core of LunaEngine's UI system, providing a flexible and
themeable foundation for building complex user interfaces in Pygame applications.

class _UIDGenerator

Description

Internal class for generating unique IDs for UI elements.

Generates IDs in the format: ui_{element_type}_{counter}
Example: ui_button_1, ui_label_2, ui_dropdown_1

Methods
def __init__(self: Any) -> Any
No documentation
def generate_id(self: Any, element_type: str) -> str
Generate a unique ID for a UI element.

Args:
   element_type (str): Type of the UI element (e.g., 'button', 'label')
   
Returns:
   str: Unique ID in format "ui_{element_type}_{counter}"

class UIState

Description

Enumeration of possible UI element states.

Attributes
NORMAL: Any = 0
HOVERED: Any = 1
PRESSED: Any = 2
DISABLED: Any = 3
Methods

No methods defined.

class FontManager

Description

Manages fonts and ensures Pygame font system is initialized.

Attributes
_initialized: Any = False
_default_fonts: Any = {}
Methods
def initialize(cls: Any) -> Any
Initialize the font system.

This method should be called before using any font-related functionality.
It initializes Pygame's font module if not already initialized.
def get_font(cls: Any, font_name: Optional[str] = None, font_size: int = 24) -> Any
Get a font object for rendering text.

Args:
   font_name (Optional[str]): Path to font file or None for default system font.
   font_size (int): Size of the font in pixels.
   
Returns:
   pygame.font.Font: A font object ready for text rendering.

class UIElement

Description

Base class for all UI elements providing common functionality.

Attributes:
   element_id (str): Unique identifier for this element in format ui_{type}_{counter}
   x (int): X coordinate position
   y (int): Y coordinate position
   width (int): Width of the element in pixels
   height (int): Height of the element in pixels
   root_point (Tuple[float, float]): Anchor point for positioning
   state (UIState): Current state of the element
   visible (bool): Whether element is visible
   enabled (bool): Whether element is enabled
   children (List[UIElement]): Child elements
   parent (UIElement): Parent element

Attributes
_global_engine: 'LunaEngine' = None
Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, root_point: Tuple[float, float] = (0, 0), element_id: Optional[str] = None) -> Any
Initialize a UI element with position and dimensions.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Width of the element in pixels.
   height (int): Height of the element in pixels.
   root_point (Tuple[float, float]): Anchor point for positioning where (0,0) is top-left
                                   and (1,1) is bottom-right.
   element_id (Optional[str]): Custom element ID. If None, generates automatic ID.
def get_mouse_position(self: Any, input_state: InputState) -> Tuple[int, int]
No documentation
def convert_mouse_pos(self: Any, mouse_pos: Tuple[int, int]) -> Tuple[int, int]
No documentation
def mouse_over(self: Any, input_state: InputState) -> bool
No documentation
def set_enabled(self: Any, enabled: bool) -> Any
No documentation
def get_engine(self: Any) -> 'LunaEngine'
No documentation
def set_corner_radius(self: Any, radius: int | Tuple[int, int, int, int]) -> Any
No documentation
def add_group(self: Any, group: str) -> Any
No documentation
def remove_group(self: Any, group: str) -> Any
No documentation
def clear_groups(self: Any) -> Any
No documentation
def has_group(self: Any, group: str) -> bool
No documentation
def __str__(self: Any) -> str
No documentation
def get_id(self: Any) -> str
Get the unique ID of this UI element.

Returns:
   str: The unique element ID
def set_id(self: Any, new_id: str) -> None
Set a new unique ID for this UI element.

Args:
   new_id (str): The new unique ID to set
def get_actual_position(self: Any, x: int | float = None, y: int | float = None) -> Tuple[int, int]
Calculate actual screen position based on root_point anchor.

Args:
   parent_width (int): Width of parent element if applicable.
   parent_height (int): Height of parent element if applicable.
   
Returns:
   Tuple[int, int]: The actual (x, y) screen coordinates.
def add_child(self: Any, child: Any) -> Any
Add a child element to this UI element.

Args:
   child: The child UI element to add.
def remove_child(self: Any, child: Any) -> Any
Remove a child element from this UI element.

Args:
   child: The child UI element to remove.
def set_tooltip(self: Any, tooltip: 'Tooltip') -> Any
Set tooltip for this element using a Tooltip instance.

Args:
   tooltip (Tooltip): Tooltip instance to associate with this element
def set_simple_tooltip(self: Any, text: str, **kwargs: dict) -> Any
Quick method to set a simple tooltip with text.

Args:
   text (str): Tooltip text
   **kwargs: Additional arguments for TooltipConfig
def remove_tooltip(self: Any) -> Any
Remove tooltip from this element.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update element state.

Args:
   dt (float): Delta time in seconds since last update.
def update_theme(self: Any, theme_type: ThemeType) -> Any
Update the theme for this element and all its children.

Args:
   theme_type (ThemeType): The new theme to apply.
def render(self: Any, renderer: Renderer | OpenGLRenderer) -> Any
Render this element using OpenGL backend.  
Override this in subclasses for OpenGL-specific rendering.
def on_click(self: Any) -> Any
Called when element is clicked by the user.
def on_hover(self: Any) -> Any
Called when mouse hovers over the element.

class TextLabel

Description

UI element for displaying text labels.

Methods
def __init__(self: Any, x: int, y: int, text: str, font_size: int = 24, color: Optional[Tuple[int, int, int]] = None, font_name: Optional[str] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a text label element.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   text (str): The text to display.
   font_size (int): Size of the font in pixels.
   color (Optional[Tuple[int, int, int]]): Custom text color (overrides theme).
   font_name (Optional[str]): Path to font file or None for default font.
   root_point (Tuple[float, float]): Anchor point for positioning.
   theme (ThemeType): Theme to use for text color.
   element_id (Optional[str]): Custom element ID. If None, generates automatic ID.
def get_text(self: Any) -> str
No documentation
def update_theme(self: Any, theme_type: Any) -> Any
Update theme for text label.
def set_text_color(self: Any, color: Tuple[int, int, int]) -> Any
Set the text color.

Args:
   color (Tuple[int, int, int]): RGB color tuple.
def font(self: Any) -> Any
Get the font object (lazy loading).

Returns:
   pygame.font.Font: The font object for this label.
def set_text(self: Any, text: str) -> Any
Update the displayed text and recalculate element size.

Args:
   text (str): The new text to display.
def set_theme(self: Any, theme_type: ThemeType) -> Any
Set the theme for this text label.

Args:
   theme_type (ThemeType): The theme to apply.
def _get_text_color(self: Any) -> Tuple[int, int, int]
Get the current text color.

Returns:
   Tuple[int, int, int]: RGB color tuple for the text.
def render(self: Any, renderer: 'Renderer') -> Any
Render using OpenGL backend

class ImageLabel

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, image_path: str | pygame.Surface, width: Optional[int] = None, height: Optional[int] = None, root_point: Tuple[float, float] = (0, 0), element_id: Optional[str] = None) -> Any
No documentation
def _load_image(self: Any) -> Any
Load and prepare the image.
def set_image(self: Any, image_path: str | pygame.Surface) -> Any
Change the displayed image.

Args:
   image_path (str): Path to the new image file.
def get_image(self: Any) -> pygame.Surface
No documentation
def set_size(self: Any, width: int, height: int) -> Any
No documentation
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend

class Button

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, text: str = '', font_size: int = 20, font_name: Optional[str] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
No documentation
def set_background_color(self: Any, color: Tuple[int, int, int]) -> Any
No documentation
def set_text_color(self: Any, color: Tuple[int, int, int]) -> Any
No documentation
def set_text(self: Any, text: str) -> Any
No documentation
def get_text(self: Any) -> str
No documentation
def update_theme(self: Any, theme_type: Any) -> Any
No documentation
def font(self: Any) -> Any
Get the font object (lazy loading).
def set_on_click(self: Any, callback: Callable, *args: tuple, **kwargs: dict) -> Any
Set the callback function for click events.

Args:
   callback (Callable): Function to call when button is clicked.
def set_theme(self: Any, theme_type: ThemeType) -> Any
Set the theme for this button.

Args:
   theme_type (ThemeType): The theme to apply.
def _get_colors(self: Any) -> Any
Get colors from the current theme.

Returns:
   UITheme: The current theme object.
def update(self: Any, dt: float, inputState: InputState) -> Any
No documentation
def _get_color_for_state(self: Any) -> Tuple[int, int, int]
Get the appropriate color for the current button state.

Returns:
   Tuple[int, int, int]: RGB color tuple for the current state.
def _get_text_color(self: Any) -> Tuple[int, int, int]
Get the text color from the current theme.

Returns:
   Tuple[int, int, int]: RGB color tuple for the text.
def render(self: Any, renderer: 'Renderer') -> Any
Render using OpenGL backend

class ImageButton

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, image_path: str | pygame.Surface, width: Optional[int] = None, height: Optional[int] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
No documentation
def _load_image(self: Any) -> Any
Load the button image.
def set_on_click(self: Any, callback: Callable, *args: tuple, **kwargs: dict) -> Any
Set the callback function for click events.

Args:
   callback (Callable): Function to call when button is clicked.
def get_image(self: Any) -> Any
No documentation
def set_image(self: Any, image_path: str | pygame.Surface) -> Any
No documentation
def update(self: Any, dt: float, inputState: InputState) -> Any
No documentation
def _get_overlay_color(self: Any) -> Optional[Tuple[int, int, int]]
Get overlay color based on button state.

Returns:
   Optional[Tuple[int, int, int]]: Overlay color or None for no overlay.
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend

class TextBox

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, text: str = '', font_size: int = 20, font_name: Optional[str] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, max_length: int = 0, element_id: Optional[str] = None) -> Any
No documentation
def font(self: Any) -> Any
Get the font object with lazy loading.
def get_text(self: Any) -> str
No documentation
def has_focus(self: Any) -> bool
No documentation
def on_key_down(self: Any, event: pygame.event.Event) -> Any
Handle keyboard input when focused - UPDATED with max_length support

Args:
   event: Pygame keyboard event.
def on_key_up(self: Any, event: pygame.event.Event) -> Any
Handle keyboard input when focused - UPDATED with max_length support

Args:
   event: Pygame keyboard event.
def _update_text_surface(self: Any) -> Any
Update text surface cache when text changes.
def _get_text_color(self: Any) -> Any
Get appropriate text color based on state.
def _get_background_color(self: Any) -> Any
Get background color based on state.
def set_text(self: Any, text: str) -> Any
Set the text content and trigger callback if changed.
def update(self: Any, dt: Any, inputState: Any) -> Any
No documentation
def focus(self: Any) -> Any
This will focus the textbox, like as of the user pass the mouse and click on it
def unfocus(self: Any) -> Any
This will unfocus the textbox, like as of the user pass the mouse and click on it
def _get_cursor_position(self: Any, actual_x: int, actual_y: int) -> Tuple[int, int]
Calculate cursor position - IMPROVED with bounds checking
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend - FIXED cursor visibility
def _render_text_content(self: Any, renderer: Any, actual_x: int, actual_y: int, theme: Any) -> Any
Helper method to render text content - FIXED subsurface error

class DialogBox

Description

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

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, style: Literal['default', 'rpg', 'pokemon', 'modern'] = 'default', theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a dialog box.

Args:
   x (int): X coordinate position
   y (int): Y coordinate position
   width (int): Width of dialog box
   height (int): Height of dialog box
   style (str): Visual style ("default", "rpg", "pokemon", "modern")
   theme (ThemeType): Theme to use for styling
   element_id (Optional[str]): Custom element ID
def set_text(self: Any, text: str, speaker_name: str = '', instant: bool = False) -> Any
Set dialog text and optionally a speaker name.

Args:
   text (str): The dialog text to display
   speaker_name (str): Name of the speaker (optional)
   instant (bool): Whether to display text instantly
def set_animation(self: Any, animation_type: str, speed: int = 30) -> Any
Set text animation type and speed.

Args:
   animation_type (str): "typewriter", "fade", or "instant"
   speed (int): Animation speed (characters per second for typewriter)
def skip_animation(self: Any) -> Any
Skip current text animation and show complete text.
def advance(self: Any) -> Any
Advance to next dialog or close if complete.
Returns True if there's more dialog, False if done.
def set_on_complete(self: Any, callback: Callable) -> Any
Set callback for when text animation completes.
def set_on_advance(self: Any, callback: Callable) -> Any
Set callback for when dialog is advanced.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update dialog box animations.
def render(self: Any, renderer: Any) -> Any
Render dialog box using OpenGL backend.
def _render_wrapped_text(self: Any, renderer: Any, x: int, y: int, width: int, height: int, theme: Any) -> Any
Render text with word wrapping.

class ProgressBar

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, min_val: float = 0, max_val: float = 100, value: float = 0, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, orientation: Literal['vertical', 'horizontal'] = 'horizontal', element_id: Optional[str] = None) -> Any
No documentation
def set_background_color(self: Any, color: Any) -> Any
No documentation
def set_foreground_color(self: Any, color: Any) -> Any
No documentation
def set_font_color(self: Any, color: Any) -> Any
No documentation
def set_font(self: Any, font_name: str, font_size: int) -> Any
No documentation
def set_border_color(self: Any, color: Any) -> Any
No documentation
def update_theme(self: Any, theme_type: Any) -> Any
No documentation
def set_value(self: Any, value: float) -> Any
Set the current progress value.

Args:
   value (float): New progress value.
def get_percentage(self: Any) -> float
Get progress as percentage.

Returns:
   float: Progress percentage (0-100).
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend, respecting orientation.

class UIDraggable

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
No documentation
def update(self: Any, dt: float, inputState: InputState) -> Any
No documentation
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend

class UIGradient

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, colors: List[Tuple[int, int, int]], direction: str = 'horizontal', root_point: Tuple[float, float] = (0, 0), element_id: Optional[str] = None) -> Any
No documentation
def _generate_gradient(self: Any) -> Any
Generate the gradient surface with cross-platform consistency
def _interpolate_colors_linear(self: Any, ratio: float) -> Tuple[int, int, int]
Linear color interpolation for consistent cross-platform results

Args:
   ratio (float): Interpolation ratio (0-1)
   
Returns:
   Tuple[int, int, int]: Interpolated color
def _interpolate_colors(self: Any, ratio: float) -> Tuple[int, int, int]
Interpolate between gradient colors.

Args:
   ratio (float): Interpolation ratio (0-1).
   
Returns:
   Tuple[int, int, int]: Interpolated color.
def set_colors(self: Any, colors: List[Tuple[int, int, int]]) -> Any
Set new gradient colors.

Args:
   colors (List[Tuple[int, int, int]]): New gradient colors.
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend

class Select

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, options: List[str], font_size: int = 20, font_name: Optional[str] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
No documentation
def _create_arrow_surfaces(self: Any) -> Any
Create arrow surfaces for both backends
def font(self: Any) -> Any
Get the font object.
def next_option(self: Any) -> Any
Select the next option.
def previous_option(self: Any) -> Any
Select the previous option.
def set_selected_index(self: Any, index: int) -> Any
Set selected option by index.

Args:
   index (int): Index of option to select.
def set_on_selection_changed(self: Any, callback: Callable[[int, str], None]) -> Any
Set selection change callback.

Args:
   callback (Callable): Function called when selection changes.
def update(self: Any, dt: Any, inputState: Any) -> Any
No documentation
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend
def _render_select_content(self: Any, renderer: Any, actual_x: int, actual_y: int, theme: Any) -> Any
Helper method to render select content for both backends
def _draw_fallback_arrows(self: Any, renderer: Any, actual_x: int, actual_y: int, arrow_color: Any) -> Any
Fallback arrow drawing method

class Switch

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int = 60, height: int = 30, checked: bool = False, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
No documentation
def toggle(self: Any) -> Any
Toggle the switch state.
def set_checked(self: Any, checked: bool) -> Any
Set the switch state.

Args:
   checked (bool): New state.
def set_on_toggle(self: Any, callback: Callable[[bool], None]) -> Any
Set toggle callback.

Args:
   callback (Callable): Function called when switch is toggled.
def update(self: Any, dt: Any, inputState: Any) -> Any
No documentation
def _get_colors(self: Any) -> Any
Get colors from current theme for switch
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend - CONSISTENT with Pygame

class Slider

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, min_val: float = 0, max_val: float = 100, value: float = 50, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
No documentation
def set_theme(self: Any, theme_type: ThemeType) -> Any
Set slider theme
def _get_colors(self: Any) -> Any
Get colors from current theme
def set_value(self: Any, value: float) -> Any
No documentation
def update(self: Any, dt: Any, inputState: Any) -> Any
No documentation
def render(self: Any, renderer: Any) -> Any
Render using OpenGL backend

class Dropdown

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, options: List[str] = None, font_size: int = 20, font_name: Optional[str] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, max_visible_options: int = 10, element_id: Optional[str] = None, searchable: bool = False) -> Any
No documentation
def _create_search_box(self: Any) -> Any
No documentation
def _on_search_text_changed(self: Any, text: str) -> Any
No documentation
def _update_filtered_options(self: Any) -> Any
No documentation
def font(self: Any) -> Any
No documentation
def set_options(self: Any, options: List[str], selected_index: int = 0) -> Any
No documentation
def set_theme(self: Any, theme_type: ThemeType) -> Any
No documentation
def _get_colors(self: Any) -> Any
No documentation
def _get_visible_options(self: Any) -> List[int]
No documentation
def on_scroll(self: Any, event: pygame.event.Event) -> Any
No documentation
def _get_scrollbar_track_rect(self: Any, actual_x: int, actual_y: int) -> Tuple[int, int, int, int]
Full rectangle of the vertical scrollbar (track + thumb).
def _get_scrollbar_thumb_rect(self: Any, actual_x: int, actual_y: int) -> Tuple[int, int, int, int]
Rectangle of the scrollbar thumb.
def update(self: Any, dt: float, inputState: InputState) -> Any
No documentation
def render(self: Any, renderer: Renderer) -> Any
No documentation
def _draw_arrow_polygon(self: Any, renderer: Any, points: Any, color: Any) -> Any
No documentation
def _render_expanded_options(self: Any, renderer: Any, actual_x: Any, actual_y: Any, theme: Any) -> Any
No documentation
def add_option(self: Any, option: str) -> Any
No documentation
def remove_option(self: Any, option: str) -> Any
No documentation
def set_selected_index(self: Any, index: int) -> Any
No documentation
def set_on_selection_changed(self: Any, callback: Callable[[int, str], None]) -> Any
No documentation

class UiFrame

Description

No documentation

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a UI Frame container element.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Width of the frame in pixels.
   height (int): Height of the frame in pixels.
   root_point (Tuple[float, float]): Anchor point for positioning.
   theme (ThemeType): Theme to use for frame styling.
   element_id (Optional[str]): Custom element ID. If None, generates automatic ID.
def add_child(self: Any, child: UIElement) -> Any
Add a child element to the frame.

Args:
   child (UIElement): Child element to add.
def set_background_color(self: Any, color: Optional[Tuple[int, int, int]]) -> Any
Set the background color of the frame.

Args:
   color (Optional[Tuple[int, int, int]]): RGB color tuple or None for transparent.
def set_border_color(self: Any, color: Optional[Tuple[int, int, int]]) -> Any
Set the border color of the frame.

Args:
   color (Optional[Tuple[int, int, int]]): RGB color tuple or None for no border.
def set_border(self: Any, color: Optional[Tuple[int, int, int]], width: int = 1) -> Any
Set the border properties of the frame.

Args:
   color (Optional[Tuple[int, int, int]]): Border color or None for no border.
   width (int): Border width in pixels.
def set_padding(self: Any, padding: int) -> Any
Set the padding inside the frame.

Args:
   padding (int): Padding in pixels.
def set_corner_radius(self: Any, radius: int | Tuple[int, int, int, int]) -> Any
No documentation
def get_content_rect(self: Any) -> Tuple[int, int, int, int]
Get the rectangle area available for child elements (inside padding).

Returns:
   Tuple[int, int, int, int]: (x, y, width, height) of content area.
def update_theme(self: Any, theme_type: ThemeType) -> Any
Update the theme for this frame and all its children.

Args:
   theme_type (ThemeType): The new theme to apply.
def update(self: Any, dt: Any, inputState: Any) -> Any
No documentation
def render(self: Any, renderer: Any) -> Any
Render frame using OpenGL backend
def arrange_children_vertically(self: Any, spacing: int = 5, align: str = 'left') -> Any
Arrange child elements vertically within the frame.

Args:
   spacing (int): Space between children in pixels.
   align (str): Alignment ("left", "center", "right").
def arrange_children_horizontally(self: Any, spacing: int = 5, align: str = 'top') -> Any
Arrange child elements horizontally within the frame.

Args:
   spacing (int): Space between children in pixels.
   align (str): Alignment ("top", "center", "bottom").
def clear_children(self: Any) -> Any
Remove all child elements from this frame.

class NumberSelector

Description

UI element that allows a user to select a number within a specified range
using increment and decrement controls.

This element manages its value internally, ensuring it stays within
the defined min_value and max_value. It also handles formatting with
a minimum number of digits (min_length) using padding.

Attributes:
   min_value (int): The lowest allowed value.
   max_value (int): The highest allowed value.
   min_length (int): Minimum number of digits for display padding (e.g., 5 -> '05').
   max_length (int): Maximum number of digits allowed.
   
Internal Attributes:
   _value (int): The current selected value.
   _font (pygame.font.Font): Cached font object used for rendering the number.
   _up_rect (pygame.Rect): Rectangular area for the increment button (relative position).
   _down_rect (pygame.Rect): Rectangular area for the decrement button (relative position).
   _is_up_pressed (bool): True if the increment button is currently pressed.
   _is_down_pressed (bool): True if the decrement button is currently pressed.
   _last_mouse_pos_rel (Tuple[int, int]): Last mouse position relative to the element (for state update).

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, min_value: int, max_value: int, value: int, min_length: int = 1, max_length: int = 10, step: int = 1, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize the NumberSelector element.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Width of the number selector.
   height (int): Height of the number selector.
   min_value (int): Minimum selectable value.
   max_value (int): Maximum selectable value.
   value (int): Initial value for the number selector.
   min_length (int): Minimum number of digits for display padding (defaults to 1).
   max_length (int): Maximum number of digits allowed (defaults to 10).
   step (int): Increment/decrement step size (defaults to 1).
   root_point (Tuple[float, float]): Anchor point for positioning.
   theme (ThemeType): Theme to use for styling.
   element_id (Optional[str]): Custom element ID.
def value(self: Any) -> int
Get the current selected value.

Returns:
   int: The current numeric value.
def get_value(self: Any) -> int
No documentation
def value(self: Any, new_value: int) -> Any
Set the value, ensuring it stays within min/max bounds.

Args:
   new_value (int): The new value to set.
def _format_value(self: Any) -> str
Formats the current value with padding based on min_length.

Returns:
   str: The formatted string representation of the value (e.g., '007').
def increment(self: Any) -> Any
Increments the value, respecting max_value.
def decrement(self: Any) -> Any
Decrements the value, respecting min_value.
def _setup_control_areas(self: Any) -> Any
Defines the rectangular areas for the increment (up) and decrement (down) buttons.
These are relative to the element's top-left corner (0, 0).
def _get_button_colors(self: Any, theme: Any) -> Any
Determines the colors for the buttons based on the current state and theme.

Args:
   theme: The current theme object from ThemeManager.
   
Returns:
   Tuple: (up_color, down_color, text_color, border_color, background_color)
def update(self: Any, dt: Any, inputState: Any) -> Any
No documentation
def render(self: Any, renderer: Any) -> Any
Render the NumberSelector using OpenGL backend.

Args:
   renderer: The OpenGL renderer object.

class Checkbox

Description

A binary state control element that allows a user to select a boolean value (checked or unchecked).

The Checkbox is typically rendered as a small square box that can be toggled by clicking.

Attributes:
   checked (bool): The current state of the checkbox (True if checked, False otherwise).
   label (Optional[str]): The text label to display next to the checkbox.
   label_position (str): Position of the label relative to the box ('right' or 'left').
   box_size (int): The size (width and height) of the square checkbox box.
   
Internal Attributes:
   _font (pygame.font.Font): Cached font object for rendering the label.

Attributes
on_toggle: Callable[[bool], None] = None
Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, checked: bool, label: Optional[str] = None, label_position: str = 'right', root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize the Checkbox element.

The width and height define the overall bounding box, including the label.
The actual checkbox box size is calculated based on the height.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Total width of the element (box + label).
   height (int): Total height of the element (usually the box size).
   checked (bool): Initial state of the checkbox.
   theme_type (ThemeType): Theme type for styling.
   label (Optional[str]): Text label displayed next to the box.
   label_position (str): Where to place the label ('right' or 'left').
   root_point (Tuple[float, float]): Anchor point for positioning.
   element_id (Optional[str]): Custom element ID.
def set_on_toggle(self: Any, callback: Callable[[bool], None]) -> Any
No documentation
def get_state(self: Any) -> bool
No documentation
def value(self: Any) -> bool
No documentation
def _get_colors(self: Any) -> Tuple[Tuple[int, int, int], Tuple[int, int, int], Tuple[int, int, int], Tuple[int, int, int]]
Determines the colors for the checkbox based on the current state and theme.

Args:
   theme: The current theme object from ThemeManager.
   
Returns:
   Tuple: (box_color, check_color, border_color, label_color)
def toggle(self: Any) -> Any
Toggles the state of the checkbox (True -> False, False -> True).
def update(self: Any, dt: Any, inputState: Any) -> Any
No documentation
def render(self: Any, renderer: Any) -> Any
Render the Checkbox and its label using OpenGL backend.

Args:
   renderer: The OpenGL renderer object.

class ScrollingFrame

Description

A frame container with scrollable content.

Supports both horizontal and vertical scrolling with scrollbars.
Automatically handles clipping of child elements to visible area.

Attributes:
   content_width (int): Total width of scrollable content area.
   content_height (int): Total height of scrollable content area.
   scroll_x (int): Current horizontal scroll position.
   scroll_y (int): Current vertical scroll position.
   scrollbar_size (int): Width/height of scrollbars.
   dragging_vertical (bool): Whether vertical scrollbar is being dragged.
   dragging_horizontal (bool): Whether horizontal scrollbar is being dragged.

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, content_width: int, content_height: int, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a scrolling frame.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Visible width of the frame.
   height (int): Visible height of the frame.
   content_width (int): Total width of scrollable content.
   content_height (int): Total height of scrollable content.
   root_point (Tuple[float, float]): Anchor point for positioning.
   theme (ThemeType): Theme to use for styling.
   element_id (Optional[str]): Custom element ID.
def set_background_color(self: Any, color: Tuple[int, int, int]) -> Any
Set background color for the scrolling frame.

Args:
   color (Tuple[int, int, int]): RGB color tuple.
def update_theme(self: Any, theme_type: Any) -> Any
Update theme for scrolling frame.

Args:
   theme_type (ThemeType): New theme to apply.
def clear_children(self: Any) -> Any
Remove all child elements from the scrolling frame.
def get_mouse_position(self: Any, input_state: Any) -> Tuple[int, int]
Get mouse position adjusted for scrolling.

Args:
   input_state (InputState): Current input state
   
Returns:
   Tuple[int, int]: Mouse position adjusted for scroll offset
def mouse_over(self: Any, input_state: InputState) -> bool
Check if mouse is over the scrolling frame (not adjusted for scroll).

Args:
   input_state (InputState): Current input state
   
Returns:
   bool: True if mouse is over the frame's visible area
def update(self: Any, dt: Any, inputState: Any) -> Any
Update scrolling frame state and handle user interaction.

Args:
   dt (float): Delta time in seconds.
   inputState (InputState): Current input state.
def on_scroll(self: Any, event: pygame.event.Event) -> Any
Handle mouse wheel scrolling.

Args:
   scroll_y (int): Scroll amount (positive for up, negative for down).
def render(self: Any, renderer: Any) -> Any
Render scrolling frame and its content.

Args:
   renderer (Renderer): Renderer object for drawing.
def _get_vertical_scrollbar_rect(self: Any, x: int, y: int) -> Tuple[int, int, int, int]
Get the vertical scrollbar rectangle.

Args:
   x (int): X position of frame.
   y (int): Y position of frame.
   
Returns:
   Tuple[int, int, int, int]: (x, y, width, height) of scrollbar thumb.
def _get_horizontal_scrollbar_rect(self: Any, x: int, y: int) -> Tuple[int, int, int, int]
Get the horizontal scrollbar rectangle.

Args:
   x (int): X position of frame.
   y (int): Y position of frame.
   
Returns:
   Tuple[int, int, int, int]: (x, y, width, height) of scrollbar thumb.
def _draw_horizontal_scrollbar(self: Any, renderer: Any, x: int, y: int, theme: Any) -> Any
Draw horizontal scrollbar.

Args:
   renderer (Renderer): Renderer object.
   x (int): X position of frame.
   y (int): Y position of frame.
   theme: Current theme.
def _draw_vertical_scrollbar(self: Any, renderer: Any, x: int, y: int, theme: Any) -> Any
Draw vertical scrollbar.

Args:
   renderer (Renderer): Renderer object.
   x (int): X position of frame.
   y (int): Y position of frame.
   theme: Current theme.

class Tabination

Description

A tabbed interface element that organizes content into multiple tabs.

Displays clickable tabs at the top with their content below.
Supports alternating background colors for tabs and theme-based styling.

Attributes:
   tabs (List[Dict]): List of tab information dictionaries.
   current_tab (int): Index of currently active tab.
   tab_height (int): Height of the tab headers.
   font_size (int): Font size for tab titles.
   font_name (str): Font name for tab titles.
   tab_padding (int): Padding inside tabs.

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, font_size: int = 20, font_name: Optional[str] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a Tabination element.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Width of the tabination element.
   height (int): Height of the tabination element.
   font_size (int): Font size for tab titles.
   font_name (Optional[str]): Font name for tab titles.
   root_point (Tuple[float, float]): Anchor point for positioning.
   theme (ThemeType): Theme to use for styling.
   element_id (Optional[str]): Custom element ID.
def _calculate_tab_colors(self: Any) -> Any
Calculate alternating background colors for tabs based on theme.
def font(self: Any) -> Any
Get the font object with lazy loading.
def update_theme(self: Any, theme_type: ThemeType) -> Any
Update theme for tabination and recalculate tab colors.

Args:
   theme_type (ThemeType): The new theme to apply.
def add_tab(self: Any, tab_name: str) -> bool
Add a new tab to the tabination.

Args:
   tab_name (str): Name/title of the new tab.
   
Returns:
   bool: True if tab was added successfully, False if tab already exists.
def add_to_tab(self: Any, tab_name: str, ui_element: UIElement) -> bool
Add a UI element to a specific tab.

Args:
   tab_name (str): Name of the tab to add element to.
   ui_element (UIElement): The UI element to add.
   
Returns:
   bool: True if element was added successfully, False if tab doesn't exist.
def switch_tab(self: Any, tab_index: int) -> bool
Switch to a different tab by index.

Args:
   tab_index (int): Index of tab to switch to.
   
Returns:
   bool: True if switched successfully, False if index is invalid.
def get_tab_index(self: Any, tab_name: str) -> int
Get the index of a tab by name.

Args:
   tab_name (str): Name of the tab.
   
Returns:
   int: Index of the tab, or -1 if not found.
def remove_tab(self: Any, tab_name: str) -> bool
Remove a tab and all its contents.

Args:
   tab_name (str): Name of the tab to remove.
   
Returns:
   bool: True if tab was removed, False if tab doesn't exist.
def get_tab(self: Any, tab_name: str) -> Optional[Dict[str, Any]]
Get information about a tab by name.

Args:
   tab_name (str): Name of the tab.
   
Returns:
   Optional[Dict[str, Any]]: Tab information dictionary, or None if tab doesn't exist.
def get_tab_frame(self: Any, tab_name: str) -> Optional[UiFrame]
Get the frame associated with a tab.

Args:
   tab_name (str): Name of the tab.
   
Returns:
   Optional[UiFrame]: The tab's frame, or None if tab doesn't exist.
def _get_tab_colors(self: Any, tab_index: int, is_active: bool, is_hovered: bool) -> Tuple[Tuple[int, int, int], Tuple[int, int, int]]
Get colors for a tab based on its state.

Args:
   tab_index (int): Index of the tab.
   is_active (bool): Whether tab is currently active.
   is_hovered (bool): Whether tab is being hovered.
   
Returns:
   Tuple[Tuple[int, int, int], Tuple[int, int, int]]: (bg_color, text_color)
def _get_tab_rect(self: Any, tab_index: int, actual_x: int, actual_y: int) -> Tuple[int, int, int, int]
Calculate the rectangle for a tab header.

Args:
   tab_index (int): Index of the tab.
   actual_x (int): Actual X position of tabination.
   actual_y (int): Actual Y position of tabination.
   
Returns:
   Tuple[int, int, int, int]: (x, y, width, height) of tab rectangle.
def update(self: Any, dt: Any, inputState: Any) -> Any
Update tabination state and handle tab clicks.

Args:
   dt (float): Delta time in seconds.
   inputState (InputState): Current input state.
def render(self: Any, renderer: OpenGLRenderer) -> Any
Render the tabination element with tabs and active content.

Args:
   renderer (Renderer): Renderer object for drawing.

class Clock

Description

A clock UI element that can display both analog and digital time.

Supports both 12-hour and 24-hour formats, real-time or custom time,
and various customization options.

Attributes:
   diameter (int): Diameter of the analog clock face.
   use_real_time (bool): Whether to use the system's real time.
   show_numbers (bool): Whether to show numbers on the analog clock.
   time_style (str): '12hr' or '24hr' format.
   mode (str): 'analog', 'digital', or 'both'.
   custom_time (datetime): Custom time to display (if not using real time).

Methods
def __init__(self: Any, x: int, y: int, diameter: int = 100, font_name: Optional[str] = None, font_size: int = 16, use_real_time: bool = True, show_numbers: bool = True, time_style: Literal['12hr', '24hr'] = '24hr', mode: Literal['analog', 'digital', 'both'] = 'analog', root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a Clock element.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   diameter (int): Diameter of the analog clock face.
   font_name (Optional[str]): Font for digital display and numbers.
   font_size (int): Font size for digital display.
   use_real_time (bool): Whether to use system time.
   show_numbers (bool): Whether to show numbers on analog clock.
   time_style (str): '12hr' or '24hr' format.
   mode (str): 'analog', 'digital', or 'both'.
   root_point (Tuple[float, float]): Anchor point for positioning.
   theme (ThemeType): Theme for styling.
   element_id (Optional[str]): Custom element ID.
def font(self: Any) -> Any
Get the main font object.
def small_font(self: Any) -> Any
Get the smaller font for analog clock numbers.
def update_theme(self: Any, theme_type: ThemeType) -> Any
Update theme colors for the clock.
def set_face_color(self: Any, color: Tuple[int, int, int]) -> Any
Set the clock face color.
def set_border_color(self: Any, color: Tuple[int, int, int]) -> Any
Set the clock border color.
def set_hand_colors(self: Any, hour: Tuple[int, int, int], minute: Tuple[int, int, int], second: Tuple[int, int, int]) -> Any
Set the colors for clock hands.
def set_number_color(self: Any, color: Tuple[int, int, int]) -> Any
Set the color for analog clock numbers.
def set_digital_text_color(self: Any, color: Tuple[int, int, int]) -> Any
Set the color for digital display text.
def set_time(self: Any, time_struct: time.struct_time) -> Any
Set a custom time for the clock.

Args:
   time_struct (time.struct_time): Time structure from time.localtime()
def set_time_from_string(self: Any, time_str: str, format_str: str = '%H:%M:%S') -> Any
Set time from a string.

Args:
   time_str (str): Time string.
   format_str (str): Format string for parsing.
def get_time_string(self: Any) -> str
Get the current time as a formatted string.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update the clock time.
def render(self: Any, renderer: Renderer) -> Any
Render the clock.
def _render_analog_clock(self: Any, renderer: Renderer, x: int, y: int) -> Any
Render the analog clock face and hands.
def _draw_clock_numbers(self: Any, renderer: Renderer, center_x: int, center_y: int, radius: int) -> Any
Draw numbers around the clock face.
def _draw_tick_marks(self: Any, renderer: Renderer, center_x: int, center_y: int, radius: int) -> Any
Draw tick marks for minutes/seconds.
def _draw_hand(self: Any, renderer: Renderer, center_x: int, center_y: int, angle: float, length: float, width: int, color: Tuple[int, int, int]) -> Any
Draw a clock hand.
def _render_digital_clock(self: Any, renderer: Renderer, x: int, y: int) -> Any
Render the digital clock display.

class AudioVisualizer

Description

Real-time audio visualization element that displays audio data in various styles.

Supports multiple visualization modes and can connect to OpenAL audio sources.

Attributes:
   style (str): Visualization style ('bars', 'waveform', 'circle', 'particles', 'spectrum')
   source: OpenAL audio source to visualize
   color_gradient (List[Tuple[int, int, int]]): Colors for gradient visualization
   bar_width (int): Width of bars in bar mode
   bar_spacing (int): Spacing between bars
   sensitivity (float): Audio sensitivity/amplification
   smoothing (float): Smoothing factor for transitions

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, style: Literal['bars', 'waveform', 'circle', 'particles', 'spectrum'] = 'bars', source: Any = None, color_gradient: Optional[List[Tuple[int, int, int]]] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize an audio visualizer.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Width of visualizer.
   height (int): Height of visualizer.
   style (str): Visualization style.
   source: OpenAL audio source or pygame Sound object.
   color_gradient (Optional[List[Tuple[int, int, int]]]): Color gradient for visualization.
   root_point (Tuple[float, float]): Anchor point for positioning.
   theme (ThemeType): Theme for styling.
   element_id (Optional[str]): Custom element ID.
def _initialize_audio_data(self: Any) -> Any
Initialize audio data buffers.
def _generate_gradient_surface(self: Any) -> Any
Generate a gradient surface for fast color lookups.
def _interpolate_gradient(self: Any, ratio: float) -> Tuple[int, int, int]
Interpolate color from gradient.

Args:
   ratio (float): Position in gradient (0-1).
   
Returns:
   Tuple[int, int, int]: Interpolated color.
def set_style(self: Any, style: str) -> Any
Change visualization style.

Args:
   style (str): New style ('bars', 'waveform', 'circle', 'particles', 'spectrum').
def set_source(self: Any, source: Any) -> Any
Set audio source for visualization.

Args:
   source: OpenAL audio source or pygame Sound object.
def set_color_gradient(self: Any, gradient: List[Tuple[int, int, int]]) -> Any
Set color gradient for visualization.

Args:
   gradient (List[Tuple[int, int, int]]): List of RGB colors.
def set_sensitivity(self: Any, sensitivity: float) -> Any
Set audio sensitivity/amplification.

Args:
   sensitivity (float): Sensitivity factor (0.1-5.0).
def set_smoothing(self: Any, smoothing: float) -> Any
Set smoothing factor for transitions.

Args:
   smoothing (float): Smoothing factor (0.0-1.0).
def _get_audio_data(self: Any) -> List[float]
Get audio data from source.

Returns:
   List[float]: Audio data samples.
def _process_audio_data(self: Any, raw_data: List[float]) -> Any
Process audio data with smoothing and peak detection.

Args:
   raw_data (List[float]): Raw audio data.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update audio visualizer.

Args:
   dt (float): Delta time in seconds.
   inputState (InputState): Current input state.
def render(self: Any, renderer: Renderer) -> Any
Render audio visualizer.

Args:
   renderer (Renderer): Renderer object.
def _render_bars(self: Any, renderer: Renderer, x: int, y: int) -> Any
Render bar visualization.

Args:
   renderer (Renderer): Renderer object.
   x (int): X position.
   y (int): Y position.
def _render_waveform(self: Any, renderer: Renderer, x: int, y: int) -> Any
Render waveform visualization.

Args:
   renderer (Renderer): Renderer object.
   x (int): X position.
   y (int): Y position.
def _render_circle(self: Any, renderer: Renderer, x: int, y: int) -> Any
Render circular visualization.

Args:
   renderer (Renderer): Renderer object.
   x (int): X position.
   y (int): Y position.
def _render_particles(self: Any, renderer: Renderer, x: int, y: int) -> Any
Render particle visualization.

Args:
   renderer (Renderer): Renderer object.
   x (int): X position.
   y (int): Y position.
def _render_spectrum(self: Any, renderer: Renderer, x: int, y: int) -> Any
Render frequency spectrum visualization.

Args:
   renderer (Renderer): Renderer object.
   x (int): X position.
   y (int): Y position.
def _get_bar_color(self: Any, value: float) -> Tuple[int, int, int]
Get color for bar based on value.

Args:
   value (float): Bar value (0-1).
   
Returns:
   Tuple[int, int, int]: RGB color.
def _get_waveform_color(self: Any, position: float) -> Tuple[int, int, int]
Get color for waveform segment.

Args:
   position (float): Position along waveform (0-1).
   
Returns:
   Tuple[int, int, int]: RGB color.
def _get_circle_color(self: Any, position: float) -> Tuple[int, int, int]
Get color for circle segment.

Args:
   position (float): Position around circle (0-1).
   
Returns:
   Tuple[int, int, int]: RGB color.
def _get_particle_color(self: Any, value: float, index: int) -> Tuple[int, int, int]
Get color for particle.

Args:
   value (float): Particle value.
   index (int): Particle index.
   
Returns:
   Tuple[int, int, int]: RGB color.
def _get_spectrum_color(self: Any, frequency: float) -> Tuple[int, int, int]
Get color for spectrum segment.

Args:
   frequency (float): Frequency position (0-1).
   
Returns:
   Tuple[int, int, int]: RGB color.

class Pagination

Description

Pagination control for navigating through multiple pages of content.

Displays page numbers and navigation buttons to switch between pages.
Supports custom button styles and ellipsis for large page ranges.

Attributes:
   total_pages (int): Total number of pages.
   current_page (int): Currently selected page (1-indexed).
   max_visible_pages (int): Maximum number of page buttons to show.
   show_prev_next (bool): Whether to show previous/next buttons.
   show_first_last (bool): Whether to show first/last page buttons.
   button_style (str): Style for page buttons ('numbers', 'dots', 'compact').

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, total_pages: int = 1, current_page: int = 1, max_visible_pages: int = 7, show_prev_next: bool = True, show_first_last: bool = True, button_style: Literal['numbers', 'dots', 'compact'] = 'numbers', root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a Pagination element.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Width of pagination control.
   height (int): Height of pagination control.
   total_pages (int): Total number of pages.
   current_page (int): Starting page (1-indexed).
   max_visible_pages (int): Max page buttons to display.
   show_prev_next (bool): Show previous/next buttons.
   show_first_last (bool): Show first/last page buttons.
   button_style (str): Style of page buttons.
   root_point (Tuple[float, float]): Anchor point for positioning.
   theme (ThemeType): Theme for styling.
   element_id (Optional[str]): Custom element ID.
def set_page(self: Any, page: int) -> Any
Set the current page.

Args:
   page (int): New page number (1-indexed).
def set_total_pages(self: Any, total_pages: int) -> Any
Set the total number of pages.

Args:
   total_pages (int): New total pages.
def set_current_page(self: Any, page: int) -> Any
Set the current page.

Args:
   page (int): New page number (1-indexed).
def next_page(self: Any) -> Any
Go to the next page.
def previous_page(self: Any) -> Any
Go to the previous page.
def first_page(self: Any) -> Any
Go to the first page.
def last_page(self: Any) -> Any
Go to the last page.
def set_on_page_change(self: Any, callback: Callable[[int, int], None]) -> Any
Set callback for page changes.

Args:
   callback (Callable): Function called when page changes.
def _trigger_page_change(self: Any, old_page: int) -> Any
Trigger page change callback.
def _calculate_visible_pages(self: Any) -> List[int]
Calculate which page numbers to display.

Returns:
   List[int]: List of page numbers to show.
def _create_buttons(self: Any) -> Any
Create or update page navigation buttons.
def _update_button_states(self: Any) -> Any
Update enabled/disabled states of navigation buttons.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update pagination state.
def render(self: Any, renderer: Renderer) -> Any
Render pagination.

class TextArea

Description

Multi-line text input area with word wrapping and scrollbars.

Supports text editing, selection, copy/paste, and line numbers.

Attributes:
   text (str): The text content.
   line_numbers (bool): Whether to show line numbers.
   word_wrap (bool): Whether to wrap long lines.
   read_only (bool): Whether text is read-only.
   tab_size (int): Number of spaces for tab character.

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, text: str = '', font_size: int = 16, font_name: Optional[str] = None, line_numbers: bool = True, word_wrap: bool = True, read_only: bool = False, tab_size: int = 4, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a TextArea element.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Width of text area.
   height (int): Height of text area.
   text (str): Initial text content.
   font_size (int): Font size for text.
   font_name (Optional[str]): Font name.
   line_numbers (bool): Show line numbers.
   word_wrap (bool): Enable word wrapping.
   read_only (bool): Make text read-only.
   tab_size (int): Spaces per tab.
   root_point (Tuple[float, float]): Anchor point.
   theme (ThemeType): Theme for styling.
   element_id (Optional[str]): Custom element ID.
def font(self: Any) -> Any
Get font with lazy loading.
def get_text(self: Any) -> str
Get the text content.
def set_text(self: Any, text: str) -> Any
Set the text content.
def _update_dimensions(self: Any) -> Any
Update text area dimensions based on settings.
def _update_text_buffer(self: Any) -> Any
Update text buffer when text changes.
def _save_to_undo_stack(self: Any) -> Any
Save current state to undo stack.
def undo(self: Any) -> Any
Undo the last change.
def redo(self: Any) -> Any
Redo the last undone change.
def _get_visible_lines(self: Any) -> List[int]
Get list of line indices visible in current view.
def _get_cursor_screen_pos(self: Any) -> Tuple[int, int]
Get cursor position in screen coordinates.
def _scroll_to_cursor(self: Any) -> Any
Scroll to ensure cursor is visible.
def _insert_text(self: Any, text: str) -> Any
Insert text at cursor position.
def _delete_selection(self: Any) -> Any
Delete currently selected text.
def _get_selection_text(self: Any) -> str
Get text from current selection.
def copy(self: Any) -> Any
Copy selected text to clipboard.
def cut(self: Any) -> Any
Cut selected text to clipboard.
def paste(self: Any) -> Any
Paste text from clipboard.
def select_all(self: Any) -> Any
Select all text.
def _move_cursor(self: Any, line_delta: int, column_delta: int, extend_selection: bool = False) -> Any
Move cursor position.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update text area state.
def on_key_down(self: Any, event: pygame.event.Event) -> Any
Handle key down events for text editing.

Args:
   event (pygame.event.Event): Key down event.
def on_key_up(self: Any, event: pygame.event.Event) -> Any
Handle key up events for text input.

Args:
   event (pygame.event.Event): Key up event.
def _get_cursor_from_mouse(self: Any, mouse_pos: Tuple[int, int]) -> Tuple[int, int]
Get cursor position from mouse coordinates.
def handle_key_event(self: Any, event: Any) -> Any
Handle keyboard event.
def render(self: Any, renderer: Renderer) -> Any
Render text area.
def _draw_selection_highlight(self: Any, renderer: Renderer, actual_x: int, actual_y: int, line_num: int, line_y: int) -> Any
Draw selection highlight for a line.
def _calculate_text_width(self: Any, text: str) -> int
Calculate pixel width of text (with tab support).

class FileFinder

Description

File selection element with text field and browse button.

Displays selected file path and allows browsing filesystem via dialog.
Supports file filtering and custom icons.

Attributes:
   file_path (str): Currently selected file path.
   file_filter (List[str]): List of file extensions to filter.
   dialog_title (str): Title for file dialog.
   button_text (str): Text for browse button.
   show_icon (bool): Whether to show file icon.

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, file_path: str = '', file_filter: Optional[List[str]] = None, dialog_title: str = 'Select File', button_text: str = 'Browse...', show_icon: bool = True, icon_path: Optional[str] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a FileFinder element.

Args:
   x (int): X coordinate position.
   y (int): Y coordinate position.
   width (int): Width of element.
   height (int): Height of element.
   file_path (str): Initial file path.
   file_filter (Optional[List[str]]): File extension filters (e.g., ['.txt', '.py']).
   dialog_title (str): Title for file dialog.
   button_text (str): Text for browse button.
   show_icon (bool): Show file icon.
   icon_path (Optional[str]): Custom icon path.
   root_point (Tuple[float, float]): Anchor point.
   theme (ThemeType): Theme for styling.
   element_id (Optional[str]): Custom element ID.
def _check_tkinter(self: Any) -> bool
Check if tkinter is available.
def _create_child_elements(self: Any) -> Any
Create child UI elements.
def _get_default_icon(self: Any) -> pygame.Surface
Create default file icon.
def set_file_path(self: Any, path: str) -> Any
Set the file path programmatically.

Args:
   path (str): New file path.
def _update_icon(self: Any) -> Any
Update icon based on current file type.
def _open_file_dialog(self: Any) -> Any
Open file selection dialog.
def _open_tkinter_dialog(self: Any) -> Any
Open tkinter file dialog.
def _open_simple_dialog(self: Any) -> Any
Open simple pygame-based file dialog.
def _get_initial_directory(self: Any) -> Optional[str]
Get initial directory for file dialog.
def set_on_file_selected(self: Any, callback: Callable[[str], None]) -> Any
Set callback for when file is selected.

Args:
   callback (Callable): Function called with selected file path.
def get_file_path(self: Any) -> str
Get current file path.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update file finder state.
def render(self: Any, renderer: Renderer) -> Any
Render file finder.

class ChartVisualizer

Description

A versatile data visualization component that can display various chart types:
bar charts (vertical/horizontal), pie charts, line charts, and scatter plots.

Supports animated transitions when data changes, automatic normalization,
legends, titles, and customizable colors. Designed to work with any renderer
that provides basic drawing primitives.

Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, data: Optional[List[float]] = None, labels: Optional[List[str]] = None, colors: Optional[List[Tuple[int, int, int]]] = None, chart_type: Literal['bar', 'pie', 'line', 'scatter'] = 'bar', orientation: Literal['vertical', 'horizontal'] = 'vertical', title: str = '', show_labels: bool = True, show_legend: bool = False, min_value: Optional[float] = None, max_value: Optional[float] = None, root_point: Tuple[float, float] = (0, 0), theme: ThemeType = None, element_id: Optional[str] = None) -> Any
Initialize a ChartVisualizer.

Args:
   x (int): X coordinate.
   y (int): Y coordinate.
   width (int): Width of the element.
   height (int): Height of the element.
   data (Optional[List[float]]): Numeric data to plot.
   labels (Optional[List[str]]): Labels for each data point/slice.
   colors (Optional[List[Tuple[int,int,int]]]): RGB colors per data point.
   chart_type (str): 'bar', 'pie', 'line', or 'scatter'.
   orientation (str): For bar charts: 'vertical' or 'horizontal'.
   title (str): Chart title displayed at the top.
   show_labels (bool): Whether to draw data labels.
   show_legend (bool): Whether to draw a legend at the bottom.
   min_value (Optional[float]): Override minimum Y value (for non-pie charts).
   max_value (Optional[float]): Override maximum Y value.
   root_point (Tuple[float,float]): Anchor point.
   theme (ThemeType): Theme to apply.
   element_id (Optional[str]): Unique element ID.
def _default_colors(self: Any) -> List[Tuple[int, int, int]]
Return a default color palette for charts.
def title_font(self: Any) -> Any
No documentation
def label_font(self: Any) -> Any
No documentation
def legend_font(self: Any) -> Any
No documentation
def set_data(self: Any, data: List[float], labels: Optional[List[str]] = None, animate: bool = False, duration: float = 0.5) -> Any
Update the chart's data, optionally with a smooth transition.

Args:
   data (List[float]): New data values.
   labels (Optional[List[str]]): New labels (if None, existing labels are kept).
   animate (bool): If True, transitions over 'duration' seconds.
   duration (float): Duration of animation in seconds.
def update(self: Any, dt: float, inputState: InputState) -> Any
Update animations and recalculate if needed.
def _recalc(self: Any) -> Any
Recalculate internal data (normalized values, angles) for rendering.
def _get_color(self: Any, index: int) -> Tuple[int, int, int]
Return the color for a given data index, cycling if necessary.
def render(self: Any, renderer: Renderer) -> Any
Main render entry point – draws background, title, chart, and legend.
def _render_bar(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
Draw a bar chart (vertical or horizontal) with labels.
def _render_pie(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
Draw a pie chart with optional labels.
def _render_line(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
Draw a line chart with data points and labels.
def _render_scatter(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
Draw a scatter plot (points only) with optional labels.
def _render_legend(self: Any, renderer: Any, x: Any, y: Any, theme: Any) -> Any
Draw a simple color‑coded legend at the bottom.
Back to Ui Module