JEditList User Manual

WILDCREST ASSOCIATES

Using JEditList as an end user

Popup click is the indication made on a given system to invoke the standard Java popup menu (for example, right mouse button click on Windows and Solaris and command key ("Apple" or "clover" key) and click on the Macintosh).  Popup click on a JEditList brings up the JEditList popup menu which contains most of the JEditList commands.  Each popup menu command also has a keyboard equivalent.  The popup menu and keyboard equivalents may be separately enabled, disabled, changed, reordered, or invoked by different means, allowing creation of different subsets of JEditList functionality and different user interfaces for particular applications (see below).

(NOTE: The use of a popup menu makes JEditList different from the Wildcrest Associates EditList JavaBean, which is a similar component built on AWT List.  JEditList uses a true Swing JPopupMenu, whereas EditList could not use an AWT PopupMenu due to a bug in Windows JDK 1.1.x, which forced us to create a popup dialog window instead.)
 

JEditList commands

There are 15 commands which may be invoked from the popup menu and/or keyboard equivalents (or programmatically).  In addition there are 2 other user interactions: drag reordering which only works with the mouse, and first letter keystroke jump-to which only works from the keyboard.

All commands work on the currently selected list item or items.  Single items are selected by clicking on them with the mouse.  Clicking on a new  item usually deselects all previously selected item(s), but multiple items can also be selected at the same time.  Typically, holding down the shift key and clicking on a second item selects all the items in between ("single interval selection").  Or holding down the "control" key and clicking allows the user to select multiple disjoint items ("multiple interval selection").  These different selection modes may be specified using the standard JList API's. Select All is also provided as a JEditList command.

(NOTE: Because of the implementation of AWT Lists, the behavior of the Wildcrest Associates EditList component is somewhat different in single vs. multiple selection mode.  However, the improved Swing JList implementation allows JEditList to work uniformly for both single or multiple selection modes.)

There are three main categories of JEditList commands: modification, reordering, and navigation, plus undo/redo.

Modification

• Cut - The selected item or items are copied into the clipboard (replacing any previous clipboard contents) and deleted from the JEditList.  If no items are selected, the clipboard and list are left unchanged.
• Copy - The selected item or items are copied into the clipboard (replacing any previous contents).  If no items are selected, the clipboard is left unchanged.
• Paste - The item or items in the clipboard are inserted as a group in place of the first selected item in the list (or inserted at the top of the list if nothing is selected) and any other selected items are deleted.  After this operation, the pasted items are selected.
• Insert - The item or items in the clipboard are inserted as a group immediately before the first selected item in the list (or at the top of the list if nothing is selected).  After this operation, the inserted items are selected, so that performing "Delete" reverses the operation.  If no items are in the clipboard, an item called "*new item*" is inserted.
• Append - The item or items in the clipboard are inserted as a group after the last item in the list.  After this operation, the appended items are selected, so that performing "Delete" reverses the operation.  If no items are in the clipboard, an item called "*new item*" is appended..
• Delete - The selected item or items are deleted from the list.  As a convenience, the new item that moves into the first deleted item's position is automatically selected.  If the bottom item of the list was single item deleted, the new bottom item is selected (unless the list is empty).  In this way, users may click on an item anywhere in the list and repeatedly hit Delete to delete successive adjacent items and eventually the entire list.
• Edit - A vertical edit bar is placed at the end of the first selected item.  Any typed characters are inserted at the vertical bar position.  The vertical bar may be moved left or right using the left and right arrow keys.  The "Backspace" key will erase the immediately preceding character.  The "Delete" key will clear all the text in the item.  Hitting "Enter" ends the editing for this item.  Clicking on another item or anywhere outside the JEditList also ends the editing for this item.

• Drag - Click, drag, and release to move items anywhere else in the list.  List is constantly updated as the item is dragged.  When the drag operation is finished, the dragged item remains selected.  Regardless of whether multiple items were originally selected, the single item clicked at the start of the drag is the item that is dragged.  (NOTE: For the Wildcrest Associates EditList, drag is disabled in multiple selection mode, whereas with JEditList drag is always enabled and works fine).
• Sort down - The list is sorted alphabetically in descending order (A...Z top to bottom).  Sort is case-insensitive.
• Sort up - The list is sorted alphabetically in ascending order (Z...A top to bottom).  Sort is case-insensitive

• Select All - All the items in the list are selected.
• Page Down - The view of the list is scrolled down by one "page" (visible group of items).  The last, perhaps partially visible, item becomes the new top item.
• Page Up - The view of the list is scrolled up by one ""page" (visible groups of items).  The first, perhaps partially visible, item becomes the new bottom item.
• Top - The list is scrolled to the top.
• Bottom - The list is scrolled to the bottom.
• Keystroke Jump-to - Each time a key is pressed on the keyboard, the list scrolls to the next item starting with that letter and the resulting item is selected. Typing the same letter repeatedly will jump to each successive item beginning with that letter, wrapping around to the top of the list when the bottom is reached. Keystroke jump-to is case insensitive.

• Undo/Redo - Any of the JEditList commands that change the list can be undone by invoking "Undo"  The commands that can be undone are specifically the10 commands in the Modification and Reordering sections above, but not the 6 Navigation commands or ordinary selection or scrolling operations, as none of these actually change the list.  Invoking "Undo" again invokes a "Redo" of the undone operation, alternating undo/redo thereafter.  Each instance of JEditList has its own undo/redo buffer, so every JEditList can undo and redo its own most recent operation.

There are 5 commands that work with the clipboard: Cut, Copy, Paste, Insert, and Append.  On any Cut or Copy command, JEditList copies the selected item or items into both a local JEditList clipboard and to the system clipboard.  If no intervening Cut or Copy is performed, then a subsequent Paste, Insert, or Append to the same or another JEditList will take its data from the local JEditList clipboard.  This means that full Objects (not just strings) will cut and paste within and between JEditLists in the same applet or application.  This is useful if, for example, you implement list item Objects containing both an icon and a string and using a custom ListCellRenderer to display them (see section below on "Using Objects and custom ListCellRenderers in JEditList")

As of JDK 1.1, Java can only cut and paste plain text strings to and from the system clipboard.  Therefore, any cut and paste operations outside of JEditList instances in a given applet or application will be converted to plain text strings (for detailed rules governing cut and paste operations involving JEditLists with Object items see "Clipboard interactions for JEditLists with Object items" below)

In Java applications and in applets run by the JDK appletviewer, the system clipboard works fine and you can cut and paste text items between JEditList and any other text in any other Java or non-Java application.  However, in Java applets running in browsers such as Netscape Communicator or Microsoft Internet Explorer, the system clipboard is by default not accessible from unsigned Java applets, which are for security reasons restricted to the browser "sandbox".  As a result, in these contexts you cannot cut and paste outside the JEditList components of a single applet.  The first such attempted operation results in an exception being thrown, which is caught by JEditList, and thereafter only the local JEditList clipboard is used.  Communicator and Internet Explorer may be specially configured to allow unsigned applets or signed applets access outside the sandbox.  In this way, depending upon the particular system and security settings, system clipboard operations may be enabled for Java applets, allowing JEditList to cut and paste text to other components, applets, and applications without these limitations..
 
 

Using JEditList as a JavaBean

When you bring up the property list for JEditList (left), you will be able to see and edit all the property values supported by JEditList. The properties may be set as desired, with values as defined in the JEditList Javadoc documentation and in the documentation for the standard Swing JList component which JEditList extends.

All the JEditList properties are bound properties.  You may use your visual programming environment to do property-to-property binding in either direction between and among JEditList components and your other beans.  None of the JEditList properties are constrained properties since JEditList 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.

JEditList is fully serializable.  After any of their properties are customized,  instances of JEditList beans can be saved along with any other beans to which they may be wired.  When reloaded, the JEditList 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 JEditList bean.  In particular, all the commands that appear in the popup menu and have keyboard equivalents are implemented as public methods (see "Customizing JEditList" below) and may be used as targets of any other actionPerformed or stateChanged events, such as buttons, menus, checkboxes, textfields, etc.
 
 
 
 

Using JEditList as a class

JEditList may also be used programmatically as a simple class. JEditList is distributed in the package com.wildcrest.jeditlist (because of the many inner classes in the implementation of JEditList, an additional level of package, "jeditlist", is used to group these files).  A com folder containing a wildcrest subfolder which contains an jeditlist subfolder has inside it JEditList.class and all its associated classes.  Either the com folder should be placed somewhere in your classpath or you should include JEditList.jar which contains the same classes in your classpath (see Installation instructions).

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

The easiest way to create a JEditList is with its zero-argument constructor:
  JEditList();

Complete, simple example

The following is a simple but complete Java applet that uses JEditList (inside a JScrollPane, as is the usual practice):

  import javax.swing.*;
  import com.wildcrest.jeditlist.JEditList;

  public class JEditListTest extends JApplet {
    public void init() {
      setSize(300,400);
      JScrollPane scrollPane = new JScrollPane();
      scrollPane.setSize(150,200);
      getContentPane().add(scrollPane);
      JEditList list = new JEditList();
      String[] items = {"Item 1","Item 2","Item 3","Item 4","Item 5","Item 6"};
      list.setListData(items);
      scrollPane.getViewport().add(list);
    }
  }
 

Customizing JEditList

JEditList has a large list of features, not all of which are desired in all applications.  For example, you may want a list that users can reorder (for example, to indicate a ranking) but not be allowed to remove, add, or edit items.  Or you may wish to have a list only for accumulating new items, or a list from which items may removed but not otherwise changed.  Or you may wish to have different keyboard equivalents or your own popup menu with a subset of the commands in a different order or using different words.  Or you may wish to replace or augment the popup menu and keyboard equivalents with menu items or buttons of your own.  Or you may simply want a standard non-editable JList but prefer the improved scrolling and jump-to navigational features of JEditList.

To facilitate these kinds of customization, JEditList has four boolean properties and corresponding "set" and "is" methods (see JEditList Javadoc documentation) for enabling/disabling and reading the different JEditList capabilities (NOTE: These methods do not function in the Free Version of JEditList and all four properties are always true)..  The four boolean properties are:

popupMenuEnabled -  specifies whether the popup menu is enabled or disabled
keyboardCommandsEnabled - specifies whether the keyboard equivalents are enabled or disabled
keystrokeJumptoEnabled - specifies whether the keystroke jump-to feature is enabled or disabled
reorderingEnabled - specifies whether the drag reordering feature is enabled or disabled

For example, if all four properties are set to false, JEditList reverts to being a standard Swing JList.

If reorderingEnabled is set to true and the rest are set to false, JEditList becomes a "JReorderingList", i.e., a list whose items can only be rearranged.  Others combinations may be employed as appropriate for your application.

Command-by-command customization is possible because all of the popup menu commands (and their keyboard equivalents) are separately callable.  The public methods corresponding to each of the commands are:

Modification

• Cut -  cutSelectedItems(list);  // (list is the instance of JEditList to be affected)
• Copy - copySelectedItems(list);
• Paste - pasteClipboardItems(list);
• Insert - insertClipboardItems(list);
• Append - appendClipboardItems(list);
• Delete - deleteSelectedItems(list);
• Edit - beginEditing(list);

also:  finishEditing(list);   // terminate editing operation (automatic when "Enter" is pressed)

• Drag - Not a popup menu or keyboard equivalent command, is separately enabled (see above)
• Sort down - sortDown(list);
• Sort up - sortUp(list);

• Select All - selectAllItems(list);
• Page Up - scrollPageUp(list);
• Page Down - scrollPageDown(list);
• Top - scrollTop(list);
• Bottom - scrollBottom(list);
• Keystroke Jump-to - Not a popup menu or keyboard equivalent command, is separately enabled (see above)

• Undo/Redo - undoLastChange(list); // restore list to last undoRemember state and swaps undoRemember and redoRemember states

also:      undoRemember(list);   // remembers state of current list contents, selections, and scroll position (use just before last command)
also:      redoRemember(list);   // remembers state of current list contents, selections, and scroll position (use just after last command)

  // 1) create your JEditList
  JEditList list = new JEditList();

  // 2) turn off all default popup menu items and keyboard equivalents
  list.setPopupMenuEnabled(false);         // not available in Free Version
  list.setKeyboardCommandsEnabled(false);  // not available in Free Version

  // 3) if you want keyboard equivalents, set up your own keyboard handler
  list.addKeyListener(new YourKeyHandler(list));

  // and have YourKeyHandler contain code like:
  if (e.getKeyCode()==KeyEvent.VK_X && e.isControlDown()) cutSelectedItems(list);

  // 4) if you want your own JPopupMenu, create your JPopupMenu and for each popup JMenuItem include:
  popupItem5.addActionListener(new YourPopupActionHandler(list));

  // then set up YourPopupMouseHandler and have it show() the popup on right click
  list.addMouseListener(new YourPopupMouseHandler(list, popup));

  // and have YourPopupActionHandler contain code like:
  if (e.getActionCommand().equals("Cut")) cutSelectedItems(list);
 

To facilitate your customization of JEditList, we include for your use the complete code for JEditList's default popup menu creation, popup menu processing, and keyboard equivalent processing  (only provided with the Product Version, not the Free Version, of JEditList).
 

setLightWeightPopupEnabled
isLightWeightPopupEnabled

These two methods are provided to allow you to control the lightWeightPopupEnabled flag for the JEditList popup menu.  This flag defaults to true in Swing and provides for optimal speed if you use nothing but lightweight Swing components.  But if you intermix Swing components and heavyweight AWT components, the popup menu may overlap some of your heavyweight components or backgrounds and not display properly.  In this case setting the lightWeightPopupEnabled flag to false will fix this but with a cost in performance.  An excellent discussion of the issues involved in intermixing lightweight and heavyweight components is available at the Sun Java site.
 

setListItems
getListItems

As a convenience to developers, JEditList supports two methods for setting and getting JEditList items if they are simple Strings.  The setListItems method takes a single String argument which represents the desired list items concatenated together into one long String separated by line separators (e.g. "\n").  Similarly, getListItems returns a String with the current list items represented in this way.  The two methods are used to implement a new listItems property in JEditList.  The standard JList supports no property for letting you specify list items in a visual development environment or bean tool.  However, with JEditList when you click on its listItems property, it will bring up a custom JEditListItemsPropertyEditor.  In this property editor window, you can enter or edit your (string-only) list items, one per line, which become the list items in your JEditList.
 

Using Objects and custom ListCellRenderers in JEditList

The use of JEditList for lists containing Strings is straightforward and involves no special code on your part.  Swing also permits JLists, and therefore JEditLists, to contain arbitrary Object list items with a custom ListCellRenderer to display them, for example, a JLabel containing an icon and a text string such as shown on the left.   However, because of the JEditList commands that involve reading and writing list items, you need to meet a few special requirements so that your list item Object class can fully support all JEditList functionality.

Even if you do nothing special in your JEditList, the following commands will work fine and fully preserve list item Objects:
        Delete, Reorder, Select All, Page Up, Page Down, Top, and Bottom.
In particular, note that you can reorder JEditLists containing arbitrary Object list items with no extra work on your part.

Some JEditList commands need to be able to read a String that represents each list item Object.  These commands are:
        Sort Up, Sort Down, and Keystroke Jump-To..
The String is needed to determine alphabetical order for the sorting commands and the starting letters for the keystroke jump-to command.  To specify the String, in the class where you define your list item Objects you need to implement a specific method:
    String getItemString(Object obj).

JEditList will find your getItemString method via the Java Core Reflection (Introspection) APIs.  JEditList will then call getItemString  for each of your list item Objects and use the returned String values in the sorting and jump-to operations.  For example, if your list item Objects are JLabel's containing an icon and a string, your getItemString method should return the string portion of the JLabel.

If you do not implement a getItemString method, after JEditList fails to find it using Introspection, it will instead call toString() for each list item Object.  The toString method is already defined in Java for the String class and all the wrapper classes for raw types such as Integer, Long, Float, Double, etc., producing the String equivalent of the value you would expect.   The toString method is also defined for all other Java classes and ultimately Object itself.  In some cases toString produces the String you might want but in most cases it provides an object identifier such as the class name and paramString information, which is probably not what you want.  Implementing getItemString allows you to specify the desired user-readable string.

The remaining JEditList commands require getItemString plus two additional capabilities: 1) the ability to write the String portion of your list item Objects and 2) the ability to clone (copy) your list item Objects.  The JEditList commands requiring these capabilities are:
        Cut, Copy, Paste, Insert, Append, and Edit.
To support these commands, you need to implement getItemString plus two more methods in your list item Object class:
      void setItemString(Object obj, String str).
 and
     Object cloneItem(Object obj).

The setItemString method takes as arguments your list item Object and desired String, and your implementation needs to set the String value for the Object to the String provided.  For example, it would set the text string portion of a JLabel icon + string pair.  JEditList will look for setItemString by Introspection, and if it fails to find it, it will simply assign the String provided directly into the Object.  For a simple String this produces the right result, but for other Objects you generally need to implement setItemString to get what you want.

The cloneItem method takes your list item Object as an argument, and expects you to create and return a new, separate copy of the Object with the same values.  When you cut a list item and paste it multiple times, new list item Objects need to be created for each paste operation (not copies of references to the original Object).  Typically your cloneItem method will call the appropriate constructor for your list item Object class and copy the input Object values.  JEditList will look for your cloneItem method by Introspection, and if it fails to find it, it will create a new String containing the result of toString for your list item Object.  For a simple String this produces the right result, but for other Objects you generally need to implement cloneItem to get what you want.

To facilitate your use of Objects and custom ListCellRenderers in your JEditList, we provide the complete code for a JEditList with custom list item Object and ListCellRenderer classes.  In this example, the custom list item Objects are JLabels containing an icon and text string, the most common non-String case.  This code includes a MyListItem class for the list items Objects themselves, including the needed getItemString, setItemString, and cloneItem methods, plus a custom MyListCellRenderer class.
 

Clipboard interactions for JEditLists with Object items

Since you may have multiple JEditList components with list items that are Objects of the same or different types, in the same or different programs, as well as non-JEditList components, JEditList implements all the following clipboard interaction rules to provide maximum possible interoperability and preservation of clipboard information.  The primary need for these rules is because of the fact that in Java JDK 1.1, only String transfers are supported through the system clipboard.

If you cut and paste from a JEditList with Object list items...

...to a JEditList, same program, same Object type or empty...
            => clone and transfer source list Objects

...to a non-empty JEditList, same program, different Object types...
            => clone first item in destination list, getItemString from source list, setItemString in destination list

...to a non-JEditList or a different program...
            => transfer String obtained from getItemString
 

If you cut and paste from a non-JEditList or a different program...

...to a non-empty JEditList with Object list items...
            => clone first item in destination list, transfer String using setItemString

...to an empty JEditList with Object list items...
            => transfer String as a new String