Skip to content

Commit 22d2d67

Browse files
fnagelscottgonzalez
fnagel
authored and
scottgonzalez
committed
Selectmenu: added Selectmenu entry. Fixes jquery#67 
1 parent 07599c0 commit 22d2d67

File tree

1 file changed

+183
-0
lines changed

1 file changed

+183
-0
lines changed

‎entries/selectmenu.xml

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
<?xml version="1.0"?>
2+
<entry name="selectmenu" type="widget">
3+
<title>Selectmenu Widget</title>
4+
<desc>A jQuery UI widget that duplicates and extends the functionality of a native HTML select element, allowing it to be customizable in behavior and appearance far beyond the limitations of a native select.</desc>
5+
<longdesc>
6+
<p>Selectmenu Widget will act as a proxy back to the original select element, controlling its state for form submission or serialization.</p>
7+
8+
<p>Selectmenu Widget support both in-place "popup" or drop-down styles. It supports optgroups and custom markup to render specific presentations like multiple lines.</p>
9+
10+
<p>The select or its options can be disabled by adding the <code>disbaled="disabled"</code> attribite to that element.</p>
11+
12+
<h3>Keyboard interaction</h3>
13+
14+
<p>When the menu is open, the following key commands are available:</p>
15+
<ul>
16+
<li>UP/LEFT - Move focus to the previous item. If on first item, move focus to the last item.</li>
17+
<li>DOWN/RIGHT - Move focus to the next item. If on last item, move focus to the first item.</li>
18+
<li>END/PAGE DOWN - Focus last item.</li>
19+
<li>HOME/PAGE UP - Focus first item.</li>
20+
<li>ESCAPE - Close the select.</li>
21+
<li>ENTER - Select the currently focused item and close the select.</li>
22+
<li>ALT+UP/DOWN - Toggle select.</li>
23+
<li>SPACE - Toggle select.</li>
24+
</ul>
25+
26+
<p>When the menu is closed, the following key commands are available:</p>
27+
<ul>
28+
<li>UP/LEFT - Select the previous item. If on first item, select the last item.</li>
29+
<li>DOWN/RIGHT - Select the next item. If on last item, select the first item.</li>
30+
<li>END/PAGE DOWN - Select last item.</li>
31+
<li>HOME/PAGE UP - Select first item.</li>
32+
<li>ALT+UP/DOWN - Toggle select.</li>
33+
<li>SPACE - Toggle select.</li>
34+
</ul>
35+
</longdesc>
36+
<note id="functional-css"/>
37+
<added>1.10</added>
38+
<options>
39+
<option name="dropdown" type="Boolean" default="true" example-value="false">
40+
<desc>If set to <code>true</code> the menu will open as a pop-up. Otherwise the menu is opened below the button just like a native select element.</desc>
41+
</option>
42+
<option name="appendTo" type="Selector" default='"body"' example-value='"#someElem"'>
43+
<desc>Which element the menu should be appended to. Override this when the selectmenu is inside a <code>position: fixed</code> element. Otherwise the popup menu would still scroll with the page.</desc>
44+
</option>
45+
<option name="position" type="Object" default='{ my: "left top", at: "left bottom", collision: "none" }' example-value='{ my : "left+10 center", at: "right center" }'>
46+
<desc>Identifies the position of the menu in relation to the associated button element. Please note position option <code>my</code> and <code>at</code> will be overwritten if option <code>dropdown</code> is set to <code>true</code>. You can refer to the <a href="/position">jQuery UI Position</a> utility for more details about the various options.</desc>
47+
</option>
48+
</options>
49+
<events>
50+
<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
51+
<event name="open">
52+
<desc>Triggered when menu is opened.</desc>
53+
<argument name="event" type="Event"/>
54+
</event>
55+
<event name="focus">
56+
<desc>
57+
Triggered when an items gains focus.
58+
</desc>
59+
<argument name="event" type="Event"/>
60+
<argument name="ui" type="Object">
61+
<property name="item" type="jQuery">
62+
<desc>The focused item.</desc>
63+
</property>
64+
</argument>
65+
</event>
66+
<event name="select">
67+
<desc>
68+
Triggered when a menu item is selected.
69+
</desc>
70+
<argument name="event" type="Event"/>
71+
<argument name="ui" type="Object">
72+
<property name="item" type="jQuery">
73+
<desc>The selected item.</desc>
74+
</property>
75+
</argument>
76+
</event>
77+
<event name="close">
78+
<desc>Triggered when the menu is hidden.</desc>
79+
<argument name="event" type="Event"/>
80+
</event>
81+
<event name="change">
82+
<desc>Triggered when the selected item has changed. Not every <code>select</code> event will fire an <code>change</code> event.</desc>
83+
<argument name="event" type="Event"/>
84+
<argument name="ui" type="Object">
85+
<property name="item" type="jQuery">
86+
<desc>The active item.</desc>
87+
</property>
88+
</argument>
89+
</event>
90+
</events>
91+
<methods>
92+
<method name="open">
93+
<desc>Opens the dialog.</desc>
94+
</method>
95+
<method name="close">
96+
<desc>Closes the Selectmenu menu.</desc>
97+
</method>
98+
<method name="refresh">
99+
<desc>
100+
Parses the original element again and rerenders the menu. New options or optgroups can be added, removed or disabled.
101+
</desc>
102+
</method>
103+
<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
104+
<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
105+
<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
106+
<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
107+
<method name="widget">
108+
<desc>Returns a <code>jQuery</code> object containing the button element.</desc>
109+
</method>
110+
<method name="menuWidget">
111+
<desc>Returns a <code>jQuery</code> object containing the menu element.</desc>
112+
</method>
113+
</methods>
114+
<example>
115+
<desc>A simple jQuery UI Selectmenu</desc>
116+
<code><![CDATA[
117+
$('#speed').selectmenu();
118+
]]></code>
119+
<html><![CDATA[
120+
<label for="speed">Select a speed:</label>
121+
<select name="speed" id="speed">
122+
<option value="Slower">Slower</option>
123+
<option value="Slow">Slow</option>
124+
<option value="Medium" selected="selected">Medium</option>
125+
<option value="Fast">Fast</option>
126+
<option value="Faster">Faster</option>
127+
</select>
128+
]]></html>
129+
</example>
130+
<example>
131+
<desc>A simple jQuery UI Selectmenu with optgroups</desc>
132+
<code><![CDATA[
133+
$('#files').selectmenu();
134+
]]></code>
135+
<html><![CDATA[
136+
<label for="files">Select a file:</label>
137+
<select name="files" id="files">
138+
<optgroup label="Scripts">
139+
<option value="jquery">jQuery.js</option>
140+
<option value="jqueryui">ui.jQuery.js</option>
141+
</optgroup>
142+
<optgroup label="Other files">
143+
<option value="somefile">Some unknown file</option>
144+
<option value="someotherfile">Some other file</option>
145+
</optgroup>
146+
</select>
147+
]]></html>
148+
</example>
149+
<example>
150+
<desc>A jQuery UI Selectmenu with overflow in pop-up mode</desc>
151+
<code><![CDATA[
152+
var withOverflow = $('#number').selectmenu({
153+
dropdown: false
154+
});
155+
withOverflow.selectmenu("menuWidget").addClass("overflow");
156+
]]></code>
157+
<html><![CDATA[
158+
<label for="number">Select a number:</label>
159+
<select name="number" id="number">
160+
<option value="1">1</option>
161+
<option value="2" selected="selected">2</option>
162+
<option value="3">3</option>
163+
<option value="4">4</option>
164+
<option value="5">5</option>
165+
<option value="6">6</option>
166+
<option value="7">7</option>
167+
<option value="8">8</option>
168+
<option value="9">9</option>
169+
<option value="10">10</option>
170+
<option value="11">11</option>
171+
<option value="12">12</option>
172+
<option value="13">13</option>
173+
<option value="14">14</option>
174+
<option value="15">15</option>
175+
<option value="16">16</option>
176+
<option value="17">17</option>
177+
<option value="18">18</option>
178+
<option value="19">19</option>
179+
</select>
180+
]]></html>
181+
</example>
182+
<category slug="widgets"/>
183+
</entry>

0 commit comments

Comments
 (0)