Utilities

Utilities

dgrid includes a few modules under the util directory, which provide common utilities.

util/mouse

The util/mouse module defines a number of simulated events which are useful in situations which require the mouse moving into and/or out of rows or cells. These scenarios warrant custom simulated events due to the often-problematic bubbling nature of the mouseover and mouseout DOM events.

The following simulated events are provided:

• enterRow: fires when the mouse moves into a row within the body of a list or grid.
• leaveRow: fires when the mouse moves out of a row within the body of a list or grid.
• enterCell: fires when the mouse moves into a cell within the body of a grid.
• leaveCell: fires when the mouse moves out of a cell within the body of a grid.
• enterHeaderCell: fires when the mouse moves into a cell within the header of a grid.
• leaveHeaderCell: fires when the mouse moves out of a cell within the header of a grid.

util/touch

The util/touch module defines two simple extension events, tap and doubletap, for detecting the respective actions on touch devices.

In addition, it exposes the following functions:

• countCurrentTouches(event, node) - a function which counts the number of currently active touches which fall within the given node; useful in cases where other handlers may call stopPropagation, thus affecting other means of counting touches.
• selector(selector, eventType, children) - a version of the selector function from dojo/on, with an additional fix to work around issues experienced on iOS Safari. This is used by dgrid/Selection and dgrid/tree for touch event handling.

util/misc

The util/misc module provides miscellaneous utility functions. Currently this consists of functions related to throttling or debouncing function calls (particularly for events which tend to fire rapidly, such as scroll).

For those unfamiliar with these concepts, they both center around the idea of limiting the frequency in which functions are called.

• throttling limits a function to being called at most once within a given period of time; subsequent calls within the same time window are ignored.
• debouncing involves waiting until a certain amount of time has elapsed before calling the function; the target function will not be called at all until no calls have been made within that amount of time.

util/misc provides three functions relating to these concerns: throttle, debounce, and throttleDelayed, all of which return new functions wrapped with the appropriate limiting logic. These functions accept three parameters: the function to limit, the context to run that function in (global if unspecified), and an optional delay. If a delay is not specified, it falls back to the value of defaultDelay, which is also exposed on the util/misc module return value.

throttle and debounce do what one would expect based on the above definitions. throttleDelayed acts like throttle, but runs the target function after each time window elapses, rather than before it. This can be useful for things like scroll events, where the last event is really what matters, but you still want to handle intermediate events as well.