MovableComponent
public final class MovableComponent extends Component
This Component can be attached to a single instance of an Entity. When attached, this Component will enable the user to translate the Entity by pointing and dragging on it.
Creating this Component with MovableComponent.createCustomMovable will create the Component but not move the attached Entity. It requires an EntityMoveListener which will provide suggested Poses from the system that an application can use to move the attached Entity. This should be used if the application wants to add custom logic for the Entity's movement. MovableComponent.createSystemMovable will create the Component and move the attached Entity when the user drags it to a position recommended by the system. MovableComponent.createAnchorable will create the Component, move the attached Entity when the user drags it, and also potentially reparent the Entity to a new AnchorSpace. This will occur if the user lets go of the Entity near a perception plane that matches the settings in the provided AnchorPlacement.
This component cannot be attached to an AnchorSpace or to the ActivitySpace. Calling Entity.addComponent to an Entity with these types will return false.
Summary
Public methods |
|
|---|---|
final void |
addMoveListener(@NonNull EntityMoveListener entityMoveListener)Adds a listener to the set of active listeners for the move events. |
final void |
addMoveListener(Adds a listener to the set of active listeners for the move events. |
static final @NonNull MovableComponent |
createAnchorable(Public factory function for creating a MovableComponent. |
static final @NonNull MovableComponent |
createCustomMovable(Public factory function for creating a MovableComponent. |
static final @NonNull MovableComponent |
createSystemMovable(@NonNull Session session, boolean scaleInZ)Public factory function for creating a MovableComponent. |
final @NonNull FloatSize3d |
getSize()The size of the move affordance in local space virtual meters. |
final void |
removeMoveListener(@NonNull EntityMoveListener entityMoveListener)Removes a listener from the set of active listeners for the move events. |
final void |
setSize(@NonNull FloatSize3d value)The size of the move affordance in local space virtual meters. |
Protected methods |
|
|---|---|
boolean |
Called by the framework when this component is being added to an |
void |
Called by the framework when this component is being removed from an |
Public methods
addMoveListener
public final void addMoveListener(@NonNull EntityMoveListener entityMoveListener)
Adds a listener to the set of active listeners for the move events. The listener will be invoked regardless of whether the Entity is being moved by the system or the user.
The listener is invoked on the main thread.
| Parameters | |
|---|---|
@NonNull EntityMoveListener entityMoveListener |
The move event listener to set. |
addMoveListener
public final void addMoveListener(
@NonNull Executor executor,
@NonNull EntityMoveListener entityMoveListener
)
Adds a listener to the set of active listeners for the move events. The listener will be invoked regardless of whether the Entity is being moved by the system or the user.
The listener is invoked on the provided Executor. If the app intends to modify the UI elements/views during the callback, the app should provide the thread executor that is appropriate for the UI operations. For example, if the app is using the main thread to render the UI, the app should provide the main thread (Looper.getMainLooper()) executor. If the app is using a separate thread to render the UI, the app should provide the executor for that thread.
| Parameters | |
|---|---|
@NonNull Executor executor |
The executor to run the listener on. |
@NonNull EntityMoveListener entityMoveListener |
The move event listener to set. |
createAnchorable
public static final @NonNull MovableComponent createAnchorable(
@NonNull Session session,
@NonNull Set<@NonNull AnchorPlacement> anchorPlacement,
boolean disposeParentOnReAnchor
)
Public factory function for creating a MovableComponent.
This Component can be attached to a single instance of an Entity. When attached, this Component will enable the user to translate the Entity by pointing and dragging on it.
When created with this function the MovableComponent will move and potentially Anchor the Entity. When anchored a new AnchorSpace will be created and set as the parent of the Entity. If the entity is moved off of a created AnchorSpace it will be reparented to the ActivitySpace. An EntityMoveListener can be attached to receive callbacks when the Entity is being moved and to see if it was reparented to an AnchorSpace.
This component cannot be attached to an AnchorSpace or to the ActivitySpace. Calling Entity.addComponent to an Entity with these types will return false.
This functionality requires Session to be called with androidx.xr.runtime.PlaneTrackingMode.HORIZONTAL_AND_VERTICAL. This configuration requires that the SCENE_UNDERSTANDING_COARSE Android permission is granted. If not granted, the anchorable functionality will be disabled, and the element will behave as if the anchoring functionality was not applied.
| Parameters | |
|---|---|
@NonNull Session session |
The |
@NonNull Set<@NonNull AnchorPlacement> anchorPlacement |
A Set containing different |
boolean disposeParentOnReAnchor |
A Boolean, which if set to true, when an Entity is moved off of an |
| Returns | |
|---|---|
@NonNull MovableComponent |
MovableComponent instance. |
| Throws | |
|---|---|
IllegalArgumentException |
if created with an Empty Set of for anchorPlacement |
createCustomMovable
public static final @NonNull MovableComponent createCustomMovable(
@NonNull Session session,
boolean scaleInZ,
Executor executor,
@NonNull EntityMoveListener entityMoveListener
)
Public factory function for creating a MovableComponent.
This Component can be attached to a single instance of an Entity. When attached, this Component will enable the user to translate the Entity by pointing and dragging on it.
When created with this function the MovableComponent will not move or rescale the Entity, but it could be done using the EntityMoveListener.onMoveUpdate callback.
This component cannot be attached to an AnchorSpace or to the ActivitySpace. Calling Entity.addComponent to an Entity with these types will return false.
| Parameters | |
|---|---|
@NonNull Session session |
The |
boolean scaleInZ |
A Boolean which tells the system to update the scale of the Entity as the user moves it closer and further away. This is mostly useful for Panel auto-rescaling with distance. |
Executor executor |
The executor to run the listener on. If set to null, the listener will be invoked on the main thread. |
@NonNull EntityMoveListener entityMoveListener |
A move event listener for the event. The application should set the entity position and scale as desired using |
| Returns | |
|---|---|
@NonNull MovableComponent |
MovableComponent instance. |
createSystemMovable
public static final @NonNull MovableComponent createSystemMovable(@NonNull Session session, boolean scaleInZ)
Public factory function for creating a MovableComponent.
This Component can be attached to a single instance of an Entity. When attached, this Component will enable the user to translate the Entity by pointing and dragging on it.
When created with this function the MovableComponent will move and rescale the Entity. EntityMoveListener can be attached to received callbacks when the Entity is being moved.
This component cannot be attached to an AnchorSpace or to the ActivitySpace. Calling Entity.addComponent to an Entity with these types will return false.
| Parameters | |
|---|---|
@NonNull Session session |
The |
boolean scaleInZ |
A Boolean which tells the system to update the scale of the Entity as the user moves it closer and further away. This is mostly useful for Panel auto-rescaling with distance. |
| Returns | |
|---|---|
@NonNull MovableComponent |
MovableComponent instance. |
getSize
public final @NonNull FloatSize3d getSize()
The size of the move affordance in local space virtual meters. This property determines the size of the bounding box that is used to draw the draggable move affordances around the Entity. This property can be modified if the move affordance needs to be larger or smaller than the Entity itself.
When attaching this component to an entity, the apps may update this value to appropriate new value, such as the size of the entity this component is being added to. If apps don't set this value, the component will try to use the entity's dimensions as value for this property where applicable, or default to (1 x 1 x 1).
removeMoveListener
public final void removeMoveListener(@NonNull EntityMoveListener entityMoveListener)
Removes a listener from the set of active listeners for the move events.
| Parameters | |
|---|---|
@NonNull EntityMoveListener entityMoveListener |
The move event listener to remove. |
setSize
public final void setSize(@NonNull FloatSize3d value)
The size of the move affordance in local space virtual meters. This property determines the size of the bounding box that is used to draw the draggable move affordances around the Entity. This property can be modified if the move affordance needs to be larger or smaller than the Entity itself.
When attaching this component to an entity, the apps may update this value to appropriate new value, such as the size of the entity this component is being added to. If apps don't set this value, the component will try to use the entity's dimensions as value for this property where applicable, or default to (1 x 1 x 1).
Protected methods
onAttach
protected boolean onAttach(@NonNull Entity entity)
Called by the framework when this component is being added to an Entity.
This method is triggered when Entity.addComponent is invoked. Implementations should override this method to perform setup logic or to validate if the component is compatible with the provided entity.
| Returns | |
|---|---|
boolean |
|
onDetach
protected void onDetach(@NonNull Entity entity)
Called by the framework when this component is being removed from an Entity.
This method is triggered when Entity.removeComponent is invoked. Implementations should override this method to release resources or undo any changes made during onAttach.