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

    Class RadioButtonInteractionHandler<Value>

    Radio button interaction handler with exclusive group selection behavior.

    Extends CheckBoxInteractionHandler with radio button-specific exclusive selection behavior. Radio buttons work in groups where only one can be selected at a time, managed externally by RadioButtonManager. The frozen state prevents re-selection of already selected buttons.

    Unlike checkboxes, radio buttons require external group management and do not operate independently. The RadioButtonManager controls both selection and frozen states across the entire button group to maintain exclusive selection behavior.

    Typically instantiated internally by RadioButtonMesh/RadioButtonSprite constructors or convertToRadioButton* utility functions, then managed by RadioButtonManager.

    // Creating radio buttons from geometry and materials
    import { RadioButtonMesh, StateMaterialSet } from '@masatomakino/threejs-interactive-object';
    import { BoxGeometry, MeshBasicMaterial } from 'three';

    const materials = new StateMaterialSet({
      normal: new MeshBasicMaterial({ color: 0x888888 }),
      over: new MeshBasicMaterial({ color: 0xaaaaaa }),
      selected: new MeshBasicMaterial({ color: 0xff0000 }),
      selectedOver: new MeshBasicMaterial({ color: 0xaa0000 })
    });

    const radio1 = new RadioButtonMesh({
      geo: new BoxGeometry(1, 1, 1),
      material: materials
    });
    const radio2 = new RadioButtonMesh({
      geo: new BoxGeometry(1, 1, 1),
      material: materials
    });

    radio1.interactionHandler.value = { id: 'option1', label: 'Choice A' };
    radio2.interactionHandler.value = { id: 'option2', label: 'Choice B' };

    // Converting existing Mesh to radio button
    import { convertToRadioButtonMesh, StateMaterialSet } from '@masatomakino/threejs-interactive-object';
    import { Mesh, BoxGeometry, MeshBasicMaterial } from 'three';

    const existingMesh1 = new Mesh(new BoxGeometry(1, 1, 1), new MeshBasicMaterial());
    const existingMesh2 = new Mesh(new BoxGeometry(1, 1, 1), new MeshBasicMaterial());
    const convertedRadio1 = convertToRadioButtonMesh<string>(existingMesh1);
    const convertedRadio2 = convertToRadioButtonMesh<string>(existingMesh2);

    // Set up materials for radio button states
    const radioMaterials = new StateMaterialSet({
      normal: new MeshBasicMaterial({ color: 0x888888 }),
      over: new MeshBasicMaterial({ color: 0xaaaaaa }),
      selected: new MeshBasicMaterial({ color: 0xff0000 }),
      selectedOver: new MeshBasicMaterial({ color: 0xaa0000 })
    });
    convertedRadio1.interactionHandler.materialSet = radioMaterials;
    convertedRadio2.interactionHandler.materialSet = radioMaterials;

    convertedRadio1.interactionHandler.value = 'option1';
    convertedRadio2.interactionHandler.value = 'option2';

    // RadioButtonManager setup (required for both approaches above)
    import { RadioButtonManager } from '@masatomakino/threejs-interactive-object';

    // Create manager and add radio buttons to group
    const radioManager = new RadioButtonManager<string>();
    radioManager.addButton(radio1, radio2);

    // Listen for exclusive selection events from manager
    radioManager.on('select', (event) => {
      console.log('Selected radio button:', event.interactionHandler?.value);
      // Only one radio button can be selected at a time
    });

    Type Parameters

    • Value

      Type of arbitrary data associated with this radio button. Used for identifying specific options in radio button groups.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    _alpha _enable _isExclusivelySelected _isSelect _materialSet? hoverPointerIds interactionScannable pressPointerIds state value view prefixed

    Accessors

    alpha enabled frozen isExclusivelySelected isFrozen isOver isPress materialSet mouseEnabled selection

    Methods

    _setSelectionOverride addListener calculateCurrentState 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 RadioButtonInteractionHandler<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_isExclusivelySelected

    _isExclusivelySelected: boolean = false

    Protected_isSelect

    _isSelect: boolean = false

    Protected Optional Internal_materialSet

    _materialSet?: StateMaterialSet

    Internal reference to the material set.

    hoverPointerIds: Set<number> = ...

    Set of pointer IDs currently hovering over the object.

    Tracks all pointer IDs that have entered the object area but not yet left. Used for multitouch hover state management. Multiple pointers can simultaneously hover over the same interactive object.

    interactionScannable: boolean = true

    Controls whether this object is scannable by MouseEventManager during interaction detection.

    When false, MouseEventManager will skip this object during checkTarget() processing, preventing it from receiving any pointer events. This is different from enable/disable which only affects handler-level processing.

    true
    pressPointerIds: Set<number> = ...

    Set of pointer IDs currently in pressed state.

    Tracks all pointer IDs that have triggered down events but not yet corresponding up events. Used for multitouch support and same-ID click detection. The Set automatically prevents duplicate pointer ID storage and provides O(1) add/delete/has operations.

    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: RadioButtonMesh<Value> | RadioButtonSprite<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 multiplier value (minimum 0.0 for transparency, no maximum limit)

      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.

      Values above 1.0 are permitted to allow compensation for materials with low base opacity (e.g., alpha=5.0 with material opacity=0.2 results in final opacity=1.0). Negative values are clamped to 0.0 to prevent invalid opacity states.

    • get enabled(): boolean

      Indicates whether the object is currently enabled for interactions.

      Returns boolean

      True if the object is enabled, false if disabled

      This getter provides read-only access to the internal enabled state. When enabled, the object can respond to pointer interactions; when disabled, the object becomes non-interactive and displays in disabled visual state.

    • get frozen(): boolean

      Temporarily prevents interaction handling while maintaining current visual state.

      Returns boolean

      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
    • set frozen(value: boolean): void

      Parameters

      • value: boolean

      Returns void

    • get isExclusivelySelected(): boolean

      Gets the current exclusive selection state of the radio button.

      Returns boolean

      True if the radio button is exclusively selected (non-interactive), false otherwise

      Returns the exclusive selection state that prevents re-selection of already selected radio buttons. This state is controlled externally by RadioButtonManager to maintain exclusive selection behavior in radio button groups. When a radio button is exclusively selected, it becomes non-interactive to prevent re-selection of the same option.

    • get isFrozen(): boolean

      Gets the current frozen state of the radio button.

      Returns boolean

      True if the radio button is frozen (selected and non-interactive), false otherwise

      Use isExclusivelySelected instead. This property will be removed in the next minor version.

      Legacy property for backward compatibility. Use isExclusivelySelected for better clarity about the RadioButtonManager's exclusive selection behavior.

      isExclusivelySelected - Recommended replacement property

    • get isOver(): boolean

      Indicates whether any pointer is currently hovering over the object.

      Returns boolean

      True if one or more pointers are over the object, false otherwise

      Computed from the size of the hoverPointerIds Set. Returns true when any pointer is hovering over the interactive object, supporting both single and multitouch scenarios while maintaining backward compatibility.

    • get isPress(): boolean

      Indicates whether any pointer is currently pressed down on the object.

      Returns boolean

      True if one or more pointers are pressed down, false otherwise

      Computed from the size of the pressPointerIds Set. Returns true when any pointer is pressed down on the interactive object, supporting both single and multitouch scenarios while maintaining backward compatibility.

    • get materialSet(): undefined | StateMaterialSet

      Gets the current StateMaterialSet managing visual states.

      Returns undefined | StateMaterialSet

      The current material set, or undefined if none is assigned

    • set materialSet(value: undefined | StateMaterialSet): void

      Sets the StateMaterialSet for managing visual states.

      Parameters

      • value: undefined | StateMaterialSet

        The material set to assign, or undefined to remove

      Returns void

      When a new material set is assigned, the handler automatically updates the display object's material to reflect the current interaction state. Setting the same material set again will not trigger an update.

    Methods

    _setSelectionOverride

    • _setSelectionOverride(bool: boolean): void
      Internal

      Forces selection state change for exclusive radio button group management.

      Parameters

      • bool: boolean

        True to select the radio button, false to deselect

      Returns void

      Internal method specifically designed for RadioButtonManager to force selection state changes during exclusive group management. This method ensures predictable visual behavior in radio button groups:

      • Selection (true): Forces normal state for consistent normalSelect material
      • Deselection (false): Restores appropriate interaction state from internal flags
      • This method is intended only for RadioButtonManager internal use
      • Bypasses all activity checks (disabled/frozen states)
      • Ensures exclusive selection groups have predictable visual appearance
      • Selection: Forces normal state to guarantee normalSelect material display
      • Deselection: Reconstructs state from flags (_enable) and aggregated getters (isPress, isOver)
    • Protected

      Calculates the appropriate interaction state based on current conditions.

      Returns ClickableState

      The calculated interaction state

      Determines the correct interaction state by evaluating enable status and pointer conditions in priority order: disabled → pressed → hovering → normal. This method provides consistent state calculation logic used by switchEnable and other state management operations.

      State priority:

      1. If disabled, returns "disable"
      2. If any pointer is pressed, returns "down"
      3. If any pointer is hovering, returns "over"
      4. Otherwise returns "normal"
    • Protected

      Checks if the radio button can respond to pointer interactions.

      Returns boolean

      True if the radio button is enabled and not exclusively selected, false otherwise

      Overrides the base checkActivity to include exclusive selection state consideration. Radio buttons become exclusively selected when chosen to prevent re-selection, implementing the exclusive selection behavior required for radio button groups.

      Activity status depends on both:

      • _enable state (inherited from ButtonInteractionHandler)
      • _isExclusivelySelected state (RadioButton-specific, controlled by RadioButtonManager)

      The exclusive selection state is managed externally by RadioButtonManager, not by the radio button itself. When a radio button is selected, RadioButtonManager sets isExclusivelySelected=true to prevent further interactions.

      RadioButtonManager.select - External method that controls exclusive selection state

    • 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) and clears both pressed-pointer and hover-pointer states.

    • 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 based on current pointer conditions ("over" or "normal"). This is equivalent to calling switchEnable(true) and, on enable, clears pressed-pointer state while preserving hover state.

    • Handles pointer click interactions by toggling selection state and emitting select events.

      Returns void

      Overrides base onMouseClick to implement checkbox toggle behavior. Toggles internal selection state, emits select event, and updates material for visual feedback. Respects activity state via checkActivity to ensure API consistency.

      select - Emitted with the updated selection state after toggling

    • Handles pointer down events and transitions to pressed state.

      Parameters

      Returns void

      Processes pointer down events by checking activity status, adding the pointer ID to the pressed set, transitioning to "down" visual state, and emitting the down event. Supports multiple simultaneous pointers. 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 with multi-touch suppression.

      Parameters

      Returns void

      Processes pointer up events by checking for same-pointer-ID press state, removing the pointer from the pressed set, determining the next visual state based on hover status, and emitting the up event. Click events are only triggered when the same pointer ID was previously pressed down (same-ID click detection).

      Multi-touch Click Suppression: When a click is triggered, all remaining pressed pointers are cleared to prevent subsequent click events. This matches native browser behavior where multi-touch gestures suppress synthetic click events.

      Browser behavior investigation on iPad revealed that multi-touch interactions naturally suppress click events. This implementation replicates that behavior by clearing the press map after the first successful click, preventing additional pointers from triggering subsequent clicks during the same multi-touch interaction.

      up - Emitted when the pointer is released

      click - Emitted when a complete same-ID click interaction is detected. Only the first completing pointer in a multi-touch scenario triggers this event.

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

      Parameters

      • Optionalevent: keyof ThreeMouseEventMap<Value>

      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 disabled, all pointer states are cleared to prevent stale multitouch interactions. When enabled, only press states are cleared while hover states are preserved to maintain visual feedback.

      Press state clearing on enable prevents unintended click events when a button is programmatically enabled while a pointer was previously pressed down. Hover state preservation maintains proper visual feedback for pointers that are still over the object when it becomes enabled.

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

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

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods