Lookup TextField

Purpose

This extension provides a text field with additional lookup functionality. The lookup is achieved by choosing a value from a popup list which is displayed on demand. While typing in the text field, the filter set on the ULCLookupTextField is queried to narrow down the choices in the popup list. Browsing the lookup list and selecting a value can be achieved with mouse or keyboard. The ULCLookupTextField is highly configurable.

ULCLookupTextField

The Lookup List includes the following features:

  • search results are narrowed down while typing
  • choose value from popup list and accept selection by pressing <Enter>
  • accept selection and move to next/previous component by pressing <Tab>/<Shift><Tab>
  • accept selection by double-clicking on popup list item
  • close popup list without accepting selection by pressing <Esc>
  • browse through popup list using <Up>, <Down>, <PgUp>, and <PgDown>
  • double-click on text field to open popup list
  • text input that is not valid is shown in different foreground color
  • configurable icon is displayed to distinguish the widget from a plain text field
  • custom filter strategies can be set
  • widget is backed by a model
  • all attributes can be changed at runtime
  • add listener to be notified about selection changes

How to use

You instantiate, configure, and add an ULCLookupTextField like any other ULC widget, as will be shown in the example below.

The constructor requires the parent window in which the new lookup text field will reside.

ULCLookupTextField field = new ULCLookupTextField(parentWindow);

You define the data available to the data lookup list by implementing the ILookupTextFieldModel and setting it on the ULCLookupTextField. A DefaultLookupTextFieldModel is available which is based on a string array. By default, an empty DefaultLookupTextFieldModel is set on the widget.

field.setModel(new DefaultLookupTextFieldModel(new String[]{"Homer", "Marge", "Bart", "Lisa", "Maggie"}));

On the widget, a string filter must be set which decides for each element of the ILookupTextFieldModel if it matches a given input string. By default, a Perl5RegExpStringFilter is set on the widget.

field.setFilter(new GlobRegExpStringFilter());

Additional aspects of the Look&Feel can be set, like the number of visible rows of the lookup list, the maximum number of rows to select from, and the foreground color to signal invalid user input. If the number of elements that match the filter is higher than the maximum number of rows to select from, these additional elements will not be shown but an ellipsis ('...').

field.setVisibleLookupRowCount(5);
field.setMaxLookupRowCount(12);
field.setErrorForeground(Color.orange);

In order to visually distinguish a ULCTextField from a ULCLookupTextField, each instance of a ULCLookupTextField can be configured with an icon which is displayed at the right border of the widget.

field.setIndicatorIcon(new ULCIcon(DemoLookup.class.getResource("/down.png")));
field.setIndicatorIconGap(3);

How it is implemented

The UILookupTextField class serves as a proxy to the ULCLookupTextField class. UILookupTextField inherits from PatchedUITextField and ULCLookupTextField inherits from ULCTextField. The class PatchedUITextField will be obsolete with the release of ULC 5.2.1.

UILookupTextField listens to events from the underlying JTextField and handles as much event processing as possible on the client side. The server-side is only queried for updating the lookup list data.

Resources