Difference between revisions of "RAP/Incubator/DropDown"

Revision as of 07:36, 30 August 2013

The DropDown incubator project aims to provide a simple and efficient text input assist for RAP, also known as "type ahead", "auto suggest", "auto complete" or "field assist" in various frameworks. The current git master is only compatible to RAP master, but there is also a RAP 2.1 compatible branch that has the same features and API. P2 repositories for both versions can be found here.

The DropDown Widget

The org.eclipse.rap.addons.dropdown.DropDown widget can be found in the org.eclipse.rap.addons.dropdown bundle and is basically a free-floating List (including setItems and Selection event support) that can be attached to a Text widget or any other control. When made visible (DropDown.show()), the DropDown will be placed below the widget. It will hide automatically if the parent (Text) looses focus, ESC is pressed or an item in the DropDown is clicked. While it is visible (and the parent is focused), the selection can be changed using the "Up" and "Down" keys. This is the full extend of its functionality.

AutoSuggest

The org.eclipse.rap.addons.autosuggest.AutoSuggest component aims to provide a complete solution for text input assistance. It wraps the DropDown widget and requires only the Text widget and a data source to work properly. It can be found in the org.eclipse.rap.addons.autosuggest bundle, which has a dependency to the RAP/ClientScripting project if you use the RAP 2.1 version. (It has no special dependencies in RAP 2.2+ since these RAP versions already include ClientScripting.)

DataSource

A minimal setup of a AutoSuggest requires an instance of DataSource, which in turn requires a DataProvider.

Example:

   Text text = new Text( parent, SWT.BORDER );
   DataSource dataSource = new DataSource();
   dataSource.setDataProvider( new ArrayDataProvider( "text1", "text2", "text3" ) );
   AutoSuggest autoSuggest = new AutoSuggest( text );
   autoSuggest.setDataSource( dataSource );

The AutoSuggest will be disposed automatically with the Text widget. Please be aware that currently (as of August 2013) DataSources live on the client as long as the session does. Equal DataSources should therefore be re-used instead of re-created to not waste client memory.

Templates

Unless set up differently, the suggestions that are presented to the user are simple strings that are identical to the string that will be inserted when a suggestion is selected. To allow different forms of presentation a template can be set on the data source. Currently the only available template is ColumnTemplate, which allows prestenting the suggestions as table with multiple columns. When using ColumnTemplate a matching data provider needs to be implemented, ColumnDataProvider. This provider allows defining a column text for each suggestion (getTexts), as well as the text that is actually inserted (getValue).

Example:

   Text text = new Text( parent, SWT.BORDER );
   DataSource dataSource = new DataSource();
   dataSource.setTemplate( new ColumnTemplate( 50, 150, 150 ) ); // the column widths
   ColumnDataProvider dataProvider = new ColumnDataProvider() {
     public Iterable<?> getSuggestions() {
       return Arrays.asList( someArray ); // for example an array of string arrays (String[][])
     }
     public String getValue( Object element ) {
       String[] value = ( String[] )element;
       return value[ 0 ];
     }
     public String[] getTexts( Object element ) {
       String[] value = ( String[] )element;
       return new String[] { value[ 0 ], value[ 2 ], value[ 3 ] };
     }
   } );
   dataSource.setDataProvider( dataProvider );
   AutoSuggest autoSuggest = new AutoSuggest( text );
   autoSuggest.setDataSource( dataSource );