Page MenuHomeGitPull.it
Diviner Javelin Docs JX.Vector

class JX.Vector
Javelin Documentation ()

Query and update positions and dimensions of nodes (and other things) within within a document. Each vector has two elements, 'x' and 'y', which usually represent width/height ('dimension vector') or left/top ('position vector').

Vectors are used to manage the sizes and positions of elements, events, the document, and the viewport (the visible section of the document, i.e. how much of the page the user can actually see in their browser window). Unlike most Javelin classes, JX.Vector exposes two bare properties, 'x' and 'y'. You can read and manipulate these directly:

// Give the user information about elements when they click on them.
JX.Stratcom.listen(
  'click',
  null,
  function(e) {
    var p = new JX.Vector(e);
    var d = JX.Vector.getDim(e.getTarget());

    alert('You clicked at <' + p.x + ',' + p.y + '> and the element ' +
          'you clicked is ' + d.x + 'px wide and ' + d.y + 'px high.');
  });

You can also update positions and dimensions using vectors:

// When the user clicks on something, make it 10px wider and 10px taller.
JX.Stratcom.listen(
  'click',
  null,
  function(e) {
    var target = e.getTarget();
    JX.$V(target).add(10, 10).setDim(target);
  });

Additionally, vectors can be used to query document and viewport information:

var v = JX.Vector.getViewport(); // Viewport (window) width and height.
var d = JX.Vector.getDocument(); // Document width and height.
var visible_area = parseInt(100 * (v.x * v.y) / (d.x * d.y), 10);
alert('You can currently see ' + visible_area + ' % of the document.');

The function JX.$V() provides convenience construction of common vectors.

Tasks

Builtin Events

  • invoke(type, more) — Invoke a class event, notifying all listeners. You must declare the events your class invokes when you install it; see @{function:JX.install} for documentation. Any arguments you provide will be passed to listener callbacks.
  • static listen(type, callback) — Static listen interface for listening to events produced by any instance of this class. See @{method:listen} for documentation.

Querying Positions and Dimensions

  • construct(x, y) — Construct a vector, either from explicit coordinates or from a node or event. You can pass two Numbers to construct an explicit vector:
  • static getPos(node) — Determine where in a document an element is (or where an event, like a click, occurred) by building a new vector containing the position of a Node or @{class:JX.Event}. The 'x' component of the vector will correspond to the pixel offset of the argument relative to the left edge of the document, and the 'y' component will correspond to the pixel offset of the argument relative to the top edge of the document. Note that all vectors are generated in document coordinates, so the scroll position does not affect them.
  • static getDim(node) — Determine the width and height of a node by building a new vector with dimension information. The 'x' component of the vector will correspond to the element's width in pixels, and the 'y' component will correspond to its height in pixels.
  • static getScroll() — Determine the current scroll position by building a new vector where the 'x' component corresponds to how many pixels the user has scrolled from the left edge of the document, and the 'y' component corresponds to how many pixels the user has scrolled from the top edge of the document.
  • static getViewport() — Determine the size of the viewport (basically, the browser window) by building a new vector where the 'x' component corresponds to the width of the viewport in pixels and the 'y' component corresponds to the height of the viewport in pixels.
  • static getDocument() — Determine the size of the document, including any area outside the current viewport which the user would need to scroll in order to see, by building a new vector where the 'x' component corresponds to the document width in pixels and the 'y' component corresponds to the document height in pixels.

Changing Positions and Dimensions

  • setPos(node) — Move a node around by setting the position of a Node to the vector's coordinates. For instance, if you want to move an element to the top left corner of the document, you could do this (assuming it has 'position: absolute'):
  • setDim(node) — Change the size of a node by setting its dimensions to the vector's coordinates. For instance, if you want to change an element to be 100px by 100px:

Manipulating Vectors

  • add(x, y) — Change a vector's x and y coordinates by adding numbers to them, or adding the coordinates of another vector. For example:

Other Methods

  • static getAggregateScrollForNode(node) — Get the aggregate scroll offsets for a node and all of its parents.
  • static getPosWithScroll(node) — Get the sum of a node's position and its parent scroll offsets.
  • static initialize() — On initialization, the browser-dependent viewport root is determined and stored.

Methods

invoke(type, more)
Inherited

JX.Base

Invoke a class event, notifying all listeners. You must declare the events your class invokes when you install it; see JX.install() for documentation. Any arguments you provide will be passed to listener callbacks.

Parameters
stringtypeEvent type, must be declared when class is installed.
...moreZero or more arguments.
Return
JX.EventEvent object which was dispatched.

static listen(type, callback)
Inherited

JX.Base

Listen for events emitted by this object instance. You can also use the static flavor of this method to listen to events emitted by any instance of this object.

See also listen() in JX.Stratcom.

JX.Base

Static listen interface for listening to events produced by any instance of this class. See listen() for documentation.

Parameters
stringtypeType of event to listen for.
functioncallbackFunction to call when this event occurs.
Return
objectA reference to the installed listener. You can later remove the listener by calling this object's remove() method.

