API Docs for: 1.0.0

Input

Extends Component
Defined in: src/input/input.js:1
Module: input
Parent Module: xeogl

Publishes keyboard and mouse events that occur on the parent Scene's Canvas.

  • Each Scene provides an Input on itself as a read-only property.

Usage

In this example, we're subscribing to some mouse and key events that will occur on a Scene's Canvas.

var myScene = new xeogl.Scene();

var input = myScene.input;

// We'll save a handle to this subscription
// to show how to unsubscribe, further down
var handle = input.on("mousedown", function(coords) {
      console.log("Mouse down at: x=" + coords[0] + ", y=" + coords[1]);
});

input.on("mouseup", function(coords) {
      console.log("Mouse up at: x=" + coords[0] + ", y=" + coords[1]);
});

input.on("mouseclicked", function(coords) {
     console.log("Mouse clicked at: x=" + coords[0] + ", y=" + coords[1]);
});

input.on("dblclick", function(coords) {
      console.log("Double-click at: x=" + coords[0] + ", y=" + coords[1]);
});

input.on("keydown", function(keyCode) {
       switch (keyCode) {

           case this.KEY_A:
              console.log("The 'A' key is down");
              break;

           case this.KEY_B:
              console.log("The 'B' key is down");
              break;

           case this.KEY_C:
              console.log("The 'C' key is down");
              break;

           default:
              console.log("Some other key is down");
      }
    });

input.on("keyup", function(keyCode) {
       switch (keyCode) {

           case this.KEY_A:
              console.log("The 'A' key is up");
              break;

           case this.KEY_B:
              console.log("The 'B' key is up");
              break;

           case this.KEY_C:
              console.log("The 'C' key is up");
              break;

           default:
              console.log("Some other key is up");
       }
    });

// TODO: ALT and CTRL keys etc

Unsubscribing from Events

In the snippet above, we saved a handle to one of our event subscriptions.

We can then use that handle to unsubscribe again, like this:

input.off(handle);

Methods

create

(
  • [cfg]
  • [instanceId]
)

Convenience method for creating a Component within this Component's Scene.

You would typically use this method to conveniently instantiate components that you'd want to share (ie. "instance") among your Entities.

The method is given a component type, configuration and optional instance ID, like so:

var material = myComponent.create(xeogl.PhongMaterial, {
     diffuse: [1,0,0],
     specular: [1,1,0]
}, "myMaterial");

The first time you call this method for the given type and instanceId, this method will create the PhongMaterial, passing the given attributes to the component's constructor.

If you call this method again, specifying the same type and instanceId, the method will return the same component instance that it returned the first time, and will ignore the configuration:

var material2 = component.create(xeogl.PhongMaterial, { specular: [1,1,0] }, "myMaterial");

So in this example, our PhongMaterial will continue to have the red specular and diffuse color that we specified the first time.

Each time you call this method with the same type and instanceId, the Scene will internally increment a reference count for the component instance. You can release the shared component instance with a call to Scene/putSharedComponent:method, and once you have released it as many times as you got it, the Scene will destroy the component.

Parameters:

  • [cfg] optional

    Configuration for the component instance - only used if this is the first time you are getting the component, ignored when reusing an existing instance.

  • [instanceId] String | Number optional

    Identifies the shared component instance. Note that this is not used as the ID of the component - you can specify the component ID in the cfg parameter.

Returns:

:

destroy

()

Destroys this component.

Fires a destroyed event on this Component.

Automatically disassociates this component from other components, causing them to fall back on any defaults that this component overrode on them.

TODO: describe effect with respect to #create

error

(
  • message
)

Logs an error for this component to the JavaScript console.

