EditList User Manual

[Main Page] [Sample Applet] [User Manual] [Javadoc Documentation]
[Installation & Compatibility] [License & Contact Information]

EditList is a Java List component which lets users interactively add, remove, replace, and reorder its items. EditList supports all functionality of the standard Java AWT List in addition to these interactive capabilities. EditList can be used by developers as either a JavaBean in visual programming environments or programmatically as a regular Java class.

Using EditList as an end user

EditList preserves the normal behavior of a standard Java AWT List in all respects. In addition, EditList interprets two further gestures, dragging and pop-up click, as invoking additional behavior.

Pop-up click is the indication made on a given system to invoke the standard Java pop-up menu. For example, it is right mouse button click on Windows and Solaris and command key ("Apple" or "clover" key) and click on the Macintosh. Pop-up click on an EditList brings up the EditList edit dialog. A standard Java pop-up menu itself was not used for a number of reasons: 1) in the Windows JDK 1.1.x systems there is a bug that causes pop-up menus attached to peer-based components such as Lists to not display the text of the pop-up menu items, 2) pop-ups are transient and a modeless dialog window is useful because it can remain open, 3) the edit dialog can contain both a text entry field and the command buttons, and 4) the edit dialog can be resized. But the pop-up click gesture was still viewed as the best way to bring up the EditList edit dialog.

The standard Java AWT List on which EditList is based has two fundamental modes: single selection mode and multiple selection mode. EditList has similar but distinct behavior depending on which mode a list is in.

Single selection mode

In single selection mode, only one item can be selected at a time. Clicking on a second item unselects the first item. When a list item is selected, its value is displayed in the EditList edit dialog text field, where it may be edited by the user. The edit dialog buttons operate as follows in single selection mode:

Delete - Hitting Delete removes the selected item from the list. As a convenience, the new item that moves into the deleted item's position is automatically selected. If the bottom item of the list was deleted, the new bottom item is selected (unless the list is empty). In this way, users may click on any item and repeatedly hit Delete to delete multiple adjacent items.
Replace - Hitting Replace replaces the selected item in the list with the current text entered in the text field. This item, now replaced, stays selected.
Insert - Hitting Insert causes the current text in the text field to become a new item added to the list immediately preceding the selected item. The newly inserted item is automatically selected, so that performing Delete reverses the operation.
Append - Hitting Append causes the current text in the text field to become a new item added to the end of the current list. Append was needed since Insert as defined cannot put a new item at the end of the list. The appended item is automatically selected.

Whether or not the EditList edit dialog is open, the user can also Drag list items to reorder them. Click, drag, and release to move single items anywhere in the list. During the drag operation the selected (highlighted) slot is updated automatically. If the mouse is dragged above or below the list, the list is automatically scrolled down or up, respectively. When the drag click is released, the dragged item will vacate the slot where it was initially selected and be moved to the slot highlighted when the drag click is released.

Multiple selection mode

In multiple selection mode, multiple items can be selected at a time. How this is done varies by the underlying system. On Windows it is by clicking on items one at a time, on Macintosh is it by clicking on items while holding down the shift key. Clicking on a selected item a second time unselects that item. When a single list item is selected, its value is displayed in the EditList edit dialog text field. If two or more items are selected, the first selected item in the list appears in the edit dialog texts field followed by "....." to indicate that multiple selections are present. The edit dialog buttons then operate as follows in multiple selection mode:

Delete - Hitting Delete removes all the selected item from the list. Unlike single selection mode, no items are selected following this operation.
Replace - Hitting Replace replaces each of the selected items in the list with the current text entered in the text field. All these items, now replaced, stay selected.
Insert - Hitting Insert causes the current text in the text field to become a set of new items added to the list immediately preceding each of the selected items. All of these new items are automatically selected, so that performing Delete reverses the operation.
Append - Hitting Append causes the current text in the text field to become a new item added to the end of the current list. The appended item is automatically selected and any previously selected items are deselected.

Drag is disabled in multiple selection mode. The JDK 1.1.x implementation of List does not permit a workable implementation of drag when multiple section mode is on. In particular, there is no API in the standard Java AWT List that reports on what item the drag click was started or on what item the drag click was released. In single selection mode, these can be inferred from the single highlighted item at the start and at the end of the drag. In multiple selection mode it is possible to infer the item clicked when drag begins by comparing getSelectedIndexes() before and after the initial click. But on some platforms, notably Windows, the underlying system provides an outline highlight of the drag destination, but it is not reported as a selected item and there is no other API for obtaining this information. Attempts can be made to infer this position from the mouse Y position and keeping track of the makeVisible() calls used to scroll the list while dragging. But since the user can separately control the list scroll bar and there is no API for finding out what is the currently visible scroll position of the list, this approach ultimately doesn't work. Platforms like the Macintosh that use shift-click to perform multiple selection could be made to work, since dragging itself still works like single selection mode drag. But even if multiple drag was possible, it would be necessary to define whether multiple items drag as a group with the same spacing or whether they became adjacent, neither of which is completely intuitive for users. For all these reasons, EditList does not support drag when in multiple selection mode.

