DEMOS
DOCS
FEATURES
DOWNLOAD
PURCHASE
CONTACT
BLOG
Show:

ZoomWidget Class

Provides Pan/Zoom functionality.

Constructor

ZoomWidget

(
  • params
  • [params.zoomRange=[0.05,
)

Parameters:

  • params Object

    Constructor parameters

    • canvas Selector | Element

      The element to apply pan/zoom to.

    • viewport Selector | Element

      The element that will act as the viewport for the canvas.

    • bind Function

      Function that can bind to an event on an element.

    • unbind Function

      Function that can unbind from an event on an element.

    • height Function

      A function that can return the height for some element.

    • width Function

      A function that can return the width for some element.

    • offset Function

      A function that can return {left:.., top:..} for some element

    • id Function

      A function that can return an id for some element.

    • [domElement] Function optional

      A function that can translate between objects referenced by the widget and DOM elements. It might be the case that no tranlation is required - you deal only in DOM elements. But also you might use this with jQuery, and pass around jQuery selectors. So this function just normalises elements. If not supplied, the default function assumes elements are already DOM elements.

    • [events] Object optional

      Optional map of event handlers

      • [zoom] Function optional
        Optional function callback for when zoom changes.
      • [pan] Function optional
        Optional function callback for when pan changes.
      • [mousedown] Function optional
        Optional function callback for mousedown event.
      • [mouseup] Function optional
        Optional function callback for mouseup event.
      • [mousemove] Function optional
        Optional function callback for mousemove event.
      • [maybeZoom] Function optional
        Optional interceptor for zoom. Returning false prevents zoom from occurring.
      • [transformOrigin] Function optional
        Optional function callback for transform origin change. This is given the [x,y] (in percent) of the new origin, and the [left, top] (in absolute values) of the canvas.
    • [clamp=true] Boolean optional

      Whether to clamp when panning such that there is always content visible.

    • [clampZoom=true] Boolean optional

      Whether to clamp when zooming such that there is always content visible.

    • [clampToBackground=false] Boolean optional

      Whether or not to clamp to the background image. This flag means the widget will always ensure at least some of the background is visible. See clampToBackgroundExtents for a variant of this.

    • [clampToBackgroundExtents=false] Boolean optional

      Clamps movement so that when zoomed out, the background image always fills the viewport.

    • [onBackgroundReady] Function optional

      Optional callback to hit when the background image has loaded.

    • [panDistance=50] Number optional

      How far, in pixels, to pan on pan nudge.

    • [zoom=1] Number optional

      Initial zoom for the widget.

    • [enableWheelZoom=true] Boolean optional

      Whether or not wheel zoom is enabled.

    • [wheelFilter] Function optional

      Optional function to call to check if wheel zooming should be enabled for the current event target.

    • [wheelReverse] Boolean optional

      Optional Defaults to false. If true, the zoom direction is reversed: wheel up zooms out, and wheel down zooms in.

    • [wheelZoomMetaKey=false] Boolean optional

      If true, the "meta" key (CMD on Mac, Ctrl on windows/linux) must be pressed in order for wheel zoom to operate. This can be useful if your UI fills the screen in one or more axes and your users would not be able to scroll past the Surface widget.

    • [enablePan=true] Boolean optional

      Whether or not pan is enabled.

    • [enablePanButtons=true] Boolean optional

      Whether or not wheel pan buttons are drawn and enabled.

    • [enableAnimation=true] Boolean optional

      Enable animations for panning. Defaults to true.

    • [enabled=true] Boolean optional

      Whether or not the widget is enabled, ie. responding to mouse input.

    • [background] Object optional

      Optional background image parameters

      • [url] String optional
        URL for the background. Required for both single images and tiled backgrounds.
      • [type="simple"] String optional
        "simple" or "tiled" - the type of background.
      • [tileSize] Number optional
        For tiled backgrounds, provides the width and height of tiles. Every tile is assumed to have these dimensions, even if the tile has whitespace in it.
      • [width] Number optional
        Required for tiled backgrounds. Indicates the width of the full image.
      • [height] Number optional
        Required for tiled backgrounds. Indicates the height of the full image.
      • [maxZoom] Number optional
        Required for tiled backgrounds. Indicates the maximum zoom level. Zoom starts at 0 - fully zoomed out - and increases in integer values from there. Eash successive zoom level is twice the zoom of the previous level, meaning two times as many tiles in each direction.
    • [filter] Function optional

      Optional filter that will be called on down event, with the event target and the event. Returning true from this function means the widget should respond to the event.

    • [padding] Number optional

      Optional values for padding in the x/y axes to leave around the content. This is only of any use if you have disabled panning via mouse drag, since in that case the user sees only scroll bars and has no way of navigating beyond the content. Some padding makes the UI nicer to use. Default is [0,0].

    • [consumeRightClick=true] Boolean optional

      Useful for development: set this to false if you don't want the widget to consume context menu clicks.

    • [smartMinimumZoom=false] Boolean optional

      Means that the lower zoom bound refers to a multiple of the content bounds, not the viewport.

  • [params.zoomRange=[0.05, Number

    3] ] Zoom range for the widget.

Methods

add

(
  • el
  • [id]
  • [pos]
)

Adds the given element to those that this widget is tracking.

Parameters:

  • el Element

    Element to begin tracking.

  • [id] String optional

    Optional id of the element. This might be called from a context in which the id is known already, so we can save some work.

  • [pos] Number optional

    Optional location for the node. If not provided, the position will be retrieved from a call to the DOM.

alignBackground

(
  • [axes]
)

Positions the widget so that the edges of the background align with the viewport. This method is useful for snapping to a corner of the background.

Parameters:

  • [axes] String optional

    Spec for the axes to align to. This should be a space-separated string containing a value for the x (allowed values left and right) and, optionally, y (allowed values top and bottom) axes. The default value is "left top".

applyZoomToElement

(
  • el
  • [zoomToSet]
)

Applies either the widget's current zoom to the given element, or some supplied zoom.

Parameters:

  • el Element

    Element to set zoom on.

  • [zoomToSet] Number optional

    Optional zoom value; if omitted we use the widget's current zoom.

centerBackground

()

Position the widget so the background is centered in the viewport, without changing the current zoom.

centerContent

(
  • params
)

Centers the tracked content inside the viewport, but does not adjust the current zoom.

Parameters:

  • params Object

    Method parameters.

    • [bounds] Object optional

      Bounds info. This is in an internal format and only used when this method is called by the widget itself. Otherwise it is calculated.

    • [doNotAnimate=false] Boolean optional

      If true, don't animate while centering.

    • [onComplete] Function optional

      Optional function to call on operation complete (centering may be animated).

    • [onStep] Function optional

      Optional function to call on operation step (centering may be animated).

    • [doNotFirePanEvent=false] Boolean optional

      If true, a pan event will not be fired.

centerContentHorizontally

(
  • params
)

Centers the tracked content inside the viewport horizontally, but does not adjust the current zoom.

Parameters:

  • params Object

    Method parameters.

    • [bounds] Object optional

      Bounds info. This is in an internal format and only used when this method is called by the widget itself. Otherwise it is calculated.

    • [doNotAnimate=false] Boolean optional

      If true, don't animate while centering.

    • [onComplete] Function optional

      Optional function to call on operation complete (centering may be animated).

    • [onStep] Function optional

      Optional function to call on operation step (centering may be animated).

    • [doNotFirePanEvent=false] Boolean optional

      If true, a pan event will not be fired.

centerContentVertically

(
  • params
)

Centers the tracked content inside the viewport vertically, but does not adjust the current zoom.

Parameters:

  • params Object

    Method parameters.

    • [bounds] Object optional

      Bounds info. This is in an internal format and only used when this method is called by the widget itself. Otherwise it is calculated.

    • [doNotAnimate=false] Boolean optional

      If true, don't animate while centering.

    • [onComplete] Function optional

      Optional function to call on operation complete (centering may be animated).

    • [onStep] Function optional

      Optional function to call on operation step (centering may be animated).

    • [doNotFirePanEvent=false] Boolean optional

      If true, a pan event will not be fired.

centerOn

(
  • element
  • [cparams]
)

Centers the given element in the viewport, vertically and/or horizontally.

Parameters:

  • element Element | String

    Element, or element id, to center.

  • [cparams] Object optional

    Optional extra parameters.

    • [horizontal=true] Boolean optional

      Whether or not to center horizontally

    • [vertical=true] Boolean optional

      Whether or not to center vertically

    • [doNotAnimate=false] Boolean optional

      If true, animation will not be switched on for the operation.

    • [onComplete] Boolean optional

      Optional on complete callback

    • [onStep] Boolean optional

      Optional on animation step callback.

    • [fillRatio=0.4] Number optional

centerOnAndZoom

(
  • element
  • [fillRatio=0.6]
)

Centers on the given element and then adjusts the zoom of the widget so that the short axis of the viewport is [1 / fillRatio] larger than its corresponding axis on the centered node. fillRatio is basically a measure of how much context you want to see around the node on which you centered.

Parameters:

  • element Element | String

    Element, or element id, to center.

  • [fillRatio=0.6] Number optional

    Proportional ratio of the corresponding node's edge to the viewport's short edge.

centerOnHorizontally

(
  • element
)

Centers the given element in the viewport, vertically only.

Parameters:

  • element Element | String

    Element, or element id, to center.

centerOnHorizontally

(
  • element
)

Centers the given element in the viewport, horizontally only.

Parameters:

  • element Element | String

    Element, or element id, to center.

findIntersectingNodes

(
  • origin
  • dimensions
  • [enclosed=false]
  • [filter]
  • [candidates]
)
Object

Finds all nodes that intersect to any extent the rectangle defined by the given origin and dimensions. This rectangle is taken to be in the coordinate space of the page, ie. a value of [0,0] for the origin means the page's top/left corner. A future version could take an optional third argument specifying the element whose origin to use.

Parameters:

  • origin Number

    [x,y] location for center of search. IMPORTANT: This is relative to the page origin.

  • dimensions Number

    Width and height of search area.

  • [enclosed=false] Boolean optional

    If true, returns only nodes that are enclosed by the given search area. Otherwise returns nodes that both intersect and are enclosed.

  • [filter] Function optional

    Optional filter function. This is passed the (id, node, boundingRect) of some element and should return true for elements that should be included in results.

  • [candidates] Object | Element optional

    Optional map of (id->element), or an array of elements or element ids, identifying the elements to include in the search. If not provided, all elements are tested.

Returns:

Object:

A list of objects containing {id:id, el:element, r:bounding rect} that either intersect or are enclosed by the search area.

findNearbyNodes

(
  • origin
  • radius
  • [mustBeInViewport=false]
  • [filter]
)
Object

Finds all nodes whose centers are within a rectangle with origin as its center, and a width and height of radius / 2.

Parameters:

  • origin Number

    [x,y] location for center of search. IMPORTANT: This is relative to the page origin.

  • radius Number

    Radius of search.

  • [mustBeInViewport=false] Boolean optional

    If true, first check that the given origin is within the viewport.

  • [filter] Function optional

    Optional filter function. Should return true for elements that should be included in results.

Returns:

Object:

A list of objects containing {id:id, el:element, r:bounding rect}, sorted in ascending order of distance of the center of the bounding rectangle from the given origin.

fixElement

(
  • el
  • constraints
  • pos
)

Appends an element to the content such that it is zoomed with everything else, but constrains pan in one or both axes so that the element remains fixed with respect to the viewport origin.

Parameters:

  • el Element

    The DOM element to append.

  • constraints Object

    Flags to indicate optional constraint to each axis.

  • pos Number

    [left,top] location of the element's origin.

getApparentCanvasLocation

()

Returns the apparent [left,top] of the canvas inside the viewport - the coordinates, in real pixel values, of where the origin of the canvas appears to be. This apparent origin is not necessarily the same as the [left,top] values of the canvas, because the transform origin and zoom values change things. This function can be used in conjunction with the content bounds by widgets such as the miniview, to calculate what is actually visible in the viewport at some point in time.

Returns:

[Integer[]] [left,top] of the canvas, relative to the viewport's 0,0.

getBoundsInfo

() Object

Gets the current bounds information.

Returns:

Object:

An object with these fields: w - width of the content h - height of the content x - minimum x value of all nodes in the content y - minimum y value of all nodes in the content vw - width of the viewport vh - height of the viewport padding - padding around the content (an array) z - smallest zoom that could result in all the content being visible inside the viewport zoom - current zoom

getElementPositions

() Object

Returns the current map of element ids -> positions.

Returns:

Object:

Map of { id->[x,y]} positions.

getPan

() Number

Gets the current [left,top] of the panned content.

Returns:

Number:

[left,top], in pixels, of the panned content, where [0,0] is the origin of the viewport.

getTransformOrigin

() Number

Gets the current transform origin, in an object of the form [ left, top ]. The coordinate space is pixels.

Returns:

Number:

[left,top] values for the transform origin.

getViewportCenter

() Number

Gets the canvas location that corresponds to the center of the viewport. Note that this may describe a point outside of the content bounds.

Returns:

Number:

left,top location of the logical position on the canvas corresponding to the center of the viewport.

getZoom

() Number

Gets the current zoom.

Returns:

Number:

Current zoom value

getZoomRange

() Number

Gets the current zoom range.

Returns:

Number:

Array of [min, max] current zoom values.

isInViewport

(
  • x
  • y
)
Boolean

Returns whether or not the given point (relative to page origin) is within the viewport for the widget.

Parameters:

  • x Number

    X location of point to test

  • y Number

    Y location of point to test

Returns:

Boolean:

True if the point is within the viewport, false if not.

mapEventLocation

(
  • event
  • [doNotAdjustForOffset=false]
)
Object

Maps the page location of the given event to a value relative to the viewport origin, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position relative to the target element's [left,top] corner. If you wish, you can supply true for 'doNotAdjustForOffset', to suppress that behavior.

Parameters:

  • event Event

    Browser event

  • [doNotAdjustForOffset=false] Boolean optional

    Whether or not to adjust for the offset of the viewport in the page.

Returns:

Object:

The mapped location, as {left:number, top:number}

mapLocation

(
  • left
  • top
  • [doNotAdjustForOffset=false]
)
Object

Maps the given page location to a value relative to the viewport origin, allowing for zoom and pan of the canvas. This takes into account the offset of the viewport in the page so that what you get back is the mapped position relative to the target element's [left,top] corner. If you wish, you can supply true for 'doNotAdjustForOffset', to suppress that behavior.

Parameters:

  • left Number

    X location

  • top Number

    Y location

  • [doNotAdjustForOffset=false] Boolean optional

    Whether or not to adjust for the offset of the viewport in the page.

Returns:

Object:

The mapped location, as {left:number, top:number}

nudgeWheelZoom

(
  • delta
  • [e]
)

Nudges the wheel zoom by the given amount. This function is intended for use by components that control zoom via the mouse wheel, and not for general usage. See nudgeZoom for a more general version of this.

Parameters:

  • delta Number

    Amount to change zoom by.

  • [e] Event optional

    Original event that caused the nudge. May be null.

nudgeZoom

(
  • delta
  • [e]
)
Number

Nudges the zoom by the given amount. Zoom will be clamped to the current zoom range in effect and the value that was ultimately set is returned from this function.

Parameters:

  • delta Number

    Amount to change zoom by. The value you pass in here is multiplied by 100 to give a percentage value: 1 is 100%, for instance, 0.05 is 5%. You can pass in negative numbers to zoom out.

  • [e] Event optional

    Original event that caused the nudge. May be null.

Returns:

Number:

The zoom that was set. Zoom will be clamped to the allowed range.

pageLocation

(
  • e
)
Integer

Decodes the page location from the given event, taking touch devices into account.

Parameters:

  • e Object

    Event from which to decode location

Returns:

Integer:

[left, top] of the given event.

pan

(
  • dx
  • dy
  • [animate
)

Pans the content by dx and dy.

Parameters:

  • dx Number

    Amount to pan in X direction

  • dy Number

    Amount to pan in Y direction

  • [animate Boolean

    = false] Whether or not to animate the pan.

positionChanged

(
  • el
  • [pos]
  • [id]
)

Registers that an element has changed position, updating bounds info as necessary.

Parameters:

  • el Element

    Element that has just moved.

  • [pos] Number optional

    New position. If this is omitted, it will be calculated.

  • [id] String optional

    Optional id of the element. This might be called from a context in which the id is known already, so we can save some work.

positionElementAt

(
  • el
  • x
  • y
  • [xShift=0]
  • [yShift=0]
  • [ensureOnScreen=false]
)

Places (using style.left and style.top) the given element at the given x,y, which is taken to mean an x,y value on the canvas. At zoom 1, with no panning, this will be the same as the given x,y value relative to the viewport origin. But once the canvas has been zoomed and panned we have to map to the altered coordinates. This function also takes into account the difference between the offset of the viewport in the page and the offset of the given element. It is assumed, just because of what this method does, that the given element will be positioned absolute, but this method does nothing to ensure that.

Parameters:

  • el Selector | Element | String

    Element to position.

  • x Number

    X location on canvas to move element's left edge to.

  • y Number

    Y location on canvas to move element's top edge to.

  • [xShift=0] Number optional

    Optional absolute number of pixels to shift the element by in the x axis after calculating its position relative to the canvas. Typically you'd use this to place something other than the top left corner of your element at the desired location.

  • [yShift=0] Number optional

    Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.

  • [ensureOnScreen=false] Boolean optional

    If true, will ensure that x and y positions are never negative.

positionElementAtEventLocation

(
  • el
  • evt
  • [xShift=0]
  • [yShift=0]
)

Places (using style.left and style.top) the given element at the page x,y corresponding to the given event. It is assumed, just because of what this method does, that the given element will be positioned absolute, but this method does nothing to ensure that.

Parameters:

  • el Selector | Element | String

    Element to position.

  • evt Event

    Event to position element at.

  • [xShift=0] Number optional

    Optional absolute number of pixels to shift the element by in the x axis after calculating its position relative to the canvas. Typically you'd use this to place something other than the top left corner of your element at the desired location.

  • [yShift=0] Number optional

    Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.

positionElementAtPageLocation

(
  • el
  • x
  • y
  • [xShift=0]
  • [yShift=0]
)

Places (using style.left and style.top) the given element at the given page x,y. It is assumed, just because of what this method does, that the given element will be positioned absolute, but this method does nothing to ensure that.

Parameters:

  • el Selector | Element | String

    Element to position.

  • x Number

    X location on canvas to move element's left edge to.

  • y Number

    Y location on canvas to move element's top edge to.

  • [xShift=0] Number optional

    Optional absolute number of pixels to shift the element by in the x axis after calculating its position relative to the canvas. Typically you'd use this to place something other than the top left corner of your element at the desired location.

  • [yShift=0] Number optional

    Optional absolute number of pixels to shift the element by in the y axis after calculating its position relative to the canvas.

relayout

(
  • extents
)

Tells the widget that a relayout has occurred. If panning is disabled, the widget will move the canvas element so that all content is visible, and adjust the transform origin so that the ui zooms from the apparent top left corner. Nothing happens as a result of this method if panning is enabled.

Parameters:

  • extents Object

    Bounds information, as an arry of [minX, minY, maxX, maxY.

remove

(
  • el
)

Removes the given element from the list this widget is tracking. Note that this widget does not remove the element from the DOM.

Parameters:

  • el Selector | Element

    Element to stop tracking.

reset

()

Removes all tracked elements and resets the widget.

setApparentCanvasLocation

(
  • left
  • top
)
Number

Sets the apparent canvas location - see the notes for getApparentCanvasLocation.

Parameters:

  • left Number

    Value in pixels for left edge of canvas.

  • top Number

    Value in pixels for top edge of canvas.

Returns:

Number:

[left,top] of the actual origin set, after clamping.

setBackground

(
  • params
)

Sets the background for the canvas element.

Parameters:

  • params Object

    Method parameters

    • [img] Image optional

      Image to use. Optional; you can also supply an image url

    • [url] String optional

      Image URL.

    • [type="simple"] String optional

      "tiled" or "simple": whether to use a single background image or to tile it.

    • [tiling="logarithmic"] String optional

      Default is "logarithmic": each layer is assumed to have a maximum of (2^level+1) tiles in each axis (for instance at level 0, 2 tiles in each axis. Alternatively you can set this to be "absolute", which means that at the maximum zoom level the number of tiles in each axis is computed as the size of the image in that axis divided by the tile size in that axis (rounded up of course). Then at subsequent levels below, the

    • [onBackgroundReady] Function optional

      Optional function to call when the image has loaded.

setBoundsFor

(
  • id
  • pos
  • w
  • h
)

Manually set the bounds (position, and x/y) for some element, by id.

Parameters:

  • id String

    ID of the element to set bounds for.

  • pos Number

    Origin of the element

  • w Number

    Width of the element

  • h Number

    Height of the element

setClamping

(
  • c
)

Sets whether or not the widget clamps the movement of the canvas during pan/zoom to ensure that the managed content never disappears from view.

Parameters:

  • c Boolean

    Whether or not to clamp movement.

setEnabled

(
  • state
)

Sets whether or not the component should respond to mouse events.

Parameters:

  • state Boolean

    Whether or not to respond to mouse events.

setFilter

(
  • f
)

Sets the filter used to determine whether or not a given event should begin a pan.

Parameters:

  • f Function

    A function that will be given the current mouse event. You must return true from the function if you wish for a pan to begin.

setFilter

(
  • filterFn
)

Sets (or clears) the filter that will be called if the widget needs to know whether to respond to an event that would start a pan. By default, the widget responds to down events on the viewport or the canvas, but not on child nodes. You can supply a function that the widget will call in the event that the down event did not occur on the viewport or the canvas; returning true from this function will cause the pan to begin.

Parameters:

  • filterFn Function

    Function to set as the filter; may be null if you wish to clear it. The function should return true if it wants to honour the down event on the given element.

setPan

(
  • left
  • top
  • [animate
  • [onComplete]
  • [onStep]
)

Sets the position of the panned content's origin.

Parameters:

  • left Number

    Position in pixels of the left edge of the panned content.

  • top Number

    Position in pixels of the top edge of the panned content.

  • [animate Boolean

    = false] Whether or not to animate the pan.

  • [onComplete] Function optional

    If animate is set to true, an optional callback for the end of the pan.

  • [onStep] Function optional

    If animate is set to true, an optional callback for each frame in the pan.

setSuspendRendering

(
  • val
)

Sets whether or not rendering is suspended, which for the moment means that when updateBounds is called, the widget doesn't sort the bounds, since we know there will be more changes to the positions and/or sizes of elements.

Parameters:

  • val Object

    True to suspend rendering, false to re-enable rendering. If an update was called during the time that rendering was suspended, the positions are sorted once rendering is re-enabled.

setTransformOrigin

(
  • left
  • top
)

Sets the current transform origin, in pixels. Used mainly to support save/restore state.

Parameters:

  • left Number

    Position of the X coordinate of the transform origin.

  • top Number

    Position of the Y coordinate of the transform origin.

setTransFormOriginForElement

(
  • el
  • xy
)

Sets the transform origin for some element. This is really just exposed as a helper, since there seems little point in reinventing the wheel if you have this widget in your codebase and you need to perform this operation. The Miniview uses this, for instance.

Parameters:

  • el Element

    Element to set transform origin for.

  • xy Number

    Transform origin for element.

setViewportCenter

(
  • xy
)

Sets the location of the canvas such that the given point appears at the center of the viewport.

Parameters:

  • xy Number

    left, top location of the point on the canvas to position in the center of the viewport.

setWheelFilter

(
  • f
)

Sets the filter used to determine whether or not a given wheel event should be responded to.

Parameters:

  • f Function

    A function that will be given the current mouse event. You must return false from the function if you wish for the wheel event to be responded to.

setZoom

(
  • z
  • animate
  • [dontFireEvent=false]
)
Number

Sets the current zoom, clamping it to the allowed range.

Parameters:

  • z Number

    Zoom value. If this is outside the allowed bounds it will be clamped.

  • animate Boolean

    Whether to animate the change in zoom, or just go straight to the new zoom level.

  • [dontFireEvent=false] Boolean optional

    If true, a zoom event will not be fired.

Returns:

Number:

Current zoom. This may or may not be the value you asked for - it might have been clamped to the current allowed zoom range.

setZoomRange

(
  • zr
  • [doNotClamp]
)
Number

Sets the current zoom range. By default, this method checks if the current zoom is within the new range, and if it is not then setZoom is called, which will cause the zoom to be clamped to an allowed value in the new range. You can disable this by passing true for doNotClamp.

Parameters:

  • zr Number

    New range, as an array consisting of [lower, upper] values. Lower must be less than upper.

  • [doNotClamp] Boolean optional

    If true, will not check the current zoom to ensure it falls within the new range.

Returns:

Number:

Array of [min, max] current zoom values.

showElementAt

(
  • el
  • x
  • y
)

Takes some element that is in the DOM and moves it so that it appears at the given x,y over the canvas, allowing for the current zoom and pan. It is expected that the element is not one that is currently managed by the widget - a common use case for this is some dialog, which you do not want to append to the canvas since it would have the zoom effect applied.

Parameters:

  • el Selector | Element | String

    Selector, DOM element or element id representing the element to move.

  • x Number

    X location to move to.

  • y Number

    Y location to move to.

start

(
  • e
)

Programmatically report a down event in order to kick the widget into action.

Parameters:

  • e Event

    Mouse event to use to kick things off.

zoomToBackground

(
  • [params.onComplete]
  • [params.onStep]
  • [params.doNotAnimate=false]
)

Zooms the display so that the background fits inside the viewport.

Parameters:

  • [params.onComplete] Function optional

    Optional function to call on operation complete (centering may be animated).

  • [params.onStep] Function optional

    Optional function to call on operation step (centering may be animated).

  • [params.doNotAnimate=false] Boolean optional

    If true, centering content will not use animation.

zoomToElements

(
  • zParams
)

Zooms the display so that all the given elements fit inside the viewport.

Parameters:

  • zParams Object
    • elements Element

      List of DOM elements to zoom to.

    • [fill=0.90] Number optional

      A decimal indicating how much of the viewport to fill with the zoomed content.

    • [doNotZoomIfVisible=false] Boolean optional

      If true and the widget determines the entire selection is already visible, the zoom will not be adjusted.

    • [doNotAnimate=true] Boolean optional

      By default the widget does not animate this operation. You can override that behaviour by setting doNotAnimate:false.

zoomToEvent

(
  • e
  • increment
)

Zooms the component by the given increment, centered on the location at which the given event occurred.

Parameters:

  • e Event

    Browser event

  • increment Number

    Amount to zoom by (a positive or negative number). If this takes the component out of the current zoom range, it will be clamped.

zoomToFit

(
  • [params.padding=0]
  • [params.fill=0.9]
  • [params.onComplete]
  • [params.onStep]
  • [params.doNotAnimate=true]
  • [params.doNotZoomIfVisible=false]
  • [params.doNotFirePanEvent=false]
)

Zooms the display so that all the tracked elements fit inside the viewport. This method will also, by default, increase the zoom if necessary - meaning the default behaviour is to adjust the zoom so that the content fills the viewport. You can suppress zoom increase by setting doNotZoomIfVisible:true on the parameters to this method.

Parameters:

  • [params.padding=0] Number optional

    Optional padding to leave around all elements.

  • [params.fill=0.9] Number optional

    Amount of the viewport to fill. By default, this method will zoom so that the content is 0.9 times the size of the viewport. Aesthetically this makes for a more pleasing result than filling the viewport entirely.

  • [params.onComplete] Function optional

    Optional function to call on operation complete (centering may be animated).

  • [params.onStep] Function optional

    Optional function to call on operation step (centering may be animated).

  • [params.doNotAnimate=true] Boolean optional

    By default, the centering content step does not use animation. This is due to this method being used most often to initially setup a UI.

  • [params.doNotZoomIfVisible=false] Boolean optional

    If true, no action is taken if the content is currently all visible.

  • [params.doNotFirePanEvent=false] Boolean optional

    If true, a pan event will not be fired.

zoomToFitIfNecessary

(
  • [params.padding
  • [params.fill=0.9]
  • [params.onComplete]
  • [params.onStep]
  • [params.doNotAnimate=true]
)

Zooms the display so that all the tracked elements fit inside the viewport, but does not make any adjustments to zoom if all the elements are currently visible (it still does center the content though).

Parameters:

  • [params.padding Number

    = 0] Optional padding to leave around all elements.

  • [params.fill=0.9] Number optional

    Amount of the viewport to fill. By default, this method will zoom so that the content is 0.9 times the size of the viewport. Aesthetically this makes for a more pleasing result than filling the viewport entirely.

  • [params.onComplete] Function optional

    Optional function to call on operation complete (centering may be animated).

  • [params.onStep] Function optional

    Optional function to call on operation step (centering may be animated).

  • [params.doNotAnimate=true] Boolean optional

    By default, the centering content step does not use animation. This is due to this method being used most often to initially setup a UI.