btburnett3 / jquery.ui.spinner

jQuery.ui.spinner 1.10
jQuery.ui extension for a numeric spinner

Licensing
----------

Written by Brant Burnett <http://btburnett.com/> <mailto:btburnett3@gmail.com>
jQuery.ui.spinner is distributed under the terms of the GNU Lesser General Public License (GPL)

jQuery.ui.spinner is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

jQuery.ui.spinner is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with jQuery.ui.spinner.  If not, see <http://www.gnu.org/licenses/>.

The basic rules of the license are the you can use and change the code here as you see fit,
but you can't remove the license and you can't sell the code.  Please review the license
for more details.

Source Control
---------------

The root branch for jQuery.ui.spinner is hosted on GitHub at
<http://github.com/btburnett3/jquery.ui.spinner/>.

Overview
---------

jQuery.ui.spinner is based upon jQuery UI 1.7 <http://ui.jquery.com>, and provides a new
spinner widget that can be added to any text box.  It fully uses the theme settings created by the
ThemeRoller, and has been tested for compatibility with IE 6/7/8, Firefox 2/3, Safari 3.1, and
Opera 9.  Supports both mouse and keyboard input, and validates input directly into the text box.
It requires only minimal CSS to be supplied, mostly relying on the CSS built into the jQuery UI
framework.

I did a lot of experimenting to try to find the best method that would work across a variety of
web browswers while still using the jQuery UI theme framework rather than images.  I finally
settled on this method of spans with display: inline-block set on them, which is then
positioned next to the text box using absolute positioning, relative to an outer wrapper that
is relative positioned.  The only restriction I know of with this system is that if you put
a right margin on the text box, you must specify it in pixels.

To use, add the CSS found in ui.spinner.css to your jQuery UI CSS files, or link to it
separately.  Then include the ui.spinner.js or ui.spinner.min.js script file beneath your
include for jQuery UI.  Finally, during or after $(document).ready call $("#myinput").spinner()
to add the spinner to your text box.

Options
--------

The spinner also support a variety of options which can be passed in an object to the
constructor.  Page wide defaults can be assigned to $.ui.spinner.defaults.

  min (float)
    Minimum allowed value of the spinner.  If left with the default, null, there will be no
    minimum unless the input has a maximum length.  Then the minimum will be calculated.  For
    a textbox with a maximum length of 3 characters, the minimum will be -99, etc.
          
  max (float)
    Maximum allowed value of the spinner.  If left with the default, null, there will be no
    maximum unless the input has a maximum length.  Then the maximum will be calculated.  For
    a textbox with a maximum length of 3 characters, the maximum will be 999, etc.
    
  places (integer)
    Number of decimal places to display.  Defaults to use the number of places found in step.
        
  step (float)
    A positive number that the spinner should be incremented by when up is clicked or pressed.
    The spinner will be decremented by this amount for down.  Defaults to 1.
    
  largeStep (float)
    Used like step, but for when page up or page down are pressed to jump in larger
    amounts.  Defaults to 10.
    
  group (string)
    Grouping separator.  Would commonly be set to ',', defaults to ''.
  
  point (string)
    Decimal point character.  Defaults to '.'.
    
  prefix (string)
    Character prefix before the number.  Commonly used for currency symbols.  Defaults to ''.
    
  suffix (string)
    Character suffix after the number.  Commonly used for percentage signs.  Defaults to ''.
    
  className (string)
    Optional class name that should be applied to the container span that is created around
    the input and the buttons
    
  showOn (string)
    Defines when the spin buttons are visible
    'always': Spin buttons are always visible
    'focus': Spin buttons are only visible when the input has focus
    'hover': Spin buttons are only visible when the mouse is hovering over the input
    'both': Spin buttons are visible when the input has focus or is being hovered over
    
  width (integer)
    Width in pixels of the spinner.  Defaults to 16.
    
  increment (array or string)
    Controls the speed of the incremental spin when you hold a button or key down.  Can be set
    to 'fast' or 'slow' to use predefined speeds.  However, you can also supply an array of
    objects to control the speed increments, or null to stop continuous spinning.  The default
    is 'slow'. The objects in the array must have the following properties:
    
    count (integer)
      Number of times to increment at this speed before moving to the next speed.
    
    mult (integer)
      Number to multiply the current step by.  This increases the amount of each increment.
    
    delay (integer)
      Number of milliseconds to delay between each increment.
    
  mouseWheel (boolean)
    If true then mouse wheel events will be attached.  Defaults to true.
    
  allowNull (boolean)
    If true then the control will allow a blank (null) value.  Defaults to false.
  
  format ( function(num, places, element) )
    Function that returns a formatted number.  By default formats using the prefix, suffix,
    places, and point options.  Note that this may be called during initialization before
    the spinner is fully constructed.
    
    this
      options object, should be treated as read-only
    
    num (float)
      Number to be formatted
    
    places (integer)
      Number of decimal places to display
    
    element (jQuery)
      input element
      
    
  parse ( function(num, element) )
    Function that returns a number parsed from an input string.  Will only be called if the
    input is non-null.  By default parses using the prefix, suffix, and point options.
    
    this
      options object, should be treated as read-only
    
    num (string)
      Number to be parsed
    
    element (jQuery)
      input element
    
Example Option Usage
---------------------

0 - 100 incrementing by 2:
  $("#myinput").spinner({min: 0, max: 100, increment: 2});
  
Show on hover/focus only:
  $("#myinput").spinner({showOn: 'both'});
  
Other Commands
---------------

The spinner also support commands after they are created, using the standard UI widget method
of passing strings.

$("#myinput").spinner("value")
  Returns the integer value of the input.  Returns null if the input is blank.
  
$("#myinput").spinner("value", value)
  Sets the integer value of the input.  Still validates against min and max, null blanks the
  input if nulls are allowed.
  
$("#myinput").spinner("enable")
  Enables the spinner and the input
  
$("#myinput").spinner("disable")
  Disables the spinner and the input
  
$("#myinput").spinner("destroy")
  Destroys the spinner, restoring the input to its previous state
  
$("#myinput").spinner("increment")
  Increments the spinner, just like you hit the button
  
$("#myinput").spinner("decrement")
  Decrements the spinner, just like you hit the button

$("#myinput").spinner("showButtons", [immediate])
  Shows the buttons if they are hidden.  If immediate is passed as true, the show won't be
  animated.
  
$("#myinput").spinner("hideButtons", [immediate])
  Hides the buttons if they are visible.  If immediate is passed as true, the hide won't be
  animated.
  
Version History
----------------

1.10
  Added support for mouse wheel
  Added keypress filtering for numbers, special keys only
  Fixed input always focusing on spinner init (caused error in IE)
  Added event namespacing to improve destroy
  Added allowNull option
  Renamed increment option to step
  Will now load HTML5 min, max, and step attributes
  Now sets the maxlength of the input based on min and max
  Changed incremental speed increase to use an array, or be passed 'slow' and 'fast' options
  Changing options after the spinner is created now works
  Added support for decimal places and currency prefix/suffixes
  Added support for custom formatting

1.01
  Renamed from spinbuttons to spinner
  Implemented right/left and home/end keys per the DHTML Style Guide <http://dev.aol.com/dhtml_style_guide>
  Fixed destroy implementation
  Made setValue call change event on input

1.0
  Initial release