UI Toolkit uses an event systemA way of sending events to objects in the application based on input, be it keyboard, mouse, touch, or custom input. The Event System consists of a few components that work together to send events. More info
See in Glossary to handle input and send events to all active panels.
The UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Toolkit’s event system can receive events from IMGUI and the legacy Input ManagerSettings where you can define all the different input axes, buttons and controls for your project. More info
See in Glossary. Navigation events are created from axes defined in the legacy Input Manager. Other events come from the IMGUI event queue.
Except in specific instances, you don’t need to add a component to the sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary to use the event system.
If the Scene uses more than one Panel Settings asset, the event system sends pointer events to their panels according to their Sort Order. A pointer event propagates through the panels until a panel reacts to it.
The first panel that uses an event to affect the focused element becomes the focused panel for the event system. That panel continues to receive keyboard events until another event causes a different panel to become the focused panel.
Note: Stopping an event’s propagation and giving an element focus are two separate things. For example, when you click a button, it stops the propagation and allows only the button to react to being pressed, but it doesn’t prevent the other default actions for the click, such as giving focus to the button or, in general, any focusable element that is clicked.
You can use UI Toolkit UI Documents and uGUI components at the same time.
When you add your first uGUI element in the Scene, an Event System and a Standalone Input Module are automatically added to the Scene:
The Event System reads the scene and executes events, whereas the Standalone Input Module interprets the input and requests event execution. You can replace the Standalone Input Module with other input modules. Other input modules change what input is consumed, but all events still go through the Event System to execute.
UI Toolkit uses the sorting order of the Panel and compares it with the sorting order of uGUI canvases and other valid raycast targets, to decide whether pointer events should be sent to a UI Toolkit element or to a uGUI object, or to something else in the scene. Similarly, UI Toolkit sets the Event System’s currentSelectedGameObject to make sure that when a UI Toolkit panel wants to get focus, it removes the focus from other uGUI objects, and when a uGUI object becomes selected, UI Toolkit panels automatically lose their focus.
To add the event system manually, select GameObject > UI > Event System.
When you use UI Toolkit (and uGUI) with different input systems, you need to choose different input module and event system.
The following table describes the required components and settings for each input system usage:
| Usage | Required components | Active Input Handling |
|---|---|---|
| UI Toolkit elements with legacy Input Manager | Uses the default event system. No scene component is required. | Input Manager (Old). |
| UI Toolkit elements with Input System package | An Input System UI Input Module and an Event System components. | Input System Package (New) |
| UI Toolkit elements and uGUI components with legacy Input Manager | A Standalone Input Module and an Event System components. | Input Manager (Old) or Both. |
| UI Toolkit elements and uGUI components with Input System package | An Input System UI Input Module and an Event System components. | Input System Package (New) or Both |
You can find the Active Input Handling setting in Edit > Project Settings > Player > Active Input Handling.
You can use UI Toolkit with the Input System package: