Options
All
  • Public
  • Public/Protected
  • All
Menu

@thi.ng/rstream-gestures

rstream-gestures

npm versionnpm downloads Twitter Follow

This project is part of the @thi.ng/umbrella monorepo.

About

Unified mouse, mouse wheel & multi-touch event stream abstraction. This is a support package for @thi.ng/rstream.

Status

STABLE - used in production

Breaking changes

Multi-touch support has been added in v2.0.0, resulting in a complete rewrite of gestureStream() and new event data formats.

Installation

yarn add @thi.ng/rstream-gestures
// ES module
<script type="module" src="https://unpkg.com/@thi.ng/rstream-gestures?module" crossorigin></script>

// UMD
<script src="https://unpkg.com/@thi.ng/rstream-gestures/lib/index.umd.js" crossorigin></script>

Package sizes (gzipped, pre-treeshake): ESM: 1.22 KB / CJS: 1.27 KB / UMD: 1.34 KB

Dependencies

Usage examples

Several demos in this repo's /examples directory are using this package.

A selection:

ScreenshotDescriptionLive demoSource
Canvas based dial widgetDemoSource
Doodle w/ K-nearest neighbor search result visualizationDemoSource
Mouse gesture / stroke analysis, simplification, corner detectionDemoSource
Interactive pattern drawing demo using transducersDemoSource
Canvas based Immediate Mode GUI componentsDemoSource
Worker based, interactive Mandelbrot visualizationDemoSource
Basic rstream-gestures multi-touch demoDemoSource

API

Generated API docs

GestureType

All native events are abstracted into one of the following event types:

  • START - mousedown / touchstart
  • MOVE - movemove
  • DRAG - mousemove (whilst dragging) / touchmove
  • END - mouseup / touchend / touchcancel
  • ZOOM - wheel

GestureEvent

The stream emits GestureEvent objects of:

  • type - Current translated/abstracted event type (GestureType)
  • event - Original DOM event
  • pos - Event position (transformed as per GestureStreamOpts)
  • active - Active cursors (i.e. ongoing drag / touch gestures)
  • buttons - Mouse button bitmask (same as in standard MouseEvent), or, if isTouch is true, number of active touches.
  • zoom - Current zoom factor (as per GestureStreamOpts config)
  • zoomDelta - Last WheelEvent's transformed deltaY, wheelDeltaY
  • isTouch - True, if original event was a TouchEvent
// example mouse gesture event
{
  "type": 2, // GestureType.DRAG
  "event": MouseEvent,
  "pos": [254, 169],
  "active": [
    {
      "id": 0, // always 0 for mouse gestures
      "start": [443, 37],
      "pos": [254, 169],
      "delta": [-189, 132]
    }
  ],
  "buttons": 2, // right button pressed
  "zoom": 1,
  "zoomDelta": 0,
  "isTouch": false
}

GestureStreamOpts

See the GestureStreamOpts config options for further details.

Basic usage

import { GestureType, gestureStream } from "@thi.ng/rstream-gestures";
import { trace } from "@thi.ng/rstream";
import { comp, dedupe, filter, map, pluck } from "@thi.ng/transducers";

// create event stream with custom options
const gestures = gestureStream(document.body, { smooth: 0.01 });

// subscription logging zoom value changes
gestures.subscribe(
    // trace is simply logging received values to console
    trace("zoom"),
    // composed transducer, `dedupe` ensures only changed values are received
    comp(pluck("zoom"), dedupe())
);

// another subscription computing & logging drag gesture distance(s)
gestures.subscribe(
    trace("distance"),
    comp(
        filter((e) => e.type === GestureType.DRAG),
        map((e) => e.active.map((g) => Math.hypot(...g.delta)))
    )
);

Authors

Maintainer

Contributors

License

© 2018 - 2020 Karsten Schmidt // Apache Software License 2.0

Generated using TypeDoc