construct(x, y)

Construct a vector, either from explicit coordinates or from a node or event. You can pass two Numbers to construct an explicit vector:

var p = new JX.Vector(35, 42);

Otherwise, you can pass a JX.Event or a Node to implicitly construct a vector:

var q = new JX.Vector(some_event);
var r = new JX.Vector(some_node);

These are just like calling JX.Vector.getPos() on the JX.Event or Node.

For convenience, JX.$V() constructs a new vector so you don't need to use the 'new' keyword. That is, these are equivalent:

var s = new JX.Vector(x, y);
var t = JX.$V(x, y);

Methods like getScroll(), getViewport() and getDocument() also create new vectors.

Once you have a vector, you can manipulate it with add():

var u = JX.$V(35, 42);
var v = u.add(5, -12); // v = <40, 30>
Parameters
wildx'x' component of the vector, or a @{class:JX.Event}, or a Node.
Number?yIf providing an 'x' component, the 'y' component of the vector.
Return
JX.VectorSpecified vector.

setPos(node)

Move a node around by setting the position of a Node to the vector's coordinates. For instance, if you want to move an element to the top left corner of the document, you could do this (assuming it has 'position: absolute'):

JX.$V(0, 0).setPos(node);
Parameters
NodenodeNode to move.
Return
this

setDim(node)

Change the size of a node by setting its dimensions to the vector's coordinates. For instance, if you want to change an element to be 100px by 100px:

JX.$V(100, 100).setDim(node);

Or if you want to expand a node's dimensions by 50px:

JX.$V(node).add(50, 50).setDim(node);
Parameters
NodenodeNode to resize.
Return
this

add(x, y)

Change a vector's x and y coordinates by adding numbers to them, or adding the coordinates of another vector. For example:

var u = JX.$V(3, 4).add(100, 200); // u = <103, 204>

You can also add another vector:

var q = JX.$V(777, 999);
var r = JX.$V(1000, 2000);
var s = q.add(r); // s = <1777, 2999>

Note that this method returns a new vector. It does not modify the 'this' vector.

Parameters
wildxValue to add to the vector's x component, or another vector.
Number?yValue to add to the vector's y component.
Return
JX.VectorNew vector, with summed components.

static getPos(node)

Determine where in a document an element is (or where an event, like a click, occurred) by building a new vector containing the position of a Node or JX.Event. The 'x' component of the vector will correspond to the pixel offset of the argument relative to the left edge of the document, and the 'y' component will correspond to the pixel offset of the argument relative to the top edge of the document. Note that all vectors are generated in document coordinates, so the scroll position does not affect them.

See also getDim(), used to determine an element's dimensions.

Parameters
Node|JX.EventnodeNode or event to determine the position of.
Return
JX.VectorNew vector with the argument's position.

static getDim(node)

Determine the width and height of a node by building a new vector with dimension information. The 'x' component of the vector will correspond to the element's width in pixels, and the 'y' component will correspond to its height in pixels.

See also getPos(), used to determine an element's position.

Parameters
NodenodeNode to determine the display size of.
Return
JX.$VNew vector with the node's dimensions.

static getScroll()

Determine the current scroll position by building a new vector where the 'x' component corresponds to how many pixels the user has scrolled from the left edge of the document, and the 'y' component corresponds to how many pixels the user has scrolled from the top edge of the document.

See also getViewport(), used to determine the size of the viewport.

Return
JX.$VNew vector with the document scroll position.

static getAggregateScrollForNode(node)

Get the aggregate scroll offsets for a node and all of its parents.

Note that this excludes scroll at the document level, because it does not normally impact operations in document coordinates, which everything on this class returns. Use getScroll() to get the document scroll position.

Parameters
NodenodeNode to determine offsets for.
Return
JX.VectorNew vector with aggregate scroll offsets.

static getPosWithScroll(node)

Get the sum of a node's position and its parent scroll offsets.

Parameters
NodenodeNode to determine aggregate position for.
Return
JX.VectorNew vector with aggregate position.

static getViewport()

Determine the size of the viewport (basically, the browser window) by building a new vector where the 'x' component corresponds to the width of the viewport in pixels and the 'y' component corresponds to the height of the viewport in pixels.

See also getScroll(), used to determine the position of the viewport, and getDocument(), used to determine the size of the entire document.

Return
JX.VectorNew vector with the viewport dimensions.

static getDocument()

Determine the size of the document, including any area outside the current viewport which the user would need to scroll in order to see, by building a new vector where the 'x' component corresponds to the document width in pixels and the 'y' component corresponds to the document height in pixels.

Return
JX.VectorNew vector with the document dimensions.

static initialize()

On initialization, the browser-dependent viewport root is determined and stored.

In __DEV__, JX.Vector installs a toString() method so vectors print in a debuggable way:

<23, 92>

This string representation of vectors is not available in a production context.

Return
void
Defined
lib/Vector.js:78
Extends
JX.Base
Public contents are in Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) or GNU Free Documentation License (at your option) unless otherwise noted. · Contact / Register