DragSelect

DragSelect

new DragSelect(options)

Source:
Parameters:
Name Type Description
options object The options object.
Name Type Attributes Default Description
area HTMLElement | SVGElement | Document <optional>
document area in which you can drag. If not provided it will be the whole document
autoScrollSpeed number <optional>
1 Speed in which the area scrolls while selecting (if available). Unit is pixel per movement. Default = 1
zoom number <optional>
1 Zoom scale factor (in case of using CSS style transform: scale() which messes with real positions). Unit scale zoom. Default = 1
callback function <optional>
(selected, event) => {} a callback function that gets fired when the element is dropped. This callback gets a property which is an array that holds all selected nodes. The second property passed is the event object.
customStyles boolean <optional>
false if set to true, no styles (except for position absolute) will be applied by default
hoverClass string <optional>
ds-hover the class assigned to the mouse hovered items
multiSelectMode boolean <optional>
false Add newly selected elements to the selection instead of replacing them. Default = false
onDragMove function <optional>
()=>{} It is fired when the user drags. This callback gets the event object. Executed before DragSelect function code ran, after getting the current mouse position.
onDragStartBegin function <optional>
()=>{} Is fired when the user clicks in the area. This callback gets the event object. Executed *before* DragSelect function code ran.
onDragStart function <optional>
()=>{} It is fired when the user clicks in the area. This callback gets the event object. Executed after DragSelect function code ran, before the setup of event listeners.
onElementSelect function <optional>
()=>{} It is fired every time an element is selected. This callback gets a property which is the just selected node
onElementUnselect function <optional>
()=>{} It is fired every time an element is de-selected. This callback gets a property which is the just de-selected node
selectableClass string <optional>
ds-selectable the class assigned to the elements that can be selected
selectables Array.<HTMLElement> | Array.<SVGElement> | HTMLElement | SVGElement <optional>
[] the elements that can be selected
selectedClass string <optional>
ds-selected the class assigned to the selected items
selector HTMLElement <optional>
HTMLElement the square that will draw the selection
selectorClass string <optional>
ds-selector the class assigned to the square selector helper
multiSelectKeys Array.<string> <optional>
['ctrlKey', 'shiftKey', 'metaKey'] An array of keys that allows switching to the multi-select mode (see the @multiSelectMode option). The only possible values are keys that are provided via the event object. So far: ctrlKey, shiftKey, metaKey and altKey. Provide an empty array `[]` if you want to turn off the functionality.

Members

_initialCursorPos :Object

Source:
Type:
  • Object

_initialScroll :Object

Source:
Type:
  • Object

_multiSelectKeyPressed :boolean

Source:
Type:
  • boolean

_newCursorPos :Object

Source:
Type:
  • Object

_previousCursorPos :Object

Source:
Type:
  • Object

_prevSelected :Array.<(SVGElement|HTMLElement)>

Source:
Type:
  • Array.<(SVGElement|HTMLElement)>

_selected :Array.<(SVGElement|HTMLElement)>

Source:
Type:
  • Array.<(SVGElement|HTMLElement)>

Methods

addSelectables(_nodes, addToSelectionopt) → {Array.<(HTMLElement|SVGElement)>}

Add nodes that can be selected. The algorithm makes sure that no node is added twice
Source:
Parameters:
Name Type Attributes Description
_nodes Array.<(HTMLElement|SVGElement)> dom nodes
addToSelection boolean <optional>
if elements should also be added to current selection
Returns:
Type:
Array.<(HTMLElement|SVGElement)>
_nodes the added node(s)

addSelection(_nodes, triggerCallbackopt, dontAddToSelectablesopt) → {Array.<(HTMLElement|SVGElement)>}

