@thi.ng/rstream-gestures

@thi.ng/rstream-gestures

npm versionnpm downloads Mastodon Follow

[!NOTE] This is one of 190 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

About

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

Status

STABLE - used in production

Search or submit any issues for this package

Breaking changes

v3.0.0

The gestureStream() now supports external zoom control/resetting via providing a subscription as zoom option. That itself isn't a breaking change, however a result of this is that the GestureEvents emitted by the stream do not always contain the original DOM event anymore (i.e. not in the case when the zoom factor is being reset via attached subscription).

v2.0.0

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

Related packages

  • @thi.ng/hdom - Lightweight vanilla ES6 UI component trees with customizable branch-local behaviors
  • @thi.ng/rdom - Lightweight, reactive, VDOM-less UI/DOM components with async lifecycle and @thi.ng/hiccup compatible

Installation

yarn add @thi.ng/rstream-gestures

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/rstream-gestures"></script>

Skypack documentation

For Node.js REPL:

const rstreamGestures = await import("@thi.ng/rstream-gestures");

Package sizes (brotli'd, pre-treeshake): ESM: 1.20 KB

Dependencies

Usage examples

Several projects in this repo's /examples directory are using this package:

ScreenshotDescriptionLive demoSource
Canvas based dial widgetDemoSource
Interactive visualization of closest points on ellipsesDemoSource
Interactive inverse FFT toy synthDemoSource
Doodle w/ K-nearest neighbor search result visualizationDemoSource
K-nearest neighbor search in an hash gridDemoSource
Mouse gesture / stroke analysis, simplification, corner detectionDemoSource
Interactive pattern drawing demo using transducersDemoSource
Canvas based Immediate Mode GUI componentsDemoSource
Minimal IMGUI usage exampleDemoSource
Worker based, interactive Mandelbrot visualizationDemoSource
Basic rstream-gestures multi-touch demoDemoSource
Minimal rstream dataflow graphDemoSource
Minimal shader graph developed during livestream #2DemoSource
Multi-layer vectorization & dithering of bitmap imagesDemoSource
rdom & WebGL-based image channel editorDemoSource

API

Generated API docs

GestureType

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

  • move - movemove
  • start - mousedown / touchstart
  • 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": "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 { 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 === "drag"),
map((e) => e.active.map((g) => Math.hypot(...g.delta)))
)
);

Resettable zoom

For some applications (e.g. graphical editors), it can be helpful to reset the zoom value. This can be done by supplying a stream/subscription as part of the config options:

import { reactive } from "@thi.ng/rstream";
import { gestureStream } from "@thi.ng/rstream-gestures";

// create stream for initial zoom value & for resetting
const zoomReset = reactive(1);

// create gesture stream w/ zoom subscription
const gestures = gestureStream(document.body, {
smooth: 0.01,
zoom: zoomReset
});

// ... then to reset the zoom at some point (e.g to zoom=2)
zoomReset.next(2);

Authors

If this project contributes to an academic publication, please cite it as:

@misc{thing-rstream-gestures,
title = "@thi.ng/rstream-gestures",
author = "Karsten Schmidt and others",
note = "https://thi.ng/rstream-gestures",
year = 2018
}

License

© 2018 - 2024 Karsten Schmidt // Apache License 2.0

Generated using TypeDoc