API Reference
The SelectionArea
is the main class of the library, it is responsible for handling the selection process. It is passed to each event and can be used to interact with the selection process.
Static Properties
The only static property is the version of the library.
version: string;
Methods
constructor
Instantiates a new SelectionArea
.
constructor(opt: PartialSelectionOptions): SelectionArea;
opt: PartialSelectionOptions
- The options for the selection area.
trigger
Manually triggers the start of a selection, can be used to start a selection without a user interaction.
trigger(evt: MouseEvent | TouchEvent, silent = true): void;
evt: MouseEvent | TouchEvent
- A MouseEvent or TouchEvent-like object.silent: boolean
- Ifbeforestart
should be fired.
resolveSelectables
Updates the list of selectables, useful if new elements have been added during a selection.
resolveSelectables(): void;
clearSelection
Clears the selection.
clearSelection(includeStored = true, quiet = false): void;
includeStored: boolean
- If the store should also get cleared.quiet: boolean
- If move/stop events should be fired.
getSelection
Returns currently selected elements.
getSelection(): Element[];
getSelectionArea
Returns the selection area element.
getSelectionArea(): HTMLElement;
getSelectables
Returns all selectables.
getSelectables(): Element[];
setAreaLocation
Sets the location of the selection area.
setAreaLocation(location: Partial<AreaLocation>): void;
location: Partial<AreaLocation>
- A partial AreaLocation object.
getAreaLocation
Returns the current location of the selection area.
getAreaLocation(): AreaLocation;
cancel
Cancels the current selection process.
cancel(keepEvent = false): void;
keepEvent: boolean
- If a stop event should be fired.
destroy
Unbinds all events and removes the area-element.
destroy(): void;
enable
Enables selecting elements, this is the default state.
enable(): void;
disable
Disables selecting elements.
disable(): void;
select
Manually selects elements and adds them to the store.
select(query: SelectAllSelectors, quiet = false): Element[];
query: SelectAllSelectors
- CSS Query, can be an array of queries.quiet: boolean
- If this should not trigger the move event.
deselect
Manually deselects elements and removes them from the store.
deselect(query: SelectAllSelectors, quiet = false): Element[];
query: SelectAllSelectors
- CSS Query, can be an array of queries.quiet: boolean
- If this should not trigger the move event.
Types
DeepPartial<T>
A type that makes all properties in T
optional and allows for nested optional properties.
type DeepPartial<T> = T extends unknown[] ? T : T extends HTMLElement ? T : { [P in keyof T]?: DeepPartial<T[P]>; };
Quantify<T>
A type that allows T
to be an array or a single value.
type Quantify<T> = T[] | T;
ScrollEvent
An interface that extends MouseEvent
with additional properties.
interface ScrollEvent extends MouseEvent {
deltaY: number;
deltaX: number;
}
ChangedElements
An interface representing elements that have been added or removed.
interface ChangedElements {
added: Element[];
removed: Element[];
}
SelectionStore
An interface representing the selection store.
interface SelectionStore {
touched: Element[];
stored: Element[];
selected: Element[];
changed: ChangedElements;
}
SelectionEvent
An interface representing a selection event.
interface SelectionEvent {
event: MouseEvent | TouchEvent | null;
store: SelectionStore;
selection: SelectionArea;
}
event
- The original event that triggered the selection, may benull
if manually triggered.store
- The current state of the selection store.selection
- The selection area instance.
SelectionEvents
An interface representing the selection events.
interface SelectionEvents {
beforestart: (e: SelectionEvent) => boolean | void;
beforedrag: (e: SelectionEvent) => boolean | void;
start: (e: SelectionEvent) => void;
move: (e: SelectionEvent) => void;
stop: (e: SelectionEvent) => void;
}
beforestart
- Fired before the selection starts, iffalse
is returned the selection will be canceled.beforedrag
- Fired before the selection area is moved, iffalse
is returned the move will be canceled.start
- Fired when the selection starts.move
- Fired when the selection area is moved.stop
- Fired when the selection stops.
AreaLocation
An interface representing the location of the selection area.
interface AreaLocation {
x1: number;
y1: number;
x2: number;
y2: number;
}
Coordinates
An interface representing coordinates.
interface Coordinates {
x: number;
y: number;
}
TapMode
A type representing the tap mode.
type TapMode = 'touch' | 'native';
touch
- The element was at the time of click touched "visually" (default).native
- The element was the actual element of the click event.
OverlapMode
A type representing the overlap mode, e.g. what should happen if you select an element that is already selected.
type OverlapMode = 'keep' | 'drop' | 'invert';
keep
- Keep the element selected.drop
- Deselect the element.invert
- Deselect the element if it is selected, otherwise select it (default).
SelectionOptions
An interface representing selection options, this is after defaults have been applied. It consists of the following interfaces:
interface SingleTap {
allow: boolean;
intersect: TapMode;
}
interface Features {
deselectOnBlur: boolean;
singleTap: SingleTap;
range: boolean;
touch: boolean;
}
interface Scrolling {
speedDivider: number;
manualSpeed: number;
startScrollMargins: {x: number, y: number};
}
interface Behaviour {
intersect: Intersection;
startThreshold: number | Coordinates;
overlap: OverlapMode;
scrolling: Scrolling;
triggers: Trigger[];
}
interface SelectionOptions {
selectionAreaClass: string;
selectionContainerClass: string | undefined;
container: Quantify<string | HTMLElement>;
document: Document;
selectables: Quantify<string>;
startAreas: Quantify<string | HTMLElement>;
boundaries: Quantify<string | HTMLElement>;
behaviour: Behaviour;
features: Features;
}
PartialSelectionOptions
Type of what can be passed to the SelectionArea
constructor.
type PartialSelectionOptions = DeepPartial<Omit<SelectionOptions, 'document'>> & {
document?: Document;
};