Virtual DOM events allow sophisticated interactions with a node to be encapsulated into an implementation, so that the interaction can then be expressed as a single event.

Once a pattern of interaction is encapsulated into an implementation, you can then simply think of that interaction as an event. The section What is a Virtual DOM Event? discusses the classic example of the mouseRest virtual DOM event, which encapsulates wiring of handlers for the mouseover, mousemove, mouseout and mousedown real DOM events of a node, and also manages state for a timeout.

For some of the more sophisticated virtual DOM events, wiring a handler for a single virtual DOM event may result in wiring handlers for multiple real DOM events.

That's because some virtual DOM events need to track more than one real DOM event as part of their implementation. Fortunately, the way that DOM event wiring is implemented in the UIZE JavaScript Framework, unwiring a handler for a virtual DOM event automatically results in the unwiring of all the real DOM event handlers it wired.

Virtual DOM events are semantically equivalent to real DOM events.

This means that you can use them and think about them in your application code as if they were real DOM events. This means you can wire handlers for virtual DOM events along with real DOM events. Similarly, you can unwire them along with real DOM events.

While a Virtual DOM Event itself does not take parameters, a Virtual DOM Event Maker can accept parameters and produce different instances of the same "flavor" of virtual DOM event with slightly different behavior depending on the values supplied for the parameters that the Virtual DOM Event Maker supports.

This may sound a little abstract, but what it essentially means is that you can tune the behavior of a certain type of virtual DOM event through its parameters. Take the example of the mouseRest virtual DOM event, which lets you specify how long the mouse should be rested on the node before the event is fired. This parameter makes this type of virtual DOM event more versatile than if it only supported one rest duration (for a code example that illustrates this point well, see the section Unique Parameters Translate To Unique Events).

The preferred way to specify a virtual DOM event when wiring and unwiring handlers for it is to use a reference to the virtual DOM event object.

EXAMPLE

Uize.Node.wire (
  'myNode',                                 // ID of node being wired
  Uize.Node.VirtualEvent.mouseRest (2000),  // reference to virtual DOM event object
  function () {alert ('mouse rested!')}     // the handler for the mouseRest event
);

In the above example, a handler is being wired for the virtual DOM event Uize.Node.VirtualEvent.mouseRest (2000). This call to the Uize.Node.VirtualEvent.mouseRest static method, with the value 2000 specified for the method's durationMsINT parameter, returns a virtual DOM event object for an event that will be fired when the user rests the mouse over a node for two seconds.

Specifying a virtual DOM event by object reference is preferred because it is clear from looking at the code what dependencies there are on modules that define virtual DOM events. Looking at the above example, it is clear that this code depends upon the Uize.Node.VirtualEvent module, which is where the Uize.Node.VirtualEvent.mouseRest Virtual DOM Event Maker is defined. When Specifying Virtual DOM Events By Registered Name, it is not obvious what module dependencies exist for virtual DOM events being used.

1.4.1.1. Capturing a DOM Event Object Reference

var mouseRest2000 = Uize.Node.VirtualEvent.mouseRest (2000);

Uize.Node.wire ('myNode1',mouseRest2000,function () {alert ('mouse rested on myNode1')});
Uize.Node.wire ('myNode2',mouseRest2000,function () {alert ('mouse rested on myNode2')});

When a Virtual DOM Event Maker is registered, as most are (see Register Your Virtual DOM Event), then instances of the virtual DOM event can be specified in a string, along with parameters that the Virtual DOM Event Maker may support.

EXAMPLE

Uize.Node.wire (
  'myNode',                              // ID of node being wired
  'mouseRest(2000)',                     // virtual DOM event name and parameters
  function () {alert ('mouse rested!')}  // the handler for the mouseRest event
);

In the above example, a handler is being wired for the mouseRest virtual DOM event, with a rest duration of 2000 milliseconds (2 seconds) specified. Because of the specific way that this Virtual DOM Event Maker is registered, the event name 'mouseRest(2000)' actually maps through to the method call Uize.Node.VirtualEvent.mouseRest (2000).

1.4.2.1. Advantages

