Class PanelSimulator

Management of Editor or Runtime panels used by tests. Allows for the simulation of time passing, sending events, and updating the panel in a synchronous manner. Creation and ownership of the panel is performed by the child classes.

Inheritance

object

PanelSimulator

EditorPanelSimulator

EditorWindowPanelSimulator

RuntimePanelSimulator

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: UnityEngine.UIElements.TestFramework

Assembly: Unity.UI.TestFramework.Runtime.dll

Syntax

public abstract class PanelSimulator

Properties

currentTime

The simulated time in seconds currently used by the panel. Simulates Time.RealtimeSinceStartup. Use IncrementCurrentTimeMs(long) or IncrementCurrentTime(double) to increment the time.

Declaration

public static double currentTime { get; }

Property Value

Type	Description
double

currentTimeMs

The simulated time in milliseconds currently used by the panel. Simulates Time.RealtimeSinceStartup. Use IncrementCurrentTimeMs(long) or IncrementCurrentTime(double) to increment the time.

Declaration

public static long currentTimeMs { get; }

Property Value

Type	Description
long

needsRendering

Whether rendering during a FrameUpdate(), FrameUpdateMs(long), or FrameUpdate(double) for the panel must be done via a repaint event. Defaults to false.

Declaration

public bool needsRendering { get; set; }

Property Value

Type	Description
bool

Remarks

Set this to true if the panel requires either ImmediateModeElement rendering or an IMGUIContainer's OnGUI logic.

panel

The panel associated to the instance of PanelSimulator.

Declaration

public IPanel panel { get; }

Property Value

Type	Description
IPanel

panelName

Returns the name of the panel.

Declaration

public string panelName { get; }

Property Value

Type	Description
string

pixelsPerPoint

The pixels per point scaling of the panel. Defaults to 1.

Declaration

public float pixelsPerPoint { get; set; }

Property Value

Type	Description
float

rootVisualElement

The effective root VisualElement of the panel.

Declaration

public VisualElement rootVisualElement { get; }

Property Value

Type	Description
VisualElement

Remarks

Use this property to add elements to or query the UI of the panel.

timePerSimulatedFrame

The amount of time in seconds to increment the simulated time. The simulated time is incremented by this amount through calls to IncrementCurrentTimeMs(long), IncrementCurrentTime(double), FrameUpdate() or calls to the Event simulation utility methods. Default is 0.2 seconds.

Declaration

public double timePerSimulatedFrame { get; set; }

Property Value

Type	Description
double

Remarks

This value is not automatically reset within the test fixture. Call ResetTimePerSimulatedFrameToDefault() when the value that was set is no longer required.

timePerSimulatedFrameMs

Gets or sets timePerSimulatedFrame in milliseconds. The simulated time is incremented by this amount through calls to IncrementCurrentTimeMs(long), IncrementCurrentTime(double), FrameUpdate() or calls to the Event simulation utility methods. Defaults to 200milliseconds.

Declaration

public long timePerSimulatedFrameMs { get; set; }

Property Value

Type	Description
long

Remarks

This value is not automatically reset within the test fixture. Call ResetTimePerSimulatedFrameToDefault() when the value that was set is no longer required.

Methods

Click(VisualElement, MouseButton, EventModifiers)

Sends a single click to the ve's panel.

Declaration

