ListBox


1   /*
2    * Copyright 2007 Google Inc.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5    * use this file except in compliance with the License. You may obtain a copy of
6    * the License at
7    * 
8    * http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations under
14   * the License.
15   */
16  package com.google.gwt.user.client.ui;
17  
18  import com.google.gwt.user.client.DOM;
19  import com.google.gwt.user.client.Element;
20  import com.google.gwt.user.client.Event;
21  
22  /**
23   * A widget that presents a list of choices to the user, either as a list box or
24   * as a drop-down list.
25   * 
26   * <p>
27   * <img class='gallery' SRC='ListBox.png'/>
28   * </p>
29   * 
30   * <h3>CSS Style Rules</h3>
31   * <ul class='css'>
32   * <li>.gwt-ListBox { }</li>
33   * </ul>
34   * 
35   * <p>
36   * <h3>Example</h3>
37   * {@example com.google.gwt.examples.ListBoxExample}
38   * </p>
39   */
40  public class ListBox extends FocusWidget implements SourcesChangeEvents,
41      HasName {
42  
43    private static final int INSERT_AT_END = -1;
44    private ChangeListenerCollection changeListeners;
45  
46    /**
47     * Creates an empty list box in single selection mode.
48     */
49    public ListBox() {
50      this(false);
51    }
52  
53    /**
54     * Creates an empty list box. The preferred way to enable multiple selections
55     * is to use this constructor rather than {@link #setMultipleSelect(boolean)}.
56     * 
57     * @param isMultipleSelect specifies if multiple selection is enabled
58     */
59    public ListBox(boolean isMultipleSelect) {
60      super(DOM.createSelect(isMultipleSelect));
61      sinkEvents(Event.ONCHANGE);
62      setStyleName("gwt-ListBox");
63    }
64  
65    public void addChangeListener(ChangeListener listener) {
66      if (changeListeners == null) {
67        changeListeners = new ChangeListenerCollection();
68      }
69      changeListeners.add(listener);
70    }
71  
72    /**
73     * Adds an item to the list box. This method has the same effect as
74     * 
75     * <pre>
76     * addItem(item, item)
77     * </pre>
78     * 
79     * @param item the text of the item to be added
80     */
81    public void addItem(String   item) {
82      insertItem(item, INSERT_AT_END);
83    }
84  
85    /**
86     * Adds an item to the list box, specifying an initial value for the item.
87     * 
88     * @param item the text of the item to be added
89     * @param value the item's value, to be submitted if it is part of a
90     *          {@link FormPanel}; cannot be <code>null</code>
91     */
92    public void addItem(String   item, String   value) {
93      insertItem(item, value, INSERT_AT_END);
94    }
95  
96    /**
97     * Removes all items from the list box.
98     */
99    public void clear() {
100     Element h = getElement();
101     while (DOM.getChildCount(h) > 0) {
102       DOM.removeChild(h, DOM.getChild(h, 0));
103     }
104   }
105 
106   /**
107    * Gets the number of items present in the list box.
108    * 
109    * @return the number of items
110    */
111   public int getItemCount() {
112     return DOM.getChildCount(getElement());
113   }
114 
115   /**
116    * Gets the text associated with the item at the specified index.
117    * 
118    * @param index the index of the item whose text is to be retrieved
119    * @return the text associated with the item
120    */
121   public String   getItemText(int index) {
122     Element child = DOM.getChild(getElement(), index);
123     return DOM.getInnerText(child);
124   }
125 
126   public String   getName() {
127     return DOM.getElementProperty(getElement(), "name");
128   }
129 
130   /**
131    * Gets the currently-selected item. If multiple items are selected, this
132    * method will return the first selected item ({@link #isItemSelected(int)}
133    * can be used to query individual items).
134    * 
135    * @return the selected index, or <code>-1</code> if none is selected
136    */
137   public int getSelectedIndex() {
138     return DOM.getElementPropertyInt(getElement(), "selectedIndex");
139   }
140 
141   /**
142    * Gets the value associated with the item at a given index.
143    * 
144    * @param index the index of the item to be retrieved
145    * @return the item's associated value
146    * @throws IndexOutOfBoundsException if the index is out of range
147    */
148   public String   getValue(int index) {
149     checkIndex(index);
150 
151     Element option = DOM.getChild(getElement(), index);
152     return DOM.getElementProperty(option, "value");
153   }
154 
155   /**
156    * Gets the number of items that are visible. If only one item is visible,
157    * then the box will be displayed as a drop-down list.
158    * 
159    * @return the visible item count
160    */
161   public int getVisibleItemCount() {
162     return DOM.getElementPropertyInt(getElement(), "size");
163   }
164 
165   /**
166    * Inserts an item into the list box. Has the same effect as
167    * 
168    * <pre>
169    * insertItem(item, item, index)
170    * </pre>
171    * 
172    * @param item the text of the item to be inserted
173    * @param index the index at which to insert it
174    */
175   public void insertItem(String   item, int index) {
176     insertItem(item, item, index);
177   }
178 
179   /**
180    * Inserts an item into the list box, specifying an initial value for the
181    * item.
182    * 
183    * @param item the text of the item to be inserted
184    * @param value the item's value, to be submitted if it is part of a
185    *          {@link FormPanel}.
186    * @param index the index at which to insert it
187    */
188   public void insertItem(String   item, String   value, int index) {
189     DOM.insertListItem(getElement(), item, value, index);
190   }
191 
192   /**
193    * Determines whether an individual list item is selected.
194    * 
195    * @param index the index of the item to be tested
196    * @return <code>true</code> if the item is selected
197    */
198   public boolean isItemSelected(int index) {
199     checkIndex(index);
200 
201     Element option = DOM.getChild(getElement(), index);
202     return DOM.getElementPropertyBoolean(option, "selected");
203   }
204 
205   /**
206    * Gets whether this list allows multiple selection.
207    * 
208    * @return <code>true</code> if multiple selection is allowed
209    */
210   public boolean isMultipleSelect() {
211     return DOM.getElementPropertyBoolean(getElement(), "multiple");
212   }
213 
214   public void onBrowserEvent(Event event) {
215     if (DOM.eventGetType(event) == Event.ONCHANGE) {
216       if (changeListeners != null) {
217         changeListeners.fireChange(this);
218       }
219     } else {
220       super.onBrowserEvent(event);
221     }
222   }
223 
224   public void removeChangeListener(ChangeListener listener) {
225     if (changeListeners != null) {
226       changeListeners.remove(listener);
227     }
228   }
229 
230   /**
231    * Removes the item at the specified index.
232    * 
233    * @param index the index of the item to be removed
234    */
235   public void removeItem(int index) {
236     Element child = DOM.getChild(getElement(), index);
237     DOM.removeChild(getElement(), child);
238   }
239 
240   /**
241    * Sets whether an individual list item is selected.
242    * 
243    * <p>
244    * Note that setting the selection programmatically does <em>not</em> cause
245    * the {@link ChangeListener#onChange(Widget)} event to be fired.
246    * </p>
247    * 
248    * @param index the index of the item to be selected or unselected
249    * @param selected <code>true</code> to select the item
250    */
251   public void setItemSelected(int index, boolean selected) {
252     checkIndex(index);
253 
254     Element option = DOM.getChild(getElement(), index);
255     DOM.setElementPropertyBoolean(option, "selected", selected);
256   }
257 
258   /**
259    * Sets the text associated with the item at a given index.
260    * 
261    * @param index the index of the item to be set
262    * @param text the item's new text
263    * @throws IndexOutOfBoundsException if the index is out of range
264    */
265   public void setItemText(int index, String   text) {
266     checkIndex(index);
267     if (text == null) {
268       throw new NullPointerException  ("Cannot set an option to have null text");
269     }
270     DOM.setOptionText(getElement(), text, index);
271   }
272 
273   /**
274    * Sets whether this list allows multiple selections. <em>NOTE: The preferred
275    * way of enabling multiple selections in a list box is by using the
276    * {@link #ListBox(boolean)} constructor. Using this method can spuriously
277    * fail on Internet Explorer 6.0.</em>
278    * 
279    * @param multiple <code>true</code> to allow multiple selections
280    */
281   public void setMultipleSelect(boolean multiple) {
282     // TODO: we can remove the above doc admonition once we address issue 1007
283     DOM.setElementPropertyBoolean(getElement(), "multiple", multiple);
284   }
285 
286   public void setName(String   name) {
287     DOM.setElementProperty(getElement(), "name", name);
288   }
289 
290   /**
291    * Sets the currently selected index.
292    * 
293    * <p>
294    * Note that setting the selected index programmatically does <em>not</em>
295    * cause the {@link ChangeListener#onChange(Widget)} event to be fired.
296    * </p>
297    * 
298    * @param index the index of the item to be selected
299    */
300   public void setSelectedIndex(int index) {
301     DOM.setElementPropertyInt(getElement(), "selectedIndex", index);
302   }
303 
304   /**
305    * Sets the value associated with the item at a given index. This value can be
306    * used for any purpose, but is also what is passed to the server when the
307    * list box is submitted as part of a {@link FormPanel}.
308    * 
309    * @param index the index of the item to be set
310    * @param value the item's new value; cannot be <code>null</code>
311    * @throws IndexOutOfBoundsException if the index is out of range
312    */
313   public void setValue(int index, String   value) {
314     checkIndex(index);
315     Element option = DOM.getChild(getElement(), index);
316     DOM.setElementProperty(option, "value", value);
317   }
318 
319   /**
320    * Sets the number of items that are visible. If only one item is visible,
321    * then the box will be displayed as a drop-down list.
322    * 
323    * @param visibleItems the visible item count
324    */
325   public void setVisibleItemCount(int visibleItems) {
326     DOM.setElementPropertyInt(getElement(), "size", visibleItems);
327   }
328 
329   private void checkIndex(int index) {
330     Element elem = getElement();
331     if ((index < 0) || (index >= DOM.getChildCount(elem))) {
332       throw new IndexOutOfBoundsException  ();
333     }
334   }
335 }
336
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags