# Handling Input #

## Forms of Input #

Our goal is to make writing cross-platform interactions simple. Input schemes may vary with the device used to interact with your application, so we provide event handlers to normalize the most common types of inputs across mouse, keyboard, and gamepad.

On the desktop, the easiest way to interact with an application is with the mouse cursor. However, in VR headsets the cursor is gaze-based: things you look at are the target of input events. Similarly, depending on the platform, selecting a component may come from a key press, a mouse click, a screen tap, or gamepad input. We provide event handlers that can target specific input devices so that you can write platform-specific interactions, but we also provide generalized input handlers that are raised by similar actions on each platform.

If you're looking for simple, button-style, `onClick` behavior, that is provided out of the box by VrButton.

## Cursor Visibility #

When the user is in a VR headset, it can be difficult to tell exactly what components are currently in focus. To help with this, we provide a visible application-level cursor that sits at the center of the field of vision.

There are two settings that control the cursor behavior, both of which are passed at initialization time.

- `cursorEnabled` - If set to true, the cursor will be visible
- `cursorAutoHide` - If set to true, and the cursor is enabled, the cursor will only be visible when hovering over components that have event handlers.

These settings are set at initialization time, which means they can be defined in one of two different places. The first is in your `index.html` page: `ReactVR.init()` takes a map of options as its third argument.

<!-- vr/index.html --> <script> ReactVR.init( '../index.vr.bundle?platform=vr', document.body, // third argument is a map of initialization options { cursorEnabled: true, cursorAutoHide: true, } ); </script>

Alternatively, if you want these options to be compiled into your application, you can also set them in the autogenerated `vr/client.js` file. These options are passed as the last argument when the `VRInstance` is constructed.

// vr/client.js const vr = new VRInstance(bundle, 'YourProject', parent, { // Custom initialization options go here cursorEnabled: true, cursorAutoHide: true, ...options, });

## Supported Input Events #

### `onEnter` #

This event raises whenever the platform cursor begins intersecting with a component. On desktop platforms, this occurs when the mouse cursor intersects with a component. In a VR headset, this occurs when the cursor at the center of the user's view begins intersecting with the component.

### `onExit` #

This event raises whenever the platform cursor stops intersecting with a component. On desktop platforms, this occurs when the mouse cursor leaves a component. In a VR headset, this occurs when the cursor at the center of the user's view stops intersecting with the component.

### `onGazeEnter` #

This event only raises when the cursor at the center of the viewport begins intersecting with a component.

### `onGazeExit` #

This event only raises when the cursor at the center of the viewport stops intersecting with a component.

### `onMouseEnter` #

This event only raises when the desktop mouse cursor begins intersecting with a component.

### `onMouseExit` #

This event only raises when the desktop mouse cursor stops intersecting with a component.

### `onInput` #

This event captures all interactions for all devices. On its own, it provides a steady stream of events, but they can be filtered down to capture specific actions. For instance, the `onClick` handler of `VrButton` filters events to capture the primary buttons for each input channel.

## Example #

The following code builds a simple component that changes text color when the user looks at it, or hovers with the mouse cursor:

class ColorChange extends React.Component { constructor() { super(); this.state = {textColor: 'white'}; } render() { return ( <Text style={{color: this.state.textColor}} onEnter={() => this.setState({textColor: 'red'})} onEnter={() => this.setState({textColor: 'white'})}> This text will turn red when you look at it. </Text> ); } }
← Prev Next →

You can edit the content above on GitHub and send us a pull request!