CrossBrowdy API documentation

Namespace: CB_Mouse

CB_Mouse

Static class to manage the mouse and related. It will return itself if it is tried to be instantiated.

Source:

Namespaces

CursorImage

Methods

<static> getButtons() → {Object}

Tells what mouse buttons are down (LEFT, MIDDLE and/or RIGHT buttons).

Source:
Returns:

Returns an object using the following format (where "true" means that the button is being pressed): { LEFT : boolean, MIDDLE : boolean, RIGHT : boolean }

Type
Object

<static> getLockElement( [avoidCache]) → {Element|null}

Gets the lock element for the mouse pointer (if any) or null otherwise. More information: Pointer Lock API.

Parameters:
Name Type Argument Default Description
avoidCache boolean <optional>
 false

If set to false, the returning value will use the previously-cached value (updated when this function is called with this parameter set to true or the onPointerLockChange or analog event is fired or when the CB_Mouse.lock or CB_Mouse.unlock functions are called successfully).
Source:
Returns:

Returns the lock element for the mouse pointer (if any) or null otherwise.

Type
Element | null

<static> getX( [e] [, ignoreScroll] [, ignoreLock]) → {number}

Gets and returns the X coordinate (horizontal position) of the mouse (relative to the window in desktop) in pixels.

Parameters:
Name Type Argument Default Description
e Event <optional>

Mouse event object. If not provided, the returning value will use the previously-cached value (updated the last time that the onMouseMove event was fired).
ignoreScroll boolean <optional>
 false

If set to true, the horizontal scroll position will not be added to the returning value.
ignoreLock boolean <optional>
 false

If set to true, it will ignore whether the cursor is being locked or not. Otherwise, if set to false and the cursor is locked, the returning value will only have in mind the position in the locking element.
Source:
Returns:

Returns the X coordinate (horizontal position) of the mouse (relative to the window in desktop) in pixels.

Type
number

<static> getXMovement( [e]) → {number}

Returns the current X (horizontal) movement (useful when the mouse pointer is locked) in pixels. More information: MouseEvent.movementX.

Parameters:
Name Type Argument Description
e Event <optional>

Mouse event object. If not provided, the returning value will use the previously-cached value (updated the last time that the onMouseMove event was fired).
Source:
Returns:

Returns the current X (horizontal) movement (useful when the mouse pointer is locked) in pixels.

Type
number

<static> getXRelative(x [, ignoreScroll]) → {number}

Gets and returns the current X coordinate (horizontal position) in pixels of the mouse relative to a given X position. The returning value uses the previously-cached value (updated the last time that the onMouseMove event was fired).

Parameters:
Name Type Argument Default Description
x number

The X coordinate (horizontal position) in pixels. The returning value will be calculated relatively to it.
ignoreScroll boolean <optional>
 false

If set to true, the horizontal scroll position will not be added to the returning value.
Source:
To Do:
Returns:

Returns the current X coordinate (horizontal position) in pixels of the mouse relative to a given X position.

Type
number

<static> getY( [e] [, ignoreScroll] [, ignoreLock]) → {number}

Gets and returns the Y coordinate (vertical position) of the mouse (relative to the window in desktop) in pixels.

Parameters:
Name Type Argument Default Description
e Event <optional>

Mouse event object. If not provided, the returning value will use the previously-cached value (updated the last time that the onMouseMove event was fired).
ignoreScroll boolean <optional>
 false

If set to true, the vertical scroll position will not be added to the returning value.
ignoreLock boolean <optional>
 false

If set to true, it will ignore whether the cursor is being locked or not. Otherwise, if set to false and the cursor is locked, the returning value will only have in mind the position in the locking element.
Source:
Returns:

Returns the Y coordinate (vertical position) of the mouse (relative to the window in desktop) in pixels.

Type
number

<static> getYMovement( [e]) → {number}

Returns the current Y (vertical) movement (useful when the mouse pointer is locked) in pixels. More information: MouseEvent.movementY.

Parameters:
Name Type Argument Description
e Event <optional>

Mouse event object. If not provided, the returning value will use the previously-cached value (updated the last time that the onMouseMove event was fired).
Source:
Returns:

Returns the current Y (vertical) movement (useful when the mouse pointer is locked) in pixels.

Type
number

<static> getYRelative(y [, ignoreScroll]) → {number}

Gets and returns the current Y coordinate (vertical position) in pixels of the mouse relative to a given Y position. The returning value uses the previously-cached value (updated the last time that the onMouseMove event was fired).

Parameters:
Name Type Argument Default Description
y number

The Y coordinate (vertical position) in pixels. The returning value will be calculated relatively to it.
ignoreScroll boolean <optional>
 false

If set to true, the vertical scroll position will not be added to the returning value.
Source:
To Do:
Returns:

Returns the current Y coordinate (vertical position) in pixels of the mouse relative to a given Y position.

Type
number

<static> hide( [element] [, recursive])

Hides the mouse cursor in a given DOM element by changing its internal CSS code of the style.cursor property.

Parameters:
Name Type Argument Default Description
element Element <optional>
 document.body

If a DOM element is given, the mouse cursor will be hidden when it is over this DOM element. Otherwise, it will be hidden in the whole document (using document.body as element).
recursive boolean <optional>
 true

If it is set to true, all the child DOM elements will also be affected.
Source:
To Do:
  • Check whether the path used in the "url" is right or not (now it uses the CB_scriptPath variable).

<static> isLockSupported() → {boolean}

Tells whether mouse pointer lock is supported or not. More information: Pointer Lock API.

Source:
Returns:

Returns whether mouse pointer lock is supported or not.

Type
boolean

<static> isLocked( [avoidCache]) → {boolean}

Tells whether the mouse pointer is locked or not. More information: Pointer Lock API.

Parameters:
Name Type Argument Default Description
avoidCache boolean <optional>
 false

Used as the parameter to call the CB_Mouse.getLockElement function internally.
Source:
Returns:

Returns whether the mouse pointer is locked or not.

Type
boolean

<static> isOverCircle(centreX, centreY, radius [, element]) → {boolean}

Tells whether the mouse is over a given circle or not.

Parameters:
Name Type Argument Description
centreX number

The X coordinate (horizontal position) of the center of the circle in pixels.
centreY number

The Y coordinate (vertical position) of the center of the circle in pixels.
radius number

The radius of the circle in pixels.
element Element <optional>

If a DOM element is given, the mouse coordinates will be calculated relatively to the position of this DOM element.
Source:
Returns:

Returns whether the mouse is over the given circle or not.

Type
boolean

<static> isOverElement(element) → {boolean}

Tells whether the mouse is over a given DOM element or not.

Parameters:
Name Type Description
element Element

The DOM element where we want to know whether the mouse is over or not.
Source:
Returns:

Returns whether the mouse is over the given DOM element or not.

Type
boolean

<static> isOverEllipse(centreX, centreY, radiusX, radiusY [, rotation] [, rotationUseDegrees]) → {boolean}

Tells whether the mouse is over a given ellipse or not.

Parameters:
Name Type Argument Default Description
centreX number

The "X" coordinate of the center of the ellipse.
centreY number

The "Y" coordinate of the center of the ellipse.
radiusX number

The X (horizontal) radius of the ellipse.
radiusY number

The Y (vertical) radius of the ellipse.
rotation number <optional>
 0

The ellipse rotation. The value given will be considered either degrees or radians depending on the given "rotationUseDegrees" parameter (by default, it is considered radians). Not implemented yet!
rotationUseDegrees boolean <optional>
 false

Defines whether the "rotation" given should be considered degrees or not (radians). Not implemented yet!
Source:
Returns:

Returns whether the mouse is over the given ellipse or not.

Type
boolean

