Raxol.Terminal.Graphics.MouseInteraction (Raxol v2.0.1)

View Source

Provides mouse interaction capabilities for terminal graphics elements.

This module enables:

  • Click detection on graphics elements
  • Hover events for graphics
  • Drag and drop support for graphics
  • Mouse gesture recognition
  • Hit testing for complex graphics layouts

Usage

# Register a graphics element for mouse interaction
MouseInteraction.register_interactive_element(graphics_id, %{
  bounds: %{x: 10, y: 5, width: 100, height: 50},
  callbacks: %{
    on_click: &handle_click/1,
    on_hover: &handle_hover/1
  }
})

# Process mouse events
MouseInteraction.handle_mouse_event(%{
  type: :click,
  x: 50, y: 20,
  button: :left
})

Summary

Types

bounds()
coordinates()
interaction_callbacks()
interactive_element()
mouse_button()
mouse_event()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

clear_selection()

Clears the current selection.

get_drag_state()

Gets the current drag state.

get_interactive_elements()

Gets all currently interactive elements.

get_selection_state()

Gets the current selection state.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

handle_manager_info(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_info/2.

handle_mouse_event(mouse_event)

Processes a mouse event and triggers appropriate callbacks.

register_interactive_element(graphics_id, element_config)

Registers a graphics element for mouse interaction.

set_element_enabled(graphics_id, enabled)

Enables or disables mouse interaction for an element.

set_text_selection_mode(graphics_id, enabled)

Sets text selection mode for an element.

start_link(init_opts \\ [])
unregister_interactive_element(graphics_id)

Unregisters a graphics element from mouse interaction.

update_config(config_updates)

Updates configuration options for the mouse interaction manager.

update_element_bounds(graphics_id, new_bounds)

Updates the bounds of an interactive element.

Types

bounds()

@type bounds() :: %{
  x: non_neg_integer(),
  y: non_neg_integer(),
  width: non_neg_integer(),
  height: non_neg_integer()
}

coordinates()

@type coordinates() :: %{x: non_neg_integer(), y: non_neg_integer()}

interaction_callbacks()

@type interaction_callbacks() :: %{
  optional(:on_click) => function(),
  optional(:on_hover) => function(),
  optional(:on_drag_start) => function(),
  optional(:on_drag) => function(),
  optional(:on_drag_end) => function(),
  optional(:on_double_click) => function(),
  optional(:on_triple_click) => function(),
  optional(:on_context_menu) => function(),
  optional(:on_selection_start) => function(),
  optional(:on_selection_change) => function(),
  optional(:on_selection_end) => function()
}

interactive_element()

@type interactive_element() :: %{
  graphics_id: non_neg_integer(),
  bounds: bounds(),
  callbacks: interaction_callbacks(),
  z_index: integer(),
  enabled: boolean(),
  metadata: map()
}

mouse_button()

@type mouse_button() :: :left | :right | :middle | :wheel_up | :wheel_down

mouse_event()

@type mouse_event() :: %{
  type: :click | :press | :release | :move | :hover | :drag | :context_menu,
  x: non_neg_integer(),
  y: non_neg_integer(),
  button: mouse_button() | nil,
  modifiers: map(),
  timestamp: non_neg_integer()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

clear_selection()

@spec clear_selection() :: :ok

Clears the current selection.

get_drag_state()

@spec get_drag_state() :: map() | nil

Gets the current drag state.

get_interactive_elements()

@spec get_interactive_elements() :: [interactive_element()]

Gets all currently interactive elements.

get_selection_state()

@spec get_selection_state() :: map() | nil

Gets the current selection state.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

handle_manager_info(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_info/2.

handle_mouse_event(mouse_event)

@spec handle_mouse_event(mouse_event()) ::
  {:handled, non_neg_integer()} | :not_handled

Processes a mouse event and triggers appropriate callbacks.

Parameters

  • mouse_event - Mouse event data including type, coordinates, button

Returns

  • {:handled, element_id} - Event was handled by an interactive element
  • :not_handled - No interactive element handled the event

register_interactive_element(graphics_id, element_config)

@spec register_interactive_element(non_neg_integer(), map()) :: :ok | {:error, term()}

Registers a graphics element for mouse interaction.

Parameters

  • graphics_id - ID of the graphics element
  • element_config - Configuration including bounds, callbacks, etc.

Examples

MouseInteraction.register_interactive_element(123, %{
  bounds: %{x: 10, y: 5, width: 100, height: 50},
  callbacks: %{
    on_click: fn event -> Log.info("Clicked!") end,
    on_hover: fn event -> Log.info("Hovered!") end
  },
  z_index: 1,
  metadata: %{type: :button, id: "submit_btn"}
})

set_element_enabled(graphics_id, enabled)

@spec set_element_enabled(non_neg_integer(), boolean()) :: :ok | {:error, term()}

Enables or disables mouse interaction for an element.

set_text_selection_mode(graphics_id, enabled)

@spec set_text_selection_mode(non_neg_integer(), boolean()) :: :ok | {:error, term()}

Sets text selection mode for an element.

start_link(init_opts \\ [])

unregister_interactive_element(graphics_id)

@spec unregister_interactive_element(non_neg_integer()) :: :ok

Unregisters a graphics element from mouse interaction.

update_config(config_updates)

@spec update_config(map()) :: :ok

Updates configuration options for the mouse interaction manager.

update_element_bounds(graphics_id, new_bounds)

@spec update_element_bounds(non_neg_integer(), bounds()) :: :ok | {:error, term()}

Updates the bounds of an interactive element.