Big Surface frees DOM elements from the shackles of scroll bars. WIth Big Surface, users are free to move through
the space inside the element with their mouse pointer or via touch gestures. Developers (you) can place elements
anywhere in side the element, whether it's top:100px; left:-300px; or top:-47474px; left:348949px;. Big Surface
uses CSS3 transforms and hardware acceleration for smooth movement within the limitless plane.
For plain JavaScript applications, use the dist/big-surface.js, which will inject the BigSurface object to the global scope. You can also use the file as a AMD or CommonJS module.
In the API BigSurface (capitalized) refers to the module object and bigSurface (lowercase) refers to a
BigSurface instance which is created via BigSurface.create. Any parameter starting with opt_ is optional.
Constructor function which returns a new BigSurface instance. The container is the element which will contain the BigSurface.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodySets the per-step movement speed limit in pixels for the bigSurface. For example, if target is "10", then at most the user will be able to move 10 pixels per frame (assuming 60 frames/second). If a duration is given, the speed will tween from the current value to the target value using an easing function (quadratic by default). If a callback function is given, it will be called after the given duration.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.speed(8,2);// Take 2 seconds to speed up to 8 pixels per frame in 2 second, this will trigger 'move start'setTimeout(function(){bigSurface.speed(0,10);// Take 10 seconds to come to a stop, after which the 'move stop' will fire},2000);Same as bigSurface.speed but only for horizontal movement.
Same as bigSurface.speed but only for vertical movement.
Allows for binding callbacks to the following events:
- "move start", triggered when a user has the ability to move within the bigSurface.
- "move stop", triggered when a bigSurface is locked and a user may not move within it.
- "pointer tracking start", triggered when the tracking of the users' pointer (mouse or touch) begins.
- "pointer tracking stop", triggered when the tracking of the users' pointer stops.
Just because a move event triggers doesn't mean the bigSurface is moving, it only signals that it's capable of moving if the user interacts with it. Same with pointer tracking -- the pointer can be tracked even while the bigSurface is locked so that when it's unlocked, it can react accordingly to the last known position of the users pointer.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.on('move start',function(){console.log("The user is free to move within the bigSurface!");})Detaches an event listener which was previously bound using bigSurface.on.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.on('move start',moveStartHandler);// bind a handlerbigSurface.removeListener('move start',moveStartHandler);// undo the previous line of codeThe "infinite" bigSurface element which you can append absolutely positioned elements to.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.appendChild(myElement);// Attach an element to the bigSurface (should be absolutely positioned)The element containing the bigSurface element. This is essentially the "window" at which the user sees the bigSurface through.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.container===document.body;// trueModifies a CSS property of the bigSurface element (sets the style named name to value). If a opt_duration is given,
a CSS transition will occur between the current value and the given value. If no value is given, this returns
the current value of the style.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.css('opacity',0,10);// take 10 seconds to fade out the bigSurfaceModifies a CSS3 transform property of the bigSurface element (sets the style named name to value). If a
opt_duration is given, a CSS transition will occur between the current value and the given value. If no
value is given, this returns the current value of the transform.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.cssTransform('rotate','10deg');// rotate the bigSurface 10deg immediatelyModifies a CSS3 filter property of the bigSurface element (sets the style named name to value). If a
opt_duration is given, a CSS transition will occur between the current value and the given value. If no
value is given, this returns the current value of the filter.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.cssFilter('blur','100px',20);// Take 20 seconds to blur the bigSurface at 100pxModifies a CSS3 transition property of the bigSurface element (sets the style named name to value). If no
value is given, this returns the current value of the transition.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.cssFilter('opacity','100');// Set the transition time of opacity changes to 100 secondsSets the base horizontal movement of the bigSurface. For example, if target is "-10", the bigSurface will move towards the left 10 pixels per frame. If a duration is given, the speed will tween from the current value to the target value using an easing function (quadratic by default). If a callback function is given, it will be called after the given duration.
varbigSurface=BigSurface.create(document.body);// Create inside the entire document bodybigSurface.horizontalWind(5);// Move the bigSurface 5px to the right every frameSame as the horizontal wind, except for vertical movement.
This is the function which tells the bigSurface to slow movement when the pointer is near the center of the bigSurface
and to speed up when it's near the edges. Use this to set or get the gradient funtion used to determine the
speed of movement relative to the user's pointer positions relative to the bigSurface. The gradient is quadratic
in by default. The gradient must have the following function signature:
speedGradient(currentPointerPosition, 0, 1 or -1 (depending on direction), halfWidth or halfHeight)
it must return a value between -1 and 1 which will be used as a multiplier against the bigSurface speed limit.
For getting/setting just the horizontal speed gradient.
For getting/setting just the horizontal speed gradient.
Retrieves the current bigSurface width.
Retrieves the current bigSurface height.
Retrieves the current bigSurface top.
Retrieves the current bigSurface left.
This project uses boilerplate-gulp. Run 'gulp dev' to develop and have incremental builds, continuous testing, etc. Run 'gulp' to run regenerate the dist files.