<static> isOverLine(lineX1, lineY1, lineX2, lineY2 [, tolerance] [, element]) → {boolean}

Tells whether the mouse is over a given line (infinite line) or not.

Parameters:
Name Type Argument Default Description
lineX1 number

The X coordinate (horizontal position) of the first pixel of the line.
lineY1 number

The Y coordinate (vertical position) of the first pixel of the line.
lineX2 number

The X coordinate (horizontal position) of the second pixel of the line.
lineY2 number

The Y coordinate (vertical position) of the second pixel of the line.
tolerance number <optional>
 1

The amount of loss of precision we can tolerate to consider a collision.
element Element <optional>

If a DOM element is given, the mouse coordinates will be calculated relatively to the position of this DOM element.
Source:
To Do:
  • Think about using a "width" parameter (apart from the "tolerance" parameter).
Returns:

Returns whether the mouse is over the given line (infinite line) or not.

Type
boolean

<static> isOverRectangle(rectangleX, rectangleY, rectangleWidth, rectangleHeight [, element]) → {boolean}

Tells whether the mouse is over a given rectangle or not.

Parameters:
Name Type Argument Description
rectangleX number

The X coordinate (horizontal position) of the first pixel of the rectangle (upper left corner).
rectangleY number

The Y coordinate (vertical position) of the first pixel of the rectangle (upper left corner).
rectangleWidth number

The width of the rectangle in pixels.
rectangleHeight number

The height of the rectangle in pixels.
element Element <optional>

If a DOM element is given, the mouse coordinates will be calculated relatively to the position of this DOM element.
Source:
Returns:

Returns whether the mouse is over the given rectangle or not.

Type
boolean

<static> isOverSegment(lineX1, lineY1, lineX2, lineY2 [, tolerance] [, element]) → {boolean}

Tells whether the mouse is over a given line segment or not.

Parameters:
Name Type Argument Default Description
lineX1 number

The X coordinate (horizontal position) of the first pixel of the line segment.
lineY1 number

The Y coordinate (vertical position) of the first pixel of the line segment.
lineX2 number

The X coordinate (horizontal position) of the second pixel of the line segment.
lineY2 number

The Y coordinate (vertical position) of the second pixel of the line segment.
tolerance number <optional>
 1

The amount of loss of precision we can tolerate to consider a collision.
element Element <optional>

If a DOM element is given, the mouse coordinates will be calculated relatively to the position of this DOM element.
Source:
To Do:
  • Think about using a "width" parameter (apart from the "tolerance" parameter).
Returns:

Returns whether the mouse is over the given line segment or not.

Type
boolean

<static> lock( [target], callbackOk, callbackError) → {Element|null}

Locks the mouse pointer (if possible). More information: Pointer Lock API.

Parameters:
Name Type Argument Default Description
target Element <optional>
 document.body

The DOM element that the mouse pointer will be locked to.
callbackOk function

Function callback that will be called (without parameters) if the mouse pointer could be locked successfully.
callbackError function

Function callback that will be called (without parameters) if the mouse pointer could not be locked successfully.
Source:
Returns:

Returns the current lock element for the mouse pointer (if any) or null otherwise.

Type
Element | null

<static> normalizeEvent(e) → {Event}

Tries to return the given mouse event object with some properties normalized (since different clients can use different values) and perhaps some new properties added (in the case they were missing), when possible. The new attached methods and properties may include polyfills, etc. It also calls the CB_Events.normalize function internally. Some properties added or affected could be deltaX, deltaY, deltaZ, force, clientX, clientY, etc.

Parameters:
Name Type Description
e Event

Mouse event object. If not provided, it will use the value of "event", "window.event", "Event" or an empty object ("{}").
Source:
To Do:
Returns:

Returns the mouse event object normalized.

Type
Event