1.4.2.2. Disadvantages

1.4.2.3. Important Considerations

Different combinations of parameter values supplied to a Virtual DOM Event Maker will produce unique Virtual DOM Event objects.

As such, different handlers can be wired for virtual DOM events that only differ in their parameter values - for the same DOM node. Consider the following example...

EXAMPLE

Uize.Node.wire (
  'myNode',
  {
    'mouseRest(500)':function () {console.log ('mouse rested on myNode for .5 seconds')},
    'mouseRest(1000)':function () {console.log ('mouse rested on myNode for 1 second')},
    'mouseRest(1500)':function () {console.log ('mouse rested on myNode for 1.5 seconds')},
    'mouseRest(2000)':function () {console.log ('mouse rested on myNode for 2 seconds')}
  }
);

In the above example, four event handlers are being wired. Each of the four virtual DOM events being wired up are created from the same Uize.Node.VirtualEvent.mouseRest static method, but each is considered a different event. This allows different handlers to be registered for each.

After the above code has executed, resting the mouse on the DOM node with the id of "myNode" for longer than two seconds will result in all four mouseRest events being fired, and all four handlers will be executed in order and at 500 millisecond intervals. The handler for the mouseRest(500) event will be executed after resting the mouse for 500 milliseconds, the handler for the mouseRest(1000) event will be executed after resting the mouse for 1000 milliseconds, the handler for the mouseRest(1500) event will be executed after resting the mouse for 1500 milliseconds, and the handler for the mouseRest(2000) event will be executed after resting the mouse for 2000 milliseconds.

If you were to rest the mouse on the node for 1500 milliseconds, then only the handlers for the mouseRest(500), mouseRest(1000), and mouseRest(1500) events would be executed. If you were to rest the mouse on the node for 1000 milliseconds, then only the handlers for the mouseRest(500) and mouseRest(1000) events would be executed. If you were to rest the mouse on the node for 500 milliseconds, then only the handler for the mouseRest(500) event would be executed. And if you were to rest the mouse on the node for less than 500 milliseconds, then none of the handlers would be executed.

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.Node.VirtualEvent module.

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

1.8.1.2. Remain-in-state Registered Virtual DOM Events

Click-with-modifier virtual DOM events are events that are fired when a node is clicked with a specific combination of modifier keys pressed.

These events are useful when you need to trigger different actions when a node is clicked with different modifier keys pressed. For example, you may want clicking on a navigation link to navigate in normal increments, ctrl-clicking on the same link to navigate in finer increments, and shift-clicking on the link to navigate in coarser increments. Now, you can certainly achieve this effect without the help of the click-with-modifier virtual DOM events, simply by wiring a handler to the click event of the navigation link and then inspecting the values of the ctrlKey and shiftKey properties of the DOM event object in your handler code. However, the virtual DOM events provide a more concise and readable way to express this kind of event wiring.

Consider the following hypothetical example that wires up different behaviors for clicking (no modifier keys pressed), ctrl-clicking (only ctrl modifier key pressed), shift-clicking (only shift modifier key pressed), and alt-clicking (only alt modifier key pressed)...

INSTEAD OF...

Uize.Node.wire (
  'myNode',
  'click',
  function (_event) {
    if (!_event.shiftKey && !_event.ctrlKey && !_event.altKey) {
      doClickAction ();
    } else if (_event.ctrlKey && !_event.shiftKey && !_event.altKey) {
      doCtrlClickAction ();
    } else if (_event.shiftKey && !_event.ctrlKey && !_event.altKey) {
      doShiftClickAction ();
    } else if (_event.altKey && !_event.ctrlKey && !_event.shiftKey) {
      doAltClickAction ();
    }
  }
);

USE...

Uize.Node.wire (
  'myNode',
  {
    'click()':doClickAction,
    'ctrlClick()':doCtrlClickAction,
    'shiftClick()':doShiftClickAction,
    'altClick()':doAltClickAction
  }
);

