001: /*
002: * GWT-Ext Widget Library
003: * Copyright(c) 2007-2008, GWT-Ext.
004: * licensing@gwt-ext.com
005: *
006: * http://www.gwt-ext.com/license
007: */
008:
009: package com.gwtext.client.widgets.form;
010:
011: import com.google.gwt.core.client.JavaScriptObject;
012: import com.google.gwt.user.client.Element;
013: import com.gwtext.client.core.Template;
014: import com.gwtext.client.data.SimpleStore;
015: import com.gwtext.client.data.Store;
016: import com.gwtext.client.util.JavaScriptObjectHelper;
017: import com.gwtext.client.widgets.form.event.ComboBoxListener;
018: import com.gwtext.client.widgets.Shadow;
019:
020: public class ComboBox extends TextField {
021:
022: public static Mode REMOTE = new Mode("remote");
023: public static Mode LOCAL = new Mode("local");
024:
025: public static Trigger ALL = new Trigger("all");
026: public static Trigger QUERY = new Trigger("query");
027:
028: private String displayField;
029:
030: private static JavaScriptObject configPrototype;
031:
032: static {
033: init();
034: }
035:
036: private static native void init()/*-{
037: var c = new $wnd.Ext.form.Checkbox();
038: @com.gwtext.client.widgets.form.Checkbox::configPrototype = c.initialConfig;
039: }-*/;
040:
041: protected JavaScriptObject getConfigPrototype() {
042: return configPrototype;
043: }
044:
045: public String getXType() {
046: return "combo";
047: }
048:
049: public ComboBox() {
050: }
051:
052: public ComboBox(String fieldLabel) {
053: super (fieldLabel);
054: }
055:
056: public ComboBox(String fieldLabel, String name) {
057: super (fieldLabel, name);
058: }
059:
060: public ComboBox(String fieldLabel, String name, int width) {
061: super (fieldLabel, name, width);
062: }
063:
064: public ComboBox(JavaScriptObject jsObj) {
065: super (jsObj);
066: }
067:
068: protected native JavaScriptObject create(JavaScriptObject jsObj) /*-{
069: return new $wnd.Ext.form.ComboBox(jsObj);
070: }-*/;
071:
072: protected native Element getElement(JavaScriptObject jsObj) /*-{
073: //for trigger fields, we want the text area as well as the trigger button to be treated as the element
074: //unit
075: var extEl = jsObj.wrap;
076: if(extEl == null || extEl === undefined) {
077: return null;
078: }
079: var el = extEl.dom;
080: if(el == null || el === undefined) {
081: return null;
082: //forms buttons are detached when initially added
083: } else {
084: //There's an inconsistency in Ext where most elements have the property 'el' set to Ext's Element
085: //with the exception of Menu->Item, Menu->Separator, Menu->TextItem, Toolbar.Item and subclasses
086: //(Toolbar.Separator, Toolbar.Spacer, Toolbar.TextItem) where the 'el' property is set to
087: //the DOM element itself. Therefore retruning 'el' if 'el' is not Ext's Element. See details in issue 39.
088: return el.dom || el ;
089: }
090: }-*/;
091:
092: public native void clearValue() /*-{
093: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
094: cb.clearValue();
095: }-*/;
096:
097: public native void collapse() /*-{
098: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
099: cb.collapse();
100: }-*/;
101:
102: public native void doQuery(String query, boolean forceAll) /*-{
103: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
104: cb.doQuery(query, forceAll);
105: }-*/;
106:
107: public native void expand() /*-{
108: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
109: cb.expand();
110: }-*/;
111:
112: public native String getValue() /*-{
113: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
114: var val = cb.getValue();
115: return val === '' ? null : val.toString();
116: }-*/;
117:
118: public native boolean isExpanded() /*-{
119: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
120: return cb.isExpanded();
121: }-*/;
122:
123: public native void select(int index, boolean scrollIntoView) /*-{
124: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
125: cb.select(index, scrollIntoView);
126: }-*/;
127:
128: public native void selectByValue(String value,
129: boolean scrollIntoView) /*-{
130: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
131: cb.selectByValue(value, scrollIntoView);
132: }-*/;
133:
134: private native void setEditableRendered(boolean value) /*-{
135: var cb = this.@com.gwtext.client.widgets.Component::getOrCreateJsObj()();
136: cb.setEditable(value);
137: }-*/;
138:
139: /**
140: * Sets the specified value into the field. If the value finds a match, the corresponding record text will be displayed in the field. If the value does
141: * not match the data value of an existing item, and the valueNotFoundText config option is defined, it will be displayed as the default field text. Otherwise the field will be blank (although the value will still be set).
142: */
143: public void setValue(String value) {
144: super .setValue(value);
145: }
146:
147: public native void addListener(ComboBoxListener listener) /*-{
148: this.@com.gwtext.client.widgets.form.Field::addListener(Lcom/gwtext/client/widgets/form/event/FieldListener;)(listener);
149:
150: var fieldJ = this;
151:
152: this.@com.gwtext.client.widgets.Component::addListener(Ljava/lang/String;Lcom/google/gwt/core/client/JavaScriptObject;)('beforequery',
153: function(o) {
154: var cbJ = @com.gwtext.client.widgets.form.event.ComboBoxCallback::instance(Lcom/google/gwt/core/client/JavaScriptObject;)(o);
155: return listener.@com.gwtext.client.widgets.form.event.ComboBoxListener::doBeforeQuery(Lcom/gwtext/client/widgets/form/ComboBox;Lcom/gwtext/client/widgets/form/event/ComboBoxCallback;)(fieldJ,cbJ);
156: }
157: );
158:
159: this.@com.gwtext.client.widgets.Component::addListener(Ljava/lang/String;Lcom/google/gwt/core/client/JavaScriptObject;)('beforeselect',
160: function(fld, record, index) {
161: var recordJ = @com.gwtext.client.data.Record::instance(Lcom/google/gwt/core/client/JavaScriptObject;)(record);
162: return listener.@com.gwtext.client.widgets.form.event.ComboBoxListener::doBeforeSelect(Lcom/gwtext/client/widgets/form/ComboBox;Lcom/gwtext/client/data/Record;I)(fieldJ, recordJ, index);
163: }
164: );
165:
166: this.@com.gwtext.client.widgets.Component::addListener(Ljava/lang/String;Lcom/google/gwt/core/client/JavaScriptObject;)('collapse',
167: function(fld) {
168: listener.@com.gwtext.client.widgets.form.event.ComboBoxListener::onCollapse(Lcom/gwtext/client/widgets/form/ComboBox;)(fieldJ);
169: }
170: );
171: this.@com.gwtext.client.widgets.Component::addListener(Ljava/lang/String;Lcom/google/gwt/core/client/JavaScriptObject;)('expand',
172: function(fld) {
173: listener.@com.gwtext.client.widgets.form.event.ComboBoxListener::onExpand(Lcom/gwtext/client/widgets/form/ComboBox;)(fieldJ);
174: }
175: );
176:
177: this.@com.gwtext.client.widgets.Component::addListener(Ljava/lang/String;Lcom/google/gwt/core/client/JavaScriptObject;)('select',
178: function(fld, record, index) {
179: var recordJ = @com.gwtext.client.data.Record::instance(Lcom/google/gwt/core/client/JavaScriptObject;)(record);
180: listener.@com.gwtext.client.widgets.form.event.ComboBoxListener::onSelect(Lcom/gwtext/client/widgets/form/ComboBox;Lcom/gwtext/client/data/Record;I)(fieldJ, recordJ, index);
181: }
182: );
183: }-*/;
184:
185: public static class Mode {
186: private String mode;
187:
188: private Mode(String mode) {
189: this .mode = mode;
190: }
191:
192: public String getMode() {
193: return mode;
194: }
195: }
196:
197: public static class Trigger {
198: private String trigger;
199:
200: private Trigger(String trigger) {
201: this .trigger = trigger;
202: }
203:
204: public String getTrigger() {
205: return trigger;
206: }
207: }
208:
209: // --- config properties
210:
211: /**
212: * The text query to send to the server to return all records for the list with no
213: * filtering (defaults to '')
214: *
215: * @param allQuery the all query string
216: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
217: */
218: public void setAllQuery(String allQuery)
219: throws IllegalStateException {
220: setAttribute("allQuery", allQuery, true);
221: }
222:
223: /**
224: * The underlying data field name to bind to this ComboBox (defaults to undefined if mode = 'remote' or 'text' if mode = 'local').
225: *
226: * @param displayField the display field
227: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
228: */
229: public void setDisplayField(String displayField)
230: throws IllegalStateException {
231: setAttribute("displayField", displayField, true);
232: JavaScriptObject store = JavaScriptObjectHelper
233: .getAttributeAsJavaScriptObject(config, "store");
234: if (store != null) {
235: setFilterColParam(store, displayField);
236: } else {
237: this .displayField = displayField;
238: }
239: }
240:
241: private native void setFilterColParam(JavaScriptObject store,
242: String displayField) /*-{
243: store.baseParams['filterCol'] = displayField;
244: }-*/;
245:
246: /**
247: * False to prevent the user from typing text directly into the field, just like a traditional select (defaults to true).
248: *
249: * @param editable false to disable editing
250: */
251: public void setEditable(boolean editable) {
252: if (!isCreated()) {
253: setAttribute("editable", editable, true);
254: } else {
255: setEditableRendered(editable);
256: }
257: if (!editable) {
258: //if its not editable, set the fields value to be the underlying Store's value and not the disaply field.
259: //if the field is editable, then we cant make this assumtion because hte user might want to have the user
260: //any text that is not in the store and have this value submitted. under such circumstances it is expected that
261: //the user makes the decision and sets hiddenName if desired
262: String name = getName();
263: if (name != null) {
264: setHiddenName(name);
265: }
266: }
267: }
268:
269: /**
270: * True to restrict the selected value to one of the values in the list, false to allow the user to set arbitrary text
271: * into the field (defaults to false)
272: *
273: * @param forceSelection true to force selection
274: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
275: */
276: public void setForceSelection(boolean forceSelection)
277: throws IllegalStateException {
278: setAttribute("forceSelection", forceSelection, true);
279: String name = getName();
280: //if its not editable, set the fields value to be the underlying Store's value and not the disaply field.
281: //if the field is editable, then we cant make this assumtion because hte user might want to have the user
282: //any text that is not in the store and have this value submitted. under such circumstances it is expected that
283: //the user makes the decision and sets hiddenName if desired
284: if (name != null) {
285: setHiddenName(name);
286: }
287: }
288:
289: /**
290: * The height in pixels of the dropdown list resize handle if resizable = true (defaults to 8)
291: *
292: * @param handleHeight the handle height
293: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
294: */
295: public void setHandleHeight(int handleHeight)
296: throws IllegalStateException {
297: setAttribute("handleHeight", handleHeight, true);
298: }
299:
300: /**
301: * If specified, a hidden form field with this name is dynamically generated to store the field's data value
302: * (defaults to the underlying DOM element's name)
303: *
304: * @param hiddenName the hidden name
305: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
306: */
307: public void setHiddenName(String hiddenName)
308: throws IllegalStateException {
309: setAttribute("hiddenName", hiddenName, true);
310: }
311:
312: /**
313: * True to hide the trigger element and display only the base text field (defaults to false).
314: *
315: * @param hideTrigger true to hide trigger
316: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
317: */
318: public void setHideTrigger(boolean hideTrigger)
319: throws IllegalStateException {
320: setAttribute("hideTrigger", hideTrigger, true);
321: }
322:
323: /**
324: * A CSS class to apply to the trigger.
325: *
326: * @param triggerClass the trigger CSS class.
327: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
328: */
329: public void setTriggerClass(String triggerClass)
330: throws IllegalStateException {
331: setAttribute("triggerClass", triggerClass, true);
332: }
333:
334: /**
335: * A CSS selector in any format supported by {@link com.gwtext.client.core.DomQuery} that will be used to determine
336: * what nodes this DataView will be working with.
337: *
338: * @param itemSelector the items selector
339: */
340: public void setItemSelector(String itemSelector) {
341: setAttribute("itemSelector", itemSelector, true);
342: }
343:
344: /**
345: * True to indicate this is a linked combo box.
346: *
347: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
348: */
349: public void setLinked(boolean linked) throws IllegalStateException {
350: if (linked) {
351: setAttribute("lastQuery", "", true);
352: }
353: }
354:
355: /**
356: * True to prevent the ComboBox from rendering until requested
357: * (should always be used when rendering into an Editor, defaults to false).
358: *
359: * @param lazyRender true to lazy render
360: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
361: */
362: public void setLazyRender(boolean lazyRender)
363: throws IllegalStateException {
364: setAttribute("lazyRender", lazyRender, false);
365: }
366:
367: /**
368: * A valid anchor position value.
369: *
370: * @param anchorPosition the anchor position
371: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
372: */
373: public void setListAlign(String anchorPosition)
374: throws IllegalStateException {
375: setAttribute("listAlign", anchorPosition, true);
376: }
377:
378: /**
379: * CSS class to apply to the dropdown list element (defaults to '').
380: *
381: * @param listClass list css class
382: */
383: public void setListClass(String listClass) {
384: setAttribute("listClass", listClass, true, true);
385: }
386:
387: /**
388: * The width in pixels of the dropdown list (defaults to the width of the ComboBox field)
389: *
390: * @param listWidth the list width
391: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
392: */
393: public void setListWidth(int listWidth)
394: throws IllegalStateException {
395: setAttribute("listWidth", listWidth, true);
396: }
397:
398: /**
399: * The text to display in the dropdown list while data is loading. Only applies when mode = 'remote'
400: * (defaults to 'Loading...')
401: *
402: * @param loadingText the loading text
403: */
404: public void setLoadingText(String loadingText) {
405: setAttribute("loadingText", loadingText, true, true);
406: }
407:
408: /**
409: * The maximum height in pixels of the dropdown list before scrollbars are shown (defaults to 300).
410: *
411: * @param maxHeight the max height
412: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
413: */
414: public void setMaxHeight(int maxHeight)
415: throws IllegalStateException {
416: setAttribute("maxHeight", maxHeight, true);
417: }
418:
419: /**
420: * The minimum number of characters the user must type before autocomplete and typeahead activate
421: * (defaults to 4, does not apply if editable = false)
422: *
423: * @param minChars the min chars before autocomplete
424: */
425: public void setMinChars(int minChars) {
426: setAttribute("minChars", minChars, true, true);
427: }
428:
429: /**
430: * The minimum width of the dropdown list in pixels (defaults to 70, will be
431: * ignored if listWidth has a higher value).
432: *
433: * @param minListWidth the min list width
434: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
435: */
436: public void setMinListWidth(int minListWidth)
437: throws IllegalStateException {
438: setAttribute("minListWidth", minListWidth, true);
439: }
440:
441: /**
442: * Set to {@link com.gwtext.client.widgets.form.ComboBox#LOCAL} if the ComboBox loads local data.
443: * (defaults to {@link com.gwtext.client.widgets.form.ComboBox#REMOTE} which loads from the server)
444: *
445: * @param mode local or remote mode
446: */
447: public void setMode(ComboBox.Mode mode) {
448: setAttribute("mode", mode.getMode(), false);
449: }
450:
451: /**
452: * If greater than 0, a paging toolbar is displayed in the footer of the dropdown list and the filter queries will
453: * execute with page start and limit parameters. Only applies when mode = 'remote' (defaults to 0).
454: *
455: * @param pageSize the page size
456: * @see #setMode(com.gwtext.client.widgets.form.ComboBox.Mode)
457: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
458: */
459: public void setPageSize(int pageSize) throws IllegalStateException {
460: setAttribute("pageSize", pageSize, true);
461: }
462:
463: /**
464: * The length of time in milliseconds to delay between the start of typing and sending the query to filter the
465: * dropdown list (defaults to 500 if mode = 'remote' or 10 if mode = 'local')
466: *
467: * @param queryDelay query delay in milliseconds
468: * @see #setMode(com.gwtext.client.widgets.form.ComboBox.Mode)
469: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
470: */
471: public void setQueryDelay(int queryDelay)
472: throws IllegalStateException {
473: setAttribute("queryDelay", queryDelay, true);
474: }
475:
476: /**
477: * Name of the query as it will be passed on the querystring (defaults to 'query')
478: *
479: * @param queryParam the query param
480: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
481: */
482: public void setQueryParam(String queryParam)
483: throws IllegalStateException {
484: setAttribute("queryParam", queryParam, true);
485: }
486:
487: /**
488: * True to add a resize handle to the bottom of the dropdown list (defaults to false).
489: *
490: * @param resizable true for resizale
491: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
492: */
493: public void setResizable(boolean resizable)
494: throws IllegalStateException {
495: setAttribute("resizable", resizable, true);
496: }
497:
498: /**
499: * CSS class to apply to the selected item in the dropdown list (defaults to 'x-combo-selected')
500: *
501: * @param selectedClass the selected css class
502: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
503: */
504: public void setSelectedClass(String selectedClass)
505: throws IllegalStateException {
506: setAttribute("selectedClass", selectedClass, true);
507: }
508:
509: /**
510: * True for default effect
511: *
512: * @param shadow true to enable shadow
513: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
514: */
515: public void setShadow(boolean shadow) throws IllegalStateException {
516: setAttribute("shadow", shadow, true);
517: }
518:
519: /**
520: * "sides" for the default effect, "frame" for 4-way shadow, and "drop" for bottom-right.
521: *
522: * @param shadow shadow style
523: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
524: */
525: public void setShadow(Shadow.Type shadow)
526: throws IllegalStateException {
527: setAttribute("shadow", shadow.getType(), true);
528: }
529:
530: /**
531: * The data store to which this combo is bound (defaults to undefined)
532: *
533: * @param store the combobox store
534: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
535: */
536: public void setStore(Store store) throws IllegalStateException {
537: if (store instanceof SimpleStore) {
538: setTriggerAction(ALL);
539: if (!isCreated())
540: setMode(LOCAL);
541: }
542: setAttribute("store", store.getJsObj(), true);
543: if (displayField != null) {
544: setFilterColParam(store.getJsObj(), displayField);
545: }
546: }
547:
548: /**
549: * If supplied, a header element is created containing this text and added into the top of the dropdown list
550: * (defaults to undefined, with no header element).
551: *
552: * @param title the combobox title
553: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
554: */
555: public void setTitle(String title) throws IllegalStateException {
556: setAttribute("title", title, true);
557: }
558:
559: /**
560: * Set the template to use to render the ComboBox items. Used to customize dispaly of ComboBox items.
561: * <br/><br/>
562: * For example the template below uses the fields 'url' and 'text' from the Store's RecordDef.
563: * <br/><br/>
564: * setTpl(new Template("<div class=\"x-combo-list-item\">" +
565: * "<em>{url}</em><strong>{text}</strong>" +
566: * "<div class=\"x-clear\"></div></div>"));
567: *
568: * @param template template to use for rendering items.
569: * @see Store
570: * @see com.gwtext.client.data.RecordDef
571: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
572: */
573: public void setTpl(Template template) throws IllegalStateException {
574: String html = template.getHtml();
575: setTpl(html);
576: }
577:
578: /**
579: * Set the template to use to render the ComboBox items. Used to customize dispaly of ComboBox items.
580: * <br/><br/>
581: * For example the template below uses the fields 'url' and 'text' from the Store's RecordDef.
582: * <br/><br/>
583: * setTpl(new Template("<div class=\"x-combo-list-item\">" +
584: * "<em>{url}</em><strong>{text}</strong>" +
585: * "<div class=\"x-clear\"></div></div>"));
586: *
587: * @param template template to use for rendering items.
588: * @see Store
589: * @see com.gwtext.client.data.RecordDef
590: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
591: */
592: public void setTpl(String template) throws IllegalStateException {
593: if (template.indexOf("<tpl") == -1) {
594: template = "<tpl for=\".\">" + template + "</tpl>";
595: }
596: setAttribute("tpl", template, true);
597: }
598:
599: /**
600: * The action to execute when the trigger field is activated. Use 'all' to run the query specified by the allQuery
601: * config option (defaults to 'query').
602: *
603: * @param triggerAction the trigger action
604: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
605: */
606: public void setTriggerAction(ComboBox.Trigger triggerAction)
607: throws IllegalStateException {
608: setAttribute("triggerAction", triggerAction.getTrigger(), true);
609: }
610:
611: /**
612: * True to populate and autoselect the remainder of the text being typed after a configurable delay (typeAheadDelay)
613: * if it matches a known value (defaults to false).
614: *
615: * @param typeAhead enable type ahead
616: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
617: */
618: public void setTypeAhead(boolean typeAhead)
619: throws IllegalStateException {
620: setAttribute("typeAhead", typeAhead, true);
621: }
622:
623: /**
624: * The length of time in milliseconds to wait until the typeahead text is displayed if typeAhead = true (defaults to 250)
625: *
626: * @param typeAheadDelay typeahead delay in milliseconds
627: * @throws IllegalStateException this property cannot be changed after the Component has been rendered
628: */
629: public void setTypeAheadDelay(int typeAheadDelay)
630: throws IllegalStateException {
631: setAttribute("typeAheadDelay", typeAheadDelay, true);
632: }
633:
634: /**
635: * The underlying data value name to bind to this CombBox (defaults to undefined if mode = 'remote' or 'value' if mode = 'local').
636: * Note: use of a valueField requires the user make a selection in order for a value to be mapped.
637: *
638: * @param valueField the value field
639: */
640: public void setValueField(String valueField) {
641: setAttribute("valueField", valueField, true, true);
642: }
643:
644: /**
645: * When using a name/value combo, if the value passed to setValue is not found in the store, valueNotFoundText
646: * will be displayed as the field text if defined (defaults to undefined).
647: *
648: * @param valueNotFoundText text when value not found
649: */
650: public void setValueNotFoundText(String valueNotFoundText) {
651: setAttribute("valueNotFoundText", valueNotFoundText, true, true);
652: }
653:
654: }
|