{"_id":"5a8356d8d3dc0f008636c6e8","category":{"_id":"5a8356d8d3dc0f008636c6d6","version":"5a8356d8d3dc0f008636c6d4","project":"5a065a6134873d0010b396ab","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-18T21:08:45.730Z","from_sync":false,"order":1,"slug":"develop","title":"Develop"},"user":"579fce4e1435850e00dfbbbb","project":"5a065a6134873d0010b396ab","parentDoc":null,"version":{"_id":"5a8356d8d3dc0f008636c6d4","project":"5a065a6134873d0010b396ab","__v":1,"createdAt":"2018-02-13T21:21:28.228Z","releaseDate":"2018-02-13T21:21:28.228Z","categories":["5a8356d8d3dc0f008636c6d5","5a8356d8d3dc0f008636c6d6","5a8356d8d3dc0f008636c6d7","5a8356d8d3dc0f008636c6d8"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.3.0","version":"1.3.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-24T04:34:57.318Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"Input events are triggered through controllers like the Daydream Controller or Oculus Gear Touchpad. Viro UI controls respond to input events via event handlers in a bubbled up fashion: events are passed up the Node hierarchy until they encounter a Node that can handle and potentially swallow the event.\n\nThere are many kinds of events: click, drag, fuse, pinch, rotate, and more. However, not all platforms support all events; it is largely dependent on the controller type. All events originate from a given *source*. The source identifies which input button is being pressed, and from which controller (for platforms that feature multiple hand-held controllers, for example). \n\nEach Viro event handler callback provides a unique numeric source identifier that corresponds to an input source on the physical controller. You can view a mapping of input source IDs to Gear, Cardboard, and Daydream below. \n[block:api-header]\n{\n  \"title\": \"Event Handlers\"\n}\n[/block]\nThese methods are used to register listeners to respond to controller-driven events. Events start at the \"hovered\" (or focused) [Node](https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html). If that Node cannot respond to the event (e.g. if it does not have the appropriate listener installed), the event will bubble up the scene graph to that Node's parent, and so on, until a Node that can handle the event is found.\n\nAll events are also received by the [Controller](https://developer.viromedia.com/virocore/reference/com/viro/core/Controller.html), which provides a centralized place to respond to all events regardless of what Nodes they targeted.\n\n[Node.setClickListener(ClickListener)][1]\nClick events are fired when the user taps while focused on a Node. \n\n[Node.setDragListener(DragListener)][2]\nDrag events are fired when a Node is being dragged by the user; that is, when the user performs a click down on a Node, holds that click, and then physically moves the controller (or tilts the headset). The view will automatically drag in VR, and as it does so, the DragListener event callback is continually triggered with the latest 3D location of the object. It is also important to note that the DragListener must be assigned to a Node to make that Node draggable.\n\n[Node.setHoverListener(HoverListener)][3]\nHover events are fired when the user moves his or her reticle over a Node, or stops hovering over a Node.\n\n[Node.setFuseListener(FuseListener)][4]\nFuse events are fired when the user hovers his or her reticle over the Node and remain hovered for `timeToFuse` milliseconds. The `timeToFuse` parameter is optional and is defaulted to 2000ms. This parameter is set via [Node.setTimeToFuse(float)](https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setTimeToFuse(float)).\n\n[Node.setTouchpadTouchListener(TouchpadTouchListener)][5]\n[Node.setTouchpadSwipeListener(TouchpadSwipeListener)][6]\n[Node.setTouchpadScrollListener(TouchpadScrollListener)][7]\nTouch, swipe, and scroll events are fired a Node is touched, swiped, or scrolled using a *touchpad* by the user; that is, when the user performs an action on a touchpad while hovering on top of the targeted Node. For the scroll listener, the distance the user has scrolled by is given as a unit ratio of the touch pad from 0.0 to 1.0 for both X and Y coordinates. These events are mainly used by the Gear VR platform, which features a touchpad on the headset.\n\n[Node.setGesturePinchListener(GesturePinchListener)][8]\n[Node.setGestureRotateListener(GestureRotateListener)][9]\nGesture pinch and rotate events are fired when the user uses multitouch to 'pinch' over a Node or 'swivel' over the Node to create a rotation. These events are used by AR platforms, where the controller is the screen.\n\n[1]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setClickListener(com.viro.core.ClickListener)\n[2]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setDragListener(com.viro.core.DragListener)\n[3]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setHoverListener(com.viro.core.HoverListener)\n[4]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setFuseListener(com.viro.core.FuseListener)\n[5]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setTouchpadTouchListener(com.viro.core.TouchpadTouchListener)\n[6]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setTouchpadSwipeListener(com.viro.core.TouchpadSwipeListener)\n[7]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setTouchpadScrollListener(com.viro.core.TouchpadScrollListener)\n[8]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setGesturePinchListener(com.viro.core.GesturePinchListener)\n[9]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setGestureRotateListener(com.viro.core.GestureRotateListener)\n[block:api-header]\n{\n  \"title\": \"Supported Controllers\"\n}\n[/block]\nAt the very least,`Click` is guaranteed to be supported across all platforms. However, due to the physical limitations of controllers on each platform, certain events as shown below may not be supported.\n\n|Events|Daydream|GearVR|Android Cardboard| IOS Cardboard| iOS AR | Android AR |\n|:------|:----------:|:----------:|:----------:|:----------:|:----------:|:----------:|\n|Click| Supported|Supported |Supported |Supported | Supported | Supported |\n|Hover| Supported |Supported |Supported |Supported |  Supported |  Supported |\n|Drag| Supported|Supported |Supported |Not Supported | Supported | Supported |\n|Fuse| Supported|Supported |Supported |Not Supported | Not Supported | Not Supported |\n|Scroll| Supported|Not Supported |Not Supported |Not Supported | Not Supported | Not Supported |\n|Swipe| Supported|Supported |Not Supported |Not Supported | Not Supported | Not Supported |\n|Touch| Supported|Supported |Not Supported |Not Supported | Not Supported | Not Supported |\n|Pinch| Not Supported| Not Supported |Not Supported |Not Supported | Supported | Supported |\n|Rotate| Not Supported| Not Supported |Not Supported |Not Supported | Supported | Supported |\n\nDifferent types of controllers may result in different forms of interactivity or UI. For example, users can easily scroll through galleries with Daydream's touch pad, but additional UI buttons may be needed for Cardboard. \n[block:api-header]\n{\n  \"title\": \"Platform Specific Input Source Identifiers\"\n}\n[/block]\nAs mentioned above, a unique numeric source identifier that corresponds to an input source on the physical controller. This section will go through the mappings of sources for Cardboard, GearVR and Daydream.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/4c75011-controller_cardboard.png\",\n        \"controller_cardboard.png\",\n        800,\n        511,\n        \"#747474\"\n      ],\n      \"caption\": \"Cardboard (Android & iOS)\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Input Source Value\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"1\",\n    \"1-0\": \"2\",\n    \"0-1\": \"Main Controller\",\n    \"1-1\": \"Primary Cardboard Trigger\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/a5b7f83-controller_gear_vr.png\",\n        \"controller_gear_vr.png\",\n        800,\n        511,\n        \"#747474\"\n      ],\n      \"caption\": \"GearVR\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Input Source Value\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"1\",\n    \"0-1\": \"Main Controller\",\n    \"1-0\": \"2\",\n    \"1-1\": \"Gear Touch Pad\",\n    \"2-0\": \"3\",\n    \"2-1\": \"Gear Back Button\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/71bb4df-controller_daydream.png\",\n        \"controller_daydream.png\",\n        800,\n        511,\n        \"#747474\"\n      ],\n      \"caption\": \"Daydream\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Input Source Value\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"1\",\n    \"1-0\": \"2\",\n    \"2-0\": \"3\",\n    \"3-0\": \"4\",\n    \"4-0\": \"5\",\n    \"5-0\": \"6\",\n    \"0-1\": \"Main Controller\",\n    \"1-1\": \"Daydream TouchPad\",\n    \"2-1\": \"Daydream App Button\",\n    \"3-1\": \"Daydream Home Button\",\n    \"4-1\": \"Volume Up Button\",\n    \"5-1\": \"Volume Down Button\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"\"\n}\n[/block]","excerpt":"","slug":"events","type":"basic","title":"Input Events"}
Input events are triggered through controllers like the Daydream Controller or Oculus Gear Touchpad. Viro UI controls respond to input events via event handlers in a bubbled up fashion: events are passed up the Node hierarchy until they encounter a Node that can handle and potentially swallow the event. There are many kinds of events: click, drag, fuse, pinch, rotate, and more. However, not all platforms support all events; it is largely dependent on the controller type. All events originate from a given *source*. The source identifies which input button is being pressed, and from which controller (for platforms that feature multiple hand-held controllers, for example). Each Viro event handler callback provides a unique numeric source identifier that corresponds to an input source on the physical controller. You can view a mapping of input source IDs to Gear, Cardboard, and Daydream below. [block:api-header] { "title": "Event Handlers" } [/block] These methods are used to register listeners to respond to controller-driven events. Events start at the "hovered" (or focused) [Node](https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html). If that Node cannot respond to the event (e.g. if it does not have the appropriate listener installed), the event will bubble up the scene graph to that Node's parent, and so on, until a Node that can handle the event is found. All events are also received by the [Controller](https://developer.viromedia.com/virocore/reference/com/viro/core/Controller.html), which provides a centralized place to respond to all events regardless of what Nodes they targeted. [Node.setClickListener(ClickListener)][1] Click events are fired when the user taps while focused on a Node. [Node.setDragListener(DragListener)][2] Drag events are fired when a Node is being dragged by the user; that is, when the user performs a click down on a Node, holds that click, and then physically moves the controller (or tilts the headset). The view will automatically drag in VR, and as it does so, the DragListener event callback is continually triggered with the latest 3D location of the object. It is also important to note that the DragListener must be assigned to a Node to make that Node draggable. [Node.setHoverListener(HoverListener)][3] Hover events are fired when the user moves his or her reticle over a Node, or stops hovering over a Node. [Node.setFuseListener(FuseListener)][4] Fuse events are fired when the user hovers his or her reticle over the Node and remain hovered for `timeToFuse` milliseconds. The `timeToFuse` parameter is optional and is defaulted to 2000ms. This parameter is set via [Node.setTimeToFuse(float)](https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setTimeToFuse(float)). [Node.setTouchpadTouchListener(TouchpadTouchListener)][5] [Node.setTouchpadSwipeListener(TouchpadSwipeListener)][6] [Node.setTouchpadScrollListener(TouchpadScrollListener)][7] Touch, swipe, and scroll events are fired a Node is touched, swiped, or scrolled using a *touchpad* by the user; that is, when the user performs an action on a touchpad while hovering on top of the targeted Node. For the scroll listener, the distance the user has scrolled by is given as a unit ratio of the touch pad from 0.0 to 1.0 for both X and Y coordinates. These events are mainly used by the Gear VR platform, which features a touchpad on the headset. [Node.setGesturePinchListener(GesturePinchListener)][8] [Node.setGestureRotateListener(GestureRotateListener)][9] Gesture pinch and rotate events are fired when the user uses multitouch to 'pinch' over a Node or 'swivel' over the Node to create a rotation. These events are used by AR platforms, where the controller is the screen. [1]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setClickListener(com.viro.core.ClickListener) [2]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setDragListener(com.viro.core.DragListener) [3]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setHoverListener(com.viro.core.HoverListener) [4]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setFuseListener(com.viro.core.FuseListener) [5]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setTouchpadTouchListener(com.viro.core.TouchpadTouchListener) [6]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setTouchpadSwipeListener(com.viro.core.TouchpadSwipeListener) [7]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setTouchpadScrollListener(com.viro.core.TouchpadScrollListener) [8]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setGesturePinchListener(com.viro.core.GesturePinchListener) [9]: https://developer.viromedia.com/virocore/reference/com/viro/core/Node.html#setGestureRotateListener(com.viro.core.GestureRotateListener) [block:api-header] { "title": "Supported Controllers" } [/block] At the very least,`Click` is guaranteed to be supported across all platforms. However, due to the physical limitations of controllers on each platform, certain events as shown below may not be supported. |Events|Daydream|GearVR|Android Cardboard| IOS Cardboard| iOS AR | Android AR | |:------|:----------:|:----------:|:----------:|:----------:|:----------:|:----------:| |Click| Supported|Supported |Supported |Supported | Supported | Supported | |Hover| Supported |Supported |Supported |Supported | Supported | Supported | |Drag| Supported|Supported |Supported |Not Supported | Supported | Supported | |Fuse| Supported|Supported |Supported |Not Supported | Not Supported | Not Supported | |Scroll| Supported|Not Supported |Not Supported |Not Supported | Not Supported | Not Supported | |Swipe| Supported|Supported |Not Supported |Not Supported | Not Supported | Not Supported | |Touch| Supported|Supported |Not Supported |Not Supported | Not Supported | Not Supported | |Pinch| Not Supported| Not Supported |Not Supported |Not Supported | Supported | Supported | |Rotate| Not Supported| Not Supported |Not Supported |Not Supported | Supported | Supported | Different types of controllers may result in different forms of interactivity or UI. For example, users can easily scroll through galleries with Daydream's touch pad, but additional UI buttons may be needed for Cardboard. [block:api-header] { "title": "Platform Specific Input Source Identifiers" } [/block] As mentioned above, a unique numeric source identifier that corresponds to an input source on the physical controller. This section will go through the mappings of sources for Cardboard, GearVR and Daydream. [block:image] { "images": [ { "image": [ "https://files.readme.io/4c75011-controller_cardboard.png", "controller_cardboard.png", 800, 511, "#747474" ], "caption": "Cardboard (Android & iOS)" } ] } [/block] [block:parameters] { "data": { "h-0": "Input Source Value", "h-1": "Description", "0-0": "1", "1-0": "2", "0-1": "Main Controller", "1-1": "Primary Cardboard Trigger" }, "cols": 2, "rows": 2 } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/a5b7f83-controller_gear_vr.png", "controller_gear_vr.png", 800, 511, "#747474" ], "caption": "GearVR" } ] } [/block] [block:parameters] { "data": { "h-0": "Input Source Value", "h-1": "Description", "0-0": "1", "0-1": "Main Controller", "1-0": "2", "1-1": "Gear Touch Pad", "2-0": "3", "2-1": "Gear Back Button" }, "cols": 2, "rows": 3 } [/block] [block:image] { "images": [ { "image": [ "https://files.readme.io/71bb4df-controller_daydream.png", "controller_daydream.png", 800, 511, "#747474" ], "caption": "Daydream" } ] } [/block] [block:parameters] { "data": { "h-0": "Input Source Value", "h-1": "Description", "0-0": "1", "1-0": "2", "2-0": "3", "3-0": "4", "4-0": "5", "5-0": "6", "0-1": "Main Controller", "1-1": "Daydream TouchPad", "2-1": "Daydream App Button", "3-1": "Daydream Home Button", "4-1": "Volume Up Button", "5-1": "Volume Down Button" }, "cols": 2, "rows": 6 } [/block] [block:api-header] { "title": "" } [/block]