forked from brantburnett/jquery.ui.spinner
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
221 lines (163 loc) · 7.89 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
jQuery.ui.spinner 1.20
jQuery.ui extension for a numeric spinner
Licensing
----------
Written by Brant Burnett <http://btburnett.com/> <mailto:[email protected]>
Copyright (c) 2009-2010 Brant Burnett
Dual licensed under the MIT or GPL Version 2 licenses.
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.
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.8 <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.20
Updated for the UI 1.8 widget factory
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