public void Click(VisualElement ve, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
VisualElement	ve	VisualElement whose panel should receive the events.
MouseButton	button	The MouseButton for the events.
EventModifiers	modifiers	The EventModifiers for the events.

Remarks

The position of the click is the center of the ve's worldBound. Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

Click(Vector2, MouseButton, EventModifiers)

Sends a single click to the panel.

Declaration

public void Click(Vector2 position, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
Vector2	position	The Absolute position for the events.
MouseButton	button	The MouseButton for the events.
EventModifiers	modifiers	The EventModifiers for the events.

Remarks

The position of the click is the center of the ve's worldBound. Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

DoubleClick(VisualElement, MouseButton, EventModifiers)

Sends a double click to the panel.

Declaration

public void DoubleClick(VisualElement ve, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
VisualElement	ve	VisualElement whose panel should receive the events.
MouseButton	button	The MouseButton for the events.
EventModifiers	modifiers	The EventModifiers for the events.

Remarks

The position of the click is the center of the ve's worldBound. Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

DoubleClick(Vector2, MouseButton, EventModifiers)

Sends a double click to the panel.

Declaration

public void DoubleClick(Vector2 position, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
Vector2	position	The Absolute position for the events.
MouseButton	button	The MouseButton for the events.
EventModifiers	modifiers	The EventModifiers for the events.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

DragAndDrop(Vector2, Vector2, MouseButton, EventModifiers)

Sends a PointerDownEvent, incremental PointerMoveEvents, and a PointerUpEvent`, in that order, to the panel.

Declaration

public void DragAndDrop(Vector2 positionFrom, Vector2 positionTo, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
Vector2	positionFrom	The Absolute starting position of the Mouse.
Vector2	positionTo	The Absolute final position to move the Mouse to.
MouseButton	button	The MouseButton for the events.
EventModifiers	modifiers	The EventModifiers for the events.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

ExecuteCommand(string)

Sends an ExecuteCommandEvent for the specified commandName to the panel.

Declaration

public void ExecuteCommand(string commandName)

Parameters

Type	Name	Description
string	commandName	The name of the command to execute.

Remarks

ExecuteCommandEvent are only officially supported in Editor (not Runtime). The event will be dispatched to the focused element. Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

FrameUpdate()

Increments the simulated time by the amount specified in timePerSimulatedFrame and then performs a FrameUpdate(double).

Declaration

public void FrameUpdate()

See Also

FrameUpdate(double)

FrameUpdateMs(long)

FrameUpdate(double)

Performs a frame update of the panel.

Declaration

public abstract void FrameUpdate(double time)

Parameters

Type	Name	Description
double	time	The amount of time in seconds to increment the simulated time.

Remarks

This method simulates yielding a frame by the following:

- Updates the scheduler and the panel's visual tree updaters.

- Advances the time by the amount specified in time.

- When needsRendering is true, it triggers rendering for the panel's `ImmediateModeElement` and invokes `IMGUIContainer`'s `OnGUI` with a Repaint Event.

See Also

FrameUpdate()

FrameUpdateMs(long)

FrameUpdateMs(long)

Increments the simulated time by the amount specified in timeMs (in milliseconds) and then performs a FrameUpdate(double).

Declaration

public void FrameUpdateMs(long timeMs)

Parameters

Type	Name	Description
long	timeMs	The amount of time in milliseconds to increment the simulated time.

See Also

FrameUpdate()

FrameUpdate(double)

GetDefaultPanelSize()

The default size of the panel. Set to (500.0f, 500.0f).

Declaration

public static Vector2 GetDefaultPanelSize()

Returns

Type	Description
Vector2	Vector2 representing the default size of the panel.

IncrementCurrentTime(double)

Increments the current simulated time by the provided time (in seconds) amount.

Declaration

public static void IncrementCurrentTime(double time)

Parameters

Type	Name	Description
double	time	The amount of time in seconds to increment the simulated time.

IncrementCurrentTimeMs(long)

Increments the current simulated time by the provided timeMs (in milliseconds) amount.

Declaration

public static void IncrementCurrentTimeMs(long timeMs)

Parameters

Type	Name	Description
long	timeMs	The amount of time in milliseconds to increment the simulated time.

KeyDown(KeyCode, EventModifiers)

Sends key events to the panel to simulate pressing down a given key.

Declaration

public void KeyDown(KeyCode keyCode, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
KeyCode	keyCode	The KeyCode for the event.
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

To send text, use TypingText(string, bool).

To send `Return`, use ReturnKeyPress(EventModifiers).

To send `KeypadEnter`, use KeypadEnterKeyPress(EventModifiers).

To send `Tab`, use TabKeyPress(EventModifiers).

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

KeyPress(KeyCode, EventModifiers)

Sends key events to the panel to simulate pressing a given key.

Declaration

public void KeyPress(KeyCode keyCode, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
KeyCode	keyCode	The KeyCode for the event.
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

For sending text, use the TypingText(string, bool) function.

For sending Return or KeypadEnter, use the ReturnKeyPress(EventModifiers) or KeypadEnterKeyPress(EventModifiers) function.

For sending Tab, use the TabKeyPress(EventModifiers) function.

KeyUp(KeyCode, EventModifiers)

Sends key events to the panel to simulate releasing a given key.

Declaration

public void KeyUp(KeyCode keyCode, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
KeyCode	keyCode	The KeyCode for the event.
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

To send text, use TypingText(string, bool).

To send `Return`, use ReturnKeyPress(EventModifiers).

To send `KeypadEnter`, use KeypadEnterKeyPress(EventModifiers).

To send `Tab`, use TabKeyPress(EventModifiers).

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

KeypadEnterKeyPress(EventModifiers)

Sends key events to the panel to simulate pressing the KeypadEnter key.

Declaration

public void KeypadEnterKeyPress(EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

MouseDown(VisualElement, MouseButton, EventModifiers)

Sends a PointerDownEvent to the panel.

Declaration

public void MouseDown(VisualElement ve, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
VisualElement	ve	VisualElement whose panel should receive the events.
MouseButton	button	The MouseButton for the event.
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

The position of the event is the center of the ve's worldBound. Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

MouseDown(Vector2, MouseButton, EventModifiers)

Sends a PointerDownEvent to the panel.

Declaration

public void MouseDown(Vector2 position, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
Vector2	position	The Absolute position for the event in ui coordinates.
MouseButton	button	The MouseButton for the event.
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

MouseMove(Vector2, EventModifiers)

Sends a PointerMoveEvent event to the panel.

Declaration

public void MouseMove(Vector2 positionTo, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
Vector2	positionTo	The Absolute position to move the Mouse to.
EventModifiers	modifiers	The EventModifiers for the events.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

MouseMove(Vector2, Vector2, EventModifiers)

Sends incremental PointerMoveEvents to the panel.

Declaration

public void MouseMove(Vector2 positionFrom, Vector2 positionTo, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
Vector2	positionFrom	The Absolute starting position of the Mouse.
Vector2	positionTo	The Absolute final position to move the Mouse to.
EventModifiers	modifiers	The EventModifiers for the events.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

MouseUp(VisualElement, MouseButton, EventModifiers)

Sends a PointerUpEvent to the panel.

Declaration

public void MouseUp(VisualElement ve, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
VisualElement	ve	VisualElement whose panel should receive the events.
MouseButton	button	The MouseButton for the event.
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

The position of the event is the center of the ve's worldBound. Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

MouseUp(Vector2, MouseButton, EventModifiers)

Sends a PointerUpEvent to the panel.

Declaration

public void MouseUp(Vector2 position, MouseButton button = MouseButton.LeftMouse, EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
Vector2	position	The Absolute position for the event.
MouseButton	button	The MouseButton for the event.
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

ResetCurrentTime()

Resets the current simulated time to zero.

Declaration

public static void ResetCurrentTime()

ResetTimePerSimulatedFrameToDefault()

Resets the timePerSimulatedFrame to its default value of 0.2 seconds. The timePerSimulatedFrame is not automatically reset within the test fixture. Call this function when the value that was set is no longer required.

Declaration

public void ResetTimePerSimulatedFrameToDefault()

ReturnKeyPress(EventModifiers)

Sends key events to the panel to simulate pressing the Return key.

Declaration

public void ReturnKeyPress(EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

ScrollWheel(Vector2, Vector2)

Sends a WheelEvent to the panel.

Declaration

public void ScrollWheel(Vector2 delta, Vector2 position)

Parameters

Type	Name	Description
Vector2	delta	The delta (scroll amount) for the event.
Vector2	position	The Absolute position for the event.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

TabKeyPress(EventModifiers)

Sends key events to the panel to simulate pressing the Tab key.

Declaration

public void TabKeyPress(EventModifiers modifiers = EventModifiers.None)

Parameters

Type	Name	Description
EventModifiers	modifiers	The EventModifiers for the event.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

TypingText(string, bool)

Sends key events to the panel to simulate typing the given text.

Declaration

public void TypingText(string text, bool useKeypad = false)

Parameters

Type	Name	Description
string	text	Text to type.
bool	useKeypad	Whether keypad KeyCodes (e.g. Keypad0, KeypadMinus) should be used instead of Alpha KeyCodes (e.g. Alpha0, Minus). Default is false.

Remarks

Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.

Only officially supports US layout keyboard and English language.

On Windows, Linux, and Mac runtime platforms, sends UI Toolkit key events.

On most other runtime platforms, sets the text using the `TouchScreenKeyboard`.

On Switch, does nothing to prevent freezing the device, please set it directly on the TextElement instead.

ValidateCommand(string)

Sends a ValidateCommandEvent for the specified commandName to the panel.

Declaration

public void ValidateCommand(string commandName)

Parameters

Type	Name	Description
string	commandName	The name of the command to execute.

Remarks

ValidateCommandEvent are only officially supported in Editor (not Runtime). The event will be dispatched to the focused element. Increments the current simulated time by timePerSimulatedFrame after dispatching each event. After all events have been sent, disposes of the events.