package org.litesoft.GWT.forms.client.components;

import org.litesoft.GWT.client.widgets.*;

import com.google.gwt.event.dom.client.*;
import com.google.gwt.event.shared.*;
import com.google.gwt.user.client.ui.*;

public interface FormComboBoxFocusWidget extends IFocusWidget
{
    /**
     * Adds a listener interface to receive change events.
     *
     * @param listener the listener interface to add
     */
    @Deprecated
    public void addChangeListener( ChangeListener listener );

    public HandlerRegistration addChangeHandler( ChangeHandler handler );

    /**
     * Gets the number of items present in the list box.
     *
     * @return the number of items
     */
    public int getItemCount();

    /**
     * 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 );

    /**
     * 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 );

    /**
     * Gets the currently-selected item. If multiple items are selected, this
     * method will return the first selected item.
     *
     * @return the selected index, or <code>-1</code> if none is selected
     */
    public int getSelectedIndex();

    /**
     * Sets the currently selected index.
     * <p/>
     * <p/>
     * Note that setting the selected index programmatically does <em>not</em>
     * cause the {@link ChangeListener#onChange(Widget)} event to be fired.
     * </p>
     *
     * @param index the index of the item to be selected
     */
    public void setSelectedIndex( int index );

    /**
     * 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 );
}