Adds several items to the selection list also adds the specific classes and take into account all calculations. Does not clear the selection, in contrary to .setSelection Can add multiple nodes at once, in contrary to .select
Source:
Parameters:
Name Type Attributes Description
_nodes Array.<(HTMLElement|SVGElement)> one or multiple nodes
triggerCallback boolean <optional>
if callback should be called
dontAddToSelectables boolean <optional>
if element should not be added to the list of selectable nodes
Returns:
Type:
Array.<(HTMLElement|SVGElement)>
all selected nodes

break()

Function break: used in callbacks to disable the execution of the upcoming code at the specific moment In contrary to stop(): - Event listeners, callback calls and calculation will continue working - Selector won’t display and will not select
Source:

checkIfInsideSelection(forceopt) → {boolean}

Checks if any selectable element is inside selection.
Source:
Parameters:
Name Type Attributes Description
force boolean <optional>
forces through. Handles first clicks and accessibility. Here is user is clicking directly onto some element at start, (contrary to later hovers) we can assume that he really wants to select/deselect that item.
Returns:
Type:
boolean

clearSelection(triggerCallbackopt) → {Array.<(HTMLElement|SVGElement)>}

Unselect / Deselect all current selected Nodes
Source:
Parameters:
Name Type Attributes Description
triggerCallback boolean <optional>
if callback should be called
Returns:
Type:
Array.<(HTMLElement|SVGElement)>
this.selected, should be empty

getAreaRect(area) → {Object}

Returns the top/left/bottom/right/width/height values of a node. If Area is document then everything except the sizes will be nulled.
Source:
Parameters:
Name Type Description
area HTMLElement | SVGElement | any
Returns:
Type:
Object

getCurrentCursorPosition() → {Object}

Returns the last seen position of the cursor/selector
Source:
Returns:
Type:
Object

getCursorPos(eventopt, _areaopt, ignoreScrollopt) → {Object}

Returns cursor x, y position based on event object Will be relative to an area including the scroll unless advised otherwise
Source:
Parameters:
Name Type Attributes Description
event Object <optional>
_area HTMLElement | SVGElement | false <optional>
containing area / this.area if === undefined / document if === false
ignoreScroll boolean <optional>
if true, the scroll will be ignored
Returns:
Type:
Object
cursor { x/y }

getCursorPositionDifference(usePreviousCursorDifferenceopt) → {Object}

Returns the cursor position difference between start and now If usePreviousCursorDifference is passed, it will output the cursor position difference between the previous selection and now
Source:
Parameters:
Name Type Attributes Description
usePreviousCursorDifference boolean <optional>
Returns:
Type:
Object

getInitialCursorPosition() → {Object}

Returns the starting/initial position of the cursor/selector
Source:
Returns:
Type:
Object

getPreviousCursorPosition() → {Object}

Returns the previous position of the cursor/selector
Source:
Returns:
Type:
Object

getScroll(areaopt) → {Object}

Returns the current x, y scroll value of a container If container has no scroll it will return 0
Source:
Parameters:
Name Type Attributes Description
area HTMLElement | SVGElement <optional>
Returns:
Type:
Object
scroll X/Y

getSelectables() → {Array.<(HTMLElement|SVGElement)>}

Gets all nodes that can be selected
Source:
Returns:
Type:
Array.<(HTMLElement|SVGElement)>
this.selectables

getSelection() → {Array.<(HTMLElement|SVGElement)>}

Returns the current selected nodes
Source:
Returns:
Type:
Array.<(HTMLElement|SVGElement)>

isCursorNearEdge(eventopt, area) → {'top'|'bottom'|'left'|'right'|false}

Check if the selector is near an edge of the area
Source:
Parameters:
Name Type Attributes Description
event Object <optional>
event object.
area HTMLElement | SVGElement the area.
Returns:
Type:
'top' | 'bottom' | 'left' | 'right' | false

removeSelectables(_nodes, removeFromSelectionopt) → {Array.<(HTMLElement|SVGElement)>}

