Giter VIP home page Giter VIP logo

jquery.panzoom's Introduction

jQuery Panzoom

Panzoom is a progressive plugin to create panning and zooming functionality for an element. Panzoom supports the same browsers as jQuery 2.0 and can be used with jQuery 1.9.0+ or jQuery 2.0+. Rather than setting width and height on an image tag, Panzoom uses CSS transforms and matrix functions to take advantage of hardware/GPU acceleration in the browser, which means the element can be anything: an image, a video, an iframe, a canvas, text, WHATEVER. And although IE<=8 is not supported, this plugin is future-proof.

jquery.panzoom.min.js (6.2kb/2.4kb gzip), included in this repo, is compressed with uglifyjs.

Mobile support

Panzoom includes support for touch gestures and even supports pinch gestures for zooming. It is perfectly suited for both mobile and desktop browsers. You'll be amazed at how well this performs on your iPad or iPhone.

SVG support

As of v0.2.0, Panzoom supports panning and zooming SVG elements directly, in browsers that support SVG.

Dependencies

Panzoom obviously depends on jQuery, but it also depends on Modernizr for its touch gesture support detection.
If Modernizr is not included, touch gestures will simply not be used and it will fail silently.
However, mobile behavior is not supported without Modernizr and its touch support feature detect.

Loading Panzoom

Panzoom can obviously be included with your scripts at the end of the body, but Panzoom supports AMD for javascript module love.

With script tags:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="/js/plugins/jquery.panzoom.js"></script>

With AMD loader in an anonymous module:

define([ "jquery", "plugins/jquery.panzoom" ], function( $ ) {
  $(document).ready(function() {
    $(".panzoom-elements").panzoom();
  });
});

Initialization

$(".panzoom-elements").panzoom();

// Pass options
$("a.panzoom-elements").panzoom({
  minScale: 0,
  $zoomRange: $("input[type='range']")
});

Options

All options can be overridden by passing an object literal like any other plugin,
or with the "option" method.

Panzoom.defaults = {
  // Should always be non-empty
  // Used to bind jQuery events without collisions
  // A guid is not added here as different instantiations/versions of panzoom
  // on the same element is not supported, so don't do it.
  eventNamespace: ".panzoom",

  // Whether or not to transition the scale
  transition: true,

  // Default cursor style for the element
  cursor: "move",

  // There may be some use cases for zooming without panning or vice versa
  disablePan: false,
  disableZoom: false,

  // The increment at which to zoom
  // adds/subtracts to the scale each time zoomIn/Out is called
  increment: 0.3,

  minScale: 0.4,
  maxScale: 5,

  // Animation duration (ms)
  duration: 200,
  // CSS easing used for scale transition
  easing: "ease-in-out",

  // Zoom buttons/links collection (you can also bind these yourself - e.g. `$button.on("click", function( e ) { e.preventDefault(); $elem.panzooom("zoomIn"); });` )
  $zoomIn: $(),
  $zoomOut: $(),
  // Range input on which to bind zooming functionality
  $zoomRange: $(),
  // Reset buttons/links collection on which to bind the reset method
  $reset: $(),
  // Bind a handler to the `panzoomend` event
  // This is fired on mouseup or touchend when the user
  // finishes a move or pinched zoom
  // This can also be bound normally on the panzoom element
  // e.g. `$elem.on("panzoomend", function( e, panzoom ) { console.log( panzoom.getMatrix() ); });`
  onEnd: undefined
};

Methods

Methods can be called in the same way as a widget from the jQuery UI widget factory. Pass a method name when calling panzoom. Strings are interpreted as method names.

option

// One at a time
// Sets the scale increment option
$elem.panzoom("option", "increment", 0.4);

// Several options at once
$elem.panzoom("option", {
  increment: 0.4,
  minScale: 0.1,
  maxScale: 2,
  duration: 500,
  $reset: $("a.reset-panzoom, button.reset-panzoom")
});

Any option can be changed. See the defaults above for a list.

reset

$elem.panzoom("reset");

Reset the transform matrix to its original value. All panning and zooming is reset.

zoom( [scale[, noSetRange]] )

@param {Number|Boolean} [scale] The exact scale to which to zoom or a boolean indicating to transition a zoom out
@param {Boolean} [noSetRange] Specify that the method should not set the $zoomRange value (as is the case when $zoomRange is calling zoom on change. No need to set that value. This parameter can be ignored.)

// Transition a zoom in based on the scale increment, min and max values
$elem.panzoom("zoom");

// Transition a zoom out
$elem.panzoom("zoom", true);

// Set the scale immediately without a transition
$elem.panzoom("zoom", 1.2);

Transition a zoom in based on the scale increment, min and max values, and animation duration and easing. This method handles both zooming in and zooming out.
If the method is passed a number, zoom() will immediately set that scale without transitioning. This is mostly useful for the range input and pinch gestures.

instance

var panzoom = $elem.panzoom("instance");

Retrieves the Panzoom instance(s) from the set. If there are multiple elements in the set, you will get an array of instances. If there is only one, you will just get that instance of Panzoom.

destroy

$elem.panzoom("destroy");

Unbinds all events and removes all data, including the Panzoom instance on the element.

Internal

These methods are basically private, but could be useful under certain circumstances.

getMatrix

Retrieve the current transform matrix of the panzoom element as an array of values. This is mostly for internal use.

$elem.panzoom("getMatrix");
// => [1, 0, 0, 1, 0, 0]

setMatrix( matrix[, animate] )

@param {Array} matrix
@param {Boolean} [animate] Whether to animate the transform change

// Flip the element upside down
$elem.panzoom("setMatrix", [ 1, 0, 0, -1, 0, 0 ]);

Sets the transform matrix of the panzoom element. It accepts the matrix as an array. The return value is undefined.

transition( [off] )

$elem.panzoom("transition");
// Turn off transition
$elem.panzoom("transition", true);
// Note: this is different than...
$elem.panzoom("option", "transition", true);
// ... which just sets the `transition` option, indicating whether transitioning is allowed at all.
// If the transition option is false, `$elem.panzoom("transition")` will only ever set transition to "none".

Applies the transition to the element. If off is true, it removes the transition.

Events

"panzoomend"

Arguments

  1. e (jQuery.Event): jQuery event object
  2. panzoom (Panzoom): The panzoom instance
  3. changed (Boolean): Whether the matrix changed during the panzoom event.

Currently, there is only one custom event. It is fired when the user finishes a move or finishes a pinch zoom gesture on mobile.

Testing

Tests can be run by opening test/index.html in a browser or by using grunt and phantomjs. See CONTRIBUTING.md for more info.

Tests are written with mocha and chai for bdd-style assertions.

jquery.panzoom's People

Contributors

timmywil avatar

Watchers

James Cloos avatar Saman Gholami 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.