The console message will have this format: [ERROR] [<component type> =<component id>: <message>

Also fires the message as an error event on the parent Scene.

Parameters:

  • message String

    The message to log

fire

(
  • event
  • value
  • [forget=false]
)

Fires an event on this component.

Notifies existing subscribers to the event, optionally retains the event to give to any subsequent notifications on the event as they are made.

Parameters:

  • event String

    The event type name

  • value Object

    The event parameters

  • [forget=false] Boolean optional

    When true, does not retain for subsequent subscribers

isType

(
  • type
)
Boolean

Tests if this component is of the given type, or is a subclass of the given type.

The type may be given as either a string or a component constructor.

This method works by walking up the inheritance type chain, which this component provides in property superTypes, returning true as soon as one of the type strings in the chain matches the given type, of false if none match.

Examples:

var myRotate = new xeogl.Rotate({ ... });

myRotate.isType(xeogl.Component); // Returns true for all xeogl components
myRotate.isType("xeogl.Component"); // Returns true for all xeogl components
myRotate.isType(xeogl.Rotate); // Returns true
myRotate.isType(xeogl.Transform); // Returns true
myRotate.isType("xeogl.Transform"); // Returns true
myRotate.isType(xeogl.Entity); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.Entity

Parameters:

  • type String | Function

    Component type to compare with, eg "xeogl.PhongMaterial", or a xeogl component constructor.

Returns:

Boolean:

True if this component is of given type or is subclass of the given type.

log

(
  • message
)

Logs a console debugging message for this component.

The console message will have this format: [LOG] [<component type> <component id>: <message>

Also fires the message as a log event on the parent Scene.

Parameters:

  • message String

    The message to log

off

(
  • handle
)

Cancels an event subscription that was previously made with on or once.

Parameters:

  • handle String

    Publication handle

on

(
  • event
  • callback
  • [scope=this]
)
String

Subscribes to an event on this component.

The callback is be called with this component as scope.

Parameters:

  • event String

    The event

  • callback Function

    Called fired on the event

  • [scope=this] Object optional

    Scope for the callback

Returns:

String:

Handle to the subscription, which may be used to unsubscribe with {@link #off}.

once

(
  • event
  • callback
  • [scope=this]
)

Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is handled.

This is equivalent to calling on, and then calling off inside the callback function.

Parameters:

  • event String

    Data event to listen to

  • callback Function(data)

    Called when fresh data is available at the event

  • [scope=this] Object optional

    Scope for the callback

warn

(
  • message
)

Logs a warning for this component to the JavaScript console.

The console message will have this format: [WARN] [<component type> =<component id>: <message>

Also fires the message as a warn event on the parent Scene.

Parameters:

  • message String

    The message to log

Properties

destroyed

Boolean

True as soon as this Component has been destroyed

id

String final

Unique ID for this Component within its parent Scene.

isDefault

Boolean

Indicates whether this is one of the Scene's built-in Components.

json

JSON final

JSON object containing the state of this Component.

KEY_A

Number final

Code for the A key.

KEY_ADD

Number final

Code for the ADD key.

KEY_ALT

Number final

Code for the ALT key.

KEY_B

Number final

Code for the B key.

KEY_BACK_SLASH

Number final

Code for the BACK_SLASH key.

KEY_BACKSPACE

Number final

Code for the BACKSPACE key.

KEY_C

Number final

Code for the C key.

KEY_CAPS_LOCK

Number final

Code for the CAPS_LOCK key.

KEY_CLOSE_BRACKET

Number final

Code for the CLOSE_BRACKET key.

KEY_COMMA

Number final

Code for the COMMA key.

KEY_CTRL

Number final

Code for the CTRL key.

KEY_D

Number final

Code for the D key.

KEY_DASH

Number final

Code for the DASH key.

KEY_DECIMAL_POINT

Number final

Code for the DECIMAL POINT key.

KEY_DELETE

Number final

Code for the DELETE key.

KEY_DIVIDE

Number final

Code for the DIVIDE key.

KEY_DOWN_ARROW

Number final

Code for the DOWN_ARROW key.

KEY_E

Number final

Code for the E key.

KEY_END

Number final

Code for the END key.

KEY_ENTER

Number final

Code for the ENTER key.

KEY_EQUAL_SIGN

Number final

Code for the EQUAL_SIGN key.

KEY_ESCAPE

Number final

Code for the ESCAPE key.

KEY_F

Number final

Code for the F key.

KEY_F1

Number final

Code for the F1 key.

KEY_F10

Number final

Code for the F10 key.

KEY_F11

Number final

Code for the F11 key.

KEY_F12

Number final

Code for the F12 key.

KEY_F2

Number final

Code for the F2 key.

KEY_F3

Number final

Code for the F3 key.

KEY_F4

Number final

Code for the F4 key.

KEY_F5

Number final

Code for the F5 key.

KEY_F6

Number final

Code for the F6 key.

KEY_F7

Number final

Code for the F7 key.

KEY_F8

Number final

Code for the F8 key.

KEY_F9

Number final

Code for the F9 key.

KEY_FORWARD_SLASH

Number final

Code for the FORWARD_SLASH key.

KEY_G

Number final

Code for the G key.

KEY_GRAVE_ACCENT

Number final

Code for the GRAVE_ACCENT key.

KEY_H

Number final

Code for the H key.

KEY_HOME

Number final

Code for the HOME key.

KEY_I

Number final

Code for the I key.

KEY_INSERT

Number final

Code for the INSERT key.

KEY_J

Number final

Code for the J key.

KEY_K

Number final

Code for the K key.

KEY_L

Number final

Code for the L key.

KEY_LEFT_ARROW

Number final

Code for the LEFT_ARROW key.

KEY_LEFT_WINDOW

Number final

Code for the LEFT_WINDOW key.

KEY_M

Number final

Code for the M key.

KEY_MULTIPLY

Number final

Code for the MULTIPLY key.

KEY_N

Number final

Code for the N key.

KEY_NUM_0

Number final

Code for the 0 key.

KEY_NUM_1

Number final

Code for the 1 key.

KEY_NUM_2

Number final

Code for the 2 key.

KEY_NUM_3

Number final

Code for the 3 key.

KEY_NUM_4

Number final

Code for the 4 key.

KEY_NUM_5

Number final

Code for the 5 key.

KEY_NUM_6

Number final

Code for the 6 key.

KEY_NUM_7

Number final

Code for the 7 key.

KEY_NUM_8

Number final

Code for the 8 key.

KEY_NUM_9

Number final

Code for the 9 key.

KEY_NUM_LOCK

Number final

Code for the NUM_LOCK key.

KEY_NUMPAD 2

Number final

Code for the number pad 2 key.

KEY_NUMPAD_0

Number final

Code for the number pad 0 key.

KEY_NUMPAD_1

Number final

Code for the number pad 1 key.

KEY_NUMPAD_3

Number final

Code for the number pad 3 key.

KEY_NUMPAD_4

Number final

Code for the number pad 4 key.

KEY_NUMPAD_5

Number final

Code for the number pad 5 key.

KEY_NUMPAD_6

Number final

Code for the number pad 6 key.

KEY_NUMPAD_7

Number final

Code for the number pad 7 key.

KEY_NUMPAD_8

Number final

Code for the number pad 8 key.

KEY_NUMPAD_9

Number final

Code for the number pad 9 key.

KEY_O

Number final

Code for the O key.

KEY_OPEN_BRACKET

Number final

Code for the OPEN_BRACKET key.

KEY_P

Number final

Code for the P key.

KEY_PAGE_DOWN

Number final

Code for the PAGE_DOWN key.

KEY_PAGE_UP

Number final

Code for the PAGE_UP key.

KEY_PAUSE_BREAK

Number final

Code for the PAUSE_BREAK key.

KEY_PERIOD

Number final

Code for the PERIOD key.

KEY_Q

Number final

Code for the Q key.

KEY_R

Number final

Code for the R key.

KEY_RIGHT_ARROW

Number final

Code for the RIGHT_ARROW key.

KEY_RIGHT_WINDOW

Number final

Code for the RIGHT_WINDOW key.

KEY_S

Number final

Code for the S key.

KEY_SCROLL_LOCK

Number final

Code for the SCROLL_LOCK key.

KEY_SELECT

Number final

Code for the SELECT key.

KEY_SEMI_COLON

Number final

Code for the SEMI_COLON key.

KEY_SHIFT

Number final

Code for the SHIFT key.

KEY_SINGLE_QUOTE

Number final

Code for the SINGLE_QUOTE key.

KEY_SPACE

Number final

Code for the SPACE key.

KEY_SUBTRACT

Number final

Code for the SUBTRACT key.

KEY_T

Number final

Code for the T key.

KEY_TAB

Number final

Code for the TAB key.

KEY_U

Number final

Code for the U key.

KEY_UP_ARROW

Number final

Code for the UP_ARROW key.

KEY_V

Number final

Code for the V key.

KEY_W

Number final

Code for the W key.

KEY_X

Number final

Code for the X key.

KEY_Y

Number final

Code for the Y key.

KEY_Z

Number final

Code for the Z key.

metadata

Object

Arbitrary, user-defined metadata on this component.

scene

Scene final

The parent Scene that contains this Component.

string

String final

Inherited from Component but overwritten in src/component.js:1056

String containing the serialized JSON state of this Component.

superTypes

Array of String final

An array of strings that indicates the chain of super-types within this component's inheritance hierarchy.

For example, if this component is a Rotate, which extends Transform, which in turn extends Component, then this property will have the value:

["xeogl.Component", "xeogl.Transform"]
                    

Note that the chain is ordered downwards in the hierarchy, ie. from super-class down towards sub-class.

type

String final

JavaScript class name for this Component.

This is used when loading Scenes from JSON, and is included in the JSON representation of this Component, so that this class may be instantiated when loading it from the JSON representation.

For example: "xeogl.AmbientLight", "xeogl.ColorTarget", "xeogl.Lights" etc.

Events

dblclick

Fired whenever the mouse is double-clicked over the parent Scene's Canvas.

Event Payload:

  • value Number, Number

    The mouse coordinates within the Canvas,

destroyed

Fired when this Component is destroyed.

devicemotion

Fires on a regular interval and returns data about the rotation (in degrees per second) and acceleration (in meters per second squared) of the device, at that moment in time. Some devices do not have the hardware to exclude the effect of gravity.

Event Payload:

  • Float32Array Object

    acceleration The acceleration of the device, in meters per second squared, as a 3-element vector. This value has taken into account the effect of gravity and removed it from the figures. This value may not exist if the hardware doesn't know how to remove gravity from the acceleration data.

  • Float32Array Object

    accelerationIncludingGravity The acceleration of the device, in meters per second squared, as a 3-element vector. This value includes the effect of gravity, and may be the only value available on devices that don't have a gyroscope to allow them to properly remove gravity from the data.

  • , Object

    Number interval The interval, in milliseconds, at which this event is fired. The next event will be fired in approximately this amount of time.

  • Float32Array Object

    rotationRate The rates of rotation of the device about each axis, in degrees per second.

deviceorientation

Fired when fresh data is available from an orientation sensor about the current orientation of the device as compared to the Earth coordinate frame. This data is gathered from a magnetometer inside the device. See Orientation and motion data explained for more info.

Event Payload:

  • Number Object

    alpha The current orientation of the device around the Z axis in degrees; that is, how far the device is rotated around a line perpendicular to the device.

  • Number Object

    beta The current orientation of the device around the X axis in degrees; that is, how far the device is tipped forward or backward.

  • Number Object

    gamma The current orientation of the device around the Y axis in degrees; that is, how far the device is turned left or right.

  • Boolean Object

    absolute This value is true if the orientation is provided as a difference between the device coordinate frame and the Earth coordinate frame; if the device can't detect the Earth coordinate frame, this value is false.

keydown

Fired whenever a key is pressed while the parent Scene's Canvas has input focus.

Event Payload:

keyup

Fired whenever a key is released while the parent Scene's Canvas has input focus.

Event Payload:

mouseclicked

Fired whenever the mouse is clicked over the parent Scene's Canvas.

Event Payload:

  • value Number, Number

    The mouse coordinates within the Canvas,

mousedown

Fired whenever the mouse is pressed over the parent Scene's Canvas.

Event Payload:

  • value Number, Number

    The mouse coordinates within the Canvas,

mousedown

Fired whenever the mouse is moved over the parent Scene's Canvas.

Event Payload:

  • value Number, Number

    The mouse coordinates within the Canvas,

mouseenter

Fired whenever the mouse is moved into of the parent Scene's Canvas.

Event Payload:

  • value Number, Number

    The mouse coordinates within the Canvas,

mouseleave

Fired whenever the mouse is moved out of the parent Scene's Canvas.

Event Payload:

  • value Number, Number

    The mouse coordinates within the Canvas,

mouseup

Fired whenever the mouse is released over the parent Scene's Canvas.

Event Payload:

  • value Number, Number

    The mouse coordinates within the Canvas,

mousewheel

Fired whenever the mouse wheel is moved over the parent Viewer's Canvas.

Event Payload:

  • delta Number

    The mouse wheel delta,

orientationchange

Fired when the orientation of the device has changed.

Event Payload:

  • orientation Object

    The orientation: "landscape-primary", "landscape-secondary", "portrait-secondary" or "portrait-primary"

  • orientationAngle Object

    The orientation angle in degrees: 90 for landscape-primary, -90 for landscape-secondary, 180 for portrait-secondary or 0 for portrait-primary.