What you'll notice from the example is that the code using the click-with-modifier virtual DOM events is considerably smaller - and, certainly, also easier to read. The click Virtual DOM Event is only fired when the node is clicked with no modifier keys pressed. Likewise, the ctrlClick Virtual DOM Event is only fired when only the ctrl modifier key is pressed. The same principle applies to the shiftClick and altClick virtual DOM events. When using the normal click event, one has to do all the testing for modifier keys oneself, whereas the click-with-modifier virtual DOM events take care of all of this for you.

IMPORTANT

Important to note here is that the click Virtual DOM Event must be specified as 'click()' - if you were to omit the parentheses then you would be wiring a handler for the standard click DOM event.

1.8.2.1. Click-with-modifier Virtual DOM Event Static Methods

1.8.2.2. Click-with-modifier Registered Virtual DOM Events

The features listed in this section have been introduced in this module.

STATIC METHODS

Uize.Node.VirtualEvent.altClick | Uize.Node.VirtualEvent.click | Uize.Node.VirtualEvent.ctrlAltClick | Uize.Node.VirtualEvent.ctrlClick | Uize.Node.VirtualEvent.getCached | Uize.Node.VirtualEvent.keyRemainDown | Uize.Node.VirtualEvent.keyRemainUp | Uize.Node.VirtualEvent.makeRemainInStateEventMaker | Uize.Node.VirtualEvent.mouseRemainDown | Uize.Node.VirtualEvent.mouseRemainOut | Uize.Node.VirtualEvent.mouseRemainOver | Uize.Node.VirtualEvent.mouseRemainUp | Uize.Node.VirtualEvent.mouseRest | Uize.Node.VirtualEvent.register | Uize.Node.VirtualEvent.remainBlurred | Uize.Node.VirtualEvent.remainFocused | Uize.Node.VirtualEvent.resolve | Uize.Node.VirtualEvent.shiftAltClick | Uize.Node.VirtualEvent.shiftClick | Uize.Node.VirtualEvent.shiftCtrlAltClick | Uize.Node.VirtualEvent.shiftCtrlClick

STATIC PROPERTIES

Uize.Node.VirtualEvent.moduleName

No features have been overridden in this module.

This module has no inherited features.

Uize.Node.VirtualEvent.Edge

There is no dedicated unit tests module for the Uize.Node.VirtualEvent module.

A string, identifying the combination of the event and its parameters, and that should always be the same for the same combination of parameter values.

SYNTAX

[eventName]([eventParameters])

The value of the virtualDomEvent Property should consist of the name of the virtual DOM event, followed by parentheses that contain a serialization of the parameter values for the virtual DOM event. For virtual DOM events that don't support any parameters, the parentheses should still be present but should be empty.

EXAMPLE 1

mouseRest(1000)

The mouseRest virtual DOM event can accept a single durationMsINT parameter. For a 1000 millisecond mouseRest event, the value of the virtualDomEvent Property in the event object would be 'mouseRest(1000)', representing the registered name of the event's Virtual DOM Event Maker, combined with the serialization of the parameter values inside parentheses.

EXAMPLE 2

ctrlClick()

The ctrlClick virtual DOM event does not take any parameters, and so the value of the virtualDomEvent Property is simply the registered name of the event's Virtual DOM Event Maker followed by empty parentheses.

A function, that will be called at the time that the Virtual DOM Event is wired up for a specific node, and that is responsible for performing the more complex wiring logic in order to implement the virtual DOM event for the node.

A function reference that you specify for this property should expect to receive three parameters and have the following basic structure...

SYNTAX

function (nodeOBJ,handlerFUNC,subWiringsOwnerIdSTR) {
  // wire up the logic and DOM events to implement this virtual DOM event
}

2.1.2.1. nodeOBJ

2.1.2.2. handlerFUNC

2.1.2.3. subWiringsOwnerIdSTR

To gain a better understanding of the virtual DOM event object's interface, let's take a look at a basic example...

EXAMPLE

var myCtrlClick = {
  virtualDomEvent:'myCtrlClick()',
  wire:function (_node,_handler,_subWiringsOwnerId) {
    Uize.Node.wire (
      _node,
      'click',
      function (_event) {
        if (_event.ctrlKey && !_event.shiftKey && !_event.altKey && !_event.metaKey)
          _handler.call (_node,_event)
        ;
      }
    );
  }
};

Uize.Node.wire ('myNode1',myCtrlClick,function () {alert ('myNode1 was ctrl-clicked')});
Uize.Node.wire ('myNode2',myCtrlClick,function () {alert ('myNode2 was ctrl-clicked')});

In the above example, a virtual DOM event object is being defined and then assigned to the local variable myCtrlClick. Any handler wired for this event will be executed when the user clicks on the node for which the event is wired, while holding down the ctrl modifier key and no other modifier keys. This somewhat basic virtual DOM event is not parameterized like the mouseRest event that was mentioned earlier. To learn how to implement parameterized virtual DOM events, consult the more advanced section Implementing Virtual DOM Events.

Looking at the function specified for the wire Property, you'll notice that it wires up a handler for the real "click" DOM event for the node, and this handler tests to see if only the ctrl modifier key is pressed by checking the values of the ctrlKey, shiftKey, altKey, and metaKey properties of the DOM event object. If only the ctrl modifier key is pressed, then the handler supplied when calling the wire Property function will be called as an instance method on the node for which the virtual DOM event is wired. This is done by calling the call method on the handler function, and supplying a reference to the DOM node as the first parameter (the this context) and a reference to the "click" DOM event as the second parameter (the single parameter that the handler function will receive).

Once the virtual DOM event object has been defined, it can then be used to wire DOM nodes. In this example, the myCtrlClick virtual DOM event is being wired for the two nodes with the id values of "myNode1" and "myNode2". This is done simply by specifying myCtrlClick as the event when calling the Uize.Node.wire static method. Here you can clearly see a major benefit of virtual DOM events: once a particular interaction is expressed and encapsulated in the form of a virtual DOM event, that event can then be applied against any number of DOM nodes. A virtual DOM event is an elegant vehicle for code reuse when it comes to DOM event driven user interaction patterns.

To allow virtual DOM events to be Customizable Using Parameters, a virtual DOM event maker can accept parameters.

For virtual DOM event makers that do accept parameters, different combinations of parameter values should result in different Virtual DOM Event objects being returned, but the same object should always be returned for the same combination of parameter values. This is partly for performance reasons, to reduce the number of virtual DOM event objects created when using virtual DOM events extensively, but a more important reason is to allow handlers wired for a particular virtual DOM event to be matched during unwiring. Consider the following example...

EXAMPLE

Uize.Node.wire (
  'myNode',
  Uize.Node.VirtualEvent.mouseRest (1000),
  function () {alert ('Mouse rested on myNode for one second!')}
);

Uize.Node.unwire ('myNode',Uize.Node.VirtualEvent.mouseRest (1000));

In the above example, a handler is wired for a 1000 millisecond mouseRest event on the DOM node with the id of "myNode". The mouseRest virtual DOM event is specified in this case by object reference (see Specifying Virtual DOM Events By Object Reference). Now, when unwiring handlers for the 1000 millisecond mouseRest event on the DOM node, the Uize.Node.VirtualEvent.mouseRest method is called again, with the same 1000 value for the method's durationMsINT parameter. Because the Uize.Node.VirtualEvent.mouseRest method always returns a reference to the same object when the same parameter values are specified, the Virtual DOM Event object specified when unwiring is the same object as was specified when wiring the node, and the Uize.Node.unwire method can successfully find the matching event wiring and unwire it.

To make it easy for virtual DOM event makers to return the same virtual DOM event object for the same parameter values, the Uize.Node.VirtualEvent.getCached static method can be used in the implementation of a virtual DOM event maker (see Implementing Virtual DOM Events for further detail).

For the purposes of illustrating various points about implementing virtual DOM events, let's consider a hypothetical example of a myRemainFocused virtual DOM event.

A handler wired for this event should be executed when the node for which the event is wired becomes focused and remains focused for a specified amount of time. This virtual DOM event is, therefore, parameterized, since its maker method should accept a single duration parameter. And, because the implementation of the event requires a timer, each wiring of this event for a specific node will need to maintain its own state.

Now, there is a remainFocused virtual DOM event implemented in the Uize.Node.VirtualEvent module, but the implementation for this event is a little more complicated and abstract because the maker method for this event is actually "manufactured" using a more generalized implementation approach that is used to manufacture all of the Remain-in-state Virtual DOM Events offered in this module. So, instead, we will focus solely on implementing a dedicated myRemainFocused event and not get too tricky just yet.

Before we get deep into looking at the implementation of the wiring logic for the myRemainFocused virtual DOM event, let's first take a look at the basic skeleton for defining this event's maker method.

EXAMPLE

MyVirtualDomEvents.myRemainFocused = function (_duration) {
  return Uize.Node.VirtualEvent.getCached (
    'myRemainFocused(' + _duration + ')',
    function (_node,_handler,_subWiringsOwnerId) {
      // ... ... ...
      // IMPLEMENTATION GOES HERE
      // ... ... ...
    }
  );
};

The first thing you should notice from the above example is that the maker method is being assigned as the MyVirtualDomEvents.myRemainFocused static method of the hypothetical MyVirtualDomEvents namespace. The maker accepts a single parameter, being the duration that the wired node needs to remain focused before the handler for the event is executed.

The maker method returns a Virtual DOM Event object, but it does so using the Uize.Node.VirtualEvent.getCached static method. This method ensures that the same object is always returned for the same duration parameter value. The first parameter for the Uize.Node.VirtualEvent.getCached method is the cache key, which is formed using the event name combined with the serialized parameter values inside parentheses.

The second parameter for the Uize.Node.VirtualEvent.getCached method is the wiring function, which corresponds to the wire property of the Virtual DOM Event object. While we won't get into implementation of the wiring logic just yet, you will notice that the wiring function accepts three parameters: a node that should be wired, the handler for the event, and an ID that should be used to associate subwirings to the master virtual DOM event wiring (more on all that later).

Virtual DOM events that are parameterized, or that manage complex interactions where event patterns need to be discerned, will need to maintain state.

There are two key levels at which state is important for virtual DOM events, State Management at the Instance Level and State Management at the Wiring Level, which are covered in more detail below...

Parameterized virtual DOM events, such as the many Remain-in-state Virtual DOM Events, can have many instances per type.

With our own Hypothetical Example, the myRemainFocused virtual DOM event can have many different instances - one for each unique value of the maker method's durationMsINT parameter. Within the scope of each different instance of this event type, the value for the durationMsINT parameter needs to maintain its integrity. This can be accomplished using a closure.

If you refer back to the example shown in the section The Basic Skeleton, you'll notice that the wiring function (the one with the "IMPLEMENTATION GOES HERE" comment in it) is a closure inside the scope that has the _duration parameter. This means that for any instance of the myRemainFocused event for a specific duration, the wiring function can access the value of the _duration parameter and count on it remaining the same for that instance of the myRemainFocused event - no matter how many nodes are wired for the same instance.

3.3.4.1. Defaulting Event Parameter Values

MyVirtualDomEvents.myRemainFocused = function (_duration) {
  if (_duration == null) _duration = 500;
  return Uize.Node.VirtualEvent.getCached (
    'myRemainFocused(' + _duration + ')',
    function (_node,_handler,_subWiringsOwnerId) {
      // ... ... ...
      // IMPLEMENTATION GOES HERE
      // ... ... ...
    }
  );
};

Beyond State Management at the Instance Level, wiring logic for more sophisticated virtual DOM events may involve state management at the wiring level.

This is especially true for virtual DOM events that require a pattern of interaction over time. In such cases, a specific wiring of such a virtual DOM event will need to keep track of where the user is in a pattern of interaction, in order to determine when the user either completes or terminates the interaction. To this end, the power of closures once again comes to our aid.

By completing the implementation of the wiring logic for the myRemainFocused virtual DOM event from our Hypothetical Example, we can demonstrate how state can be maintained by using the wiring function as a closure for other functions that can then use the wiring function's scope as a store for event state. Consider the following example...

EXAMPLE

