Java tutorial
/* * Copyright 2008 Google Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not * use this file except in compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations under * the License. */ package com.google.gwt.user.client.ui; import com.google.gwt.dom.client.Document; import com.google.gwt.dom.client.Element; import com.google.gwt.dom.client.OptionElement; import com.google.gwt.dom.client.SelectElement; import com.google.gwt.event.dom.client.ChangeEvent; import com.google.gwt.event.dom.client.ChangeHandler; import com.google.gwt.event.dom.client.HasChangeHandlers; import com.google.gwt.event.shared.HandlerRegistration; import com.google.gwt.i18n.client.HasDirection.Direction; import com.google.gwt.i18n.shared.BidiFormatter; import com.google.gwt.i18n.shared.DirectionEstimator; import com.google.gwt.i18n.shared.HasDirectionEstimator; import com.google.gwt.i18n.shared.WordCountDirectionEstimator; /** * A widget that presents a list of choices to the user, either as a list box or * as a drop-down list. * * <p> * <img class='gallery' src='doc-files/ListBox.png'/> * </p> * * <h3>CSS Style Rules</h3> * <ul class='css'> * <li>.gwt-ListBox { }</li> * </ul> * * <p> * <h3>Example</h3> * {@example com.google.gwt.examples.ListBoxExample} * </p> * * <p> * <h3>Built-in Bidi Text Support</h3> * This widget is capable of automatically adjusting its direction according to * its content. This feature is controlled by {@link #setDirectionEstimator}, * and is off by default. * </p> * * <h3>Use in UiBinder Templates</h3> * <p> * The items of a ListBox element are laid out in <g:item> elements. * Each item contains text that will be added to the list of available * items that will be shown, either in the drop down or list. (Note that * the tags of the item elements are not capitalized. This is meant to * signal that the item is not a runtime object, and so cannot have a * <code>ui:field</code> attribute.) It is also possible to explicitly * specify item's value using value attribute as shown below. * <p> * For example: * * <pre> * <g:ListBox> * <g:item> * first * </g:item> * <g:item value='2'> * second * </g:item> * </g:ListBox> * </pre> * <p> * <h3>Important usage note</h3> * <b>Subclasses should neither read nor write option text directly from the * option elements created by this class, since such text may need to be wrapped * in Unicode bidi formatting characters. They can use the getOptionText and/or * setOptionText methods for this purpose instead.</b> */ @SuppressWarnings("deprecation") public class ListBox extends FocusWidget implements SourcesChangeEvents, HasChangeHandlers, HasName, HasDirectionEstimator { public static final DirectionEstimator DEFAULT_DIRECTION_ESTIMATOR = WordCountDirectionEstimator.get(); private static final String BIDI_ATTR_NAME = "bidiwrapped"; private static final int INSERT_AT_END = -1; /** * Creates a ListBox widget that wraps an existing <select> element. * * This element must already be attached to the document. If the element is * removed from the document, you must call * {@link RootPanel#detachNow(Widget)}. * * @param element the element to be wrapped * @return list box */ public static ListBox wrap(Element element) { // Assert that the element is attached. assert Document.get().getBody().isOrHasChild(element); ListBox listBox = new ListBox(element); // Mark it attached and remember it for cleanup. listBox.onAttach(); RootPanel.detachOnWindowClose(listBox); return listBox; } private DirectionEstimator estimator; /** * Creates an empty list box in single selection mode. */ public ListBox() { this(false); } /** * Creates an empty list box. The preferred way to enable multiple selections * is to use this constructor rather than {@link #setMultipleSelect(boolean)}. * * @param isMultipleSelect specifies if multiple selection is enabled */ public ListBox(boolean isMultipleSelect) { super(Document.get().createSelectElement(isMultipleSelect)); setStyleName("gwt-ListBox"); } /** * This constructor may be used by subclasses to explicitly use an existing * element. This element must be a <select> element. * * @param element the element to be used */ protected ListBox(Element element) { super(element); SelectElement.as(element); } public HandlerRegistration addChangeHandler(ChangeHandler handler) { return addDomHandler(handler, ChangeEvent.getType()); } /** * @deprecated Use {@link #addChangeHandler} instead */ @Deprecated public void addChangeListener(ChangeListener listener) { ListenerWrapper.WrappedChangeListener.add(this, listener); } /** * Adds an item to the list box. This method has the same effect as * * <pre> * addItem(item, item) * </pre> * * @param item the text of the item to be added */ public void addItem(String item) { insertItem(item, INSERT_AT_END); } /** * Adds an item to the list box, specifying its direction. This method has the * same effect as * * <pre> * addItem(item, dir, item) * </pre> * * @param item the text of the item to be added * @param dir the item's direction */ public void addItem(String item, Direction dir) { insertItem(item, dir, INSERT_AT_END); } /** * Adds an item to the list box, specifying an initial value for the item. * * @param item the text of the item to be added * @param value the item's value, to be submitted if it is part of a * {@link FormPanel}; cannot be <code>null</code> */ public void addItem(String item, String value) { insertItem(item, value, INSERT_AT_END); } /** * Adds an item to the list box, specifying its direction and an initial value * for the item. * * @param item the text of the item to be added * @param dir the item's direction * @param value the item's value, to be submitted if it is part of a * {@link FormPanel}; cannot be <code>null</code> */ public void addItem(String item, Direction dir, String value) { insertItem(item, dir, value, INSERT_AT_END); } /** * Removes all items from the list box. */ public void clear() { getSelectElement().clear(); } public DirectionEstimator getDirectionEstimator() { return estimator; } /** * Gets the number of items present in the list box. * * @return the number of items */ public int getItemCount() { return getSelectElement().getOptions().getLength(); } /** * Gets the text associated with the item at the specified index. * * @param index the index of the item whose text is to be retrieved * @return the text associated with the item * @throws IndexOutOfBoundsException if the index is out of range */ public String getItemText(int index) { checkIndex(index); return getOptionText(getSelectElement().getOptions().getItem(index)); } public String getName() { return getSelectElement().getName(); } /** * Gets the currently-selected item. If multiple items are selected, this * method will return the first selected item ({@link #isItemSelected(int)} * can be used to query individual items). * * @return the selected index, or <code>-1</code> if none is selected */ public int getSelectedIndex() { return getSelectElement().getSelectedIndex(); } /** * Gets the value associated with the item at a given index. * * @param index the index of the item to be retrieved * @return the item's associated value * @throws IndexOutOfBoundsException if the index is out of range */ public String getValue(int index) { checkIndex(index); return getSelectElement().getOptions().getItem(index).getValue(); } /** * Gets the number of items that are visible. If only one item is visible, * then the box will be displayed as a drop-down list. * * @return the visible item count */ public int getVisibleItemCount() { return getSelectElement().getSize(); } /** * Inserts an item into the list box. Has the same effect as * * <pre> * insertItem(item, item, index) * </pre> * * @param item the text of the item to be inserted * @param index the index at which to insert it */ public void insertItem(String item, int index) { insertItem(item, item, index); } /** * Inserts an item into the list box, specifying its direction. Has the same * effect as * * <pre> * insertItem(item, dir, item, index) * </pre> * * @param item the text of the item to be inserted * @param dir the item's direction * @param index the index at which to insert it */ public void insertItem(String item, Direction dir, int index) { insertItem(item, dir, item, index); } /** * Inserts an item into the list box, specifying an initial value for the * item. Has the same effect as * * <pre> * insertItem(item, null, value, index) * </pre> * * @param item the text of the item to be inserted * @param value the item's value, to be submitted if it is part of a * {@link FormPanel}. * @param index the index at which to insert it */ public void insertItem(String item, String value, int index) { insertItem(item, null, value, index); } /** * Inserts an item into the list box, specifying its direction and an initial * value for the item. If the index is less than zero, or greater than or * equal to the length of the list, then the item will be appended to the end * of the list. * * @param item the text of the item to be inserted * @param dir the item's direction. If {@code null}, the item is displayed in * the widget's overall direction, or, if a direction estimator has * been set, in the item's estimated direction. * @param value the item's value, to be submitted if it is part of a * {@link FormPanel}. * @param index the index at which to insert it */ public void insertItem(String item, Direction dir, String value, int index) { SelectElement select = getSelectElement(); OptionElement option = Document.get().createOptionElement(); setOptionText(option, item, dir); option.setValue(value); int itemCount = select.getLength(); if (index < 0 || index > itemCount) { index = itemCount; } if (index == itemCount) { select.add(option, null); } else { OptionElement before = select.getOptions().getItem(index); select.add(option, before); } } /** * Determines whether an individual list item is selected. * * @param index the index of the item to be tested * @return <code>true</code> if the item is selected * @throws IndexOutOfBoundsException if the index is out of range */ public boolean isItemSelected(int index) { checkIndex(index); return getSelectElement().getOptions().getItem(index).isSelected(); } /** * Gets whether this list allows multiple selection. * * @return <code>true</code> if multiple selection is allowed */ public boolean isMultipleSelect() { return getSelectElement().isMultiple(); } /** * @deprecated Use the {@link HandlerRegistration#removeHandler} * method on the object returned by {@link #addChangeHandler} instead */ @Deprecated public void removeChangeListener(ChangeListener listener) { ListenerWrapper.WrappedChangeListener.remove(this, listener); } /** * Removes the item at the specified index. * * @param index the index of the item to be removed * @throws IndexOutOfBoundsException if the index is out of range */ public void removeItem(int index) { checkIndex(index); getSelectElement().remove(index); } /** * {@inheritDoc} * See note at * {@link #setDirectionEstimator(com.google.gwt.i18n.shared.DirectionEstimator)}. */ public void setDirectionEstimator(boolean enabled) { setDirectionEstimator(enabled ? DEFAULT_DIRECTION_ESTIMATOR : null); } /** * {@inheritDoc} * Note: this does not affect the direction of already-existing content. */ public void setDirectionEstimator(DirectionEstimator directionEstimator) { estimator = directionEstimator; } /** * Sets whether an individual list item is selected. * * <p> * Note that setting the selection programmatically does <em>not</em> cause * the {@link ChangeHandler#onChange(ChangeEvent)} event to be fired. * </p> * * @param index the index of the item to be selected or unselected * @param selected <code>true</code> to select the item * @throws IndexOutOfBoundsException if the index is out of range */ public void setItemSelected(int index, boolean selected) { checkIndex(index); getSelectElement().getOptions().getItem(index).setSelected(selected); } /** * Sets the text associated with the item at a given index. * * @param index the index of the item to be set * @param text the item's new text * @throws IndexOutOfBoundsException if the index is out of range */ public void setItemText(int index, String text) { setItemText(index, text, null); } /** * Sets the text associated with the item at a given index. * * @param index the index of the item to be set * @param text the item's new text * @param dir the item's direction. * @throws IndexOutOfBoundsException if the index is out of range */ public void setItemText(int index, String text, Direction dir) { checkIndex(index); if (text == null) { throw new NullPointerException("Cannot set an option to have null text"); } setOptionText(getSelectElement().getOptions().getItem(index), text, dir); } /** * Sets whether this list allows multiple selections. <em>NOTE: The preferred * way of enabling multiple selections in a list box is by using the * {@link #ListBox(boolean)} constructor. Using this method can spuriously * fail on Internet Explorer 6.0.</em> * * @param multiple <code>true</code> to allow multiple selections * @deprecated use {@link #ListBox(boolean)} instead */ @Deprecated public void setMultipleSelect(boolean multiple) { getSelectElement().setMultiple(multiple); } public void setName(String name) { getSelectElement().setName(name); } /** * Sets the currently selected index. * * After calling this method, only the specified item in the list will remain * selected. For a ListBox with multiple selection enabled, see * {@link #setItemSelected(int, boolean)} to select multiple items at a time. * * <p> * Note that setting the selected index programmatically does <em>not</em> * cause the {@link ChangeHandler#onChange(ChangeEvent)} event to be fired. * </p> * * @param index the index of the item to be selected */ public void setSelectedIndex(int index) { getSelectElement().setSelectedIndex(index); } /** * Sets the value associated with the item at a given index. This value can be * used for any purpose, but is also what is passed to the server when the * list box is submitted as part of a {@link FormPanel}. * * @param index the index of the item to be set * @param value the item's new value; cannot be <code>null</code> * @throws IndexOutOfBoundsException if the index is out of range */ public void setValue(int index, String value) { checkIndex(index); getSelectElement().getOptions().getItem(index).setValue(value); } /** * Sets the number of items that are visible. If only one item is visible, * then the box will be displayed as a drop-down list. * * @param visibleItems the visible item count */ public void setVisibleItemCount(int visibleItems) { getSelectElement().setSize(visibleItems); } /** * Retrieves the text of an option element. If the text was set by * {@link #setOptionText} and was wrapped with Unicode bidi formatting * characters, also removes those additional formatting characters. * * @param option an option element * @return the element's text */ protected String getOptionText(OptionElement option) { String text = option.getText(); if (option.hasAttribute(BIDI_ATTR_NAME) && text.length() > 1) { text = text.substring(1, text.length() - 1); } return text; } /** * <b>Affected Elements:</b> * <ul> * <li>-item# = the option at the specified index.</li> * </ul> * * @see UIObject#onEnsureDebugId(String) */ @Override protected void onEnsureDebugId(String baseID) { super.onEnsureDebugId(baseID); // Set the id of each option int numItems = getItemCount(); for (int i = 0; i < numItems; i++) { ensureDebugId(getSelectElement().getOptions().getItem(i), baseID, "item" + i); } } /** * Sets the text of an option element. If the direction of the text is * opposite to the page's direction, also wraps it with Unicode bidi * formatting characters to prevent garbling, and indicates that this was done * by setting the option's <code>BIDI_ATTR_NAME</code> custom attribute. * * @param option an option element * @param text text to be set to the element * @param dir the text's direction. If {@code null} and direction estimation * is turned off, direction is ignored. */ protected void setOptionText(OptionElement option, String text, Direction dir) { if (dir == null && estimator != null) { dir = estimator.estimateDirection(text); } if (dir == null) { option.setText(text); option.removeAttribute(BIDI_ATTR_NAME); } else { String formattedText = BidiFormatter.getInstanceForCurrentLocale().unicodeWrapWithKnownDir(dir, text, false /* isHtml */, false /* dirReset */); option.setText(formattedText); if (formattedText.length() > text.length()) { option.setAttribute(BIDI_ATTR_NAME, ""); } else { option.removeAttribute(BIDI_ATTR_NAME); } } } private void checkIndex(int index) { if (index < 0 || index >= getItemCount()) { throw new IndexOutOfBoundsException(); } } private SelectElement getSelectElement() { return getElement().cast(); } }