<static> onButtonDown(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when a mouse button is down (onMouseDown event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 document

The target where we want to attach the event listener.
Source:

<static> onButtonUp(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when a mouse button is up (onMouseUp event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 document

The target where we want to attach the event listener.
Source:

<static> onClick(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when a click happens (onClick event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 document

The target where we want to attach the event listener.
Source:

<static> onDblClick(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when a click happens (onDblClick event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 document

The target where we want to attach the event listener.
Source:

<static> onLeave(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when a mouse leaves a DOM element (onMouseLeave event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 window

The target where we want to attach the event listener.
Source:

<static> onLockChange(callbackFunction [, keepOldFunction] [, useCapture])

Sets a function to execute when the mouse pointer lock functionality changes its state (it has been either locked or unlocked, using pointerlockchange}, mozpointerlockchange or webkitpointerlockchange event) or removes it. More information: Pointer Lock API.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:

<static> onLockError(callbackFunction [, keepOldFunction] [, useCapture])

Sets a function to execute when the mouse pointer fails to either lock or unlock (using pointerlockerror, mozpointerlockerror or webkitpointerlockerror event) or removes it. More information: Pointer Lock API.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
Source:

<static> onMove(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when a click happens (onMouseMove event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 document

The target where we want to attach the event listener.
Source:

<static> onOut(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when a mouse gets out of a DOM element (onMouseOut event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 document

The target where we want to attach the event listener.
Source:

<static> onOver(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when a mouse is over a DOM element (onMouseOver event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 document

The target where we want to attach the event listener.
Source:

<static> onWheel(callbackFunction [, keepOldFunction] [, useCapture] [, target])

Sets a function to execute when the mouse wheel is used (onWheel, onMouseWheel or DOMMouseScroll event) or removes it.

Parameters:
Name Type Argument Default Description
callbackFunction function | null

The function (event listener) that we want to execute when the event is fired. The first and unique parameter received for this function will be the mouse event object (already normalized by the CB_Mouse.normalizeEvent function). If a null value is used, the event will be removed.
keepOldFunction boolean <optional>
 true

Defines whether we want to keep any possible previous event listener for the same target and event name or not.
useCapture boolean <optional>
 false

Defines whether the event we want to add will use capture or not. This parameter will be effective only if the current client supports the addEventListener method and will be used as its third parameter.
target Object <optional>
 document

The target where we want to attach the event listener.
Source:

<static> restore( [element] [, recursive])

Restores (unhides) the mouse cursor in a given DOM element by changing its internal CSS code of the style.cursor property to the default one (using "default" as the CSS code).

Parameters:
Name Type Argument Default Description
element Element <optional>
 document.body

If a DOM element is given, the mouse cursor will be restored (unhidden) when it is over this DOM element. Otherwise, it will be restored (unhidden) in the whole document (using document.body as the "element").
recursive boolean <optional>
 true

If it is set to true, all the child DOM elements will also be affected.
Source:

<static> setCSS( [CSS] [, element] [, recursive])

Sets the desired CSS code for the style.cursor property of the given DOM element.

Parameters:
Name Type Argument Default Description
CSS string <optional>
 ""

CSS code for the style.cursor property of the given DOM element. If not given, an empty string will be used.
element Element <optional>
 document.body

If a DOM element is given, the CSS code updated will affect the given DOM element. Otherwise, it will affect the whole document (using document.body as the "element").
recursive boolean <optional>
 true

If it is set to true, all the child DOM elements will also be affected.
Source:

<static> unlock() → {boolean}

Unlocks the mouse pointer (if possible). More information: Pointer Lock API.

Source:
Returns:

Returns true if the mouse pointer has been unlocked or false otherwise.

Type
boolean

<static> wasLocked() → {boolean}

Tells whether the mouse pointer was locked before or not when the CB_Mouse.isLocked function was called the last time. More information: Pointer Lock API.

Source:
Returns:

Returns whether the mouse pointer was locked before or not when the CB_Mouse.isLocked function was called the last time.

Type
boolean