Developers who which to permit both reordering and multiple selections are advised to switch the list into single selection mode to permit drag of individual items and back to multiple selection mode to permit multiple selections, either by use of a hot key or other mode indication (see comments in the "Sample Applet" section on subtle issues associated with switching from multiple selection mode to single selection mode).

Using EditList as a JavaBean

After EditList.jar is properly installed (see "Installation & Compatibility" section), you will see the EditList bean in the component palette of your visual programming environment. Click on the EditList bean and drop it on your work area. You will see an empty box indicating the EditList component.

When you bring up the property list for EditList (left), you will be able to see and edit all the property values supported by EditList. In particular, clicking on the "ListItems" field brings up a separate scrolling items property editor, into which you can type (or paste) text for your list items, one per line. The other properties may be set as desired, with values as defined in the EditList Javadoc documentation and in the documentation for the standard Java AWT List component from which EditList inherits.

All the EditList properties are bound properties. You may use your visual programming environment to do property-to-property binding in either direction between and among EditLists and your other beans. None of the EditList properties are constrained properties since EditList computes no properties of its own and presumes values will be constrained where they originate. This frees you from having to place try...catch blocks around set calls in regular programming.

EditList is fully serializable. After customizing any of their properties (including the list items), instances of EditList beans can be saved along with any other beans to which they may be wired. When reloaded, the EditList beans will each come back with their customized values.

You can perform event wiring from an actionPerformed event such as a button push to the EditList bean. EditList has no special action methods beyond the methods inherited from List, which include the standard ItemEvent when items are selected or deselected and ActionEvent on double click of items or hitting the return key.

Using EditList as a class

EditList may also be used programmatically as a simple class. EditList is distributed in the package com.wildcrest.EditList (because of the many inner classes in the implementation of EditList, it was decided to introduce an additional level of packaging to group these files). A com folder containing a wildcrest subfolder which contains an EditList subfolder has inside it EditList.class and 8 other associated classes beginning with the name EditList. These should be placed somewhere in your classpath (see Installation instructions).

You may find it useful to begin your program with:
import com.wildcrest.EditList.EditList;
or alternatively
import com.wildcrest.EditList.*;
or you may make calls to EditList with the full package name:
com.wildcrest.EditList.EditList();

EditList can be instantiated with a zero-argument constructor:
EditList();

This creates a EditList object and initializes all its property values to their defaults (shown in the property list above). You can then use:

add("Item");

to add items to your list.

EditList also has the other constructors of a regular Java AWT List:

EditList(numberRows);
to create a EditList with the given number of visible items, and:
EditList(numberRows, multipleMode);
where multipleMode is an boolean stating whether multiple selection mode is on or off.

The standard Java AWT List supports a getItems() method returning String[], a String array containing the items. EditList supports this method and introduces two new methods of its own:
setListItems(String string);
and
String getListItems();
These allow you to set and get the items of the list as one long string, containing all the items in order separated by \n (line separator) characters. Having this set and get pair allows the EditList items to show up in bean composition property sheets. EditList supports a custom property editor for the ListItems property which provides a text area in which you can view and enter your list items as simple strings one per line.

EditList also supports an EditingEnabled property with set and get methods. editingEnabled is a boolean defining whether the edit dialog and its operations (delete, replace, insert, append) are enabled. Setting this to false prevents users from changing items in the list but still permits reordering of the list (if you want to disallow both, just use the standard Java AWT List).

EditList supports an editDialogModal property with set and get methods. editDialogModal is a boolean defining whether the edit dialog is modal, i.e., remains on top and processes all input actions until dismissed by the user (see "Sample Applet" and "Installation & Compatibility" sections for some of the issues associated with modal dialogs in different environments such as browsers).

Finally, EditList supports an editDialogTitle property with set and get methods. editDialogTitle is a String defining the text in the edit dialog title bar, which is useful for identifying the list or otherwise directing the user. In the Free Version of EditList, this property is set to the string "EditList 1.0 Evaluation Only" and the setEditDialogTitle method is disabled.

The rest of the methods of EditList are as inherited from the standard Java AWT List.

The following is a simple but complete Java applet that uses EditList:

import java.applet.Applet;
import java.awt.*;
import com.wildcrest.EditList.EditList;

public class EditListTest extends Applet {
    public void init() {
       EditList editList = new EditList(4); // 4 visible items
       editList.add("Item 1");
       editList.add("Item 2");
       editList.add("Item 3");
       editList.add("Item 4");
       editList.add("Item 5");
       editList.add("Item 6");
    }
}