org.eclipse.rap.rwt.widgets

## Class DropDown

- java.lang.Object
- - org.eclipse.swt.widgets.Widget
  - - org.eclipse.rap.rwt.widgets.DropDown

All Implemented Interfaces:
  Adaptable

    public class DropDown
    extends Widget

Instances of this class represent a list of items that are attached to a control (parent). If made visible (`setVisibility(true)`), the list appears attached to the control. The user can select an item from the list using the arrows keys and Enter, or the mouse. The list disappears automatically if the control looses focus, if an item is clicked, or if the escape key is pressed. This class supports the `RWT.MARKUP_ENABLED` property the same way Table and Tree do.

Events:
  DefaultSelection, Selection

IMPORTANT: This class is not intended to be subclassed.

Since:
  2.3

### Constructor Summary

Constructors
Constructor and Description
`DropDown(Control parent)` Constructs a new instance of this class given its parent.
`DropDown(Control parent, int style)` Constructs a new instance of this class given its parent and a style value describing its behavior.

### Method Summary

Methods
`void` `addListener(int eventType, Listener listener)` Adds the listener to the collection of listeners who will be notified when an event of the given type occurs.
`void` `dispose()` Disposes of the operating system resources associated with the receiver and all its descendents.
`<T> T` `getAdapter(java.lang.Class<T> adapter)` Implementation of the `Adaptable` interface.
`java.lang.String[]` `getItems()` Returns a (possibly empty) array of `String`s which are the items in the receiver.
`Control` `getParent()` Returns the receiver's parent, which must be a `Control`.
`int` `getSelectionIndex()` Returns the zero-relative index of the item which is currently selected in the receiver, or -1 if no item is selected.
`boolean` `getVisible()` Returns `true` if the receiver is visible, and `false` otherwise.
`int` `getVisibleItemCount()` Gets the number of items that are visible in the receiver's list.
`void` `removeListener(int eventType, Listener listener)` Removes the listener from the collection of listeners who will be notified when an event of the given type occurs.
`void` `setData(java.lang.String key, java.lang.Object value)` Sets the application defined property of the receiver with the specified name to the given value.
`void` `setItems(java.lang.String[] items)` Sets the receiver's items to be the given array of items.
`void` `setSelectionIndex(int selection)` Selects the item at the given zero-relative index in the receiver.
`void` `setVisible(boolean visible)` Marks the receiver as visible if the argument is `true`, and marks it invisible otherwise.
`void` `setVisibleItemCount(int itemCount)` Sets the maximum number of items that are visible in the receiver's list.

### Methods inherited from class org.eclipse.swt.widgets.Widget

`addDisposeListener, checkSubclass, checkWidget, getData, getData, getDisplay, getListeners, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, reskin, setData, toString`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### DropDown

    public DropDown(Control parent,
            int style)

Constructs a new instance of this class given its parent and a style value describing its behavior.

Parameters:
  `parent` - a control, usually `Text`, which will be the parent of the new instance (cannot be null)
  `style` - the style of widget to construct
Throws:
  `java.lang.IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the parent is null
  `SWTException` -
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
  - ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
Since:
  3.2
See Also:
  `Text`, `Widget.checkSubclass()`

#### DropDown

    public DropDown(Control parent)

Constructs a new instance of this class given its parent.

Parameters:
  `parent` - a control, usually `Text`, which will be the parent of the new instance (cannot be null)
Throws:
  `java.lang.IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the parent is null
  `SWTException` -
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
  - ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
See Also:
  `Text`, `Widget.checkSubclass()`

### Method Detail

#### setItems

    public void setItems(java.lang.String[] items)

Sets the receiver's items to be the given array of items.

