View
The View class acts as base for anything visual in an alloapp.
It manages a tree of sub-views; its bounds (transform and size) and a connection to a low-level entity.
Constructor
view = View(bounds)
Arguments
| Name | Type | Description |
|---|---|---|
| bounds | Bounds | The View’s Bounds component |
Returns
Nothing
Methods
view:awake ()
awake() is called when entity exists and is bound to this view.
Arguments
None
Returns
Nothing
view:sleep ()
sleep() is called when the entity for the view stops existing
Arguments
None
Returns
Nothing
view:isAwake ()
does the entity for this view exist and is bound to this view?
Arguments
None
Returns
Nothing
view:doWhenAwake (todo)
schedule something to do once the entity exists for this view. If it does, do the thing immediately.
Arguments
| Name | Type | Description |
|---|---|---|
| todo | function | The function to run |
Returns
Nothing
view:setGrabbable (grabbable, grabOptions)
If this is set to true, user can grab and move this view using the grip button.
Arguments
| Name | Type | Description |
|---|---|---|
| grabbable | Boolean | Set to true to enable the View to be grabbed. |
| grabOptions | table | A table of options for the grabbable component. See Components > grabbable |
Returns
Nothing
view:setPointable (pointable)
If this is set to true, the user’s cursor can land on this view, and you can receive pointer events. (See onPointerChanged and friends)
Arguments
| Name | Type | Description |
|---|---|---|
| pointable | Boolean | Set to true to enable the View to receive pointer events. |
Returns
Nothing
view:transformFromParent ()
The mat4 describing the transform from the parent view’s location to this view’s location, i e the location in the local coordinate system of the parent view.
Arguments
None
Returns
Nothing
view:transformFromWorld ()
The mat4 describing the transform in world coordinates, i e exactly where the view is in the world instead of where it is relative to its parent.
Arguments
None
Returns
Nothing
view:convertPointFromView (point, other)
Converts point from other view to this view If other is nil then the point is assumed to be in world space
Arguments
| Name | Type | Description |
|---|---|---|
| point | Point | A point in the coordinate system of other |
| other | View | The view to convert the point from |
Returns
Nothing
view:specification ()
The specification is used to describe the entity tree.
It is required to represent this view inside the Alloverse. In a subclass, call this implementation and then add/modify your own components.
Arguments
None
Returns
Nothing
view:updateComponents (changes, removals)
Asks the backend to update components on the server.
Use this to update things you’ve specified in :specification() but now want to change.
Arguments
| Name | Type | Description |
|---|---|---|
| changes | table | A table with the desired changes, for example: {transform={…}, collider={…}} |
| removals | table | A table with the keys of componets to remove, for example: {“collider”, “skeleton”} |
Returns
Nothing
view:markAsDirty (components)
Mark one or more Components as needing to have their server-side value updated ASAP
Arguments
| Name | Type | Description | |
|---|---|---|---|
| components | string | {string} | either a string with one component to update, or a list if string components |
Returns
Nothing
view:setTransform (transform)
Give this view an extra transform on top of the bounds. This is useful for things like adding a scale effect.
Arguments
| Name | Type | Description |
|---|---|---|
| transform | cpml.mat4 | The transformation matrix to set |
Returns
Nothing
view:resetPoseFromServer ()
If the entity backing this view has moved (e g grabbed by a user, or moved by an animation), this won’t automatically update the Pose in this view.
To make sure your local state reflects what is set in-world, you can call this method to update your Pose to match whatever transform is set on the entity in the world.
Arguments
None
Returns
Nothing
view:setBounds (bounds)
Sets the View’s bounds (pose and size) in the world.
Note that simply changing a View’s Bounds won’t affect its size or position in the world until this method is run.
Arguments
| Name | Type | Description |
|---|---|---|
| bounds | Bounds | the Bounds with which to define the Size and Pose of the parent View in the world. |
Returns
Nothing
view:moveBoundsToEdge (horizontal, vertical, depthwise)
Uses superview’s bounds’ size to find an edge and move to that edge.
Returns the bounds so you can continue modifying it. See Size:getEdge()
Arguments
| Name | Type | Description |
|---|---|---|
| horizontal | ??? | |
| vertical | ??? | |
| depthwise | ??? |
Returns
Nothing
view:addSubview (subview)
Adds a View as a child component to the given View.
Arguments
| Name | Type | Description |
|---|---|---|
| subview | View | The View to be added |
Returns
Nothing
view:removeFromSuperview ()
Detaches the View from its parent
Arguments
None
Returns
Nothing
view:findView (vid)
Finds and returns a subview of the given view ID.
Arguments
| Name | Type | Description |
|---|---|---|
| vid | string | The viewId of the View to be searched for. |
Returns
| Type | Description |
|---|---|
| View | The subview corresponding to the view ID. If no view was found, nil is returned. |
view:playSound (asset, playOptions)
Plays the given sound asset ASAP.
You can use playOptions to set things like loop_count, volume, length, offset etc…
Arguments
| Name | Type | Description |
|---|---|---|
| asset | Asset | The asset to play |
| playOptions | table | A table with valid keys for the “sound_effect” component |
Returns
Nothing
view:askToFocus (avatar)
Ask the client that uses the given avatar to focus this view to take text input.
In other words: display the keyboard for that avatar.
Arguments
| Name | Type | Description |
|---|---|---|
| avatar | ??? |
Returns
Nothing
view:defocus ()
Dismiss the keyboard for the user that has currently keyboard-focused this view.
Arguments
None
Returns
Nothing
view:onGrabStarted (hand)
Callback called when a user grabs this view in order to move it.
The server will then update self.entity.components.transform to match where the user wants to move it continuously. There is no callback for when the entity is moved.
Arguments
| Name | Type | Description |
|---|---|---|
| hand | Entity | The hand entity that started the grab |
Returns
Nothing
view:onGrabEnded (hand)
Callback called when a user lets go of and no longer wants to move it.
Arguments
| Name | Type | Description |
|---|---|---|
| hand | Entity | The hand entity that released the grab. |
Returns
Nothing
view:onPointerChanged (pointer)
Callback for when a hand is interacting with a view.
NOTE: You must set view:setPointable(true), or the user’s cursor will just fall right through this view!
This is a catch-all callback; there is also onPointerEntered, onPointerMoved, onPointerExited, onTouchDown and onTouchUp if you want to react only to specific events.
Arguments
| Name | Type | Description |
|---|---|---|
| pointer | table | A table with keys (see below). |
The pointer table’s keys are as follows:
hand: The hand entity that is doing the pointingstate: “hovering”, “outside” or “touching”touching: bool, whether the hand is currently doing a poke on this viewpointedFrom: a vec3 in world coordinate space with the coordinates of the finger tip of the hand pointing at this view.pointedTo: the point on this view that is being pointed at (again, in world coordinates). |
Returns
Nothing
view:onPointerEntered (pointer)
Callback for when a hand’s pointer ray entered this view.
The state in pointer is now “hovering”
Arguments
| Name | Type | Description |
|---|---|---|
| pointer | table | see onPointerChanged. |
Returns
Nothing
view:onPointerMoved (pointer)
Callback for when a hand’s pointer moved within this view.
The pointedFrom and pointedTo in pointer now likely have new values.
Arguments
| Name | Type | Description |
|---|---|---|
| pointer | table | see onPointerChanged. |
Returns
Nothing
view:onPointerExited (pointer)
Callback for when the hand’s pointer is no longer pointing within this view.
The state in pointer is now “outside”
Arguments
| Name | Type | Description |
|---|---|---|
| pointer | table | see onPointerChanged. |
Returns
Nothing
view:onTouchDown (pointer)
Callback for when the hand’s pointer is poking/touching this view The state in pointer is now “touching”
Arguments
| Name | Type | Description |
|---|---|---|
| pointer | table | see onPointerChanged. |
Returns
Nothing
view:onTouchUp (pointer)
Callback for when the hand’s pointer stopped poking/touching this view.
This is a great time to invoke an action based on the touch. For example, if you’re implementing a button, this is where you’d trigger whatever you’re trying to trigger.
NOTE: If pointer.state is now “outside”, the user released the trigger button outside of this view, and you should NOT perform an action, but cancel it instead.
Arguments
| Name | Type | Description |
|---|---|---|
| pointer | table | see onPointerChanged. |
Returns
Nothing
view:onInteraction (inter, body, sender)
an interaction message was sent to this specific view.
See Interactions
Arguments
| Name | Type | Description |
|---|---|---|
| inter | ??? | |
| body | ??? | |
| sender | ??? |
Returns
Nothing
view:onFileDropped (filename, asset_id)
Callback called when a file is dropped on the view
Arguments
| Name | Type | Description |
|---|---|---|
| filename | string | The name of the dropped file |
| asset_id | string | The id of the asset dropped on you |
Returns
Nothing
view:addPropertyAnimation (anim)
Add an animation of a property of a component to this view For example, you might want to add a one-second animation of transform.matrix.rotation.x from 0 to 6.28, repeating.
Arguments
| Name | Type | Description |
|---|---|---|
| anim | PropertyAnimation | The animation to add to this view. |
Returns
Nothing
view:setTexture (asset)
Set the Views’s texture using an Asset.
The asset parameter can be either an Asset instance or a raw string hash
View:setTexture(asset)
Arguments
| Name | Type | Description |
|---|---|---|
| asset | Asset | An instance of an Asset |
Returns
Nothing
view:setColor (rgba)
Set the color of a View using a set of rgba values between 0 and 1.
E.g. to set the view to be red and 50% transparent, set this value to {1, 0, 0, 0.5}
View:setColor(rgba)
Arguments
| Name | Type | Description |
|---|---|---|
| rgba | table | A table defining a color value with alpha between 0-1. |
Returns
Nothing
view:layout ()
Layout this view and its children. Override to implement your own custom layout. Don’t forget to call super’s implementation, and don’t forget to markAsDirty if needed.
Arguments
None
Returns
Nothing