UIZE JavaScript Framework

MODULES Uize.Dom.VirtualEvents.Remain

1. Introduction

The Uize.Dom.VirtualEvents.Remain package implements a set of remain-in-state virtual DOM events, such as the remainOver(), remainDown(), and remainOut() events.

DEVELOPERS: Chris van Rensburg

1.1. Examples

The following example pages are good showcases for the Uize.Dom.VirtualEvents.Remain module...

Virtual DOM Events - A demonstration of various virtual DOM events, such as mouseRest, mouseRemainOver, mouseRemainDown, remainFocused, ctrlClick, shiftClick, and more.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Dom.VirtualEvents.Remain module...

SEARCH

1.2. Implementation Info

The Uize.Dom.VirtualEvents.Remain module defines the Uize.Dom.VirtualEvents.Remain package under the Uize.Dom.VirtualEvents namespace.

1.2.1. Features Introduced in This Module

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Dom.VirtualEvents.Remain module.

2. In a Nutshell

Remain-in-state virtual DOM events are events that are fired when a node remains in a specific event state for a specified amount of time.

Requiring a node to remain in a specific event state for a set amount of time before firing an event is a helpful indicator of the user being truly interested in something (as opposed to just "wandering through"). Consider the classic case of the user mousing over a node and then resting the mouse for a certain period of time over that node. You might like to know if the user does this for a specific node, because this may be your indication that the user is interested in what clicking the node might do, and you may wish to present them with a helpful tooltip that is implemented using HTML and that provides them more information about what they're considering clicking on.

Now, you probably don't want to trigger the display of an elaborate info tooltip based merely upon the user mousing over the node, since this may hamper the page's performance - especially if displaying the tooltip requires an Ajax request - and displaying and hiding chunky tooltips as the user moves the mouse across the page may be a dreadful user experience, in any event. In such cases, it would be really nice to have an event that fires only when the user has actually stopped the mouse over a node. Virtual DOM events to the rescue! Specifically, the mouseRest virtual DOM event. This event accepts a duration parameter, to let you tune how long the user needs to keep the mouse rested over the node before the event is fired.

Beyond the indispensable mouseRest virtual DOM event, a plethora of other remain-in-state virtual DOM events are built into the Uize.Dom.VirtualEvents.Remain module.

2.1. Remain-in-state Virtual DOM Event Static Methods

2.2. Remain-in-state Registered Virtual DOM Events

3. Static Methods

3.1. Uize.Dom.VirtualEvents.Remain.keyRemainDown

Returns a virtual DOM event object, for an event that is fired when the user presses down on a key on the keyboard for a focused node that supports key events, and then holds down that key for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.keyRemainDown (durationMsINT);

When a handler is wired for this virtual DOM event on a node that supports key events, a timer is started when the user presses down on a key on the keyboard while that node is focused. If the user holds down the key for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If, however, the user releases the key before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.keyRemainDown ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

NOTES

this virtual DOM event maker is registered with the name keyRemainDown
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Dom.VirtualEvents.Remain.keyRemainUp

Returns a virtual DOM event object, for an event that is fired when the user releases a key on the keyboard for a focused node that supports key events, and then doesn't press down on a key again for that node for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.keyRemainUp (durationMsINT);

When a handler is wired for this virtual DOM event on a node that supports key events, a timer is started when the user releases a key on the keyboard while that node is focused. If the user doesn't press down on a key again while that node is focused, for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If, however, the user does press down again on a key before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.keyRemainUp ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

NOTES

this virtual DOM event maker is registered with the name keyRemainUp
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.3. Uize.Dom.VirtualEvents.Remain.makeRemainInStateEventMaker

For advanced users, returns a virtual DOM event maker function, for a remain-in-state virtual DOM event that is triggered by the specified trigger events and that is canceled by the specified cancel events.

SYNTAX

eventMakerFUNC = Uize.Dom.VirtualEvents.Remain.makeRemainInStateEventMaker (
  eventNameSTR,
  defaultDurationMsINT,
  timerTriggerEventSTRorEventsARRAY,
  timerCancelEventSTRorEventsARRAY,
  triggerEventsResetTimerBOOL,        // optional
  allowRefireBOOL                     // optional
);

3.3.1. eventNameSTR

A string, specifying the name of the remain-in-state virtual DOM Event.

The virtual DOM event maker function returned by this method is automatically registered by the name specified in the eventNameSTR parameter, using the Uize.Dom.VirtualEvent.register static method.

3.3.2. defaultDurationMsINT

An integer, specifying the default duration that should be used if a value is not specified for the durationMsINT parameter when the remain-in-state virtual DOM event's maker method is called, or if the value null or undefined is specified for this parameter.

3.3.3. timerTriggerEventSTRorEventsARRAY

A string, specifying a single event, or an array specifying multiple events that should be wired up to trigger the remain-in-state timer.

3.3.4. timerCancelEventSTRorEventsARRAY

A string, specifying a single event, or an array specifying multiple events that should be wired up to cancel the remain-in-state timer.

3.3.5. triggerEventsResetTimerBOOL

An optional boolean, specifying whether or not the trigger event(s) specified in the timerTriggerEventSTRorEventsARRAY parameter should reset the remain-in-state timer.

If this optional parameter is not specified, then the value true will be used as the default.

3.3.6. allowRefireBOOL

An optional boolean, specifying whether or not the event should be allowed to be refired after it has already fired once and before a cancel event specified in the timerCancelEventSTRorEventsARRAY parameter has been fired.

If this optional parameter is not specified, then the value true will be used as the default.

EXAMPLE

Uize.Dom.VirtualEvents.Remain.mouseRest = Uize.Dom.VirtualEvents.Remain.makeRemainInStateEventMaker (
  'mouseRest',                // event name is "mouseRest"
  500,                        // default duration of 500 milliseconds
  ['mouseover','mousemove'],  // remain-in-state timer trigger events
  ['mouseout','mousedown'],   // remain-in-state timer cancel events
  true,                       // trigger events do reset timer
  false                       // don't allow refiring until cancel occurs again
);

The above call to the Uize.Dom.VirtualEvents.Remain.mouseRest method would manufacture the mouseRest virtual DOM event that is offered in this module. This method is in fact used to make all of the remain-in-state virtual DOM events that are offered in the Uize.Dom.VirtualEvents.Remain module. For an exhaustive look at how this method can be used to manufacture virtual DOM event maker functions, take a look at the source code for this module.

NOTES

this method is intended for advanced users wishing to create their own unique remain-in-state virtual DOM events, beyond those that are supplied as built-in events in this module

IMPLEMENTATION INFO

this feature was introduced in this module

3.4. Uize.Dom.VirtualEvents.Remain.mouseRemainDown

Returns a virtual DOM event object, for an event that is fired when a user mouses down on a node and doesn't mouse up from that node or mouse out of it for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainDown (durationMsINT);

When a handler is wired for this virtual DOM event on a node, a timer is started when the user mouses down on the node. If the user doesn't mouse up from the node or mouse out of it for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If, however, the user does mouse up from the node, or if the user mouses out of the node before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainDown ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

NOTES

this virtual DOM event maker is registered with the name mouseRemainDown
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.5. Uize.Dom.VirtualEvents.Remain.mouseRemainOut

Returns a virtual DOM event object, for an event that is fired when a user mouses out of a node and doesn't mouse over that node again for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainOut (durationMsINT);

When a handler is wired for this virtual DOM event on a node, a timer is started when the user mouses out of the node. If the user doesn't mouse over the node again for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If, however, the user does mouse over the node again before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainOut ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

NOTES

this virtual DOM event maker is registered with the name mouseRemainOut
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.6. Uize.Dom.VirtualEvents.Remain.mouseRemainOver

Returns a virtual DOM event object, for an event that is fired when a user mouses over a node and doesn't mouse out of that node or mouse down on it for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainOver (durationMsINT);

When a handler is wired for this virtual DOM event on a node, a timer is started when the user mouses over the node. If the user doesn't mouse out of the node or mouse down on it for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If, however, the user does mouse out of the node, or if the user mouses down on the node before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainOver ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

NOTES

this virtual DOM event maker is registered with the name mouseRemainOver
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.7. Uize.Dom.VirtualEvents.Remain.mouseRemainUp

Returns a virtual DOM event object, for an event that is fired when a user mouses up on a node and doesn't mouse down again on that node for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainUp (durationMsINT);

When a handler is wired for this virtual DOM event on a node, a timer is started when the user mouses up on the node. If the user doesn't mouse down again on the node for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If, however, the user does mouse down again on the node before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainUp ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

NOTES

this virtual DOM event maker is registered with the name mouseRemainUp
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.8. Uize.Dom.VirtualEvents.Remain.mouseRest

Returns a virtual DOM event object, for an event that is fired once the user has rested the mouse over a node (and doesn't mouse out of that node or mouse down on it) for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRest (durationMsINT);

When a handler is wired for this virtual DOM event on a node, a timer is started when the user mouses over the node. If the user rests the mouse and doesn't mouse out of the node or mouse down on it for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If the user moves the mouse but stays over the node, then the timer is reset and the handler may still be executed if the user once again rests the mouse over the node for the required amount of time. If the user moves the mouse out of the node, or if the user mouses down on the node before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.mouseRemainOut ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

Because the mouserest event is a virtual DOM event, there is no dedicated browser event object that can be supplied to a handler for this event. What is supplied to an event handler is a copy of the last mouseover or mousemove browser event (likely the latter), allowing the handler to at least have access to coordinates that reflect the mouse position when the mouserest event is fired.

NOTES

this virtual DOM event maker is registered with the name mouseRest
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.9. Uize.Dom.VirtualEvents.Remain.remainBlurred

Returns a virtual DOM event object, for an event that is fired when a node loses focus and remains blurred / unfocused for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.remainBlurred (durationMsINT);

When a handler is wired for this virtual DOM event on a node, a timer is started when the node loses focus. If the node remains blurred / unfocused for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If, however, the node regains focus before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.remainBlurred ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

NOTES

this virtual DOM event maker is registered with the name remainBlurred
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

3.10. Uize.Dom.VirtualEvents.Remain.remainFocused

Returns a virtual DOM event object, for an event that is fired when a node stays focused for a specified amount of time.

SYNTAX

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.remainFocused (durationMsINT);

When a handler is wired for this virtual DOM event on a node, a timer is started when the node becomes focused. If the node remains focused for the amount of time specified by the durationMsINT parameter, then the handler wired for this event will be executed. If, however, the node loses focus before the required amount of time has elapsed, then the timer will be canceled and the handler will not be executed.

VARIATION

virtualDomEventOBJ = Uize.Dom.VirtualEvents.Remain.remainFocused ();

When no durationMsINT parameter is specified, then the value for this parameter is defaulted to 500 (half a second).

NOTES

this virtual DOM event maker is registered with the name remainFocused
see related remain-in-state virtual DOM event static methods

IMPLEMENTATION INFO

this feature was introduced in this module

4. Registered Virtual DOM Events

4.1. keyRemainDown

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.keyRemainDown static method.

SYNTAX

keyRemainDown()
keyRemainDown(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','keyRemainDown(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

4.2. keyRemainUp

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.keyRemainUp static method.

SYNTAX

keyRemainUp()
keyRemainUp(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','keyRemainUp(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

4.3. mouseRemainDown

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.mouseRemainDown static method.

SYNTAX

mouseRemainDown()
mouseRemainDown(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','mouseRemainDown(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

4.4. mouseRemainOut

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.mouseRemainOut static method.

SYNTAX

mouseRemainOut()
mouseRemainOut(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','mouseRemainOut(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

4.5. mouseRemainOver

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.mouseRemainOver static method.

SYNTAX

mouseRemainOver()
mouseRemainOver(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','mouseRemainOver(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

4.6. mouseRemainUp

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.mouseRemainUp static method.

SYNTAX

mouseRemainUp()
mouseRemainUp(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','mouseRemainUp(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

4.7. mouseRest

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.mouseRest static method.

SYNTAX

mouseRest()
mouseRest(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','mouseRest(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

4.8. remainBlurred

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.remainBlurred static method.

SYNTAX

remainBlurred()
remainBlurred(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','remainBlurred(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

4.9. remainFocused

The registered name for the virtual DOM event maker that is implemented in the Uize.Dom.VirtualEvents.Remain.remainFocused static method.

SYNTAX

remainFocused()
remainFocused(durationMsINT)

EXAMPLE

Uize.Dom.Basics.wire ('myNode','remainFocused(500)',function () {alert ('HELLO')});

NOTES

see related remain-in-state registered virtual DOM events

5. Static Properties

5.1. Uize.Dom.VirtualEvents.Remain.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

5.2. Uize.Dom.VirtualEvents.Remain.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module