Code Monkey home page Code Monkey logo

doc22940 / selection Goto Github PK

View Code? Open in Web Editor NEW

This project forked from simonwep/selection

1.0 1.0 0.0 1.43 MB

๐Ÿ–ฑ๏ธ Selection - A simple and lightweight library to realize visual DOM Selections, like on your Desktop. No jQuery. Supports any CSS library, e.g. Bootstrap. Including vertical & horizontal scroll support.

Home Page: https://simonwep.github.io/selection/

License: MIT License

JavaScript 79.45% CSS 10.16% HTML 10.38%

selection's Introduction

Logo

Simple and easy selection library to enable visual DOM-Selection

License MIT No dependencies Support me jsdelivr hits Build Status downloads per week gzip size brotli size Current version

Demo

Features

  • Supports touch devices
  • Ultra small
  • Highly optimized
  • Simple usage
  • No jQuery
  • Vertical and horizontal scroll support

Install

Via npm

$ npm install @simonwep/selection-js --save

Include via jsdelivr.net

<script src="https://cdn.jsdelivr.net/npm/@simonwep/selection-js/dist/selection.min.js"></script>

Usage

const selection = new Selection({

    // Class for the selection-area-element
    class: 'selection-area',

    // document object - if you want to use it within an embed document (or iframe)
    frame: document,

    // px, how many pixels the point should move before starting the selection (combined distance).
    // Or specifiy the threshold for each axis by passing an object like {x: <number>, y: <number>}.
    startThreshold: 10,

    // Disable the selection functionality for touch devices
    disableTouch: false,

    // On which point an element should be selected.
    // Available modes are cover (cover the entire element), center (touch the center) or
    // the default mode is touch (just touching it).
    mode: 'touch',

    // Behaviour on single-click
    // Available modes are 'native' (element was mouse-event target) or 
    // 'touch' (element got touched)
    tapMode: 'native',

    // Enable single-click selection (Also disables range-selection via shift + ctrl)
    singleClick: true,

    // Query selectors from elements which can be selected
    selectables: [],

    // Query selectors for elements from where a selection can be start
    startareas: ['html'],

    // Query selectors for elements which will be used as boundaries for the selection
    boundaries: ['html'],

    // Query selector or dom node to set up container for selection-area-element
    selectionAreaContainer: 'body',

    // On scrollable areas the number on px per frame is devided by this amount.
    // Default is 10 to provide a enjoyable scroll experience.
    scrollSpeedDivider: 10,

    // Browsers handle mouse-wheel events differently, this number will be used as 
    // numerator to calculate the mount of px while scrolling manually: manualScrollSpeed / scrollSpeedDivider
    manualScrollSpeed: 750
});

Events

Since version 1.2.x selection-js is event-driven. Use the on(event, cb) and off(event, cb) functions to bind / unbind event-listener.

You may want to checkout the source used in the demo-page, it's easier than reading through the manual.

Event Description
beforestart The mousedown / touchstart got called inside a valid boundary. Return false to cancel selection immediatly.
start User started the selection, the startThreshold got fulfilled.
move The user dragged the mouse around.
stop The user stopped the selection, called on mouseup and touchend / touchcancel after a selection.

Every event-object contains the folling properties:

{
    oe,   // Original mouse- / touchevent.
    inst, // Selectionjs instance
    area, // Area element
    selected, // Array of currently selected elements
    changed: {
        added,  // Added elements against the previous event
        removed // Same as added but for removed elements
    }
}

Example:

selection.on('beforestart', evt => {
    
    // Use this event to decide whether a selection should take place or not.
    // For example if the user should be able to normally interact with input-elements you 
    // may want to prevent a selection if the user clicks such a element:
    // selection.on('beforestart', ({oe}) => {
    //   return oe.target.tagName !== 'INPUT'; // Returning false prevents a selection
    // });
    
    console.log('beforestart', evt);
}).on('start', evt => {

    // A selection got initiated, you could now clear the previous selection or
    // keep it if in case of multi-selection.
    console.log('start', evt);
}).on('move', evt => {

    // Here you can update elements based on their state.
    console.log('move', evt);
}).on('stop', evt => {

    // The last event can be used to call functions like keepSelection() in case the user wants
    // to select multiple elements.
    console.log('stop', evt);
});

You can find event-related examples here.

Methods

  • selection.on(event:String, cb:Function) - Appends an event listener to the given corresponding event-name (see section Events), returns the current instance so it can be chained.

  • selection.off(event:String, cb:Function) - Removes an event listener from the given corresponding event-name (see section Events), returns the current instance so it can be chained.

  • selection.option(name:String) - Returns the option by name.

  • selection.option(name:String, value:Mixed) - Set a new option value.

  • selection.disable() - Disable the functionality to make selections.

  • selection.enable() - Enable the functionality to make selections.

  • selection.destroy() - Unbinds all events and removes the area-element.

  • selection.cancel() - Cancels the current selection process.

  • selection.trigger(evt:MouseEvent|TouchEvent, silent:boolean) - Manually triggers the start of a selection. silent = true means that no beforestart event will get fired (default).

  • selection.keepSelection() - Will save the current selected elements and will append those to the next selection. Can be used to allow multiple selections.

  • selection.clearSelection() - Clear the previous selection (elements which were saved by keepSelection()).

  • selection.getSelection() - Returns currently selected elements as an Array.

  • selection.removeFromSelection(el:HTMLElement) - Removes a particular element from the current selection.

  • selection.resolveSelectables() - Need to be called if during a selection elements have been added.

  • selection.select(query:[String]|String) - Manually appends elements to the selection, can be a / an array of queries / elements. Returns actual selected elements as array.

Static methods

Selection

  • Selection.create(options:Object):Selection - Creates a new instance.

Selection.utils

  • on(el:HTMLElement, event:String, fn:Function[, options :Object]) - Attach an event handler function.
  • off(el:HTMLElement, event:String, fn:Function[, options :Object]) - Remove an event handler.
  • css(el:HTMLElement, attr:String, val:String) - Set a specific style property.
  • css(el:HTMLElement, attr:Object) - Set multiple style properties.
  • intersects(ela:HTMLElement, elb:HTMLElement):Boolean - Check if an HTMLElement intersects another.
  • selectAll(selector:String|Array):Array - Returns all HTMLElements which were selected by the selector.
  • eventPath(evt:DOMEvent):NodeList - Event.composedPath() polyfill.
  • removeElement(arr:Array, el:Object) - Removes an particular element from an Array.

selection's People

Contributors

simonwep avatar sauldoescode avatar dependabot[bot] avatar acusti avatar hendrysadrak avatar cisolarix avatar achhunna avatar alvarobernalg avatar benwerner01 avatar daniel08s avatar nordth avatar impressivewebs avatar fbergunde avatar

Stargazers

Acampbell avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.