Manipulators

To separate your event logic from your UI code, use a manipulator to handle events. Manipulators are state machines that handle user interaction with UI elements. They store, register, and unregister event callbacks. A manipulator streamlines setting up that user interaction, so you don’t have to handle each callback one by one. To handle events, use or inherit from one of the manipulators that UI Toolkit supports.

To create and use a manipulator:

Define a dedicated class that inherits from a manipulator class supported by UI Toolkit. This class encapsulates the event-handling logic tailored to the specific user interaction you want to manage.
Within the class, implement methods to respond to relevant interactions, such as mouse clicks or drags. These methods capture and process the necessary information to execute the desired behavior.
When you have finished designing the manipulator class, instantiate it and attach it to the target UI element. This attachment lets the manipulator intercept and manage the specified events, orchestrating user interactions while maintaining clear separation from your UI code.

Supported manipulators

The following table lists the supported manipulator classes:

Manipulator	Inherits from	描述
`Manipulator`		Base class for all provided manipulators.
`KeyboardNavigationManipulator`	`Manipulator`	Handles translation of device-specific input events to higher-level navigation operations with a keyboard.
`MouseManipulator`	`Manipulator`	Handles mouse input. Has a list of activation filters.
`ContextualMenuManipulator`	`MouseManipulator`	Displays a contextual menu when the user clicks the right mouse button or presses the menu key on the keyboard.
`PointerManipulator`	`MouseManipulator`	Handles pointer input. Has a list of activation filters.
`Clickable`	`PointerManipulator`	Tracks mouse events on an element, and identifies when a click occurs, which is both a pointer press and release on the same element.

示例

The following examples demonstrate how to use manipulators to handle events. They do the following:

Inherit the manipulators from the PointerManipulators class, which handles mouse input.
Use the activators list to specify the conditions that activate the manipulator. For example, to activate the manipulator when the user clicks the left mouse button, add ManipulatorActivationFilter to the activators list with the button field set to MouseButton.LeftMouse.
Use the target property to access the element that the manipulator is attached to.
Override the RegisterCallbacksOnTarget and UnregisterCallbacksFromTarget methods to register and unregister the event callbacks.

Create an ExampleDragger manipulator

The following example creates a manipulator that moves an element when you click and drag it:

[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/ui-toolkit-manual-code-examples/manipulator/ExampleDragger.cs)]

Create an ExampleResizer manipulator

The following example creates a manipulator that resizes an element when you drag it:

[!code-cs[(Modules/UIElements/Tests/UIElementsExamples/Assets/ui-toolkit-manual-code-examples/manipulator/ExampleResizer.cs)]

Add or remove a manipulator

To add a manipulator to an element, use the AddManipulator method. To remove a manipulator from an element, use the RemoveManipulator method.

The following example adds and removes the ExampleDragger to a VisualElement:

// Create a VisualElement.
var myElement = new VisualElement();

// Add manipulators to the VisualElement.
myElement.AddManipulator(new ExampleDragger());

// Remove manipulators from the VisualElement.
myElement.RemoveManipulator<ExampleDragger>();

The following example adds the ExampleResizer to a VisualElement:

var box = new VisualElement()
{
    style =
    {
        left = 100,
        top = 100,
        width = 100,
        height = 100,
        backgroundColor = Color.red
    },
    pickingMode = PickingMode.Position,
};

box.AddManipulator(new ExampleResizer());

其他资源

Respond to events with custom controls

Synthesize and send events