DerpScrubber ============ A simple JavaScript scrubber/slider widget. Copyright (c) 2011 Scott Zeid https://github.com/scottywz/DerpScrubber Demo: http://uploads.srwz.us/DerpScrubber/DerpScrubberDemo.html Example ======= ...

Percent: Alternative text herp derp%

Dependencies ============ DerpScrubber depends on [jQuery](http://jquery.com/). jQuery is not shipped with DerpScrubber. DerpScrubber should work in all modern, standards-compliant Web browsers. It has not yet been tested in any version of Internet Explorer. CSS Classes =========== The following CSS classes are available for you to use for theming purposes: * `DerpScrubber` - the root element of the scrubber bar * `DerpScrubber_container` - contains all other elements * `DerpScrubber_outer` - contains the main scrubber bar * `DerpScrubber_bar` - the main scrubber bar * `DerpScrubber_availableArea` - the portion of the bar which is available to use * `DerpScrubber_highlight` - the highlighted portion of the available area * `DerpScrubber_handleContainer` - contains the handle * `DerpScrubber_handle` - the handle of the scrubber bar These elements are nested as shown above. **Do not change the `position`, `display`, `margin*`, `padding*`, or any other properties related to the size or position of these elements, except for border-related properties.** The following classes are available on the root element depending on the state of the scrubber bar: * `DerpScrubber_enabled` * `DerpScrubber_disabled` * `DerpScrubber_clickable` * `DerpScrubber_notClickable` * `DerpScrubber_horizontal` * `DerpScrubber_vertical` Events ====== DerpScrubber supports the following events: * `move` - triggered whenever the scrubber bar is moved * `moveFinished` - triggered when the user is finished moving the scrubber bar using the mouse, or every time `DerpScrubber.move()` is called if the user did not move it using the mouse * `userMove` - triggered whenever the user moves the scrubber bar using the mouse * `userMoveFinished` - triggered when the user is finished moving the scrubber bar using the mouse You can use the `DerpScrubber.bind()` and `DerpScrubber.unbind()` methods to bind or unbind callbacks to any of these events, respectively, and `DerpScrubber.trigger()` to trigger an event. Shortcut methods in the format of `DerpScrubber.on()` (note the capitalized event name) are available to bind a callback to an event, or to trigger the event if no callback is passed. All callback functions will be passed an object with the following properties: * `scrubber` - the DerpScrubber that this was called on * `percent` - the percentage of the bar area that is highlighted * `coefficient` - `percent / 100`, useful for mathematical operations * `position` - the current size in pixels of the highlighted area (try to use `percent` or `coefficient` instead, **as you will not receive updates when the browser window is resized**). * `user` - Boolean value specifying whether or not the scrubber bar was moved by the user using the mouse * `last` - Boolean value specifying whether or not the user is finished moving the scrubber bar, or `true` if the user did not move the scrubber bar using the mouse DerpScrubber API ================ This is a listing of all properties and methods of the DerpScrubber class which are intended for public use. All methods, including constructors, may be chained unless a return value is explicitly specified. Any properties and methods not listed here are used internally and should be used or manipulated at your own risk. DerpScrubber(settings) ---------------------- Returns a new DerpScrubber with the settings passed in the settings object. Allowed settings (all are optional unless specified otherwise): * `width` - CSS width value for the entire widget (required) * `height` - CSS height value for the entire widget (required) * `barSize` - CSS width or height value for the scrubber bar if you want it to be smaller than the entire widget * `barBG` - CSS background value for the scrubber bar * `highlightBG` - CSS background value for the highlighted portion of the bar (required if you want your users to see the value) * `outerBG` - CSS background value for the area outside of the scrubber bar (only applicable if `barSize` is less than `height`) (applied to the root element with the `DerpScrubber` class, not to `.DerpScrubber_outer`) * `availableBG` - CSS background value for the available portion of the bar, if you want it to be different from the bar background * `handle` - CSS background value for the scrubber handle, or an already-made element to use as the handle, or null or any other value that truth-tests to false if no handle is desired * `clickable` - Boolean value specifying whether the scrubber bar will respond to being clicked on or dragged (defaults to `true`) The scrubber bar is **disabled** by default, in order to give you time to add it to the page. If `width` is greater than `height`, then the bar will assume that it is horizontal, and changing the position will involve dragging any part of the bar horizontally. If `width` is less than or equal to `height`, then the bar will assume that it is vertical, and changing the position will involve dragging any part of the bar vertically. The orientation is accessible as the `DerpScrubber.orientation` property. DerpScrubber(width, height, ...) -------------------------------- Returns a new DerpScrubber with the settings passed as arguments. See `DerpScrubber(settings)` for details about allowed settings. DerpScrubber.allBorders ----------------------- (Object) the total values of all border sizes on the x and y axes of the scrubber bar and its children. Properties: * `x` - total of all border sizes on the X axis * `y` - total of all border sizes on the Y axis DerpScrubber.clickable ---------------------- (Boolean) Whether or not the scrubber bar will respond to being clicked on or dragged. (Defaults to `true`.) DerpScrubber.enabled -------------------- (Boolean) Whether or not the scrubber bar is enabled. (Defaults to `false`.) DerpScrubber.orientation ------------------------ (String) `horizontal` if the scrubber bar is horizontal, or `vertical` if it is vertical. If `width` is greater than `height` in the constructor, then the bar will assume that it is horizontal, and changing the position will involve dragging any part of the bar horizontally. If `width` is less than or equal to `height`, then the bar will assume that it is vertical, and changing the position will involve dragging any part of the bar vertically. DerpScrubber.appendTo(jQueryArgument) / DerpScrubber.prependTo(jQueryArgument) ------------------------------------------------------------------------------ Appends or prepends the scrubber bar to the given element. The element can be any valid argument to the jQuery constructor, although you should have the scrubber bar added to only one element at a given time. DerpScrubber.bind(eventType, callback) -------------------------------------- Registers a callback function to be called every time the given event is triggered. `eventType` can also be an object with each property being the name of an event, and each value being the callback. See the **Events** section for more info about events. DerpScrubber.disable() ---------------------- Disables the scrubber bar, hiding the highlighted area and handle but preserving the position. DerpScrubber.enable() --------------------- Enables the scrubber bar, restoring the previous position if possible. The scrubber bar is **disabled** by default, in order to give you time to add it to the page. DerpScrubber.getAvailableCoefficient() -------------------------------------- Returns the percentage of the bar size which is available to use, **divided by 100.** This is useful for mathematical operations. Defaults to 1. DerpScrubber.getAvailablePercent() ---------------------------------- Returns the percentage of the bar size which is available to use. Defaults to 100. DerpScrubber.getAvailableSize() ------------------------------- Returns the size of the available area. Useful in conjunction with `DerpScrubber.getBarSize()`. However, try to use `DerpScrubber.getAvailablePercent()` or `DerpScrubber.getAvailableCoefficient()` instead. DerpScrubber.getBarSize() ------------------------- Returns the size of the entire scrubber bar. Useful in conjunction with `DerpScrubber.getPosition()`. However, try to use `DerpScrubber.getPercent()` or `DerpScrubber.getCoefficient()` instead. DerpScrubber.getCoefficient() ----------------------------- Returns the percentage of the bar area that is highlighted **divided by 100.** This is useful for mathematical operations, and this or `DerpScrubber.getPercent()` should be used in preference to `DerpScrubber.getPosition()`. DerpScrubber.getPercent() ------------------------- Returns the percentage of the bar area that is highlighted. This or `DerpScrubber.getCoefficient()` should be used in preference to `DerpScrubber.getPosition()`. DerpScrubber.getPosition() -------------------------- Returns the current size in pixels of the highlighted area. Try to use `DerpScrubber.getPercent()` or `DerpScrubber.getCoefficient()` instead, **as you will not receive updates when the browser window is resized.** DerpScrubber.move([position=0]) ------------------------------- Sets the size of the highlighted area to the given position, or 0 if it is null, then calls all registered `onMove` callback functions. If the position is a string value of the format `%`, then it will be interpreted as a percentage of the **entire** bar space, not just the available bar space. If `position` is null and a JavaScript event object is passed as `event`, then the cursor position will be used to determine the size of the highlighted area. This is mainly intended for internal use, and is only documented here for completeness. If the user is currently moving the scrubber bar, then this method will silently fail without triggering any move-related events. DerpScrubber.moveToCoefficient(coeff) ------------------------------------- Sets the size of the highlighted area to the given number, **times 100,** as a percentage of the entire bar space. If the user is currently moving the scrubber bar, then this method will silently fail without triggering any move-related events. DerpScrubber.moveToPercent(percent) ----------------------------------- Sets the size of the highlighted area to the given percentage of the entire bar space. You may include a percent sign at the end of the number if it is a string. If the user is currently moving the scrubber bar, then this method will silently fail without triggering any move-related events. DerpScrubber.onMove([callback]) ------------------------------- Registers a callback function to be called every time the `move` event is triggered, or calls all such callback functions if no callback is given. See the **Events** section for more info about events. DerpScrubber.onMoveFinished([callback]) --------------------------------------- Registers a callback function to be called every time the `moveFinished` event is triggered, or calls all such callback functions if no callback is given. See the **Events** section for more info about events. DerpScrubber.onUserMove([callback]) ----------------------------------- Registers a callback function to be called every time the `userMove` event is triggered, or calls all such callback functions if no callback is given. See the **Events** section for more info about events. DerpScrubber.onUserMoveFinished([callback]) ------------------------------------------- Registers a callback function to be called every time the `userMoveFinished` event is triggered, or calls all such callback functions if no callback is given. See the **Events** section for more info about events. DerpScrubber.removeFrom(jQueryArgument) --------------------------------------- Removes the scrubber bar from the given element. The element can be any valid argument to the jQuery constructor. DerpScrubber.reset() -------------------- Resets the scrubber bar to its original, disabled state, with the position set to zero. Move-related events will be triggered. DerpScrubber.setAvailableCoefficient(coeff) ------------------------------------------- Sets the percentage of the bar which is available to use to the given value **times 100.** The highlighted area will be adjusted to reflect this change. Move-related events are **not** triggered. Defaults to 1. Useful for cases when only part of the bar should be useable, such as when only part of a video or song has been loaded. DerpScrubber.setAvailablePercent(percent) ----------------------------------------- Sets the percentage of the bar which is available to use to the given value. You may include a percent sign at the end of the number if it is a string. The highlighted area will be adjusted to reflect this change. Move-related events are **not** triggered. Defaults to 100%. Useful for cases when only part of the bar should be useable, such as when only part of a video or song has been loaded. DerpScrubber.setAvailableSize(size) ----------------------------------- Sets the size of the bar which is available to use to the given value. The highlighted area will be adjusted to reflect this change. Move-related events are **not** triggered. Defaults to 100%. Useful for cases when only part of the bar should be useable, such as when only part of a video or song has been loaded. `DerpScrubber.setAvailableCoefficient()` and `DerpScrubber.setAvailablePercent()` are preferred to this method. Size can be of one of the following formats: * `%` - percentage of the entire bar's size * JavaScript number type - size in pixels; will be converted to a percentage * anything else (including null) - 100% DerpScrubber.setClickable(bool) ------------------------------- Sets the `clickable` property, which decides whether the scrubber bar will respond to being clicked on or dragged and whether the handle will be shown. The default value is `true`. **Always use this method. NEVER set the `clickable` property directly.** DerpScrubber.setEnabled(bool) ----------------------------- Enables or disables the scrubber bar based on the boolean value given. The default value is `false`. **Always use this method or `DerpScrubber.enable()` and `DerpScrubber.disable()`. NEVER set the `enabled` property directly.** DerpScrubber.trigger(eventType) ------------------------------- Triggers the given event. `eventType` can also be an array of all event names you want to trigger. See the **Events** section for more info about events. DerpScrubber.unbind(eventType[, callback]) ------------------------------------------ Unregisters the callback function that `callback` is a reference to for the given event, or all callback functions for the event if no such reference is passed. `eventType` can also be an object with each property being the name of an event, and each value being the callback (or null to remove all callbacks for the event), or an array of events for which you want to unregister all callbacks. You must pass the exact same reference that you previously passed when you registered the event, and not just a different function with identical code. See the **Events** section for more info about events.