Skip to content
This repository
Fetching contributors…

Cannot retrieve contributors at this time

file 181 lines (178 sloc) 10.123 kb
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
<?xml version="1.0"?>
<entry name="spinner" type="widget" widget-element="generated wrapper">
<title>Spinner Widget</title>
<desc>
Enhance a text input for entering numeric values, with up/down buttons and arrow key handling.
</desc>
<longdesc>
<p>Spinner wraps a text input, adds two buttons to increment and decrement the current value, along with handling key events for the same purpose. It delegates to <a href="https://github.com/jquery/globalize">Globalize</a> for number formatting and parsing.</p>

<h3>Keyboard interaction</h3>

<ul>
<li>UP: Increment the value by one step.</li>
<li>DOWN: Decrement the value by one step.</li>
<li>PAGE UP: Increment the value by one page.</li>
<li>PAGE DOWN: Decrement the value by one page.</li>
</ul>

<p>Focus stays in the text field, even after using the mouse to click one of the spin buttons.</p>
</longdesc>
<note id="functional-css"/>
<added>1.9</added>
<options>
<option name="culture" type="String" default="null" example-value='"fr"'>
<desc>Sets the culture to use for parsing and formatting the value. If <code>null</code>, the currently set culture in <code>Globalize</code> is used, see <a href="https://github.com/jquery/globalize">Globalize docs</a> for available cultures. Only relevant if the <a href="#option-numberFormat"><code>numberFormat</code></a> option is set. Requires <a href="https://github.com/jquery/globalize">Globalize</a> to be included.</desc>
</option>
<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<option name="icons" type="Object" default='{ down: "ui-icon-triangle-1-s", up: "ui-icon-triangle-1-n" }' example-value='{ down: "custom-down-icon", up: "custom-up-icon" }'>
<desc>
Icons to use for buttons, matching an icon defined by the jQuery UI CSS Framework.
<ul>
<li>up (string, default: "ui-icon-triangle-1-n")</li>
<li>down (string, default: "ui-icon-triangle-1-s")</li>
</ul>
</desc>
</option>
<option name="incremental" default="true" example-value="false">
<desc>Controls the number of steps taken when holding down a spin button.</desc>
<type name="Boolean">
<desc>When set to <code>true</code>, the stepping delta will increase when spun incessantly. When set to <code>false</code>, all steps are equal (as defined by the <a href="#option-step"><code>step</code></a> option).</desc>
</type>
<type name="Function">
<desc>Receives one parameter: the number of spins that have occurred. Must return the number of steps that should occur for the current spin.</desc>
</type>
</option>
<option name="max" default="null" example-value="50">
<desc>The maximum allowed value. The element's <code>max</code> attribute is used if it exists and the option is not explicitly set. If <code>null</code>, there is no maximum enforced.</desc>
<type name="Number">
<desc>The maximum value.</desc>
</type>
<type name="String">
<desc>If <a href="https://github.com/jquery/globalize">Globalize</a> is included, the <code>max</code> option can be passed as a string which will be parsed based on the <a href="#opiton-numberFormat"><code>numberFormat</code></a> and <a href="#option-culture"><code>culture</code></a> options; otherwise it will fall back to the native <code>parseFloat()</code> method.</desc>
</type>
</option>
<option name="min" default="null" example-value="0">
<desc>The minimum allowed value. The element's <code>min</code> attribute is used if it exists and the option is not explicitly set. If <code>null</code>, there is no minimum enforced.</desc>
<type name="Number">
<desc>The minimum value.</desc>
</type>
<type name="String">
<desc>If <a href="https://github.com/jquery/globalize">Globalize</a> is included, the <code>min</code> option can be passed as a string which will be parsed based on the <a href="#opiton-numberFormat"><code>numberFormat</code></a> and <a href="#option-culture"><code>culture</code></a> options; otherwise it will fall back to the native <code>parseFloat()</code> method.</desc>
</type>
</option>
<option name="numberFormat" type="String" default="null" example-value='"n"'>
<desc>Format of numbers passed to <a href="https://github.com/jquery/globalize"><code>Globalize</code></a>, if available. Most common are <code>"n"</code> for a decimal number and <code>"C"</code> for a currency value. Also see the <a href="#option-culture"><code>culture</code></a> option.</desc>
</option>
<option name="page" type="Number" default="10" example-value="5">
<desc>The number of steps to take when paging via the <a href="#method-pageUp"><code>pageUp</code></a>/<a href="#method-pageDown"><code>pageDown</code></a> methods.</desc>
</option>
<option name="step" default="1" example-value="2">
<desc>The size of the step to take when spinning via buttons or via the <a href="#method-stepUp"><code>stepUp()</code></a>/<a href="#method-stepDown"><code>stepDown()</code></a> methods. The element's <code>step</code> attribute is used if it exists and the option is not explicitly set.</desc>
<type name="Number">
<desc>The size of the step.</desc>
</type>
<type name="String">
<desc>If <a href="https://github.com/jquery/globalize">Globalize</a> is included, the <code>step</code> option can be passed as a string which will be parsed based on the <a href="#opiton-numberFormat"><code>numberFormat</code></a> and <a href="#option-culture"><code>culture</code></a> options, otherwise it will fall back to the native <code>parseFloat</code>.</desc>
</type>
</option>
</options>
<methods>
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<method name="pageDown">
<desc>
Decrements the value by the specified number of pages, as defined by the <a href="#option-page"><code>page</code></a> option. Without the parameter, a single page is decremented.
</desc>
<argument name="pages" type="Number" optional="true">
<desc>Number of pages to decrement, defaults to 1.</desc>
</argument>
</method>
<method name="pageUp" example-params='10'>
<desc>
Increments the value by the specified number of pages, as defined by the <a href="#option-page"><code>page</code></a> option. Without the parameter, a single page is incremented.
</desc>
<argument name="pages" type="Number" optional="true">
<desc>Number of pages to increment, defaults to 1.</desc>
</argument>
</method>
<method name="stepDown">
<desc>
Decrements the value by the specified number of steps. Without the parameter, a single step is decremented.
<p>If the resulting value is above the max, below the min, or reuslts in a step mismatch, the value will be adjusted to the closest valid value.</p>
</desc>
<argument name="steps" type="Number" optional="true">
<desc>Number of steps to decrement, defaults to 1.</desc>
</argument>
</method>
<method name="stepUp" example-params='5'>
<desc>
Increments the value by the specified number of steps. Without the parameter, a single step is incremented.
<p>If the resulting value is above the max, below the min, or reuslts in a step mismatch, the value will be adjusted to the closest valid value.</p>
</desc>
<argument name="steps" type="Number" optional="true">
<desc>Number of steps to increment, defaults to 1.</desc>
</argument>
</method>
<method name="value">
<desc>
Gets or sets the current value as a number.
</desc>
<signature return="Number" example-return-var="value">
<desc>Gets the current value as a number. The value is parsed based on the <a href="#option-numberFormat"><code>numberFormat</code></a> and <a href="#option-culture"><code>culture</code></a> options.</desc>
</signature>
<signature example-params='50'>
<argument name="value">
<desc>The value to set. If passed as a string, the value is parsed based on the <a href="#option-numberFormat"><code>numberFormat</code></a> and <a href="#option-culture"><code>culture</code></a> options.</desc>
<type name="Number"/>
<type name="String"/>
</argument>
</signature>
</method>
<xi:include href="../includes/widget-method-widget.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
</methods>
<events>
<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
<event name="start" type="spinstart">
<desc>
Triggered before a spin. Can be canceled, preventing the spin from occurring.
</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object"/>
</event>
<event name="spin" type="spin">
<desc>
Triggered during increment/decrement (to determine direction of spin compare current value with <code>ui.value</code>).
<p>Can be canceled, preventing the value from being updated.</p>
</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object">
<property name="value" type="Number">
<desc>The new value to be set, unless the event is cancelled.</desc>
</property>
</argument>
</event>
<event name="stop" type="spinstop">
<desc>Triggered after a spin.</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object"/>
</event>
<event name="change" type="spinchange">
<desc>
Triggered when the value of the spinner has changed and the input is no longer focused.
</desc>
<argument name="event" type="Event"/>
<argument name="ui" type="Object"/>
</event>
</events>
<example>
<height>50</height>
<desc>Plain number spinner</desc>
<code><![CDATA[
$( "#spinner" ).spinner();
]]></code>
<html><![CDATA[
<input id="spinner">
]]></html>
</example>
<category slug="widgets"/>
</entry>
Something went wrong with that request. Please try again.