OpenSeadragonViewerInputHook

OpenSeadragonViewerInputHook is a plugin for OpenSeadragon 1.0.0+ which provides hooks into the user input event pipeline for providing additional behavior and/or overriding the default behavior.

View the Documentation

Demo/Test Site

Usage

Prerequisite note: OpenSeadragonViewerInputHook requires OpenSeadragon version 2.0+.

The OpenSeadragonViewerInputHook bundle can be obtained the following ways:

1. Direct download openseadragon-viewerinputhook.js (and optionally openseadragon-viewerinputhook.js.map)
2. npm

    npm install @openseadragon-imaging/openseadragon-viewerinputhook

The OpenSeadragonViewerInputHook bundle can be included using a script tag in HTML or imported as a library module (ES2015, CommonJS, AMD).

A ViewerInputHook object can be created and attached (if desired) to an OpenSeadragon.Viewer two ways:

1. Call the addViewerInputHook method on the viewer
2. Create a new ViewerInputHook object, passing a viewer reference in the options parameter (optional)

Both methods return a new ViewerInputHook object, and both methods take an options parameter where the event handlers to be hooked may be specified (see the 'Details' section below).

Example using an HTML script tag

<script
  type="text/javascript"
  src="path_to/openseadragon/openseadragon.js"
></script>
<script
  type="text/javascript"
  src="path_to/openseadragon-imaging/openseadragon-viewerinputhook.js"
></script>

    // Example 1 - Use the Viewer.addViewerInputHook() method to create a ViewerInputHook

    // create an OpenSeadragon viewer
    var viewer = window.OpenSeadragon({...});
    // add a ViewerInputHook to the viewer
    var viewerInputHook = viewer.addViewerInputHook({ hooks: [...] });


    // Example 2 - Attach a new ViewerInputHook to an existing OpenSeadragon.Viewer

    var viewerInputHook = new window.OpenSeadragonImaging.ViewerInputHook({ viewer: existingviewer, hooks: [...] });

Example importing as a module

    npm install openseadragon --save
    npm install @openseadragon-imaging/openseadragon-viewerinputhook --save

import OpenSeadragon from 'openseadragon';
import OpenSeadragonViewerInputHook from '@openseadragon-imaging/openseadragon-viewerinputhook';

    // Example 1 - Use the Viewer.addViewerInputHook() method to create a ViewerInputHook

    // create an OpenSeadragon viewer
    var viewer = OpenSeadragon({...});
    // add a ViewerInputHook to the viewer
    var viewerInputHook = viewer.addViewerInputHook({ hooks: [...] });


    // Example 2 - Attach a new ViewerInputHook to an existing OpenSeadragon.Viewer

    var viewerInputHook = new OpenSeadragonViewerInputHook({ viewer: existingviewer, hooks: [...] });

Details

Event handler callbacks are specified in the hooks property (array) of the options object passed when creating a ViewerInputHook object (see example code below). Any number of hooks can be specified.

Each hook specification in the array should have three properties - tracker, handler, and hookHandler.

The tracker property of each hook definition can be a reference to any OpenSeadragon.MouseTracker instance, or one of the pre-defined OpenSeadragon viewer trackers - currently 'viewer' or 'viewer_outer'.

The handler property of each hook definition specifies which MouseTracker handler to hook. Valid values are:

1. 'enterHandler'
2. 'exitHandler'
3. 'pressHandler'
4. 'nonPrimaryPressHandler' (OpenSeadragon v1.2.1+)
5. 'releaseHandler'
6. 'nonPrimaryReleaseHandler' (OpenSeadragon v1.2.1+)
7. 'moveHandler'
8. 'stopHandler'
9. 'scrollHandler'
10. 'clickHandler'
11. 'dblClickHandler'
12. 'dragHandler'
13. 'dragEndHandler'
14. 'pinchHandler'
15. 'keyDownHandler'
16. 'keyUpHandler'
17. 'keyHandler'
18. 'focusHandler'
19. 'blurHandler'

The hookHandler property of each hook definition should be the user-defined event handler callback. All event handler callbacks have the following signature:

handlerFunc(event)

The ViewerInputHook class inserts your event hook handler methods in front of any existing event handler methods so the attached handler will be called first. Additional ViewerInputHook objects can be added on the same viewer/MouseTracker to create a chain of hook methods, where the last added handler(s) will be called first. Note: If multiple ViewerInputHook are attached to the same viewer/MouseTracker, destroy() should be called for each ViewerInputHook in reverse order of attachment!

Your hook event handler methods can control the event handling behavior in one or more of the following ways:

1. Set event.stopHandlers = true to prevent any more handlers in the event handler chain from being called
2. Set event.stopBubbling = true to prevent the original DOM event from bubbling up the DOM tree (all handlers returning false will also disable bubbling)
3. Set event.preventDefaultAction = true to prevent the viewer's default action in response to the event (currently applies to clickHandler, dragHandler, and scrollHandler on the viewer (tracker = 'viewer'))

    // Example

    var viewer = OpenSeadragon({...});

    viewer.addViewerInputHook({hooks: [
        {tracker: 'viewer', handler: 'scrollHandler', hookHandler: onViewerScroll},
        {tracker: 'viewer', handler: 'clickHandler', hookHandler: onViewerClick}
    ]});

    function onViewerScroll(event) {
        // Disable mousewheel zoom on the viewer and let the original mousewheel events bubble
        if (!event.isTouchEvent) {
            event.preventDefaultAction = true;
            return true;
        }
    }

    function onViewerClick(event) {
        // Disable click zoom on the viewer using event.preventDefaultAction
        event.preventDefaultAction = true;
        event.stopBubbling = true;
    }

Demo/Test Site

The demo site uses OpenSeadragonViewerInputHook to monitor cursor position and provide custom click and mousewheel event actions.

The source code can be found here.

TODO

1. jsdoc documentation
2. Provide hooks on reference strip events
3. Provide hooks on navigator events