/ext-4.1.0_b3/docs/source/Picker.html
HTML | 328 lines | 288 code | 40 blank | 0 comment | 0 complexity | 6da217d15a7512af73a94cc3021fd3b5 MD5 | raw file
1<!DOCTYPE html>
2<html>
3<head>
4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5 <title>The source code</title>
6 <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7 <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8 <style type="text/css">
9 .highlight { display: block; background-color: #ddd; }
10 </style>
11 <script type="text/javascript">
12 function highlight() {
13 document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14 }
15 </script>
16</head>
17<body onload="prettyPrint(); highlight();">
18 <pre class="prettyprint lang-js"><span id='Ext-form-field-Picker'>/**
19</span> * An abstract class for fields that have a single trigger which opens a "picker" popup below the field, e.g. a combobox
20 * menu list or a date picker. It provides a base implementation for toggling the picker's visibility when the trigger
21 * is clicked, as well as keyboard navigation and some basic events. Sizing and alignment of the picker can be
22 * controlled via the {@link #matchFieldWidth} and {@link #pickerAlign}/{@link #pickerOffset} config properties
23 * respectively.
24 *
25 * You would not normally use this class directly, but instead use it as the parent class for a specific picker field
26 * implementation. Subclasses must implement the {@link #createPicker} method to create a picker component appropriate
27 * for the field.
28 */
29Ext.define('Ext.form.field.Picker', {
30 extend: 'Ext.form.field.Trigger',
31 alias: 'widget.pickerfield',
32 alternateClassName: 'Ext.form.Picker',
33 requires: ['Ext.util.KeyNav'],
34
35<span id='Ext-form-field-Picker-cfg-matchFieldWidth'> /**
36</span> * @cfg {Boolean} matchFieldWidth
37 * Whether the picker dropdown's width should be explicitly set to match the width of the field. Defaults to true.
38 */
39 matchFieldWidth: true,
40
41<span id='Ext-form-field-Picker-cfg-pickerAlign'> /**
42</span> * @cfg {String} pickerAlign
43 * The {@link Ext.Element#alignTo alignment position} with which to align the picker. Defaults to "tl-bl?"
44 */
45 pickerAlign: 'tl-bl?',
46
47<span id='Ext-form-field-Picker-cfg-pickerOffset'> /**
48</span> * @cfg {Number[]} pickerOffset
49 * An offset [x,y] to use in addition to the {@link #pickerAlign} when positioning the picker.
50 * Defaults to undefined.
51 */
52
53<span id='Ext-form-field-Picker-cfg-openCls'> /**
54</span> * @cfg {String} [openCls='x-pickerfield-open']
55 * A class to be added to the field's {@link #bodyEl} element when the picker is opened.
56 */
57 openCls: Ext.baseCSSPrefix + 'pickerfield-open',
58
59<span id='Ext-form-field-Picker-property-isExpanded'> /**
60</span> * @property {Boolean} isExpanded
61 * True if the picker is currently expanded, false if not.
62 */
63
64<span id='Ext-form-field-Picker-cfg-editable'> /**
65</span> * @cfg {Boolean} editable
66 * False to prevent the user from typing text directly into the field; the field can only have its value set via
67 * selecting a value from the picker. In this state, the picker can also be opened by clicking directly on the input
68 * field itself.
69 */
70 editable: true,
71
72
73 initComponent: function() {
74 this.callParent();
75
76 // Custom events
77 this.addEvents(
78<span id='Ext-form-field-Picker-event-expand'> /**
79</span> * @event expand
80 * Fires when the field's picker is expanded.
81 * @param {Ext.form.field.Picker} field This field instance
82 */
83 'expand',
84<span id='Ext-form-field-Picker-event-collapse'> /**
85</span> * @event collapse
86 * Fires when the field's picker is collapsed.
87 * @param {Ext.form.field.Picker} field This field instance
88 */
89 'collapse',
90<span id='Ext-form-field-Picker-event-select'> /**
91</span> * @event select
92 * Fires when a value is selected via the picker.
93 * @param {Ext.form.field.Picker} field This field instance
94 * @param {Object} value The value that was selected. The exact type of this value is dependent on
95 * the individual field and picker implementations.
96 */
97 'select'
98 );
99 },
100
101
102 initEvents: function() {
103 var me = this;
104 me.callParent();
105
106 // Add handlers for keys to expand/collapse the picker
107 me.keyNav = new Ext.util.KeyNav(me.inputEl, {
108 down: me.onDownArrow,
109 esc: {
110 handler: me.onEsc,
111 scope: me,
112 defaultEventAction: false
113 },
114 scope: me,
115 forceKeyDown: true
116 });
117
118 // Non-editable allows opening the picker by clicking the field
119 if (!me.editable) {
120 me.mon(me.inputEl, 'click', me.onTriggerClick, me);
121 }
122
123 // Disable native browser autocomplete
124 if (Ext.isGecko) {
125 me.inputEl.dom.setAttribute('autocomplete', 'off');
126 }
127 },
128
129 // private
130 onEsc: function(e) {
131 var me = this;
132 if (me.isExpanded) {
133 me.collapse();
134 e.stopEvent();
135 } else {
136 // If there's an ancestor Window which will see the ESC event and hide, ensure this Field blurs
137 // so that a down arrow will not pop up a disembodied dropdown list.
138 if (me.up('window')) {
139 me.blur();
140 }
141 // Otherwise, only stop the ESC key event if it's not going to bubble up to the FocusManager
142 else if ((!Ext.FocusManager || !Ext.FocusManager.enabled)) {
143 e.stopEvent();
144 }
145 }
146 },
147
148 onDownArrow: function(e) {
149 if (!this.isExpanded) {
150 // Don't call expand() directly as there may be additional processing involved before
151 // expanding, e.g. in the case of a ComboBox query.
152 this.onTriggerClick();
153 }
154 },
155
156<span id='Ext-form-field-Picker-method-expand'> /**
157</span> * Expands this field's picker dropdown.
158 */
159 expand: function() {
160 var me = this,
161 bodyEl, picker, collapseIf;
162
163 if (me.rendered && !me.isExpanded && !me.isDestroyed) {
164 bodyEl = me.bodyEl;
165 picker = me.getPicker();
166 collapseIf = me.collapseIf;
167
168 // show the picker and set isExpanded flag
169 picker.show();
170 me.isExpanded = true;
171 me.alignPicker();
172 bodyEl.addCls(me.openCls);
173
174 // monitor clicking and mousewheel
175 me.mon(Ext.getDoc(), {
176 mousewheel: collapseIf,
177 mousedown: collapseIf,
178 scope: me
179 });
180 Ext.EventManager.onWindowResize(me.alignPicker, me);
181 me.fireEvent('expand', me);
182 me.onExpand();
183 }
184 },
185
186 onExpand: Ext.emptyFn,
187
188<span id='Ext-form-field-Picker-method-alignPicker'> /**
189</span> * Aligns the picker to the input element
190 * @protected
191 */
192 alignPicker: function() {
193 var me = this,
194 picker = me.getPicker();
195
196 if (me.isExpanded) {
197 if (me.matchFieldWidth) {
198 // Auto the height (it will be constrained by min and max width) unless there are no records to display.
199 picker.setWidth(me.bodyEl.getWidth());
200 }
201 if (picker.isFloating()) {
202 me.doAlign();
203 }
204 }
205 },
206
207<span id='Ext-form-field-Picker-method-doAlign'> /**
208</span> * Performs the alignment on the picker using the class defaults
209 * @private
210 */
211 doAlign: function(){
212 var me = this,
213 picker = me.picker,
214 aboveSfx = '-above',
215 isAbove;
216
217 me.picker.alignTo(me.inputEl, me.pickerAlign, me.pickerOffset);
218 // add the {openCls}-above class if the picker was aligned above
219 // the field due to hitting the bottom of the viewport
220 isAbove = picker.el.getY() < me.inputEl.getY();
221 me.bodyEl[isAbove ? 'addCls' : 'removeCls'](me.openCls + aboveSfx);
222 picker[isAbove ? 'addCls' : 'removeCls'](picker.baseCls + aboveSfx);
223 },
224
225<span id='Ext-form-field-Picker-method-collapse'> /**
226</span> * Collapses this field's picker dropdown.
227 */
228 collapse: function() {
229 if (this.isExpanded && !this.isDestroyed) {
230 var me = this,
231 openCls = me.openCls,
232 picker = me.picker,
233 doc = Ext.getDoc(),
234 collapseIf = me.collapseIf,
235 aboveSfx = '-above';
236
237 // hide the picker and set isExpanded flag
238 picker.hide();
239 me.isExpanded = false;
240
241 // remove the openCls
242 me.bodyEl.removeCls([openCls, openCls + aboveSfx]);
243 picker.el.removeCls(picker.baseCls + aboveSfx);
244
245 // remove event listeners
246 doc.un('mousewheel', collapseIf, me);
247 doc.un('mousedown', collapseIf, me);
248 Ext.EventManager.removeResizeListener(me.alignPicker, me);
249 me.fireEvent('collapse', me);
250 me.onCollapse();
251 }
252 },
253
254 onCollapse: Ext.emptyFn,
255
256
257<span id='Ext-form-field-Picker-method-collapseIf'> /**
258</span> * @private
259 * Runs on mousewheel and mousedown of doc to check to see if we should collapse the picker
260 */
261 collapseIf: function(e) {
262 var me = this;
263 if (!me.isDestroyed && !e.within(me.bodyEl, false, true) && !e.within(me.picker.el, false, true)) {
264 me.collapse();
265 }
266 },
267
268<span id='Ext-form-field-Picker-method-getPicker'> /**
269</span> * Returns a reference to the picker component for this field, creating it if necessary by
270 * calling {@link #createPicker}.
271 * @return {Ext.Component} The picker component
272 */
273 getPicker: function() {
274 var me = this;
275 return me.picker || (me.picker = me.createPicker());
276 },
277
278<span id='Ext-form-field-Picker-method-createPicker'> /**
279</span> * @method
280 * Creates and returns the component to be used as this field's picker. Must be implemented by subclasses of Picker.
281 * The current field should also be passed as a configuration option to the picker component as the pickerField
282 * property.
283 */
284 createPicker: Ext.emptyFn,
285
286<span id='Ext-form-field-Picker-method-onTriggerClick'> /**
287</span> * Handles the trigger click; by default toggles between expanding and collapsing the picker component.
288 * @protected
289 */
290 onTriggerClick: function() {
291 var me = this;
292 if (!me.readOnly && !me.disabled) {
293 if (me.isExpanded) {
294 me.collapse();
295 } else {
296 me.expand();
297 }
298 me.inputEl.focus();
299 }
300 },
301
302 mimicBlur: function(e) {
303 var me = this,
304 picker = me.picker;
305 // ignore mousedown events within the picker element
306 if (!picker || !e.within(picker.el, false, true)) {
307 me.callParent(arguments);
308 }
309 },
310
311 onDestroy : function(){
312 var me = this,
313 picker = me.picker;
314
315 Ext.EventManager.removeResizeListener(me.alignPicker, me);
316 Ext.destroy(me.keyNav);
317 if (picker) {
318 delete picker.pickerField;
319 picker.destroy();
320 }
321 me.callParent();
322 }
323
324});
325
326</pre>
327</body>
328</html>