misc.py

No documentation

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
_properties: Dict[str, Dict[str, Any]] = {**UIElement._properties, 'file_path': {'name': 'file path', 'key': 'file_path', 'type': str, 'editable': True, 'description': 'Currently selected file path.'}, 'file_filter': {'name': 'file filter', 'key': 'file_filter', 'type': List[str], 'editable': False, 'description': 'List of extensions to filter (e.g., [".png", ".jpg"]).'}, 'dialog_title': {'name': 'dialog title', 'key': 'dialog_title', 'type': str, 'editable': True, 'description': 'Title of the file dialog window.'}, 'button_text': {'name': 'button text', 'key': 'button_text', 'type': str, 'editable': True, 'description': 'Text on the browse button.'}, 'show_icon': {'name': 'show icon', 'key': 'show_icon', 'type': bool, 'editable': True, 'description': 'Whether to display a 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, pivot: Tuple[float, float] = (0, 0), theme: Optional[ThemeType] = None, element_id: Optional[str] = None) -> None
Initialize a file finder widget.

Args:
   x, y: Position (before anchor).
   width, height: Dimensions.
   file_path: Initial file path.
   file_filter: List of allowed extensions (e.g., [".txt", ".png"]).
   dialog_title: Title of the file dialog.
   button_text: Text on the browse button.
   show_icon: Display a file icon.
   icon_path: Path to a custom icon image.
   pivot: Anchor point.
   theme: Theme to apply.
   element_id: Custom ID.
def _get_init_args(self: Any) -> Dict[str, Any]
No documentation
def _check_tkinter(self: Any) -> bool
No documentation
def _create_child_elements(self: Any) -> None
No documentation
def _get_default_icon(self: Any) -> pygame.Surface
No documentation
def set_file_path(self: Any, path: str) -> None
Set the current file path and update the text box.
def _update_icon(self: Any) -> None
No documentation
def _open_file_dialog(self: Any) -> None
No documentation
def _open_tkinter_dialog(self: Any) -> None
No documentation
def _open_simple_dialog(self: Any) -> None
No documentation
def _get_initial_directory(self: Any) -> Optional[str]
No documentation
def set_on_file_selected(self: Any, callback: Callable[[str], None]) -> None
Register a callback for when a file is selected.
def get_file_path(self: Any) -> str
Return the current file path.
def update(self: Any, dt: float, inputState: InputState) -> None
No documentation
def render(self: Any, renderer: OpenGLRenderer) -> None
No documentation

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
_properties: Dict[str, Dict[str, Any]] = {**UIElement._properties, 'diameter': {'name': 'diameter', 'key': 'diameter', 'type': int, 'editable': True, 'description': 'Diameter of the analog clock face in pixels.'}, 'use_real_time': {'name': 'use real time', 'key': 'use_real_time', 'type': bool, 'editable': True, 'description': 'If True, uses system time. If False, use custom time set via set_time().'}, 'show_numbers': {'name': 'show numbers', 'key': 'show_numbers', 'type': bool, 'editable': True, 'description': 'Whether to show hour numbers on the analog clock face.'}, 'time_style': {'name': 'time style', 'key': 'time_style', 'type': str, 'editable': True, 'description': 'Format: "12hr" or "24hr".', 'options': ['12hr', '24hr']}, 'mode': {'name': 'mode', 'key': 'mode', 'type': str, 'editable': True, 'description': 'Display mode: "analog", "digital", or "both".', 'options': ['analog', 'digital', 'both']}, 'font_size': {'name': 'font size', 'key': 'font_size', 'type': int, 'editable': True, 'description': 'Font size for digital display and numbers.'}}
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', pivot: Tuple[float, float] = (0, 0), theme: Optional[ThemeType] = None, element_id: Optional[str] = None) -> None
Initialize a Clock element.

Args:
   x: X coordinate (before anchor).
   y: Y coordinate (before anchor).
   diameter: Diameter of the analog clock face.
   font_name: Path to a custom font file.
   font_size: Font size for digital display.
   use_real_time: Whether to use system time.
   show_numbers: Whether to show numbers on analog clock.
   time_style: '12hr' or '24hr' format.
   mode: 'analog', 'digital', or 'both'.
   pivot: Anchor point.
   theme: Theme to apply.
   element_id: Optional custom ID.
def _get_init_args(self: Any) -> Dict[str, Any]
Return constructor arguments for restarting.
def font(self: Any) -> pygame.font.Font
Get the main font object (digital display).
def small_font(self: Any) -> pygame.font.Font
Get the smaller font for analog clock numbers.
def update_theme(self: Any, theme_type: ThemeType) -> None
Update theme colors for the clock.
def set_face_color(self: Any, color: Tuple[int, int, int]) -> None
Set the clock face color (RGB).
def set_border_color(self: Any, color: Tuple[int, int, int]) -> None
Set the clock border color (RGB).
def set_hand_colors(self: Any, hour: Tuple[int, int, int], minute: Tuple[int, int, int], second: Tuple[int, int, int]) -> None
Set the colors for clock hands (hour, minute, second) as RGB tuples.
def set_number_color(self: Any, color: Tuple[int, int, int]) -> None
Set the color for analog clock numbers (RGB).
def set_digital_text_color(self: Any, color: Tuple[int, int, int]) -> None
Set the color for digital display text (RGB).
def set_time(self: Any, time_struct: time.struct_time) -> None
Set a custom time for the clock.

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

Args:
   time_str: Time string (e.g., "14:30:00").
   format_str: Format string for parsing (default "%H:%M:%S").
def get_time_string(self: Any) -> str
Get the current time as a formatted string according to time_style.
def update(self: Any, dt: float, inputState: InputState) -> None
Update the clock time.
def render(self: Any, renderer: OpenGLRenderer) -> None
Render the clock.
def _render_analog_clock(self: Any, renderer: OpenGLRenderer, x: int, y: int) -> None
Render the analog clock face and hands.
def _draw_clock_numbers(self: Any, renderer: OpenGLRenderer, center_x: int, center_y: int, radius: int) -> None
Draw numbers 1-12 around the clock face.
def _draw_tick_marks(self: Any, renderer: OpenGLRenderer, center_x: int, center_y: int, radius: int) -> None
Draw tick marks for minutes/seconds.
def _draw_hand(self: Any, renderer: OpenGLRenderer, center_x: int, center_y: int, angle: float, length: float, width: int, color: Tuple[int, int, int]) -> None
Draw a single clock hand.
def _render_digital_clock(self: Any, renderer: OpenGLRenderer, x: int, y: int) -> None
Render the digital clock display.

class ProgressBar

Description

A progress bar widget that displays a value as a filled bar.
Supports horizontal/vertical orientation and a 'soundpad' segmented style.

Internal metrics (segment gap, border widths, corner radii, shadow distances)
scale with the current ratio. User-supplied values are respected verbatim.

Attributes
_properties: Dict[str, Dict[str, Any]] = {**UIElement._properties, 'min_val': {'name': 'minimum value', 'key': 'min_val', 'type': float, 'editable': True, 'description': 'Minimum value (0% progress).'}, 'max_val': {'name': 'maximum value', 'key': 'max_val', 'type': float, 'editable': True, 'description': 'Maximum value (100% progress).'}, 'value': {'name': 'current value', 'key': 'value', 'type': float, 'editable': True, 'description': 'Current progress value.'}, 'orientation': {'name': 'orientation', 'key': 'orientation', 'type': str, 'editable': True, 'description': '"horizontal" or "vertical".', 'options': ['horizontal', 'vertical']}, 'style': {'name': 'style', 'key': 'style', 'type': str, 'editable': True, 'description': '"default" or "soundpad".', 'options': ['default', 'soundpad']}, 'draw_value': {'name': 'draw value', 'key': 'draw_value', 'type': bool, 'editable': True, 'description': 'Show percentage text inside the bar.'}}
Methods
def __init__(self: Any, x: int, y: int, width: int, height: int, min_val: float = 0, max_val: float = 100, value: float = 0, pivot: Tuple[float, float] = (0, 0), theme: Optional[ThemeType] = None, orientation: Literal['vertical', 'horizontal'] = 'horizontal', element_id: Optional[str] = None, style: str = 'default', **kwargs: dict) -> None
No documentation
def _sm(self: Any) -> float
No documentation
def segment_gap(self: Any) -> int
No documentation
def segment_gap(self: Any, value: int) -> None
No documentation
def _get_init_args(self: Any) -> Dict[str, Any]
No documentation
def set_background_color(self: Any, color: Tuple[int, int, int]) -> None
No documentation
def set_foreground_color(self: Any, color: Tuple[int, int, int]) -> None
No documentation
def set_font_color(self: Any, color: Tuple[int, int, int]) -> None
No documentation
def set_font(self: Any, font_name: str, font_size: int) -> None
No documentation
def set_border_color(self: Any, color: Tuple[int, int, int]) -> None
No documentation
def update_theme(self: Any, theme_type: ThemeType) -> None
No documentation
def set_value(self: Any, value: float) -> None
No documentation
def set_max_value(self: Any, value: float) -> None
No documentation
def set_min_value(self: Any, value: float) -> None
No documentation
def get_percentage(self: Any) -> float
No documentation
def _get_soundpad_color(self: Any, t: float) -> Tuple[int, int, int]
No documentation
def render(self: Any, renderer: OpenGLRenderer) -> None
No documentation

class ChartVisualizer

Description

A versatile data visualization component: bar, pie, line, scatter, radar charts.
Supports gradients, animations, legend, and per-element shadows.

All hard-coded internal metrics (padding, spacing, line widths, point radii,
font sizes, shadow offsets) scale with the current ratio.

Attributes
_properties: Dict[str, Dict[str, Any]] = {**UIElement._properties, 'chart_type': {'name': 'chart type', 'key': 'chart_type', 'type': str, 'editable': True, 'description': 'Type of chart: bar, pie, line, scatter, radar', 'options': ['bar', 'pie', 'line', 'scatter', 'radar']}, 'title': {'name': 'title', 'key': 'title', 'type': str, 'editable': True, 'description': 'Chart title text.'}, 'show_labels': {'name': 'show labels', 'key': 'show_labels', 'type': bool, 'editable': True, 'description': 'Display data labels.'}, 'show_legend': {'name': 'show legend', 'key': 'show_legend', 'type': bool, 'editable': True, 'description': 'Display color legend.'}, 'use_gradient': {'name': 'use gradient', 'key': 'use_gradient', 'type': bool, 'editable': True, 'description': 'Use color gradient across data points.'}, 'shadow_enabled': {'name': 'shadow enabled', 'key': 'shadow_enabled', 'type': bool, 'editable': True, 'description': 'Enable subtle shadow on chart elements.'}, 'shadow_offset': {'name': 'shadow offset', 'key': 'shadow_offset', 'type': int, 'editable': True, 'description': 'Pixel offset for element shadows.'}, 'shadow_alpha': {'name': 'shadow alpha', 'key': 'shadow_alpha', 'type': float, 'editable': True, 'description': 'Alpha of shadow (0.0–1.0).'}}
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', 'radar'] = '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, radar_max_value: float = 1.0, radar_axis_labels: Optional[List[str]] = None, pivot: Tuple[float, float] = (0, 0), theme: Optional[ThemeType] = None, element_id: Optional[str] = None, **kwargs: dict) -> None
No documentation
def _sm(self: Any) -> float
No documentation
def padding(self: Any) -> int
No documentation
def bar_spacing(self: Any) -> int
No documentation
def line_width(self: Any) -> int
No documentation
def point_radius(self: Any) -> int
No documentation
def shadow_offset(self: Any) -> int
No documentation
def shadow_offset(self: Any, value: int) -> None
No documentation
def _get_init_args(self: Any) -> Dict[str, Any]
No documentation
def _default_colors(self: Any) -> List[Tuple[int, int, int]]
No documentation
def title_font(self: Any) -> pygame.font.Font
No documentation
def label_font(self: Any) -> pygame.font.Font
No documentation
def legend_font(self: Any) -> pygame.font.Font
No documentation
def set_data(self: Any, data: List[float], labels: Optional[List[str]] = None, animate: bool = False, duration: float = 0.5) -> None
No documentation
def _recalc(self: Any) -> None
No documentation
def _get_color(self: Any, index: int) -> Tuple[int, int, int]
No documentation
def _get_point_color(self: Any, index: int, t: Optional[float] = None) -> Tuple[int, int, int]
No documentation
def _shadow_color(self: Any, color: Tuple[int, int, int]) -> Tuple[int, int, int, int]
No documentation
def render(self: Any, renderer: OpenGLRenderer) -> None
No documentation
def _render_bar(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
No documentation
def _render_pie(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
No documentation
def _render_line(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
No documentation
def _render_scatter(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
No documentation
def _render_radar(self: Any, renderer: Any, left: Any, top: Any, width: Any, height: Any, theme: Any) -> Any
No documentation
def _render_legend(self: Any, renderer: Any, x: Any, y: Any, theme: Any) -> Any
No documentation

class AudioVisualizer

Description

Real-time audio visualization element: bars, waveform, circle, particles, spectrum.
Internal spacing and stroke widths scale with the current ratio.

Attributes
_properties: Dict[str, Dict[str, Any]] = {**UIElement._properties, 'style': {'name': 'style', 'key': 'style', 'type': str, 'editable': True, 'description': 'Visualization style: bars, waveform, circle, particles, spectrum', 'options': ['bars', 'waveform', 'circle', 'particles', 'spectrum']}, 'sensitivity': {'name': 'sensitivity', 'key': 'sensitivity', 'type': float, 'editable': True, 'description': 'Audio sensitivity (0.1-5.0).'}, 'smoothing': {'name': 'smoothing', 'key': 'smoothing', 'type': float, 'editable': True, 'description': 'Smoothing factor (0.0-1.0).'}, 'num_bars': {'name': 'number of bars', 'key': 'num_bars', 'type': int, 'editable': True, 'description': 'Number of bars/segments.'}}
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, pivot: Tuple[float, float] = (0, 0), theme: Optional[ThemeType] = None, element_id: Optional[str] = None) -> None
No documentation
def _sm(self: Any) -> float
No documentation
def bar_spacing(self: Any) -> int
No documentation
def circle_thickness(self: Any) -> int
No documentation
def _get_init_args(self: Any) -> Dict[str, Any]
No documentation
def _initialize_audio_data(self: Any) -> None
No documentation
def _generate_gradient_surface(self: Any) -> None
No documentation
def _interpolate_gradient(self: Any, ratio: float) -> Tuple[int, int, int]
No documentation
def set_style(self: Any, style: str) -> None
No documentation
def set_source(self: Any, source: Any) -> None
No documentation
def set_color_gradient(self: Any, gradient: List[Tuple[int, int, int]]) -> None
No documentation
def set_sensitivity(self: Any, sensitivity: float) -> None
No documentation
def set_smoothing(self: Any, smoothing: float) -> None
No documentation
def _get_audio_data(self: Any) -> List[float]
No documentation
def _process_audio_data(self: Any, raw_data: List[float]) -> None
No documentation
def update(self: Any, dt: float, inputState: Any) -> None
No documentation
def render(self: Any, renderer: OpenGLRenderer) -> None
No documentation
def _render_bars(self: Any, renderer: OpenGLRenderer, x: int, y: int) -> None
No documentation
def _render_waveform(self: Any, renderer: OpenGLRenderer, x: int, y: int) -> None
No documentation
def _render_circle(self: Any, renderer: OpenGLRenderer, x: int, y: int) -> None
No documentation
def _render_particles(self: Any, renderer: OpenGLRenderer, x: int, y: int) -> None
No documentation
def _render_spectrum(self: Any, renderer: OpenGLRenderer, x: int, y: int) -> None
No documentation
def _get_bar_color(self: Any, value: float) -> Tuple[int, int, int]
No documentation
def _get_waveform_color(self: Any, position: float) -> Tuple[int, int, int]
No documentation
def _get_circle_color(self: Any, position: float) -> Tuple[int, int, int]
No documentation
def _get_particle_color(self: Any, value: float, index: int) -> Tuple[int, int, int]
No documentation
def _get_spectrum_color(self: Any, frequency: float) -> Tuple[int, int, int]
No documentation

class Table

Description

A tabular data display element with column headers, row styling, selection.
Fixed size and position; rows exceeding the height are clipped.
Supports images in cells (Path, AtlasItem, Icon, pygame.Surface).

Cell padding, image padding, grid line width, and the hard-coded font
size scale with the current ratio.

Attributes
_properties: Dict[str, Dict[str, Any]] = {**UIElement._properties, 'header_height': {'name': 'header height', 'key': 'header_height', 'type': int, 'editable': True, 'description': 'Height of the header row in pixels.'}, 'row_height': {'name': 'row height', 'key': 'row_height', 'type': int, 'editable': True, 'description': 'Height of each data row in pixels.'}, 'cell_padding': {'name': 'cell padding', 'key': 'cell_padding', 'type': int, 'editable': True, 'description': 'Padding inside each cell in pixels.'}, 'show_headers': {'name': 'show headers', 'key': 'show_headers', 'type': bool, 'editable': True, 'description': 'Whether to display the header row.'}, 'selection_enabled': {'name': 'selection enabled', 'key': 'selection_enabled', 'type': bool, 'editable': True, 'description': 'Allow row selection via click.'}}
Methods
def __init__(self: Any, x: int | float, y: int | float, width: int | float, height: int | float, columns: Optional[List[str]] = None, rows: Optional[List[List[Any]]] = None, header_height: int | float = 25, row_height: int | float = 25, cell_padding: int | float = 5, show_headers: bool = True, selection_enabled: bool = False, on_row_select: Optional[Callable[[int, List[Any]], None]] = None, odd_row_color: Optional[Tuple[int, int, int]] = None, even_row_color: Optional[Tuple[int, int, int]] = None, header_color: Optional[Tuple[int, int, int]] = None, header_text_color: Optional[Tuple[int, int, int]] = None, border_color: Optional[Tuple[int, int, int]] = None, pivot: Tuple[float, float] = (0, 0), theme: Optional[ThemeType] = None, element_id: Optional[str] = None) -> None
No documentation
def _sm(self: Any) -> float
No documentation
def _get_init_args(self: Any) -> Dict[str, Any]
No documentation
def font(self: Any) -> pygame.font.Font
No documentation
def update_theme(self: Any, theme_type: ThemeType) -> Any
No documentation
def _recalc(self: Any) -> None
No documentation
def _get_image_surface(self: Any, data: Any) -> Optional[pygame.Surface]
No documentation
def _draw_cell_image(self: Any, renderer: OpenGLRenderer, surf: pygame.Surface, cell_x: int, cell_y: int, cell_w: int, cell_h: int) -> None
No documentation
def add_column(self: Any, name: str) -> None
No documentation
def insert_column(self: Any, index: int, name: str) -> None
No documentation
def remove_column(self: Any, index: int) -> None
No documentation
def add_row(self: Any, data: List[Any]) -> None
No documentation
def insert_row(self: Any, index: int, data: List[Any]) -> None
No documentation
def remove_row(self: Any, index: int) -> None
No documentation
def set_cell(self: Any, row: int, col: int, value: Any) -> None
No documentation
def get_cell(self: Any, row: int, col: int) -> Any
No documentation
def clear(self: Any) -> None
No documentation
def select_row(self: Any, row_index: int) -> None
No documentation
def _content_height(self: Any) -> float
No documentation
def _max_scroll_y(self: Any) -> float
No documentation
def _scrollbar_rect(self: Any, actual_x: Any, actual_y: Any) -> Any
No documentation
def on_scroll(self: Any, event: pygame.event.Event) -> None
No documentation
def update(self: Any, dt: float, inputState: Any) -> None
No documentation
def render(self: Any, renderer: OpenGLRenderer) -> None
No documentation
def on_click(self: Any) -> Any
No documentation
Back to Ui Module