Remove nodes from the nodes that can be selected.
Source:
Parameters:
Name Type Attributes Description
_nodes Array.<(HTMLElement|SVGElement)> – dom nodes
removeFromSelection boolean <optional>
if elements should also be removed from current selection
Returns:
Type:
Array.<(HTMLElement|SVGElement)>
_nodes – the removed node(s)

removeSelection(_nodes, triggerCallbackopt, removeFromSelectablesopt) → {Array}

Removes specific nodes from the selection Multiple nodes can be given at once, in contrary to unselect
Source:
Parameters:
Name Type Attributes Description
_nodes Array.<(HTMLElement|SVGElement)> one or multiple nodes
triggerCallback boolean <optional>
if callback should be called
removeFromSelectables boolean <optional>
if element should be removed from the list of selectable nodes
Returns:
Type:
Array
all selected nodes

reset(eventopt, withCallbackopt)

Unbind functions i.e. when mouse click is released
Source:
Parameters:
Name Type Attributes Description
event Object <optional>
The event object.
withCallback boolean <optional>
whether or not the callback should be called

select(item) → {HTMLElement|SVGElement|false}

Adds an item to the selection.
Source:
Parameters:
Name Type Description
item HTMLElement | SVGElement selected item.
Returns:
Type:
HTMLElement | SVGElement | false
item

setSelectables(nodes, removeFromSelectionopt, addToSelectionopt) → {Array.<(HTMLElement|SVGElement)>}

Sets all elements that can be selected. Removes all current selectables (& their respective classes). Adds the new set to the selectables set, thus replacing the original set.
Source:
Parameters:
Name Type Attributes Description
nodes Array.<(HTMLElement|SVGElement)> – dom nodes
removeFromSelection boolean <optional>
if elements should also be removed from current selection
addToSelection boolean <optional>
if elements should also be added to current selection
Returns:
Type:
Array.<(HTMLElement|SVGElement)>
nodes – the added node(s)

setSelection(_nodes, triggerCallbackopt, dontAddToSelectablesopt) → {Array.<(HTMLElement|SVGElement)>}

Sets the current selected nodes and optionally run the callback By default, adds new elements also to the list of selectables
Source:
Parameters:
Name Type Attributes Description
_nodes Array.<(HTMLElement|SVGElement)> – dom nodes
triggerCallback boolean <optional>
if callback should be called
dontAddToSelectables boolean <optional>
if element should not be added to the list of selectable nodes
Returns:
Type:
Array.<(HTMLElement|SVGElement)>

start()

Starts the functionality. Automatically triggered when created. Also, reset the functionality after a teardown
Source:

stop(removeopt, fromSelectionopt, withCallbackopt)

Complete function teardown Will teardown/stop the whole functionality
Source:
Parameters:
Name Type Attributes Default Description
remove boolean <optional>
true if elements should be removed.
fromSelection boolean <optional>
true if elements should also be added/removed to the selection.
withCallback boolean <optional>
if elements should also be added/removed to the selection.

toggle(item) → {HTMLElement|SVGElement}

Adds/Removes an item to the selection. If it is already selected = remove, if not = add.
Source:
Parameters:
Name Type Description
item HTMLElement | SVGElement – item to select.
Returns:
Type:
HTMLElement | SVGElement
item

toggleSelection(_nodes, triggerCallbackopt, specialopt) → {Array}

Toggles specific nodes from the selection: If element is not in selection it will be added, if it is already selected, it will be removed. Multiple nodes can be given at once.
Source:
Parameters:
Name Type Attributes Description
_nodes Array.<(HTMLElement|SVGElement)> one or multiple nodes
triggerCallback boolean <optional>
if callback should be called
special boolean <optional>
if true, it also removes selected elements from possible selectable nodes & don’t add them to selectables if they are not
Returns:
Type:
Array
all selected nodes

unselect(item) → {HTMLElement|SVGElement|false}

Removes an item from the selection.
Source:
Parameters:
Name Type Description
item HTMLElement | SVGElement selected item.
Returns:
Type:
HTMLElement | SVGElement | false
item