SwingLabs: How to Use the SwingX JXList

A JXList is an extension to the standard Swing JList adding support for background row highlighting, hyperlinked elements, and filtering (coming soon!). A JXList can be used just like a JList, while allowing you to offer your users an extended feature set with no extra coding.

The extended features of JXList are:

Contents of this How-To

Working with a JXList

This section covers how to use a JXList in your code. We start with an overview of using a JXList, then continue by describing each major feature of JXList in turn.

Sample Code

This How-To is based on a single sample program, org.jdesktop.demo.sample.SampleJXListDemo in the SwingLabs-Demos subproject. Code samples shown here are taken from that class.

SampleJXListDemo can be run directly from the command line as long as you have the SwingX distribution jar in your classpath.

Getting Started with a JXList

JXList is a JList subclass, and is instantiated in the same way--you need to provide a ListModel to use it, and wrap it in a JScrollPane.

From SampleJXListDemo:

    private JXList initList() {
        // boilerplate table-setup; this would be the same for a JTable
        SampleListModel model = new SampleListModel();
        JXList list = new JXList(model);
        model.loadData();
        
        list.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
        return list;
    }

We won't show the SampleListModel here--it's just an inner class subclassing DefaultListModel that loads data from a text file. What's important is that we are just using a ListModel (or DefaultListModel), and adding rows and columns just as we would with JList.

Once we've initialized our JXList, we can add it to a JScrollPane and we're ready to use it.

Highlighting Rows

JXList supports a highlighting mechanism which visual properties of rows. With JList, you would need to supply your own renderer to do this; with JXList, you supply one or more Highlighters. A Highlighter implements rules for how a row's visual properties should be changed. This is exactly how JXTable supports highlighting, and in fact, the same code can be used with both JXList and JXTable to set up highlighting.

In the SampleJXListDemo, we ask the HighlighterFactory to create a background striping Highlighter with a pre-defined color.

    jxList.setHighlighters(HighlighterFactory.createSimpleStriping(
       HighlightFactory.CLASSIC_LINE_PRINTER));

An simple striping highlighter changes the color of every other row in the List. The CLASSIC_LINE_PRINTER mimics the color scheme on old printer paper where every other line was colored a light green, to improve legibility.

A JXList can have one or more Highlighters assigned. You can also add and remove Highlighters programmatically using addHighlighter() and removeHighlighter(). When more than one Highlighter is assigned, each one is called in turn to apply its highlighting.

In the SampleJXList demo, we add a second highlighter after the fact.

Rollover

JXList has built-in support for rollover as the mouse passes over the elements. There are a couple of good uses for this--for one, to highlight the elements in the list as the mouse gracefully soars over them, and second, to have hyperlinks change their appearance on rollover (such as adding an underline dynamically).

  // oops .. forgot one
  jxList.addHighlighter(new ColorHighlighter(Color.CYAN, Color.WHITE,
                HighlightPredicate.ROLLOVER_ROW));
  jxList.setRolloverEnabled(true);

A HighlightPredicate is a rule which a Highlighter asks before actually doing the hightlight on every cell painting: only applies the highlight effect if the condition is true. A ROLLOVER_ROW is true if the mouse location is somewhere over the row to paint. JXList has the rollover support disabled by default, so you have to explicitly enable it.

Filtering Rows from Display

As with JXTable, you can remove elements from the JXList using a Filter, without modifying the underlying model. The demo filters for elements starting with "A" and sorts the items in descending order.

        // first need to enable the filtering, it's off by default
        jxList.setFilterEnabled(true);
        jxList.setFilters(new FilterPipeline(new PatternFilter("^A", 0, 0), 
                new ShuttleSorter(0, false)));

Hyperlinked Elements

If you have elements in your list that you want to act as hyperlinks, JXList supports this out of the box.

Links to Demos and Related Documents

TODO: SwingXDemo, other demos? TODO: related classes: JXTreeTable, JXScrollPane^?, Filter^?, Highlighter^?