Working with Swings JTable – An Example

Introduction

In my previous article Fast random file access and line by line reading in Java I described how I created a random access file class that has a fast readLine() method. The reason for creating that class was, that I was implementing a random access reader for the chemistry file format sdf. Such files are ASCII text files and can contain tens of thousands of records. Each record consists of a variable amount of lines. For fast random access I wanted to index the offset where each record begins. With seek(offset) a requested record can then be accessed very quickly. To index the file it must be read line by line to search for the record separator $$$$. Therefore a fast readLine() method was crucial for performance.

After successfully implementing my reader for the sdf format, called sdf-reader, I wanted to create a GUI on top of it. I called it Free SDF Viewer. Records in sd-files contain a chemical structure and optionally associated data. Therefore sdf format is often used to exchange chemical databases and that’s also why it makes a lot of sense to use a table to visualize sd-files.

Requirements

Before diving in I created a short list of the requirements. sd-files can be huge and hence they should not have to be fully loaded into memory. If the user scrolls down in the table the rows above should not be kept in memory but the scrolling should be smooth meaning that some records should be cached.

The first column should display the chemical structure and that chemical structure must be resizable (height and width). This means that the columns width and the row height must be user adjustable. Because sd-files can contain thousands of records I also wanted to have a row header only containing the row number (1-based).

• Usable with large files
• smooth scrolling
• user adjustable column width
• user adjustable row height
• row header containing the row number (1-based)

I had some additional requirement like a nice and easy to use file chooser but that is not related to working with a JTable. All in all I had the feeling that my list was reasonable and implementation should be easy. But boy, was I wrong. It turned out to be a very bumpy ride.

Accessing the data

My first problem was how to get the data from the file into the JTable. My sdf-reader returns an SdfRecord object that contains all the data. The access is index-based meaning the first record has index 0 and so forth. It turned out to be rather straight forward. A JTable gets the data from a TableModel. The solution is to create a custom TableModel implementation. The most important method of TableModel is getValueAt(int rowIndex, int columnIndex). In this method you define how the data is retrieved. The source can be anything. A naive implementation of this method for my case will look like this:

@Override
public Object getValueAt(int rowIndex, int columnIndex) {

	SdfRecord record = sdfReader.getRecord(rowIndex);

	if (columnIndex == 0) {
		//this column is always the chemical structure
		// display the chemical structure image
		String molfile = record.getMolfile();
		ImageIcon chemicalStructure = new ChemicalStructureIcon(molfile,indigo,renderer,imageWidth, imageHeight);
		return chemicalStructure;
	} else {
		// display data. currently everything is treated as String
		// inlucding numbers and dates
		String columnName = getColumnName(columnIndex);
		String value = record.getProperty(columnName);
		return value;
	}
}

This is naive because the underlying sd-file will be accessed several times for a single row while reading exactly the same data. In my actually implementation I’m caching 100 records around the current position. So if the user scrolls up or down the data will be read from the cache. If the users scrolls far enough some data will be evicted from the cache and new data loaded. This cache logic is omitted for simplicity. For the full source code see the Free SDF Viewers project page.

You might have noticed that in above code I’m creating an instance of ChemicalStructureIcon. I will discuss this in the next chapter.

Displaying the chemical structure

I thought that displaying an image in a JTable cell would be very straightforward and easy. However that was wrong. During my search I found that one should use the ImageIcon class because JTable can render that by default. This is not entirely true. You actually have to specifically tell JTable to render ImageIcon columns as image. This is done by a custom TableCellRenderer.

private class SdfTableCellRenderer extends DefaultTableCellRenderer {

	@Override
	public void setValue(Object value) {
		if (value instanceof ImageIcon) {
			setIcon((ImageIcon) value);
			setText("");
		} else {
			setIcon(null);
			super.setValue(value);
		}
	}
}

Note that I will later show you that I extended JTable to easily initialize all my added features. That is why this is a private inner class.

After being able to see images in table cells I realized that when changing the column width, the image is not automatically adjusted to be smaller or larger. Note that changing column width is supported by default. After another search session I realized that the only solution was to extend ImageIcon and I therefore created ChemicalStructureIcon. ChemicalStructureIcon uses the Indigo Chemistry Toolkit for rendering chemical structures. The most relevant code shown below is the paintIcon(Component c, Graphics g, int x, int y) method which is called when the image is drawn. If the column width changes, the image is re-rendered automatically.

