`simvx.core.ui.virtual_controls`¶

On-screen stick and button controls, each usable by several fingers at once.

These are the drawn pieces an on-screen pad is built from, and they are here on their own for a game that wants one of them wired to its own signal rather than to a pad. A game that wants a controller on the glass adds a

class:: ~simvx.core.ui.touch_controller.TouchController, which is built from these and publishes a real controller.

Every control here takes :attr:~simvx.core.ui.enums.AcceptsPointers.ALL pointers and keys what it is holding by pointer id, so a finger on the stick and a finger on a button are two independent presses. A press is followed through the pointer that opened it: the control captures that pointer on the way down, which is what keeps a thumb that slides off the edge of the stick still steering it, and what makes the release arrive here rather than wherever the thumb happened to be.

Example: stick = VirtualJoystick() stick.moved.connect(lambda x, y: player.walk(Vec2(x, y)))

fire = VirtualButton(label="Fire")
fire.pressed.connect(player.shoot)

Module Contents¶

Classes¶

`VirtualJoystick`	Circular on-screen stick that reports a normalised vector.
`VirtualButton`	Round on-screen action button with an optional label.

Data¶

`log`
`__all__`

API¶

simvx.core.ui.virtual_controls.log¶: ‘getLogger(…)’

simvx.core.ui.virtual_controls.__all__¶: [‘VirtualButton’, ‘VirtualJoystick’]

class simvx.core.ui.virtual_controls.VirtualJoystick(**kwargs)[source]¶

Bases: simvx.core.ui.virtual_controls._MultiTouchControl

Circular on-screen stick that reports a normalised vector.

The thumb follows the pointer inside the outer ring and the reading is clamped to the unit circle, so a diagonal push is never longer than a straight one. moved carries (x, y) in -1 to 1 with +y down the screen, and fires with (0, 0) when the last finger lifts.

Example: stick = VirtualJoystick(radius=80.0) stick.moved.connect(lambda x, y: print(f”{x:.2f}, {y:.2f}”))

Initialization

dead_zone¶: ‘Property(…)’

radius¶: ‘Property(…)’

property value: simvx.core.math.types.Vec2[source]¶: The current reading, (0, 0) at rest.

on_gui_input(event) → bool | None[source]¶

on_exit_tree() → None[source]¶

on_draw(renderer)[source]¶

pointer_filter¶: ‘Property(…)’

accepts_pointers¶: ‘Property(…)’

property is_held: bool¶

size_x¶: ‘Property(…)’

size_y¶: ‘Property(…)’

min_size_x¶: ‘Property(…)’

min_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(…)’

anchor¶: ‘Property(…)’

inset¶: ‘Property(…)’

dismiss_on_outside_click¶: ‘Property(…)’

clip_contents¶: ‘Property(…)’

focus_mode¶: ‘Property(…)’

tooltip¶: ‘Property(…)’

cursor_shape¶: ‘Property(…)’

pointer_types: frozenset[simvx.core.input.enums.PointerType] | None¶: None

touch_target: bool¶: False

property wants_text_input: bool¶

size_flags_horizontal¶: ‘Property(…)’

size_flags_vertical¶: ‘Property(…)’

stretch_ratio¶: ‘Property(…)’

max_size¶: ‘Property(…)’

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

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

content_signature() → object¶

content_uses(chars: str) → bool¶

autosize_to_content() → None¶

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

property mouse_over: bool¶

property disabled: bool¶

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

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

property viewport_insets: tuple[float, float, float, float]¶

queue_redraw()¶

size_floor() → tuple[float, float]¶

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

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

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

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

property focus_rect: tuple[float, float, float, float] | None¶

is_point_inside(point) → bool¶

is_hit(event: simvx.core.input.events.PointerEvent) → bool¶

classmethod __init_subclass__(**kwargs)¶

activate() → bool¶

focus_next_control()¶

focus_previous_control()¶

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(…)’

top_level¶: ‘Property(…)’

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)¶

to_global(point) → simvx.core.math.types.Vec2¶

to_local(point) → simvx.core.math.types.Vec2¶

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

wrap_screen(margin: float = 20)¶

post_processed¶: ‘Property(…)’

property transform_render_dirty: bool¶

strict_errors: ClassVar[bool]¶: True

dev_checks: ClassVar[bool]¶: None

dev_warnings: ClassVar[bool]¶: None

freeze_check_interval: ClassVar[float]¶: 1.0

dynamic: bool¶: False

visible¶: ‘Property(…)’

update_mode¶: ‘Property(…)’

drag_threshold¶: ‘Property(…)’

focus_entered¶: ‘Signal(…)’

focus_exited¶: ‘Signal(…)’

__properties__: ClassVar[dict[str, simvx.core.descriptors.Property]]¶: None

property name: str¶

property visible_in_tree: bool¶

property input_player: simvx.core.input.players.InputPlayer¶

property input_context: simvx.core.input.contexts.InputContext | None¶

reset_error() → None¶

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

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

node_at(path, default=_NO_DEFAULT)¶

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

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

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

ancestor(target)¶

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

property path: str¶

property is_scene_root: bool¶

add_to_group(group: str)¶

remove_from_group(group: str)¶

is_in_group(group: str) → bool¶

on_ready() → None¶

on_enter_tree() → None¶

on_update(dt: float) → None¶

on_fixed_update(dt: float) → None¶

on_draw_3d(gizmos) → None¶

on_picked(event: simvx.core.input.events.PickEvent) → bool | None¶

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

stop_coroutine(gen_or_handle)¶

property focused: bool¶

drag_threshold_for(pointer_type: simvx.core.input.enums.PointerType | str) → float¶

grab_focus() → None¶

release_focus() → None¶

capture_pointer(pointer_id: int | None = None) → None¶

release_pointer(pointer_id: int | None = None) → None¶

property render_dirty: bool¶

clear_children()¶

destroy()¶

property destroying: bool¶

property destroyed: bool¶

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.core.ui.virtual_controls.VirtualButton(**kwargs)[source]¶

Bases: simvx.core.ui.virtual_controls._MultiTouchControl

Round on-screen action button with an optional label.

pressed fires when the first finger lands on it and released when the last one leaves, so two thumbs on one button are one press.

Example: jump = VirtualButton(label=”Jump”, button_radius=40.0) jump.pressed.connect(player.jump)