`simvx.editor.hints`¶

First-Run Hints: Contextual hints and interactive tour for new users.

Module Contents¶

Classes¶

`HintOverlay`	Shows contextual hints for first-time users.
`TourGuide`	Interactive first-run tour that walks through editor panels.

Data¶

log

API¶

simvx.editor.hints.log¶: ‘getLogger(…)’

class simvx.editor.hints.HintOverlay(**kwargs)[source]¶

Bases: simvx.core.ui.core.Control

Shows contextual hints for first-time users.

Displays a small overlay bar at the bottom of the parent with helpful tips based on editor context (empty scene tree, first play, etc.). Each hint is shown at most once per session.

Usage::

hints = HintOverlay()
parent.add_child(hints)
hints.show_hint("scene_tree_empty")  # Shows: "Add a node with the + button or Ctrl+A"
hints.dismiss()                      # Manually dismiss current hint

Initialization

HINTS: dict[str, str]¶: None

enabled¶: ‘Property(…)’

show_hint(key: str) → bool[source]¶

Show a hint by key, if it hasn’t been shown before.

Returns True if the hint was shown, False if already dismissed or unknown key.

dismiss() → None[source]¶: Dismiss the current hint, marking it as shown.

property active_hint: str | None[source]¶: Return the currently displayed hint key, or None.

property active_hint_text: str | None[source]¶: Return the currently displayed hint text, or None.

property shown_hints: set[str][source]¶: Return the set of hint keys that have been shown/dismissed.

reset() → None[source]¶: Reset all shown hints so they can appear again.

on_update(dt: float) → None[source]¶: Auto-dismiss hints after a timeout.

on_draw(renderer) → None[source]¶

size_x¶: ‘Property(…)’

size_y¶: ‘Property(…)’

anchor_left¶: ‘Property(…)’

anchor_top¶: ‘Property(…)’

anchor_right¶: ‘Property(…)’

anchor_bottom¶: ‘Property(…)’

margin_left¶: ‘Property(…)’

margin_top¶: ‘Property(…)’

margin_right¶: ‘Property(…)’

margin_bottom¶: ‘Property(…)’

dismiss_on_outside_click¶: ‘Property(…)’

property size: simvx.core.math.types.Vec2¶

touch_mode: str¶: ‘mouse’

property theme: simvx.core.ui.types.Theme | None¶

property mouse_over: bool¶

property focused: bool¶

property disabled: bool¶

get_theme() → simvx.core.ui.types.Theme¶

queue_redraw()¶

get_minimum_size() → simvx.core.math.types.Vec2¶

get_rect() → tuple[float, float, float, float]¶

get_global_rect() → tuple[float, float, float, float]¶

is_point_inside(point) → bool¶

place_bottom_strip(height: float) → None¶

place_top_strip(height: float) → None¶

set_anchor_preset(preset: simvx.core.ui.enums.AnchorPreset)¶

set_focus()¶

grab_focus()¶

release_focus()¶

has_focus() → bool¶

focus_next_control()¶

focus_previous_control()¶

grab_mouse()¶

release_mouse()¶

set_drag_preview(control: simvx.core.ui.core.Control)¶

property is_overlay_open: bool¶

show_overlay(modality: str = 'light', *, dim: bool | None = None, dismiss: bool | None = None, inert: bool | None = None, owner: simvx.core.ui.core.Control | None = None, initial_focus: simvx.core.ui.core.Control | None = None) → None¶

close_overlay() → None¶

position¶: ‘_SpatialVecProperty(…)’

rotation¶: ‘Property(…)’

scale¶: ‘_SpatialVecProperty(…)’

z_index¶: ‘Property(…)’

z_as_relative¶: ‘Property(…)’

render_layer¶: ‘Property(…)’

set_render_layer(index: int, enabled: bool = True) → None¶

is_on_render_layer(index: int) → bool¶

property absolute_z_index: int¶

property rotation_degrees: float¶

property world_position: simvx.core.math.types.Vec2¶

property world_rotation: float¶

property world_scale: simvx.core.math.types.Vec2¶

property world_transform: tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2, float]¶

property forward: simvx.core.math.types.Vec2¶

property right: simvx.core.math.types.Vec2¶

translate(offset: tuple[float, float] | numpy.ndarray)¶

rotate(radians: float)¶

rotate_deg(degrees: float)¶

look_at(target: tuple[float, float] | numpy.ndarray)¶