@Override
public synchronized void paintIcon(Component c, Graphics g, int x, int y) {
	Image image = getImage();
	if (image == null) {
		return;
	}
	Insets insets = ((Container) c).getInsets();
	x = insets.left;
	y = insets.top;

	int w = c.getWidth() - x - insets.right;
	int h = c.getHeight() - y - insets.bottom;

	if (w != width || h != height) {
		if (w < 16 || h < 16) {
			// 16 pixels is minimum size supported by indigo
			return;
		}
		width = w;
		height = h;
		indigo.setOption("render-image-size", w, h);
		image = renderImage();
		setImage(image);
	}

	ImageObserver io = getImageObserver();
	g.drawImage(image, x, y, w, h, io == null ? c : io);
}

You can see the complete source code on the projects web page.

Adding a row header

JTable has no concept of a row header. But not all hope is lost because JScrollPane does and a JTable usually is inside a JScrollPane. In my solution I use an extra JTable as a row header. That table has a very simple, custom TableModel.

@Override
public Object getValueAt(int rowIndex, int columnIndex) {
	return rowIndex + 1;
}

Complete source code of RowHeaderModel

To actually use this I extended JTable, added the field headerTable.This row header is initialized in the constructor of this custom JTable implementation.

public SdfTable(JScrollPane scrollPane, SdfReader sdfReader, int rowHeight) {
	super();
	//snipped other initialization code
	headerModel = new RowHeaderModel(getRowCount());
	headerTable = new JTable(headerModel);
	headerTable.setRowHeight(getRowHeight());
	headerTable.setShowGrid(false);
	headerTable.setAutoResizeMode(JTable.AUTO_RESIZE_OFF);
        // 60 -> the width of the row header in px
	headerTable.setPreferredScrollableViewportSize(new Dimension(60, 0));
	headerTable.getColumnModel().getColumn(0).setPreferredWidth(60);
	headerTable.getColumnModel().getColumn(0).setCellRenderer(new RowHeaderCellRenderer());
	// synchronize selection by using the same selection model in both tables
	headerTable.setSelectionModel(this.getSelectionModel());
	scrollPane.setRowHeaderView(headerTable);
	setPreferredScrollableViewportSize(getPreferredSize());
}

There is a lot going on here. Also note that both tables use the same SelectionModel. This means that when the user clicks in the row header, that whole row will be selected and when the user clicks on a row, the row header will be selected too.

When the row height changes, the row header must have the same new height. Therefore my JTable implementation overrides the setRowHeight() methods.

@Override
public void setRowHeight(int rowHeight) {
	super.setRowHeight(rowHeight);
	if (headerTable != null) {
		headerTable.setRowHeight(rowHeight);
	}
}

@Override
public void setRowHeight(int row, int rowHeight) {
	super.setRowHeight(row, rowHeight);
	if (headerTable != null) {
		headerTable.setRowHeight(row, rowHeight);
	}
}

Complete source code of SdfTable

Change row height with mouse

One of the requirements was that the user can adjust the row height. This must be possible for individual rows and all rows at once. First we will look into adjusting a single rows height.

Change height of single row

To listen for mouse input we need to extend MouseInputAdapter. The idea is to show a resize cursor when the mouse it at the boundary of 2 rows.  When the user then presses the left button and drags the mouse, the upper row will be resized relatively to the distance traveled by the mouse. This requires us to use basic math and geometry knowledge.

private int getResizingRow(Point p) {
	return getResizingRow(p, table.rowAtPoint(p));
}

private int getResizingRow(Point p, int row) {
	if (row == -1) {
		return -1;
	}
	int col = table.columnAtPoint(p);
	if (col == -1) {
		return -1;
	}
	Rectangle r = table.getCellRect(row, col, true);
	r.grow(0, -3);
	if (r.contains(p)) {
		return -1;
	}

	int midPoint = r.y + r.height / 2;
	int rowIndex = (p.y < midPoint) ? row - 1 : row;

	return rowIndex;
}

@Override
public void mousePressed(MouseEvent e) {
	Point p = e.getPoint();
	resizingRow = getResizingRow(p);
	mouseYOffset = p.y - table.getRowHeight(resizingRow);
	if (resizingRow >= 0) {
		table.setRowSelectionAllowed(false);
		table.setAutoscrolls(false);
	}
}

