@masatomakino/threejs-interactive-object
    Preparing search index...

    Class ButtonInteractionHandler<Value>

    Core interaction handler for pointer-interactive Three.js objects with button-like behavior.

    ButtonInteractionHandler provides comprehensive interaction management for Three.js display objects, handling pointer events, state transitions, and material updates. This class was designed as a separate handler rather than extending display objects directly due to EventEmitter3's type system limitations that prevent proper event type extension in inheritance chains.

    The handler manages four primary interaction states (see state property for details).

    click - Emitted when a complete click interaction occurs (down followed by up)

    down - Emitted when pointer is pressed down on the object

    up - Emitted when pointer is released after being pressed

    over - Emitted when pointer enters the object area

    out - Emitted when pointer leaves the object area

    import { ButtonInteractionHandler, StateMaterialSet } from '@masatomakino/threejs-interactive-object';
    import { BoxGeometry, Mesh, MeshBasicMaterial } from 'three';

    // Create materials for different states
    const materials = new StateMaterialSet({
      normal: new MeshBasicMaterial({ color: 0x0000ff }),
      over: new MeshBasicMaterial({ color: 0x00ff00 }),
      down: new MeshBasicMaterial({ color: 0xff0000 })
    });

    // Create interactive mesh
    const mesh = new Mesh(new BoxGeometry(1, 1, 1));
    const handler = new ButtonInteractionHandler({
      view: mesh,
      material: materials
    });

    // Associate custom data
    handler.value = { id: 'button1', action: 'save' };

    // Listen for events
    handler.on('click', (event) => {
      console.log('Button clicked:', handler.value);
    });

    Type Parameters

    • Value

      Type of arbitrary data associated with this interactive object. Used for identifying specific buttons in multi-button scenarios.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    _alpha _enable _isOver _isPress _materialSet? frozen mouseEnabled state value view prefixed

    Accessors

    alpha isOver isPress materialSet

    Methods

    addListener checkActivity disable emit enable eventNames listenerCount listeners off on once onMouseClick onMouseDownHandler onMouseOutHandler onMouseOverHandler onMouseUpHandler removeAllListeners removeListener switchEnable updateMaterial updateState

    Constructors

    • Creates a new ButtonInteractionHandler instance.

      Type Parameters

      • Value

      Parameters

      Returns ButtonInteractionHandler<Value>

      Initializes the interaction handler with the specified display object and optional material set. The handler immediately applies the initial material state upon creation.

      This constructor is typically not called directly by end users. Instead, it is invoked internally by display object constructors (ClickableMesh, ClickableSprite) or conversion utility functions (convertToClickableMesh, convertToClickableSprite).

      // Example 1: Creating clickable object from geometry and materials using ClickableMesh constructor
      import { ClickableMesh, StateMaterialSet } from '@masatomakino/threejs-interactive-object';
      import { BoxGeometry, MeshBasicMaterial } from 'three';

      const materials = new StateMaterialSet({
        normal: new MeshBasicMaterial({ color: 0x0000ff }),
        over: new MeshBasicMaterial({ color: 0x00ff00 }),
        down: new MeshBasicMaterial({ color: 0xff0000 })
      });

      const clickableMesh = new ClickableMesh({
        geo: new BoxGeometry(1, 1, 1),
        material: materials
      });

      clickableMesh.interactionHandler.value = { id: 'button1', action: 'save' };

      // Example 2: Converting existing Mesh to clickable using convertToClickableMesh
      import { convertToClickableMesh } from '@masatomakino/threejs-interactive-object';
      import { Mesh } from 'three';

      const existingMesh = new Mesh(new BoxGeometry(1, 1, 1), new MeshBasicMaterial());
      const convertedClickable = convertToClickableMesh<string>(existingMesh);
      convertedClickable.interactionHandler.value = 'converted-button';

      // Listen for click events
      convertedClickable.interactionHandler.on('click', (event) => {
        console.log('Button clicked:', convertedClickable.interactionHandler.value);
      });

      For most use cases, prefer using ClickableMesh/ClickableSprite constructors for new objects or convertToClickable* utility functions for existing objects, rather than instantiating ButtonInteractionHandler directly.

    Properties

    Protected Internal_alpha

    _alpha: number = 1.0

    Internal alpha multiplier for opacity control.

    Protected Internal_enable

    _enable: boolean = true

    Internal state tracking enabled/disabled status.

    Protected Internal_isOver

    _isOver: boolean = false

    Internal state tracking pointer hover status.

    Protected Internal_isPress

    _isPress: boolean = false

    Internal state tracking pointer press status.

    Protected Optional Internal_materialSet

    _materialSet?: StateMaterialSet

    Internal reference to the material set.

    frozen: boolean = false

    Temporarily prevents interaction handling while maintaining current visual state.

    When frozen is true, the object stops responding to pointer interactions but preserves its current visual state (does not switch to disable state). Useful when you want to temporarily pause interactions without changing the visual appearance to disabled.

    false
    mouseEnabled: boolean = true

    Controls whether the object responds to pointer interactions.

    When set to false, the object will not respond to any pointer interactions. This differs from the disable() method which changes the visual state.

    true
    state: ClickableState = "normal"

    Current visual interaction state of the object.

    Represents the current state used for material selection:

    • normal: Default resting state
    • over: Pointer hovering over the object
    • down: Pointer pressed down on the object
    • disable: Object is disabled and non-interactive
    value: undefined | Value

    Arbitrary data associated with this interactive object.

    The value property allows association of custom data with the interactive object, making it useful for identifying specific buttons in multi-button scenarios or storing configuration data. Event listeners can use this value to determine appropriate responses to interactions.

    // String identifier
    handler.value = 'save-button';

    // Complex object with metadata
    handler.value = { id: 'btn1', action: 'save', data: {...} };
    view: ClickableView<Value>

    The display object being managed by this interaction handler.

    This readonly reference maintains the connection between the handler and the Three.js display object (Mesh, Sprite, or Group).

    prefixed: string | boolean

    Accessors

    • set alpha(value: number): void

      Sets the opacity alpha multiplier for the material set.

      Parameters

      • value: number

        Alpha value between 0.0 (transparent) and 1.0 (opaque)

      Returns void

      Controls the overall opacity of the interactive object by setting an alpha multiplier that is applied to all materials in the material set. This allows for fade effects while preserving the relative opacity differences between different interaction states.

    Methods

    • Protected

      Checks if the object is currently active and can respond to interactions.

      Returns boolean

      True if the object is enabled and not frozen, false otherwise

      Determines whether the object should respond to pointer interactions by checking both the enabled state and the frozen flag. An object must be both enabled and not frozen to be considered active.

    • Disables the interactive object, preventing response to pointer interactions.

      Returns void

      Sets the object to a disabled state, making it unresponsive to pointer interactions and updating the interaction state to "disable". This is equivalent to calling switchEnable(false).

    • Enables the interactive object, allowing it to respond to pointer interactions.

      Returns void

      Sets the object to an enabled state, making it responsive to pointer interactions and updating the interaction state to "normal". This is equivalent to calling switchEnable(true).

    • Return an array listing the events for which the emitter has registered listeners.

      Returns (keyof ThreeMouseEventMap<Value>)[]

    • Return the number of listeners listening to a given event.

      Parameters

      Returns number

    • Hook method called when a click interaction is detected.

      Returns void

      This method is called when a complete click interaction occurs (pointer down followed by pointer up). Subclasses can override this method to implement custom click behavior. The base implementation is empty.

      This method is called before the click event is emitted, allowing subclasses to modify state or perform actions that should occur during the click process.

    • Handles pointer down events and transitions to pressed state.

      Parameters

      Returns void

      Processes pointer down events by checking activity status, updating internal press state, transitioning to "down" visual state, and emitting the down event. If the object is inactive (disabled or frozen), the event is ignored.

      down - Emitted when the pointer is successfully pressed down

    • Handles pointer up events and manages click detection logic.

      Parameters

      Returns void

      Processes pointer up events by resetting press state, determining the next visual state based on hover status, and emitting the up event. If the pointer was previously pressed down, also triggers click event emission through the onMouseClick hook.

      up - Emitted when the pointer is released

      click - Emitted when a complete click interaction is detected

    • Remove all listeners, or those of the specified event.

      Parameters

      • Optionalevent: keyof ThreeMouseEventMap<Value>

      Returns this

    • Remove the listeners of a given event.

      Type Parameters

      Parameters

      Returns this

    • Switches the interactive object between enabled and disabled states.

      Parameters

      • bool: boolean

        True to enable, false to disable

      Returns void

      Changes the enabled state of the interactive object and immediately updates the interaction state and material. When enabled, the state becomes "normal"; when disabled, the state becomes "disable".

      // Enable the button
      handler.switchEnable(true);

      // Disable the button
      handler.switchEnable(false);
    • Protected

      Updates the display object's material based on current state and settings.

      Returns void

      Applies the current alpha multiplier to the material set and retrieves the appropriate material for the current interaction state and enabled status. The material is then applied to the display object based on its type (Mesh, Sprite, or Group).

      This method handles the coordination between the abstract state management and the concrete Three.js material system. Groups are not currently supported for material updates.

    • Protected

      Updates the current interaction state and refreshes the visual representation.

      Parameters

      Returns void

      Changes the current interaction state and immediately updates the display object's material to reflect the new state. This method coordinates state management with visual feedback.

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods