DOCF-5908 - "UI Support" content model re-org

Packages/com.unity.inputsystem/Documentation~/TableOfContents.md

@@ -133,8 +133,32 @@
     * [Use an existing input device to create a layout](hid-create-custom-layout-existing.md)
     * [Use a custom class to create a layout](hid-create-custom-layout-class.md)
   * [Supported devices reference](supported-devices-reference.md)
-* [UI support](UISupport.md)
-  * [On-screen Controls](OnScreen.md)
+* [UI input](ui-input.md)
+  * [Supported UI systems](supported-ui-systems.md)
+    * [Understand UI system compatibility](understand-ui-compatibility.md)
+    * [Using UI Input Module for UI support](using-ui-input-module.md)
+      * [Introduction to the UI Input Module](introduction-ui-input-module.md)
+      * [Supported input types in the UI Input Module](supported-ui-input-types.md)
+        * [Pointer input UI support](supported-ui-input-types-pointer.md)
+        * [Navigation input UI support](supported-ui-input-types-navigation.md)
+        * [Tracked input UI support](supported-ui-input-types-tracked.md)
+      * [Access the UI Input Module](access-ui-input-module.md)
+      * [UI Input Module component reference](ui-input-module-reference.md)
+    * [Use IMGUI alongside the Input System package](use-imgui-alongside-input-system.md)
+  * [Configure UI Input Actions](configure-ui-input-action-map.md)
+  * [UI Action Map reference](ui-action-map-reference.md)
+  * [Handling input target ambiguity](handling-input-target-ambiguity.md)
+  * [Virtual Mouse for UI cursor control](virtual-mouse-ui-cursor-control.md)
+    * [Introduction to Virtual Mouse for UI cursor control](introduction-virtual-mouse.md)
+    * [Configure a Virtual Mouse for UI input](configure-virtual-mouse-input.md)
+  * [Multiplayer UI input](multiplayer-ui-input.md)
+    * [Introduction to multiplayer UI input](introduction-multiplayer-ui-input.md)
+    * [Configure multiplayer UI input](configure-multiplayer-ui-input.md)
+  * [On-screen Controls](on-screen-controls.md)
+    * [Introduction to on-screen Controls](introduction-on-screen-controls.md)
+    * [Create an on-screen button Control](create-on-screen-button-control.md)
+    * [Create an on-screen stick Control](create-on-screen-stick-control.md)
+    * [Create a custom on-screen Control](create-custom-on-screen-control.md)
 * [Editor Features](EditorFeatures.md)
   * [Using Input in the Editor](UseInEditor.md)
   * [Debugging](debugging.md)

Packages/com.unity.inputsystem/Documentation~/access-ui-input-module.md

@@ -0,0 +1,13 @@
+# Access the UI Input Module component
+
+The UI Input Module is a component that passes input actions from the Input System to the UI in your scene. 
+
+You must add the UI Input Module to a GameObject in your scene, so that the UI can receive input from the Input System. To do this:
+
+1. Create a new empty GameObject
+2. Click [**Add Component**](https://docs.unity3d.com/Manual/UsingComponents.html) in the Inspector
+3. In the search field displayed, type `Input System UI Input Module`
+4. Select **Input System UI Input Module** to add it to the GameObject.
+
+
+![InputSystemUIInputModule](Images/InputSystemUIInputModuleAdd.png)

Packages/com.unity.inputsystem/Documentation~/configure-multiplayer-ui-input.md

@@ -0,0 +1,14 @@
+# Configure multiplayer UI input
+
+To enable multiplayer UI input:
+
+1. Replace the project’s [Event System](https://docs.unity3d.com/Manual/script-EventSystem.html) component with the Input System's [Multiplayer Event System](../api/UnityEngine.InputSystem.UI.MultiplayerEventSystem.html) component.
+
+
+For information on how to automatically configure the player's UI Input Module to use actions from the [Player Input](player-input-component.md) component, refer to documentation on [Player Input: UI Input](player-input-component.md#ui-input) to learn how.
+
+To define mouse UI input behaviour for a Multiplayer Event System:
+
+1. Create an empty GameObject.
+1. In the Multiplayer Event System, set **Player Root** to the new GameObject.
+1. For any UI selectables that you want the Multiplayer Event System to interact with, move their GameObjects in the hierarchy so that they are child GameObjects of the **Player Root** GameObject.

Packages/com.unity.inputsystem/Documentation~/configure-ui-input-action-map.md

@@ -0,0 +1,36 @@
+# Configure the UI input action map
+
+The default [project-wide actions asset](./about-project-wide-actions.md) comes with a built-in action map named **UI**, which contains all the actions required for UI interaction. To configure the bindings for these actions, use the [Actions Editor](./actions-editor.md). 
+
+To open the UI action map:
+
+1. Go to **Project Settings > Input System Package**
+1. In the **Action Maps** column, select **UI**.
+
+![ProjectSettingsInputActionsUIActionMap](Images/ProjectSettingsInputActionsUIActionMap.png)
+
+The default [project-wide actions asset](./about-project-wide-actions.md) comes with all the required actions to be compatible with UI Toolkit and Unity UI.
+
+## Modify UI input actions
+
+You can modify, add, or remove bindings to the named actions in the UI action map to suit your project. However, to remain compatible with UI Toolkit, you must not change:
+
+* The name of the action map (**UI**)
+* The names of the actions it contains
+* Their respective **Action Types**.
+
+To see the specific actions and types that the [UI Input Module](../api/UnityEngine.InputSystem.UI.InputSystemUIInputModule.html) class expects, refer to the [UI action map reference](ui-action-map-reference).
+
+## Reset the UI action map
+
+>[!IMPORTANT]
+>These instructions reset both the UI action map and the Player action map to their default bindings.
+
+To reset the UI action map to its default bindings:
+
+1. Open the **More (⋮)** menu, at the top-right of the Input Actions Editor window.
+1. Select **Reset**.
+
+To restore functionality to runtime `OnGUI` methods, you can change the **Active Input Handling** setting to **Both**. Doing this means that Unity processes the input twice, which could introduce a small performance impact.
+
+This only affects runtime (play mode) `OnGUI` methods. Editor GUI code is unaffected and continues to receive input events.

Packages/com.unity.inputsystem/Documentation~/configure-virtual-mouse-input.md

@@ -0,0 +1,27 @@
+# Configure a Virtual Mouse for UI input
+To configure the Virtual Mouse component with the Unity UI system:
+
+1. Create a UI GameObject with an **Image** component. This GameObject is the mouse pointer. It can help to rename it "_Pointer_".
+2. Parent the pointer GameObject as a child of your **Canvas** GameObject that contains the UI which the cursor should operate on.
+3. Set the anchor position of the GameObject's `RectTransform` to the bottom left.
+4. Ensure your pointer GameObject is the last child of the Canvas so that the cursor draws on top of everything else.
+5. Add a **Virtual Mouse** component to the GameObject.
+6. Drag the **Image** component of the pointer GameObject into the **Cursor Graphic** field of the Virtual Mouse component.
+7. Drag the **Rect Transform** component of the pointer GameObject to the **Cursor Transform** field of the Virtual Mouse component.
+
+>[!NOTE]
+> Do not set up gamepads and joysticks for [navigation input](supported-ui-input-types-navigation.md) while using the Virtual Mouse component. If, for example, the Virtual Mouse component is configured to receive input from gamepads, and `Move`, `Submit`, and `Cancel` on the UI Input Module are also linked to the gamepad, then the UI receives input from the gamepad on two channels, and triggers the input twice.
+
+## Control the virtual mouse via the Input System
+
+To configure the input to drive the virtual mouse, do one of the following:
+
+* Add bindings on the various actions (such as **Stick Action**).
+* Enable **Use Reference** and link existing actions from an input actions asset.
+
+## Control the system mouse cursor with the virtual mouse
+
+To set the virtual mouse to control the system mouse cursor:
+1. Set [Cursor Mode](../api/UnityEngine.InputSystem.UI.VirtualMouseInput.html#UnityEngine_InputSystem_UI_VirtualMouseInput_cursorMode) to **Hardware Cursor If Available**. 
+
+In this mode, the **Cursor Graphic** is hidden when a system mouse is present, and you use [Mouse.WarpCursorPosition](../api/UnityEngine.InputSystem.Mouse.html#UnityEngine_InputSystem_Mouse_WarpCursorPosition_UnityEngine_Vector2_) to move the system mouse cursor instead of the software cursor. The transform linked through **Cursor Transform** is not updated.

Packages/com.unity.inputsystem/Documentation~/create-custom-on-screen-control.md

@@ -1 +1,31 @@
-# Create a custom on-screen control 
+# Create a custom on-screen control
+
+To create custom [input controls](Controls.md), you can extend [`OnScreenControl`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html).
+
+The following sample demonstrates one way to do this:
+
+```CSharp
+    [AddComponentMenu("Input/On-Screen Button")]
+    public class OnScreenButton : OnScreenControl, IPointerDownHandler, IPointerUpHandler
+    {
+        public void OnPointerUp(PointerEventData data)
+        {
+            SendValueToControl(0.0f);
+        }
+
+        public void OnPointerDown(PointerEventData data)
+        {
+            SendValueToControl(1.0f);
+        }
+
+        [InputControl(layout = "Button")]
+        [SerializeField]
+        private string m_ControlPath;
+
+        protected override string controlPathInternal
+        {
+            get => m_ControlPath;
+            set => m_ControlPath = value;
+        }
+    }
+```

Packages/com.unity.inputsystem/Documentation~/create-on-screen-button-control.md

@@ -0,0 +1,11 @@
+# Create an on-screen button control
+
+To create an on-screen button:
+
+1. Add a UI `Button` object.
+2. Add the [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) component to it.
+3. Set the [controlPath](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_controlPath) to refer to a [`ButtonControl`](../api/UnityEngine.InputSystem.Controls.ButtonControl.html) (for example, `<Gamepad>/buttonSouth`). The type of device referenced by the control path determines the type of virtual device created by the component.
+
+![OnScreenButton](Images/OnScreenButton.png)
+
+The [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) component requires the target control to be a `Button` control. [`OnScreenButton`](../api/UnityEngine.InputSystem.OnScreen.OnScreenButton.html) sets the target control value to 1 when it receives a pointer-down (`IPointerDownHandler.OnPointerDown`) event, or 0 when it receives a pointer-up (`IPointerUpHandler.OnPointerUp`) event.

Packages/com.unity.inputsystem/Documentation~/create-on-screen-stick-control.md

@@ -0,0 +1,32 @@
+# Create an on-screen stick control
+
+To create an on-screen stick:
+
+1. Create a UI `Image` object.
+2. Add the [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) component to it.
+3. Set the [`controlPath`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_controlPath) to refer to a [`Vector2Control`](../api/UnityEngine.InputSystem.Controls.Vector2Control.html) (for example, `<Gamepad>/leftStick`). The type of device referenced by the control path determines the type of virtual device created by the component.
+
+![OnScreenStick](Images/OnScreenStick.png)
+
+The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) component requires the target control to be a `Vector2` control. [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) starts the movement of the stick control when it receives a pointer-down (`IPointerDownHandler.OnPointerDown`) event, and stops it when it receives a pointer-up (`IPointerUpHandler.OnPointerUp`) event.
+
+In-between, the stick moves according to the pointer being dragged (`IDragHandler.OnDrag`) within a box centered on the pointer-down screen point, and with an edge length  defined in the component's __Movement Range__ property. A movement range of 50, for example, means that the stick's on-screen area is 25 pixels up, down, left, and right of the pointer-down point on screen.
+
+If you want to be notified when the user starts and/or stops touching the on-screen stick, implement `IPointerDownHandler` and/or `IPointerUpHandler` on a component and add it to the stick `GameObject`.
+
+## Isolate stick controls
+
+The [`OnScreenStick`](../api/UnityEngine.InputSystem.OnScreen.OnScreenStick.html) simulates input events from the device specified in the [`OnScreenControl.control`](../api/UnityEngine.InputSystem.OnScreen.OnScreenControl.html#UnityEngine_InputSystem_OnScreen_OnScreenControl_control) property. To the Input System itself, these are normal events and can cause the paired device to change in games and applications where dynamic device switching is used, for example when the [`PlayerInput`](../api/UnityEngine.InputSystem.PlayerInput.html) component is used with the [`PlayerInput.neverAutoSwitchControlSchemes`](../api/UnityEngine.InputSystem.PlayerInput.html#UnityEngine_InputSystem_PlayerInput_neverAutoSwitchControlSchemes) propety set to false. As the stick is dragged around, the paired device will alternate between the device that owns the pointer (mouse, touch, pen etc) and the device from the control path, which can result in jittery movement of the on-screen stick.
+
+To fix this, enable **Use Isolated Input Actions**. This mode uses a local set of input action instances to drive interaction with the stick, and not the actions defined in the UI. The downside of this mode is that pointer actions will be duplicated in both the on-screen stick component and any input action assets being used to drive the UI. Note that if a set of bindings is not specified for the Pointer Down action and Pointer Move actions, the following defaults will be used:
+
+* Pointer Down action
+    - `<Mouse>/leftButton`
+    - `<Pen>/tip`
+    - `<Touchscreen>/touch*/press`
+    - `<XRController>/trigger`
+
+* Pointer Move action
+    - `<Mouse>/position`
+    - `<Pen>/position`
+    - `<Touchscreen>/touch*/position`

Packages/com.unity.inputsystem/Documentation~/handling-input-target-ambiguity.md

@@ -0,0 +1,41 @@
+# Handling input target ambiguity
+
+Understand how to manage ambiguities between input for your application's user interface (UI), and input for other parts of your application.
+
+>[!NOTE]
+>The Input System package includes a sample project called "**UI vs Game Input**". The sample demonstrates how to deal with ambiguities between inputs for UI and inputs for the game.
+
+## How Unity processes UI input
+
+Unity processes UI input through the same mechanisms as the input for the rest of your application. There's no automatic mechanism that prevents the UI and the rest of your code from consuming the same input (such as a mouse click).
+
+## Strategies for avoiding ambiguity
+
+Ambiguities can appear between, for example, code that responds to [`UI.Button.onClick`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.UI.Button.html#UnityEngine_UI_Button_onClick) and code that responds to [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) for an action bound to `<Mouse>/leftButton`.
+
+Whether such ambiguities exist depends on how you implement the UI and the UI input. The following UI implementation strategies are examples of how you can avoid these ambiguities:
+
+* Perform all interaction through UI elements. Render a scene in the background, but perform all interaction through UI events (including those such as 'background' clicks on the `Canvas`).
+* Place UI over a 2D/3D scene, but don’t let the user directly interact with the UI.
+* Place UI over a 2D/3D scene, but create a clear "mode" switch that determines whether interaction applies to the UI or the scene. For example, a first-person game on desktop might employ a [cursor lock](https://docs.unity3d.com/ScriptReference/Cursor-lockState.html) which directs input to the game when it is engaged, and to the UI when it is not engaged.
+
+There are also specific ambiguities that can arise for [pointer input](supported-ui-input-types-pointer.md) and [navigation input](supported-ui-input-types-navigation.md).
+
+## Handling pointer input ambiguities
+
+Input from pointers (mice, touchscreens, pens) can be ambiguous depending on whether or not the pointer is over a UI element when initiating an interaction. For example, if there is a button on screen, then clicking on the button may lead to a different outcome than clicking outside of the button and within the game scene.
+
+If all pointer input is handled via UI events, no ambiguities arise as the UI will implicitly route input to the respective receiver. If, however, input within the UI is handled via UI events and input in the game is handled via [actions](./actions.md), pointer input will by default lead to *both* being triggered.
+
+The easiest way to resolve such ambiguities is to respond to in-game actions by [polling](RespondingToActions.md#polling-actions) from inside [`MonoBehaviour.Update`](https://docs.unity3d.com/ScriptReference/MonoBehaviour.Update.html) methods and using [`EventSystem.IsPointerOverGameObject`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobject#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) to find out whether the pointer is over UI or not. Another way is to use [`EventSystem.RaycastAll`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobj#UnityEngine_EventSystems_EventSystem_RaycastAll_UnityEngine_EventSystems_PointerEventData_System_Collections_Generic_List_UnityEngine_EventSystems_RaycastResult__) to determine if the pointer is currently over UI.
+
+>[!NOTE]
+>Calling [`EventSystem.IsPointerOverGameObject`](https://docs.unity3d.com/Packages/[email protected]/api/UnityEngine.EventSystems.EventSystem.html?q=ispointerovergameobject#UnityEngine_EventSystems_EventSystem_IsPointerOverGameObject) from within [`InputAction`](../api/UnityEngine.InputSystem.InputAction.html) callbacks such as [`InputAction.performed`](../api/UnityEngine.InputSystem.InputAction.html#UnityEngine_InputSystem_InputAction_performed) lead to a warning. The UI updates separately after input processing, so UI state corresponds to that of the last frame/update while input is being processed.
+
+## Handling navigation input ambiguities
+
+For navigation-type devices such as gamepads, joysticks, and keyboards, you must decide explicitly whether to use input for the UI's `Move`, `Submit`, and `Cancel` inputs or for the game. This can be done by either splitting control on a device or by having an explicit mode switch.
+
+Splitting input on a device is done by simply using certain controls for operating the UI while using others to operate the game. For example, you could use the d-pad on gamepads to operate UI selection while using the sticks for in-game character control. This setup requires adjusting the bindings used by the UI actions accordingly.
+
+An explicit mode switch is implemented by temporarily switching to UI control while suspending in-game actions. For example, the left trigger on the gamepad could bring up an item selection wheel which then puts the game in a mode where the sticks are controlling UI selection, the A button confirms the selection, and the B button closes the item selection wheel. No ambiguities arise as in-game actions will not respond while the UI is in the "foreground".