Parameters:
  `items` - the array of items
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
  `java.lang.IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the items array is null
  - ERROR_INVALID_ARGUMENT - if an item in the items array is null

#### getItems

    public java.lang.String[] getItems()

Returns a (possibly empty) array of `String`s which are the items in the receiver.

Note: This is not the actual structure used by the receiver to maintain its list of items, so modifying the array will not affect the receiver.

Returns:
  the items in the receiver's list
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

#### setSelectionIndex

    public void setSelectionIndex(int selection)

Selects the item at the given zero-relative index in the receiver. If the item at the index was already selected, it remains selected. Indices that are out of range are ignored.

Parameters:
  `selection` - the index of the item to select
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

#### getSelectionIndex

    public int getSelectionIndex()

Returns the zero-relative index of the item which is currently selected in the receiver, or -1 if no item is selected.

Returns:
  the index of the selected item or -1
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

#### setVisibleItemCount

    public void setVisibleItemCount(int itemCount)

Sets the maximum number of items that are visible in the receiver's list.

Parameters:
  `itemCount` - the new number of items to be visible (default is 5)
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

#### getVisibleItemCount

    public int getVisibleItemCount()

Gets the number of items that are visible in the receiver's list.

Returns:
  the number of items that are visible
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

#### setVisible

    public void setVisible(boolean visible)

Marks the receiver as visible if the argument is `true`, and marks it invisible otherwise.

Parameters:
  `visible` - the new visibility state
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

#### getVisible

    public boolean getVisible()

Returns `true` if the receiver is visible, and `false` otherwise.

The initial value is false.

Returns:
  the receiver's visibility state
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

#### getParent

    public Control getParent()

Returns the receiver's parent, which must be a `Control`.

Returns:
  the receiver's parent
Throws:
  `SWTException` -
  - ERROR_WIDGET_DISPOSED - if the receiver has been disposed
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

#### dispose

    public void dispose()

Description copied from class: `Widget`
Disposes of the operating system resources associated with the receiver and all its descendents. After this method has been invoked, the receiver and all descendents will answer `true` when sent the message `isDisposed()`. Any internal connections between the widgets in the tree will have been removed to facilitate garbage collection.

NOTE: This method is not called recursively on the descendents of the receiver. This means that, widget implementers can not detect when a widget is being disposed of by re-implementing this method, but should instead listen for the `Dispose` event.

Overrides:
  `dispose` in class `Widget`
See Also:
  `Widget.addDisposeListener(org.eclipse.swt.events.DisposeListener)`, `Widget.removeDisposeListener(org.eclipse.swt.events.DisposeListener)`, `Widget.checkWidget()`

#### setData

    public void setData(java.lang.String key,
               java.lang.Object value)

Description copied from class: `Widget`
Sets the application defined property of the receiver with the specified name to the given value.

Applications may associate arbitrary objects with the receiver in this fashion. If the objects stored in the properties need to be notified when the widget is disposed of, it is the application's responsibility to hook the Dispose event on the widget and do so.

Overrides:
  `setData` in class `Widget`
Parameters:
  `key` - the name of the property
  `value` - the new value for the property
See Also:
  `Widget.getData(String)`

#### addListener

    public void addListener(int eventType,
                   Listener listener)

Description copied from class: `Widget`
Adds the listener to the collection of listeners who will be notified when an event of the given type occurs. When the event does occur in the widget, the listener is notified by sending it the `handleEvent()` message. The event type is one of the event constants defined in class `SWT`.

Overrides:
  `addListener` in class `Widget`
Parameters:
  `eventType` - the type of event to listen for
  `listener` - the listener which should be notified when the event occurs
See Also:
  `Listener`, `SWT`, `Widget.removeListener(int, org.eclipse.swt.widgets.Listener)`, `Widget.notifyListeners(int, org.eclipse.swt.widgets.Event)`

#### removeListener

    public void removeListener(int eventType,
                      Listener listener)

Description copied from class: `Widget`
Removes the listener from the collection of listeners who will be notified when an event of the given type occurs.

IMPORTANT: This method is not part of the SWT public API. It is marked public only so that it can be shared within the packages provided by SWT. It should never be referenced from application code.

Overrides:
  `removeListener` in class `Widget`
Parameters:
  `eventType` - the type of event to listen for
  `listener` - the listener which should no longer be notified
See Also:
  `Listener`, `Widget.addListener(int, org.eclipse.swt.widgets.Listener)`

#### getAdapter

    public <T> T getAdapter(java.lang.Class<T> adapter)

Description copied from class: `Widget`
Implementation of the `Adaptable` interface.

IMPORTANT: This method is not part of the RWT public API. It is marked public only so that it can be shared within the packages provided by RWT. It should never be accessed from application code.

Specified by:
  `getAdapter` in interface `Adaptable`
Overrides:
  `getAdapter` in class `Widget`
Parameters:
  `adapter` - the lookup class
Returns:
  an object that can be cast to the given class or `null` if there is no adapter associated with the given class.

Copyright (c) EclipseSource and others 2002, 2018. All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0