transform_points(points: list[simvx.core.math.types.Vec2]) → list[simvx.core.math.types.Vec2]¶

draw_polygon(renderer, points: list[simvx.core.math.types.Vec2], closed=True, colour=None)¶

wrap_screen(margin: float = 20)¶

hdr¶: ‘Property(…)’

property transform_render_dirty: bool¶

strict_errors: ClassVar[bool]¶: True

script_error_raised¶: ‘Signal(…)’

dynamic: bool¶: False

classmethod __init_subclass__(**kwargs)¶

property name: str¶

property update_mode: simvx.core.descriptors.UpdateMode¶

property visible: bool¶

reset_error() → None¶

add_child(node: simvx.core.node.Node) → simvx.core.node.Node¶

remove_child(node: simvx.core.node.Node)¶

reparent(new_parent: simvx.core.node.Node)¶

get_node(path: str) → simvx.core.node.Node¶

get_node_or_none(path: str) → simvx.core.node.Node | None¶

find(target, *, direct: bool = False)¶

find_all(target, *, direct: bool = False)¶

walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]¶

property path: str¶

add_to_group(group: str)¶

remove_from_group(group: str)¶

is_in_group(group: str) → bool¶

on_ready() → None¶

on_enter_tree() → None¶

on_exit_tree() → None¶

on_fixed_update(dt: float) → None¶

on_picked(event: simvx.core.events.InputEvent) → None¶

on_unhandled_input(event: simvx.core.events.TreeInputEvent) → None¶

start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle¶

stop_coroutine(gen_or_handle)¶

property render_dirty: bool¶

clear_children()¶

destroy()¶

call_deferred(method: collections.abc.Callable[..., Any], *args: Any) → None¶

property app¶

property tree: simvx.core.scene_tree.SceneTree¶

property physics¶

property physics_2d¶

__getitem__(key: str)¶

classmethod get_properties() → dict[str, simvx.core.descriptors.Property]¶

__repr__()¶

class simvx.editor.hints.TourGuide(**kwargs)[source]¶

Bases: simvx.core.ui.core.Control

Interactive first-run tour that walks through editor panels.

Displays a sequence of steps with Next/Back/Skip navigation. Each step describes a panel and its purpose. The tour is triggered on first launch and stored in preferences once completed.

Usage::

tour = TourGuide()
parent.add_child(tour)
tour.start()
tour.tour_completed.connect(on_tour_done)

Initialization

tour_completed¶: ‘Signal(…)’

start() → None[source]¶: Begin the tour from step 0.

stop() → None[source]¶: End the tour (skip or finish).

property is_active: bool[source]¶

on_update(dt: float) → None[source]¶: Keep size synced to parent so we always intercept input.

on_draw(renderer) → None[source]¶

size_x¶: ‘Property(…)’

size_y¶: ‘Property(…)’

anchor_left¶: ‘Property(…)’

anchor_top¶: ‘Property(…)’

anchor_right¶: ‘Property(…)’

anchor_bottom¶: ‘Property(…)’

margin_left¶: ‘Property(…)’

margin_top¶: ‘Property(…)’

margin_right¶: ‘Property(…)’

margin_bottom¶: ‘Property(…)’

dismiss_on_outside_click¶: ‘Property(…)’

property size: simvx.core.math.types.Vec2¶

touch_mode: str¶: ‘mouse’

property theme: simvx.core.ui.types.Theme | None¶

property mouse_over: bool¶

property focused: bool¶

property disabled: bool¶

get_theme() → simvx.core.ui.types.Theme¶

queue_redraw()¶

get_minimum_size() → simvx.core.math.types.Vec2¶

get_rect() → tuple[float, float, float, float]¶

get_global_rect() → tuple[float, float, float, float]¶

is_point_inside(point) → bool¶

place_bottom_strip(height: float) → None¶

place_top_strip(height: float) → None¶

set_anchor_preset(preset: simvx.core.ui.enums.AnchorPreset)¶

set_focus()¶

grab_focus()¶

release_focus()¶

has_focus() → bool¶

focus_next_control()¶

focus_previous_control()¶

grab_mouse()¶

release_mouse()¶

set_drag_preview(control: simvx.core.ui.core.Control)¶

property is_overlay_open: bool¶

show_overlay(modality: str = 'light', *, dim: bool | None = None, dismiss: bool | None = None, inert: bool | None = None, owner: simvx.core.ui.core.Control | None = None, initial_focus: simvx.core.ui.core.Control | None = None) → None¶