The math is one thing, more problematic was that dragging the mouse could lead to weird behavior on screen with the 2 affected rows flickering as they are constantly being (de)-selected. Also if you drag the mouse upwards to the table header, the table begins to scroll. For these reasons these features are disabled while the resizing occurs.

The row height is then changed according to the distance covered (up or down, Y-Coordinate in Swing) by the mouse when dragging.

@Override
public void mouseDragged(MouseEvent e) {
	table.clearSelection();
	int mouseY = e.getY();

	if (resizingRow >= 0) {
		int newHeight = mouseY - mouseYOffset;
		if (newHeight > 0) {
			table.setRowHeight(resizingRow, newHeight);
		}
	}
}

Complete source code of TableRowResizer

Change row height for all rows

This could be solved easily with a prompt / input were the user types in a number. However that is not user friendly at all. The idea is that if the mouse is at the edge of the top row and the table header, a resize cursor should be shown and if the mouse is pressed and dragged, all rows height will be changed. This sounds identical to above solution, however it is not. The table header is an instance of JTableHeader. It has a different cursor than JTable. So depending on mouse location either the tables or the table headers cursor must be changed into a resize cursor.

private boolean isResizingHeader(MouseEvent e) {
	Point p = e.getPoint();

	Object source = e.getSource();
	JTableHeader header = table.getTableHeader();

	if (source instanceof JTableHeader) {

		int col = table.columnAtPoint(p);
		if (col == -1) {
			return false;
		}

		return ((header.getY() + header.getHeight()) - 5) < p.y;

	} else if (source instanceof JTable) {

		int topRow = getTopRow();
		int row = table.rowAtPoint(p);

		if (row == topRow) {
			int col = table.columnAtPoint(p);
			if (col == -1) {
				return false;
			}
			Rectangle r = table.getCellRect(row, col, true);
			r.grow(0, -5);
			return r.y > p.y;
		}
	}	
	return false;
}

and for changing the cursor

@Override
public void mouseMoved(MouseEvent e) {
	if (e.getSource() instanceof JTable) {
		if (isResizingHeader(e)
				!= (table.getCursor() == resizeCursor)) {
			swapTableCursor();
		}
	} else if (e.getSource() instanceof JTableHeader) {
		if (isResizingHeader(e)
				!= (table.getTableHeader().getCursor() == resizeCursor)) {
			swapHeaderCursor();
		}
	}
}

Another issue is when the top row is only partially visible this resizing should work too. Also when changing the row height of all rows, the total height of the table changes dramatically. Without taking precautions this leads to erratic auto scrolling to different records. To prevent that, the current top row is programmatically kept at the top of the viewport.

@Override
public void mouseDragged(MouseEvent e) {
	int mouseY = e.getYOnScreen();
	if (isResizing) {
		int newHeight = table.getRowHeight() + (mouseY - yOffset);
		if (newHeight > 0) {
			yOffset = e.getYOnScreen();
			table.setRowHeight(newHeight);
			JViewport viewport = (JViewport) table.getParent();
			JScrollPane scrollPane = (JScrollPane) viewport.getParent();
			// This rectangle is relative to the table where the
			// northwest corner of cell (0,0) is always (0,0).
			Rectangle rect = table.getCellRect(topRow, 0, true);
			scrollPane.getVerticalScrollBar().setValue(rect.y);
		}
	}
}

This code has one downside, that as soon as the user drags the mouse, the top row will jump down fully into view but else it works very nicely.

See complete source code of AllRowsResizer.

Putting it all together

To put all the features together I extended JTable in my custom class SdfTable. The full constructor for SdfTable can be seen below.

public SdfTable(JScrollPane scrollPane, SdfReader sdfReader, int rowHeight) {
	super();
	DefaultTableCellRenderer r = new SdfTableCellRenderer();
	setDefaultRenderer(Object.class, r);
	TableRowResizer rowResizer = new TableRowResizer(this);
	AllRowsResizer allRowsResizer = new AllRowsResizer(this);

	TableModel tableModel = new SdfTableModel(sdfReader);
	setModel(tableModel);
	super.setRowHeight(rowHeight);
	getColumnModel().getColumn(0).setPreferredWidth(STRUCTURE_COLUMN_WIDTH);

	headerModel = new RowHeaderModel(getRowCount());
	headerTable = new JTable(headerModel);
	headerTable.setRowHeight(getRowHeight());
	headerTable.setShowGrid(false);
	headerTable.setAutoResizeMode(JTable.AUTO_RESIZE_OFF);
	headerTable.setPreferredScrollableViewportSize(new Dimension(60, 0));
	headerTable.getColumnModel().getColumn(0).setPreferredWidth(60);
	headerTable.getColumnModel().getColumn(0).setCellRenderer(new RowHeaderCellRenderer());
	// synchronize selection by using the same selection model in both tables
	headerTable.setSelectionModel(this.getSelectionModel());
	scrollPane.setRowHeaderView(headerTable);
	setPreferredScrollableViewportSize(getPreferredSize());
}

The JScrollPane argument is required for correctly setting the row header.

Complete source code of SdfTable.

Additional Features and Comments

Free SDF Viewer has some additional features not directly related to JTable and there are other issues I encounter that apply to everything in Swing.

Showing a wait cursor when loading sd-file

I created a menu with a single entry “Load SD-files…”. Clicking on it will display a FileChooser and then load and initialize an SdfTable object. This means that the code runs under the so called Event Dispatch Thread (EDT). Changes to UI Elements done in this thread will not become visible until the action completes. This means that if you change the cursor to a wait cursor and then load the sd-file in the EDT, the user will never see the wait cursor. Changing the cursor must be done in a different thread but not just any thread. You are required to use a SwingWorker thread. The take-away message is, that simple things become unexpectedly complex.

First the code executed after clicking on the “Load SD-File…” menu option:

private void loadFileMenuItemActionPerformed(java.awt.event.ActionEvent evt) {

        int returnVal = fileChooser.showOpenDialog(this);
        if (returnVal == JFileChooser.APPROVE_OPTION) {
            File file = fileChooser.getSelectedFile();
            logger.debug("Opening SD-File '{}'.", file.getAbsoluteFile());
            SdfLoader loader = new SdfLoader(this, file);
            loader.execute();
        } else {
            logger.debug("Opening of SD-file cancelled by the user.");
        }
    }

This creates and SdfLoader instance. SdfLoader extends SwingWorker. In the constructor it changes the cursor to a wait cursor, then in the doInBackground()-method the sd-file is loaded and finally in the done()-method the SdfTable is created and the cursor reverted back to its previous state.

private class SdfLoader extends SwingWorker<JTable, Void> {

	private final JFrame frame;
	private final File sdFile;
	private JTable table;
	private IOException ioException;

	public SdfLoader(JFrame frame, File sdFile) {
		this.frame = frame;
		frame.setCursor(Cursor.getPredefinedCursor(Cursor.WAIT_CURSOR));
		this.sdFile = sdFile;
	}

	@Override
	public JTable doInBackground() {
		try {
			//close old file
			if (sdfReader != null) {
				sdfReader.close();
			}
			sdfReader = new SdfReader(sdFile);
			lastOpenDir = sdFile.getParentFile();
			table = new SdfTable(jScrollPane1, sdfReader, 200);
		} catch (IOException ex) {
			logger.catching(ex);
			ioException = ex;
			table = jTable1;
		}
		return table;
	}

	@Override
	public void done() {
		if (ioException == null) {
			jTable1 = table;
			jScrollPane1.setViewportView(table);
			frame.setCursor(Cursor.getDefaultCursor());
		} else {
			JOptionPane.showMessageDialog(SdfViewer.this,
					ioException.getMessage(),
					"Error opening file",
					JOptionPane.ERROR_MESSAGE);
		}
	}
}

Remembering Settings

  One of them is remembering the last directory I sd-files was opened from. This information is written into a properties file and loaded at start-up. Future versions might make additonal use of this to store other settings like rendering options for the chemical structure. I’m mentioning this so that you are not confused by unexplained code in the main class SdfViewer.

Screenshots

First a screenshot showing a row with a different row height.

The second screen shot shows the SdfTableModel in action. The user currently is at row 139045 in a large sd-file and there are no performance issues on a standard laptop.

The full project Free SDF Viewer is available on bitbucket. There is also a download for an executable jar file in the projects downloads section.