MyVirtualDomEvents.myRemainFocused = function (_duration) {
  if (_duration == null) _duration = 500;
  return Uize.Node.VirtualEvent.getCached (
    'myRemainFocused(' + _duration + ')',
    function (_node,_handler,_subWiringsOwnerId) {
      var _timeout;
      Uize.Node.wire (
        _node,
        {
          focus:function (_event) {
            var _eventCopy = Uize.copyInto ({},_event);
            _timeout = setTimeout (
              function () {_handler.call (_node,_eventCopy)},
              _duration
            );
          },
          blur:function () {_timeout = clearTimeout (_timeout)}
        },
        _subWiringsOwnerId
      );
    }
  );
};

In the implementation of our myRemainFocused event, we are maintaining state for a _timeout variable. This variable is declared inside the wiring function's scope - a scope that is common to the handlers that are wired for the focus and blur real DOM events of the node that is being wired for the myRemainFocused virtual DOM event. This allows the blur event handler to access and modify the same state that is shared by the focus event handler. So, they're both seeing the same _timeout variable.

Now, when the myRemainFocused virtual DOM event is wired for a specific node, the focus and blur real DOM events are wired for the node, so that focusing the node sets a timeout to execute the myRemainFocused event's handler once a period of time (specified by the _duration parameter) has elapsed. If the node loses its focus before that period of time has elapsed, then the timeout is canceled. One instance of the myRemainFocused virtual DOM event (eg. MyVirtualDomEvents.myRemainFocused (1000)) can be used in multiple different wirings, and each wiring will maintain its own state for the _timeout variable during user interaction with the wired node.

More complex virtual DOM event implementations may involve maintaining much more state at the wiring level than this simple example, but the fundamental principle remains the same.

Registering a virtual DOM event is easy and is done using the Uize.Node.VirtualEvent.register static method.

Using the myRemainFocused virtual DOM event from our Hypothetical Example, the statement for registering the event would be as follows...

EXAMPLE

Uize.Node.VirtualEvent.register (
  'myRemainFocused',                  // registered name (without parentheses)
  MyVirtualDomEvents.myRemainFocused  // virtual DOM event maker method
);

The first parameter for the Uize.Node.VirtualEvent.register method is the registered name of the virtual DOM event, and the second parameter is a reference to the maker method. The registered name for a virtual DOM event does not have to match the naming of the event's maker method. By convention, however, it usually does. In our case, the maker method is MyVirtualDomEvents.myRemainFocused, and the registered name of the event is "myRemainFocused". Notice that the registered name for the event does not contain the trailing parentheses and parameter set that would be used when specifying the event in the node wiring and unwiring methods.

When registering virtual DOM events, it must be kept in mind that the names of all virtual DOM events effectively exist in the same namespace when they are registered.

This means that you registering a virtual DOM event by a name that's already in use will result in the event previously registered by that name being "unseated". Consider the following example...

EXAMPLE

Uize.Node.VirtualEvent.register ('remainFocused',MyVirtualDomEvents.myRemainFocused);

In the above example, we're registering the virtual DOM event we used in our Hypothetical Example by the name "remainFocused". Unfortunately, the Uize.Node.VirtualEvent module defines its own remainFocused virtual DOM event. So, in this case, our own implementation will override the implementation of the remainFocused event that is registered by this module.

When specifying virtual DOM events by name in the node wiring and unwiring methods, not having to dereference off a namespace makes things more concise, but using a shared namespace brings with it the peril of naming collisions.

While there are benefits to registering virtual DOM events, it should be noted that registering them is not absolutely necessary.

When a virtual DOM event's maker method is not registered, then it will not be possible to specify the event and its parameters using a string form - it will only be possible to get a reference to a virtual DOM event object by calling the maker method. It will also not be possible to specify the event when using the variation of the wiring and unwiring methods that take an eventNamesToHandlersMapOBJ parameter that specifies multiple wirings of events to handlers (for an example of this, see the section Unique Parameters Translate To Unique Events).

Depending on the application for a particular virtual DOM event, registering it may or may not be compelling.

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.Node.VirtualEvent.register static method.

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.

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

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

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.

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.