clock.py - LunaEngine Docs

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: Renderer) -> None

Render the clock.

def _render_analog_clock(self: Any, renderer: Renderer, x: int, y: int) -> None

Render the analog clock face and hands.

def _draw_clock_numbers(self: Any, renderer: Renderer, center_x: int, center_y: int, radius: int) -> None

Draw numbers 1-12 around the clock face.

def _draw_tick_marks(self: Any, renderer: Renderer, center_x: int, center_y: int, radius: int) -> None

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]) -> None

Draw a single clock hand.

def _render_digital_clock(self: Any, renderer: Renderer, x: int, y: int) -> None

Render the digital clock display.