Sample Code

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

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

From SampleJXTableDemo:

    private JXTable initTable() {
        // boilerplate table-setup; this would be the same for a JTable
        SampleTableModel model = new SampleTableModel();
        JXTable table = new JXTable(model);
        model.loadData();
        table.setPreferredScrollableViewportSize(new Dimension(500, 70));
        
        table.setSelectionMode(ListSelectionModel.SINGLE_SELECTION);
        return table;
    }

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

The Column Control is available automatically as part of =JXTable=--that is, all you need to do is call

        // All there is to it--users can now select which columns to view
        jxTable.setColumnControlVisible(true);

And it shows up. Apart from showing and hiding columns, users can also change the horizontal scroll policy, and request that columns be resized (packed). Horizontal scrolling and column packing are described below.

        TableColumnExt latitude = jxTable.getColumnExt("LATITUDE");
        latitude.setVisible(false);

This sample code shows a long and a short way to do this. Visibility is a property of a TableColumnExt, a class which extends TableColumn. TableColumn itself doesn't know about visibility, whereas TableColumnExt allows a column to negotiate visibility with its owning table. Although you create a JXTable using a TableModel which contains TableColumns, a JXTable internally uses a TableColumnExt for each column. To get a reference to the TableColumnExt, you can use one of the accessor methods--=getColumnExt(Object identifier)= and getColumnExt(int viewColumnIndex). Once we have the TableColumnExt for a column, we simply use the setVisible(boolean showIt) method to show or hide the column. The Column Control uses this visibility mechanism in the background.

In the SampleJXTableDemo, we use an AlternateRowHighlighter, a subclass of Highlighter with static constant Highlighter instances already configured for the task. The demo uses an AlternateRowHighlighter.classicLinePrinter to do the trick

    jxTable.setHighlighters(new HighlighterPipeline(new Highlighter[]{ AlternateRowHighlighter.classicLinePrinter }));

An AlternateRowHighlighter changes the color of every other row in the table. The classicLinePrinter mimics the color scheme on old printer paper where every other line was colored a light green, to improve legibility.

A JXTable can have one or more Highlighters assigned in a HighlighterPipeline. The 'pipeline' concept is also used for Filters, and for sorting. A HighlighterPipeline is instantiated with an array of Highlighters, but you can also add and remove Highlighters from the HighlighterPipeline programmatically using addHighlighter() and removeHighlighter(). In our example, we use a single Highlighter passed in as an array to the HighlighterPipeline.

In the SampleJXTable demo, we add a second highlighter after the fact--this one tracks mouse movements and highlights the row on rollover:

        // ...oops! we forgot one
        jxTable.getHighlighters().addHighlighter(new RolloverHighlighter(Color.BLACK, Color.WHITE ));
        jxTable.setRolloverEnabled(true);

When more than one Highlighter is in the HighlighterPipeline, each one is called in turn to apply its highlighting. You could add a ConditionalHighlighter on top of the AlternateHighlighter so that, apart from every other row being colored, certain columns that meet conditional criteria are automatically highlighted as well. Of course, you can also write your own Highlighters.

JXTables have column sorting turned on by default. You can disable all column sorting using setSortingEnabled(boolean allowSort). You can also disable sorting on a single column by using setSorterClass(String sorterClassName) with a null sorter class name.

The default sorter used on a column can be overridden by supplying a new Comparator for the sorting algorithm. A good example of this is in the SwingXDemo, where a point (x, y) is sorted on the value of x and y as a Point, and not as a String. In the SimpleJXTableDemo, we create a special sorter for our columns with float values, to have the column sort in proper numeric order.

        Comparator numberComparator = new Comparator() {
            public int compare(Object o1, Object o2) {
                Double d1 = Double.valueOf(o1 == null ? "0" : (String)o1);
                Double d2 = Double.valueOf(o2 == null ? "0" : (String)o2);
                return d1.compareTo(d2);
            }
        };
        // First, the long way to assign--just to show there's a Sorter involved
        Sorter sorter = jxTable.getColumnExt("ELEVATION").getSorter();
        sorter.setComparator(numberComparator);

In the SampleJXTableDemo, we use a filter to only show rows for countries who's names begin with A using a Pattern filter against the country column.

        int col = jxTable.getColumn("COUNTRY").getModelIndex();
        jxTable.setFilters(new FilterPipeline(new Filter[] { new PatternFilter("A.*", 0, col) }));

Filters don't actually remove or delete data from the TableModel; they just hide it (or, in the case of a Sorter, cause row order to appear different than the underlying model). Removing a PatternFilter, for example, will cause all rows that were previously hidden to be displayed.

Packing will have a different effect if horizontal scrolling is enabled. With horizontal scrolling, the JXTable allows the table to scroll off to the right of the viewport, so the resize algorithm doesn't need to try and fit all columns within the more constrained viewport area. If you turn horizontal scrolling on, and pack all columns, you'll see them all get adjusted to their preferred width.

We should mention that the TableColumnExt also allows you to set prototype values. A prototype value for a column is a sample String that indicates the maximum length for a value in that column. Normally, when a column is resized, the JTable has to guess at the widest column value, as in large tables it couldn't actually check all values in the column. With the prototype value, you can hint to the table the size of data that will be in that column, allowing it to resize more accurately for the data set.

Horizontal Scrolling

As described above, normally a JXTable nestled in a JScrollPane will fit all columns within the scroll pane's viewport, possibly causing some of them to resize beneath an optimal width and making them illegible. You can use setHorizontalScrolling(boolean allowHoriz) with a value of true in order for the scroll pane to allow a horizontal scrollbar, with the end result that columns are resized to their preferred width.

<-- This creates the navigation links to :  Home | Help | Index | etc.  -->

SwingLabs: How to Use the SwingX JXTable

A JXTable^? is an extension to the standard Swing JTable adding support for runtime column selection, column rearrangement, background row highlighting, sorting and other features. A JXTable can be used just like a JTable, while allowing you to offer your users an extended feature set with no extra coding.

The extended features of JXTable are:

Contents of this How-To

Working with a JXTable

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

Getting Started with a JXTable

TODO: JXTable is a JTable, so you still need to code a TableModel^? to use it, and wrap it in a JScrollPane^? if there's enough data to scroll on.

The JXTable Column Control

TODO:

Selecting Columns at Runtime

TODO:

Rearranging Columns via Drag and Drop

TODO:

Highlighting Rows

TODO:

Sorting Rows

TODO:

Filtering Rows from Display

TODO:

Resizing Columns

TODO:

Links to Demos and Related Documents

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