Jide grids developer_guide

JIDE Grids Developer Guide
PURPOSE OF THIS DOCUMENT
Welcome to the JIDE Grids, the JTable extension product in JIDE Software’s product line.
This document is for developers who want to develop applications using JIDE Grids .
WHAT IS JIDE GRIDS
Believe it or not, JTable is probably one of the most commonly used Swing components in most
Swing applications.
Many people complained about the design of JTable. Every design has its pros and cons - so
does JTable. People have so many various kinds of requirements, so it’s really hard to design such a
complex component as JTable satisfying everybody’s needs. In our opinion, it’s not the design of
JTable is not good but it left out many important features that a table should have. Good news is
JTable does leave many extension points so that you can enhance it to meet your needs. So as long as
we keep improving it, it will get better and better - JIDE Grids is one step toward this goal. All
components in JIDE Grids are related to JTable and are fully compatible with JTable.
PACKAGES
The table below lists the packages in the JIDE Grids product.
Packages Description
com.jidesoft.grid All the JTable related components are in this package,
including PropertyTable, SortableTable, CellSpanTable,
CellStyleTable, TreeTable, HierarchicalTable,
SortableTableModel, and FilterableTableModel etc.
com.jidesoft.converter Converters that can convert from String to Object and from
Object to String.
com.jidesoft.comparator1 Comparators
com.jidesoft.combobox Several ComboBox-like components such as DateComboBox
and ColorComboBox, as well as classes needed to create your
own ComboBox.
com.jidesoft.list SortableListModel, FilterableListModel and other classes
related to JList
com.jidesoft.tree SortableTreeModel, FilterableTreeModel and other classes
related to JTree
1 This package is moved to jide-common.jar as other products also need comparators.

COPYRIGHT © 2002-2005 JIDE SOFTWARE. ALL RIGHTS RESERVED
2
CLASS HIERARCHY OF ALL THE TABLES
Before we discuss each table component in detail, it’d be better to give you an overview of them.
See below for a class hierarchy of all the table components we have in JIDE Grids.
Figure 1 Class Hierarchy of Tables in JIDE Grids
As you can see, JideTable extends directly JTable since JideTable provides the features that are
suppose to be in JTable. Those features include nested table column header, cell validation support,
automatic changing row height.
ContextSensitiveTable provides way to configure different cell renderers and cell editors for each
cell. Then it comes to CellStyleTable and CellSpanTable which provide two commonly used features as
the names indicated. Next is CategorizedTable. We will not cover this table at all in this developer
guide. The reason is we are not ready to expose it as public API yet. Simply speaking, it provides
access to the expand/collapse icon since both tree table and hierarchical table need it.
After CategorizedTable, it’s SortableTable.
Till now, it’s still one line of hierarchy. After SortableTable, it divides into two types of distinct
tables. Each of them has its own special usage. One is TreeTable. PropertyTable is actually a special use
case of TreeTable. The other one is HierarchicalTable.
Generically speaking, you should make you table extending one of the last four tables
(SortableTable, HierarchicalTable, TreeTable, or PropertyTable) in the class hierarchy tree. However nothing
prevents you from using any other tables as long as you know exactly what features each table
provides.

3
CONVERTER
Before we introduce the PropertyTable, we have to cover some basic modules that the PropertyTable
based on (actually it’s not just for PropertyTable, it can be used in other places as well).
The beauty of PropertyTable is that it can use a String to represent any object type. So in this little
grid area, a lot of information can be shown. In some cases, it’s possible to convert a String to an
Object and vice-versa (however there are also some cases where there is no way to convert). To
begin, let’s explore the cases that convert a String to/from an Object.
Below is the interface of ObjectConverter. All converters should implement this interface.
public interface ObjectConverter {
/**
* Converts from object to String based on current locale.
* @param object object to be converted
* @return the String
*/
abstract String toString(Object object, ConverterContext context);
/**
* If it supports toString method.
* @return true if supports toString
*/
abstract boolean supportToString(Object object, ConverterContext context);
/**
* Converts from String to an object.
* @param string the string
* @return the object converted from string
*/
abstract Object fromString(String string, ConverterContext context);
/**
* If it supports fromString.
* @return true if it supports
*/
abstract boolean supportFromString(String string, ConverterContext context);
}
As an example, assume you are dealing with a Rectangle object, specified as (10, 20, 100, 200). If
you represent this Rectangle as the string “10; 20; 100; 200” then 80% of users will probably
understand it as a Rectangle with x equals 10, y equals 20, width equals 100 and height equals 200.
However, what about the other 20%? They might think the rectangle’s top-left corner is at Point(10,
20) and bottom-right corner at Point(100, 200). Despite this, users can generally learn by experience:
as long as you are consistent across your application, users will get used to it.

4
The situation is more complicated in the case of Color. If we consider the string “0, 100, 200” -
if people understand the RGB view of Color then 90% of them will treat as 0 as red, 100 as blue and
200 as green. However, since Color can also be represented in HSL color space (Hue, Saturation, and
Lightness), some people may consider it as hue equal 0, saturation equals 100 and lightness equals
200. What this means is that, based on your user background, you should consider adding more help
information if ambiguity may arise.
We also need to consider internationalization, since the string representation of any object may
be different under different locales.
In conclusion, we need a series of converters that convert objects so that we can display them as
string and convert them back from string. However in different applications, different converters are
required.
Although we have already built some converters and will add more over time, it is probably true
that there will never be enough. Therefore, please be prepared to create your own converters
whenever you need one.
The list below shows all the converters that we currently provide.
Figure 2 Existing converters
If you want to add your own converters then you can create one quite easily, by implementing a
class that extends the ObjectConverter interface (i.e. the four methods in this interface). Before you
use it, you must register it with ObjectConverterManager, which maps from a Class to a converter or
several converters. If you want to register several converters for the same object then you can use
ConverterContext to differentiate them.

5
There are two static methods on ObjectConverterManager that are used to register a converter:
void registerConverter(Class, ObjectConverter).
void registerConverter(Class, ObjectConverter, ConverterContext).
To help users adding their own classes that support ConverterContex, we provide an interface
called ConverterContextSupport (all of our CellEditor and CellRenders implement this interface).
We didn’t automatically register the existing converters with the ObjectConverterManager. However,
we do provide a method initDefaultConverter() which you can call to register the default converters (as
shown below). In addition to converters, this will register the default CellEditors and CellRenderers
that we have provided. If you wish to make use of this facility then make sure that you call the
initDefaultConverter() method when your application is started.
ObjectConverterManager.initDefaultConverter();
PROPERTY PANE
Background
In an Object Oriented Design, every object is composed of a combination of data and function.
In Java, we sometimes refer to this data as the ‘properties’ of the object. If you follow the JavaBean
pattern then all properties are exposed via getter and setter methods. If an application needs to deal
with an object’s properties then this can be done by displaying the name of each property, along with
its value. This is the purpose of the PropertyPane, which displays this information in table form.
Below are two examples of Property Panes, from NetBeans and JBuilder respectively. Both
graphs show the properties of a JButton. As you can see, the JButton has many properties, such as its
background color, foreground color, font, icon, text etc. As you can see, it’s quite intuitive to display
them in a table like this with the property name on the left side and the corresponding value on the
right side.
Figure 3 NetBeans PropertyPane (Above)

6
Figure 4 JBuilder 9 PropertyPane (Right)
What does a PropertyPane look like?
The picture below shows an example of a property pane, using our PropertyPane class. The
PropertyPane consists of three main parts. The top portion is a toolbar that has buttons which provide
convenient access to some features of the PropertyPane. The middle portion is the PropertyGrid, which
displays the name of each property, along with its value. The bottom portion is the description area,
which can be used to provide a more detailed description of each property.
Since the name of each property is usually very concise, the description area can very helpful
(especially for new users). However, the description area can be hidden when the user becomes
familiar with the properties
Figure 5 JIDE PropertyPane
The PropertyGrid is a two-column table, the first column of which is the name of the property and
the second column is the value of the property. If you wish, you can group sets of properties into
categories, where each category appears as gray bold text, as shown in the example above. You can
collapse categories, which you are not interested in, so that only properties you are interested in will
be shown. You can also have different levels of properties, as shown in the last row in the example
above.
If you have a large number of properties, which makes it hard to find a specific entry, then you
can click on the alphabetic button in the PropertyPane toolbar, so that the properties will be listed in
alphabetic order.

7
Figure 6 PropertyPane (Alphabetic Order)
As a user, how do I use it?
When you click the mouse on the name column, the row will be selected and the value column
will go into editing mode automatically. The type of editor that is displayed may vary depending on
the type of the data that is being edited. There are basically three types of editors.
TextField editor – For very simple types such as name, number etc.
Dropdown Popup – Rather than letting the user type free-format text, this uses a popup to help
the user select the required value. Usually the popup only needs a single selecting action. Examples
include the Color and Date input editor.
Dialog Popup – If the popup needs multiple selection actions then you should consider using a
Dialog Popup rather than a Dropdown Popup. In addition, you should use the Dialog Popup if there
is an existing dialog that you can leverage. Examples include Font, File and Multiple Line
Description.
TextField editor is very simple and so will not be discussed any further.
Below is an example of a Dropdown Popup, for selecting a color, using a combo-box-like editor.
If you click on the drop down button then the popup will be displayed.

8
Figure 7 Dropdown Cell Editor
You can also choose a value without going through the popup. Just type in the value you want in
the text field…
…and then press enter. You can see the value is set as you entered it. You should see that the
converter module has been used here to convert the string “255, 0, 255” into a Color value.
Below is an example of a Dialog Popup. Instead of the down arrow button that is used in a
Dropdown popup, a “…” button is displayed. Clicking on this will cause dialog to appear to help you
select a value.
The example below is a file chooser - clicking on the “…” will cause a FileChooser dialog to
pop up.
Figure 8 Dialog Cell Editor
As a developer, how do I use it?
If you are following the standard object bean pattern then it is quite easy to use the PropertyGrid
control. However, in the real world, not all objects are compliant with the standard bean pattern.
Furthermore, in many cases we find that we are dealing with a property which does not exist as an
attribute of any single object, but which is instead calculated ‘on the fly’, based on the values of a
number of attributes. Based on our experience of dealing with this sort of situation, we created a
class called Property - not surprisingly, it is an abstract class.
Property defines the following methods as abstract, so you need to write your own Property class
that extends Property and implement these three methods:
public abstract void setValue(Object value);
public abstract Object getValue();
public abstract boolean hasValue();

9
Things become much easier once you have created a concrete descendant of the Property class.
Then, all you need to do is to create a list of your Property objects, as an ArrayList and use this
ArrayList to create a PropertyTableModel.
ArrayList list = new ArrayList();
Property property = new ….. // create property
list.add(property);
// add more properties
PropertyTableModel model = new PropertyTableModel(list);
PropertyTable table = new PropertyTable(model);

10
BEANPROPERTY AND BEANINTROSPECTOR
The Property class provides an abstract implementation. If you want to use PropertyTable to display
JavaBean properties, it will be too tedious to create a list of properties manually. To address this
requirement, we introduced a concrete class called BeanProperty. BeanProperty implements Property on
top of PropertyDescriptor which is part of JDK JavaBean implementation.
We introduced another class call BeanIntrospector to help you introspect JavaBean. BeanIntrospector,
will create a list of properties which can be used by PropertyTableModel.
There are four different ways to create a BeanIntrospector.
1. Given an object, if it’s fully JavaBean compatible and there is corresponding BeanInfo class,
you can use BeanIntrospector(Class clazz, BeanInfo beanInfo) to create a BeanIntrospector.
2. If you know exactly the list of property names of the object but you don’t want to create a
BeanInfo, you can use BeanIntrospector(Class clazz, String[] properties) and give introspector
the information of the properties. The array of properties is in the format of
new String[] {
"propertyName1", "propertyDescription1", "propertyCategory1",
"propertyName2", "propertyDescription2", "propertyCategory2",
...
};
So if you have n properties, the array length should be have 3*n. This array will tell
BeanIntrospector what the properties are as well as the description and category which are
both part of Property.
3. In this case, you know exactly the list of property names, just like in case 2. However you
don’t want to hard code the property name into source code. We provide a way to load
the property definition from XML file. The XML file looks like this.
<Properties>
<Property name="…" displayName="…" description="…" category="…"/>
<Property name="…" displayName="…" description="…" category="…"/>
…
</Properties>
Possible attributes for Property element in the XML are "name", "displayName", "value",
"type", "description", "dependingProperties", "category", "converterContext",
"editorContext", "editable", and "autoIntrospect".
The XML file could be at any place where the code can access. However we suggest you
put it at the same package of the object class definition and copy it as resource file to class
output directory so that you can use class loader to load it. There are two constructors for
this case, BeanIntrospector(Class clazz, String fileName) and BeanIntrospector(Class clazz,
InputStream in). The first one used to load property XML as a file. The second one is to
load it using class loader.

11
4. The last case is you want to completely depend on Java reflection to find all properties.
You can use constructor BeanIntrospector(Class clazz) in this case. If using this way, it will
find a lot more properties than you need. Typically you don’t want to use this way.
However it is not a bad idea to use this in development phase to get the complete list of
properties, and then go through each one and determine which ones you want. In
production phase, you should use the first three ways and only show the properties you
want.
For example, if you use reflection to introspect Rectangle.class, you will get 18 properties.
Most of them are useless. See the first picture below. In fact, you just need to have a string
array as below.
public static final String[] RECTANGLE_PROPERTIES = new String[]{
"x", "x", "",
"y", "y", "",
"width", "width", "",
"height", "height", ""
};
And use the second way to create the introspector, and you got the property table like in
the second picture.
After you create the BeanIntrospector, you can further customize it by calling getProperty(String name)
to get the BeanProperty and then call setConverterContext() and setEditorContext() etc.
BeanIntropector has a method called createPropertyTableModel(Object object). It will create a
PropertyTableModel that can be used by PropertyTable.

12
A real example
Now let’s go through a real example to create and configure BeanIntrospector to inspect the
properties of DockableFrame.
First, let’s use constructor BeanIntropector(DockableFrame.class) to create an introspector first, then
call createPropertyTableModel and set the model on PropertyTable. Here is what you will see.
There are more than 140 properties when we tried the first time. It’s too many if we show all of
them so we just take part of them as an example and show it above. After looking through each of
them, we come up with a list of properties we want to expose. Then we create a String array of the
properties we want and use constructor BeanIntrospector(Class clazz, String[] properties) to create an
introspector. See below. As you can see, there are only 22 properties. And they are properly
categorized.

13
It’s much better but there are still a few issues. For example, initMode property is shown as a
regular integer cell. Yes, the type of the property is indeed int.class but the valid values are defined in
DockContext such as hidden, floating, docked or autohidden etc. It will be very unusable if let you
remember the mapping. It’s very easy to solve. All you need is to create an EnumConverter that maps
correctly from int value to a string value as well as corresponding EnumCellRenderer/Editor.
EnumConverter dockModeConverter = new EnumConverter("DockMode-DockableFrame", int.class,
new Object[]{
new Integer(DockContext.STATE_HIDDEN),
new Integer(DockContext.STATE_FLOATING),
new Integer(DockContext.STATE_AUTOHIDE),
new Integer(DockContext.STATE_AUTOHIDE_SHOWING),
new Integer(DockContext.STATE_FRAMEDOCKED)
},
new String[]{
"Hidden",
"Floating",
"Autohidden",
"Autohidden (showing)",
"Docked"},
new Integer(DockContext.STATE_HIDDEN));
ObjectConverterManager.registerConverter(dockModeConverter.getType(), dockModeConverter,
dockModeConverter.getContext());
EnumCellRenderer dockModeRenderer = new EnumCellRenderer(dockModeConverter);
EnumCellEditor dockModeEditor = new EnumCellEditor(dockModeConverter);

14
CellRendererManager.registerRenderer(dockModeConverter.getType(), dockModeRenderer,
dockModeRenderer.getContext());
CellEditorManager.registerEditor(dockModeConverter.getType(), dockModeEditor,
dockModeEditor.getContext());
DOCKABLE_FRAME_INTROSPECTOR.getProperty("InitMode").setConverterContext(dockMode
Converter.getContext());
DOCKABLE_FRAME_INTROSPECTOR.getProperty("InitMode").setEditorContext(dockModeEdi
tor.getContext());
The same thing applies initSide property.
The next thing we noticed is the undockedBounds property. The type is Rectangle.class. Since we have
RectangleConverter, the rectangle value is converted to a semi-colon delimited string. The values are in
the order of x, y, width and height. If user types in that format, it will be converted to rectangle.
However it’s not user-friendly. A better approach is to make undockedBounds expandable so that the
value of x, y, width, height can be modified in child properties. To make it happen, you need to call
the following.
DOCKABLE_FRAME_INTROSPECTOR.getProperty(DockableFra
me.PROPERTY_UNDOCKED_BOUNDS).setAutoIntrospect(true);
After a few customizations, we got the screen shot on your
right. As you can see, initMode and initSide properties are now
combobox. User can choose the meaningful value directly from the
list. The undockedBounds property has child properties so that user
can change the x, y, width or height directly.
We provide many built-in cell editors in JIDE Grids product as
you will see in the following sections. However there is no way we
can cover all your need. When you have a custom data type, you
may need to write your own cell editor/cell renderer/converter in
order to allow user editing that certain type in PropertyTable.

15
CELL EDITORS AND RENDERERS
The CellEditor and CellRenderer interfaces are probably the most interesting aspects of the
JTable framework. By default, a JTable assumes that each column has the same type of value, and
that each data type will use the same type of cell editor. Unfortunately, in the case of PropertyTable,
neither of these assumptions is true. Fortunately however, JTable does allow us to add extensions to
meet our requirements.
In the case of PropertyTable, each row in the value column may have different types of value,
requiring different editors - even when the same underlying data type is being used. In order to
support this requirement we have created two new classes: CellEditorManager and CellRendererManager,
using an approach similar to the ObjectConverterManager.
If we first consider the CellEditorManager, this allows you to register any cell editor with a given
data type, as defined by its class. You can also register a different cell editor to the same type using
different contexts. Different from CellRendererManager, CellEditorManager takes CellEditorFactory to
make sure an unique cell editor is used for each cell editing.
public static void registerEditor(Class clazz, CellEditorFactory editorFactory, EditorContext context)
public static void registerEditor(Class clazz, CellEditorFactory editorFactory)
As an example, the String class is generally associated with a StringCellEditor. However, if the
String is actually a font name then we associate it with a FontNameCellEditor in the context of
FontNameCellEditor.CONTEXT. If you still remember the definition of Property, you will recall that
the Property class has a field called EditorContext. This means that if you set the EditorContext of a
Property to FontNameEditor.CONTEXT then a FontNameCellEditor will be used to edit cells of that
type.
registerEditor(String.class, new CellEditorFactory() {
public CellEditor create() {
return new StringCellEditor();
}
});
registerEditor(String.class, new CellEditorFactory() {
public CellEditor create() {
return new FontNameCellEditor();
}
}, FontNameCellEditor.CONTEXT);
The Renderer framework works in a virtually identical manner to the Editor framework.
Both CellRendererManager and CellEditorManager have a method to initialize default editors or
renderers, called initDefaultRenderer() and initDefaultEditor(), respectively. Please note that these
methods are not called automatically (except in our demo code). This means that if you want to use
our default editors and renderers then you must make sure to initialize them yourself before you can
use the related classes.

16
Here is the code to register default editors and renderers:
CellEditorManager.initDefaultEditor();
CellRendererManager.initDefaultRenderer();
Figure 9 Existing CellEditors and their hierarchy
COLOR RELATED COMPONENTS
ColorChooserPanel
ColorChooserPanel is a panel that has many color buttons that the user can click on to select the
required color. This class supports the ItemListener framework, so that an itemStateChanged event
will be fired whenever a color is selected.
We support several color sets, including the 15 basic RGB colors, 40 basic colors and 215 web
colors.
Figure 10 ColorChooserPanel (15 colors)

17
Figure 11 ColorChooserPanel (40 colors)
Figure 12 ColorChooserPanel (215 web-safe colors)
In additional to color choosers, we also support gray scale - from 16 gray scales, 102 gray scales
and 256 gray scales.
Figure 13 ColorChooserPanel (16 gray scale)
Figure 14 ColorChooserPanel (102 gray scales)
ColorComboBox
Unsurprisingly, the ColorComboBox is a combo box that can choose colors. It uses
ColorChooserPanel as dropdown popup, as shown below:

18
Figure 15 ColorComboBox
Keyboard Support
ColorComboBox and ColorChooserPanel supports keyboard-only environment.
When Popup is
hidden
ALT + DOWN To Bring up the popup
When Popup is visible
ESC Hide the popup without changing the selection
LEFT Previous color to the same row. If at the beginning of a
row, go to last color of previous row
RIGHT Next color to the same row. If at the end of a row, go to
first color of next row.
UP Color at the same column of the previous row
DOWN Color at the same column of the next row
HOME First color
END Last color
ENTER Select the highlighted color and hide popup
DATE RELATED COMPONENT
DateChooserPanel
Similarly to the ColorChooserPanel, the DateChooserPanel is also a popup panel, which allows
the user to choose a Date value (again, providing ItemListener events, as appropriate).

19
Figure 16 DateChooserPanel
Figure 17 DateChooserPanel (Choosing Year)
Figure 18 DateChooserPanel (Choosing Month)
Figure 19 DateChooserPanel (showing week of year panel which is an option)
DateChooserPanel dateChooserPanel = new DateChooserPanel();
dateChooserPanel.setShowWeekNumbers(true)

20
Figure 20 DateChooserPanel (all dates after Aug 13, 2003 are disabled)
// create a DateModel first
DefaultDateModel model = new DefaultDateModel();
// setMaxDate of DateModel to Aug 13, 2003
Calendar calendar = Calendar.getInstance();
calendar.set(Calendar.YEAR, 2003);
calendar.set(Calendar.MONTH, Calendar.AUGUST);
calendar.set(Calendar.DAY_OF_MONTH, 13);
model.setMaxDate(calendar);
// create DateChooserPanel with that model.
DateChooserPanel dateChooserPanel = new DateChooserPanel(model);
Figure 21 DateChooserPanel (any weekends are disabled)
// create a DateModel first
DefaultDateModel model = new DefaultDateModel();
// add DateFilter to allow WEEKDAY_ONLY
model.addDateFilter(DefaultDateModel.WEEKDAY_ONLY);
// create DateChooserPanel with that model.
DateChooserPanel dateChooserPanel = new DateChooserPanel(model);

21
Figure 22 DateChooserPanel (Localized Version de)
There is also a view-only mode DateChooserPanel, as shown
here. In view-only mode, although setDisplayedMonth() can be used
to select which month you want to display, the user will not be able
to change it.
Figure 23 View-only Mode
You can also customize the date label, day of week label, and
the month and year labels to show some special effect. To do so,
simply create a class extending DateChooserPanel, overriding the
appropriate methods to get the visual effect that you want.
To the right is a simple example that makes each cell bigger,
grays the weekends, and shows an icon on the 1st and 15th of
each month.
Figure 24 Customized Label in View-only Mode
The methods you can override are: createDateLabel, updateDateLabel, createDayOfWeekLabel,
updateDayOfWeekLabel, createMonthLabel, updateMonthLabel, createYearLabel and
updateYearLabel. The default create methods will simply create a standard JLabel. Your
implementations can override this behavior to create whatever JComponent you want (not just a
JLabel). The update methods will update the actual value of the labels. Since the date is passed in as
parameter to all update methods, so you can check the date and do whatever you want to the labels.
For example you could look up in a database and find out if there are any historic events on that date
and add a special icon if so (perhaps adding a MouseListener to trigger some other behavior).
DateComboBox
A DateComboBox is a combo box that can choose date, using a DateChooserPanel as a
dropdown popup.

22
Figure 25 DateComboBox
Keyboard Support
DateComboBox and DateChooserPanel supports keyboard-only environment.
When Popup is
hidden
ALT + DOWN To Bring up the popup
When Popup is visible
ESC Hide the popup without changing the selection
LEFT Previous day of the selected day
RIGHT Next day of the selected day
UP Same day of the last week
DOWN Same day of the next week
HOME First day of this month
END Last day of this month
PAGE_UP Same day of the last month
PAGE_DOWN Same day of the next month
CTRL + PAGE_UP Same day of the last year
CTRL +
PAGE_DOWN
Same day of the next year
ENTER Select the highlighted date and hide popup

23
CREATE YOUR OWN COMBOBOX
ComboBox is a very useful component that extends the standard JComboBox to overcome the
restriction that you may only choose a value from a list. As you can see from the previous
discussions, this is not quite good enough. However, with help of AbstractComboBox, you can create
any type of ComboBox you want.
ComboBox has three parts – a text field editor, a button, and popup that appears when the
button is pressed. So the AbstractComboBox will allow you to customize all three parts.
/**
* Subclass should implement this method to create the actual editor component.
* @return the editor component
*/
public abstract EditorComponent createEditorComponent();
/**
* Subclass should implement this method to create the actual popup component.
* @return the popup component
*/
abstract public PopupPanel createPopupComponent();
/**
* Subclass should override this method to create the actual button component.
* If subclass doesn't implement or it returns null, a default button will be created. If type is
DROPDOWN,
* down arrow button will be used. If type is DIALOG, "..." button will be used.
* @return the button component
*/
public AbstractButton createButtonComponent() {
return null;
}
The EditorComponent is the text field editor (actually a JPanel). If you replace this with a JTextField
then it becomes normal JComboBox. Although you can create your own EditorComponent you must
make sure that it extends an EditorComponent and that it implements getValue and setValue (so that
AbstractComboBox knows how to set and get values).
PopupPanel is the base class for a ComboBox popup - in the case of standard JcomboBox this is just
a standard JList. Likewise, in the case of ColorComboBox, it’s a ColorChooserPanel. Usually people use
popup to select things, so the PopupPanel contains common methods for all pop ups, such as
knowing how to select an item and how to fire an item event when the selection changes. Please note
that although PopupPanel is usually used as a DropDown, it can also be used in a dialog (a
FileChooserPanel for example). Note also that you do have the choice of using DROPDOWN and
DIALOG when using AbstractComboBox.
The Button part of ComboBox is used to trigger the popup. By default, if it is a drop down
popup then we use a button with a down arrow. Conversely, if it is a dialog popup then we use a
button with “…” as its value.

24
Based on this, it should be easy to see how simple it is to create any type of ComboBox using the
AbstractComboBox framework. (Note also that ListComboBox is simply our implementation of
JComboBox).
Below shows an example code of a custom ComboBox – StringArrayComboBox.
/**
* <code>StringArrayComboBox</code> is a combobox which
* can be used to choose a String array.
*/
public class StringArrayComboBox extends AbstractComboBox {
public StringArrayComboBox() {
super(DIALOG);
initComponent();
}
public EditorComponent createEditorComponent() {
return new AbstractComboBox.DefaultTextFieldEditorComponent(String[].class);
}
public PopupPanel createPopupComponent() {
return new StringArrayPopupPanel();
}
public void setArray(String[] array) {
setSelectedItem(array);
}
public String[] getArray() {
Object item = getSelectedItem();
if (item == null)
return null;
if (item.getClass().isArray())
return (String[]) item;
return new String[0];
}
}
/**
* A popup panel for String array.
*/
public class StringArrayPopupPanel extends PopupPanel {
JTextArea _textArea = new JTextArea();
public StringArrayPopupPanel() {
JScrollPane scrollPane = new JScrollPane(_textArea);
scrollPane.setVerticalScrollBarPolicy(JScrollPane.VERTICAL_SCROLLBAR_ALWAYS);
scrollPane.setAutoscrolls(true);
scrollPane.setPreferredSize(new Dimension(300, 200));
setBorder(BorderFactory.createEmptyBorder(5, 5, 5, 5));
setLayout(new BorderLayout());
add(scrollPane, BorderLayout.CENTER);

25
setTitle("Choose a String Array");
}
public Object getSelectedObject() {
String text = _textArea.getText();
String[] array = text.split("n");
return array;
}
public void setSelectedObject(Object selected) {
if (selected.getClass().isArray()) {
String[] list = (String[]) selected;
StringBuffer buf = new StringBuffer();
for (int i = 0; i < list.length; i++) {
if (i > 0)
buf.append("n");
buf.append(list[i]);
}
_textArea.setText(buf.toString());
}
}
}
TreeComboBox
In additional to ListComboBox, TreeComboBox is another example of
extending AbstractComboBox to create your own ComboBox. Instead of
using JList to choose an item, TreeComboBox uses JTree.
The usage of TreeComboBox is very intuitive. There are only two
points that worth mentioning.
First, different from JList, not all tree nodes in a tree are valid selection.
In many cases, you only want the leaf node to be selected. So
TreeComboBox allows you to add your own code to determine if a
TreePath is valid selection. All you need to do is to overwrite
isValidSelection(TreePath path). By default, it always returns true, meaning
all tree nodes are valid selections. If you want only leaf node to be
selectable, you can write something like this in subclass.
protected boolean isValidSelection(TreePath path) {
TreeNode treeNode = (TreeNode) path.getLastPathComponent();
return treeNode.isLeaf();
}

26
The second point is the conversion from TreePath to String. You need to provide an algorithm
to convert from the selected TreePath to a string so that the string can be displayed in the text field
of ComboBox. The algorithm is in a method called converElementToString(). Below is the default
implementation of this method in TreeComboBox. You can see it simply uses toString to convert the
tree node to string. Subclass can overwrite this method to do your own conversion. For example, you
can convert the selected path in the screenshot above to “JTree -> sports -> football” if it makes
sense in your application.
protected String convertElementToString(Object object) {
if (object instanceof TreePath) {
Object treeNode = ((TreePath) object).getLastPathComponent();
return treeNode.toString();
}
else if (object != null) {
return object.toString();
}
else {
return "";
}
}
HOW TO CREATE YOUR OWN CELL RENDERER AND EDITOR
In this section, we will use FontNameCellEditor as an example to illustrate how to create your
own cell renderer and cell editor.
First of all, we need to decide what the type of this property is. In the case of font face name, the
type is String. However not all strings are valid font face name. That’s why we need a converter for it.
See below. In fromString() method, we enumerate all available font names in current environment. If
the String is one of the known font names, we return the String. Or else, return null.
public class FontNameConverter implements ObjectConverter {
/**
* ConverterContext for a font name.
*/
public static ConverterContext CONTEXT = new ConverterContext("FontName");
public String toString(Object object, ConverterContext context) {
if (object == null || !(object instanceof String)) {
return null;
}
else {
return (String) object;
}
}
public boolean supportToString(Object object, ConverterContext context) {

27
return true;
}
public Object fromString(String string, ConverterContext context) {
if (string.length() == 0) {
return null;
}
else {
String[] font_names =
GraphicsEnvironment.getLocalGraphicsEnvironment().getAvailableFontFamilyNames();
for (int i = 0; i < font_names.length; i++) { // check font if it is available
String font_name = font_names[i];
if (font_name.equals(string)) {
return string;
}
}
return null;
}
}
public boolean supportFromString(String string, ConverterContext context) {
return true;
}
}
Next, we need to create a cell editor. We use ListComboBoxCellEditor as base class.
/**
* CellEditor for FontFace.
*/
public class FontNameCellEditor extends ListComboBoxCellEditor {
public final static EditorContext CONTEXT = new EditorContext("FontName");
/**
* Creates FontNameCellEditor.
*/
public FontNameCellEditor() {
super(new FontNameComboBoxModel());
}
/**
* Model for the font style drop down.
*/
private static class FontNameComboBoxModel extends AbstractListModel implements
ComboBoxModel {
/** An array of the names of all the available fonts. */

28
private String[] _fontNames = null;
/** The currently selected item. */
private Object _selectedFontName;
/**
* Create a custom data model for a JComboBox.
*/
protected FontNameComboBoxModel() {
_fontNames =
GraphicsEnvironment.getLocalGraphicsEnvironment().getAvailableFontFamilyNames();
}
public void setSelectedItem(Object selection) {
this._selectedFontName = selection;
fireContentsChanged(this, -1, -1);
}
/**
* Chooses a Font from the available list.
* @param font The font to make current
*/
public void setSelectedFont(Font font) {
for (int i = 0; i < _fontNames.length; i++) {
if (font.getFontName().equals(_fontNames[i])) {
setSelectedItem(getElementAt(i));
}
}
fireContentsChanged(this, -1, -1);
}
public Object getSelectedItem() {
return _selectedFontName;
}
public int getSize() {
return _fontNames.length;
}
public Object getElementAt(int index) {
return _fontNames[index];
}
}
}
Please note, in both converter and cell editor, we have a context object. We need them because
the type is String type which has been taken to register StringConverter and StringCellEditor. We will

29
need the context object to register with our own converter and cell editor with
ObjectConverterManager and CellEditorManager. So here is the last thing you need to do.
ObjectConverterManager.registerConverter(String.class, new FontNameConverter(), FontNameConverter.CONTEXT);
CellEditorManager.registerEditor(String.class, new FontNameCellEditor(), FontNameCellEditor.CONTEXT);
To try it out, you just need to create a Property which type is String.class, converter context is
FontNameConverter.CONTEXT and editor context is FontNameCellEditor.CONTEXT. If you add this
property to PropertyTableModel, PropertyTable will automatically use FontNameCellEditor to edit
this Property and use FontNameConverter to validate the font name.
Below is another example of custom CellEditor. It continues from the StringArrayComboBox
example above. Now we will make it a CellEditor.
/**
* A String array cell editor.
*/
public class StringArrayCellEditor extends ContextSensitiveCellEditor implements TableCellEditor {
private StringArrayComboBox _comboBox;
/**
* Creates a FileNameCellEditor.
*/
public StringArrayCellEditor() {
_comboBox = new StringArrayComboBox();
_comboBox.setBorder(BorderFactory.createEmptyBorder());
}
/**
* Gets the value of the cell editor.
*
* @return the value in this cell editor.
*/
public Object getCellEditorValue() {
_comboBox.setSelectedItem(_comboBox.getEditor().getItem());
return _comboBox.getArray();
}
public Component getTableCellEditorComponent(JTable table, Object value,
boolean isSelected,
int row, int column) {
if (table != null) {
JideSwingUtilities.installColorsAndFont(_comboBox, table.getBackground(),
table.getForeground(), table.getFont());
}
_comboBox.setArray((String[]) value);
_comboBox.setConverterContext(getConverterContext());
return _comboBox;
}

30
public boolean stopCellEditing() {
_comboBox.setPopupVisible(false);
return super.stopCellEditing();
}
}
COMPARATOR
Before we introduce SortableTable, we first have to introduce the ObjectComparatorManager. This
works in a similar manner to the ObjectConverterManager which we have already discussed, with the
difference being that ObjectComparatorManager is a central place for managing comparators.
Registration of comparator can be done using the following two methods on
ObjectComparatorManager.
public static void registerComparator(Class clazz, Comparator comparator);
public static void unregisterComparator(Class clazz);
The figure to the right shows the standard comparators that we provide. If an object type
implements Comparable thenyou can use ComparableComparator. If the object can be compared as a
string (based on the value of toString()) then you can use
DefaultComparator. We also provide several comparators for
existing data types such as NumberComparator for any
Number, BooleanComparator for Boolean and
CalendarComparator for Calendars. Alternatively, you can write
your own comparator and register it with ObjectComparatorManager.
SORTABLE TABLE
A SortableTable, as the name indicates, is a table that can sort on each column. Usually a
SortableTable can only sort on one column. However this SortableTable can sort on multiple columns,
as shown below:
Figure 26 SortableTable

31
In a SortableTable, clicking on table column header will sort the column: the first click will sort
ascending; the second click descending; the third click will reset the data to the original order. To sort
on multiple columns, you just press CTRL key and hold while clicking on the other columns. A
number is displayed in the header to indicate the rank amongst the sorted columns. As an example,
in the screen shot above, the table is sorted first by “boolean column”, then by “double column” and
then by “string column”.
SortableTableModel
The core part of SortableTable is not the table itself but the SortableTableModel. This can take any
standard table model and convert to a suitable table model for use by SortableTable. Note that we
wrap up the underlying table model, which means that when you sort a column, the original table
model is unchanged (you can always call getActualModel() to get the actual table model).
As a developer, how do I use it
It’s very easy to use SortableTable in your application. Just create your table model as usual, but
instead of setting the model to JTable, set it to SortableTable. If you have your own JTable class which
extends JTable then you will need to change it to extend SortableTable.
TableModel model = new SampleTableModel();
SortableTable sortableTable = new SortableTable(model);
In the example above, SampleTableModel is just a normal table model. When you pass the model
to SortableTable, SortableTable will create a SortableTableModel internally. This means that when you call
sortableTable.getModel(), it will return you the SortableTableModel, not the SampleTableModel. However if
you call getActualModel() then the SampleTableModel will be returned.
Sometimes, you need to know the actual row since it’s different visually. For example, although
the first row may appear to be selected, since the table could be sorted, this may not be the first row
in the actual table model. Here are the two methods you need to know: getActualRowAt(int row) and
getSortedRowAt(int row). The first one will return you the actual row in the actual table model by
passing the row index on the screen; the second one does the opposite mapping.
There are several options you can use to control SortableTable. For example,
setMultiColumnSortable(Boolean) allows you to enable/disable multiple column sort. Similarly, if
you have better icons for showing the ascending/decending option on the table header, then you can
call setAscendingIcon(ImageIcon) to setDescendingIcon(ImageIcon) to replace the standard icons.
As has already been explained, the user can click the column header to sort a column. In addition
you can call sortColumn() to sort a column programmatically. You can sort either by column index, or
by column name. The interface for sorting on SortableTable is really simple. If you want to sort by
multiple columns programmatically, you will have to use SortableTableModel to do it. This provides
more methods will allow you to sort several columns or even un-sort a sorted column.
The performance of SortableTableModel
We tried to optimize the performance of SortableTableModel. The basic strategy is if the table is
completely unsort, we will sort the whole table model which could be slow if the table is huge. If the
table is sorted already and a new row is added/deleted/updated, we will do incremental sorting. For
example, insert the new row to the correct position directly.

32
As we have no idea of what the data might look like, we have to use a generic sorting algorithm.
In our case, we used shuttle sort. It’s a very fast algorithm comparing to others. However depending
on how large the table model is, it could potentially take a long time on a large table model. In the
actual use cases, user knows very well about the data. So they could develop a sorting algorithm that
is customized to the particular data.
When the table is sorted, a new row is added or deleted or some values are updated in the
underlying table model, we won’t resort the whole table again. We will listen to the table model event
from underlying table model and do incremental sort. Binary search is used by default as the table is
sorted already. In this case, as user of SortableTableModel, you need to fire the exact table model
event to tell SortableTableModel what happened in underlying table model. If you use
DefaultTableModel, all those are done automatically. If you implement your own underlying table
model basing on AbstractTableModel, you need to fire the table model event. You can refer to the
source code of DefaultTableModel to figure out what event to fire. If an incorrect event is fired, the
sorting result will be unpredictable.
Generic speaking, in our testing environment, the performance of SortableTableModel is good
enough. You can try in using LargeSortableTableDemo we included in our examples. However if you
have an even better algorithm or as I said you know your data very well so that you can play some
tricks to make sorting faster, we allow you to do so.
First, you need to extend SortableTableModel. There are three methods you need to know in
order to plug in your own algorithm. They are
protected void sort(int from[], int to[], int low, int high);
protected int search(int[] indexes, int row);
protected int compare(int row1, int row2);
When the table model is completely unsorted, sort() will be used to sort the whole table model.
If the table is sorted already, search() will be called to find out where a new row to be added or an
existing row to be deleted. So method sort can be overwritten if you want to use your own sort
algorithm. Method search can be overwritten if you want o use your own search algorithm.
In either sort() or search(), if you want to compare two rows, using the compare() method.
Usually you don’t need to overwrite it. To make it easier to understand, here is the source code we
used to do the search and sort for your reference.
Search algorithm:
protected int search(int[] indexes, int row) {
return binarySearch(indexes, row);
}
private int binarySearch(int[] indexes, int row) {
// use binary search to find the place to insert
int low = 0;
int high = indexes.length - 1;
int returnRow = high;
boolean found = false;
while (low <= high) {
int mid = (low + high) >> 1;
int result = compare(indexes[mid], row);

33
if (result < 0)
low = mid + 1;
else if (result > 0)
high = mid - 1;
else {
returnRow = mid; // key found
found = true;
break;
}
}
if (!found) {
returnRow = low;
}
return returnRow;
}
Sort algorithm:
protected void sort(int from[], int to[], int low, int high) {
shuttlesort(from, to, low, high);
}
private void shuttlesort(int from[], int to[], int low, int high) {
if (high - low < 2)
return;
int middle = (low + high) / 2;
shuttlesort(to, from, low, middle);
shuttlesort(to, from, middle, high);
int p = low;
int q = middle;
if (high - low >= 4 && compare(from[middle - 1], from[middle]) <= 0) {
for (int i = low; i < high; i++)
to[i] = from[i];
return;
}
for (int i = low; i < high; i++) {
if (q >= high || (p < middle && compare(from[p], from[q]) <= 0))
to[i] = from[p++];
else
to[i] = from[q++];
}
}

34
FILTER AND FILTERABLETABLEMODEL
Table is used to display data. Sometimes users are only interested in some important rows, so
they would like to filter other row away. This is why we need a component which can do filter on
table model.
Filter is an interface which is used to filter data. The main method is isValueFiltered(Object
value). If a value should be filtered, this method should return true. Otherwise, returns false. It also
defined other methods such as setters and getters for name, enabled as well as methods to
add/remove FilterListener. AbstractFilter is the default implement of Filter interface. It implements
most of the methods in Filter except isValueFiltered(). Subclasses should implement this method to do
the right filtering.
There is no class called FilterTable because the standard JTable or any subclass of JTable such as
SortableTable will do the job. There is a FilterableTableModel. It’s also a table model wrapper just like
SortableTableModel. FilterableTableModel allows you to add filter for each column or to the whole table.
It will use those Filter and call isValueFiltered() to decide which value to filter.
Use FilterableTableModel along with SortableTableModel
Both FilterableTableModel and SortableTableModel are table model wrappers. You can wrap
SortableTableModel into FilterableTableModel and get a table model which is both sortable and filterable.
Here is an example of how it works.
TableModel model = new DefaultTableModel();
// … code to populate the model
FilterableTableModel = new FilterableTableModel(new SortableTableModel(model));
SortableTable sortableTable = new SortableTable(filterableTableModel);
First, you create any model. Then you wrapped it into a SortableTableModel, then you wrapped it
again into a FilterableTableModel. At the end, set it as model of a SortableTable and you will get a table is
both sortable and filterable.
Note: Always wrap SortableTableModel into FilterableTableModel but not the other way around. The
reason of that is FilterableTableModel, technically speaking, should fire table row removed event when
a row is filtered. However we currently don’t do that because it will cause too many events. So
instead, we just fire one tableDataChanged event. If you wrap FilterableTableModel into a
SortableTableModel, and since SortableTableModel depends on the precise event to optimize the sorting,
tableDataChanged event will cause a resort of everything. Although it will work, it will be less efficient.

35
SORTABLE/FILTERABLE LIST AND TREE
We just talked about SortableTableModel and FilterableTableModel. In you still remember, both
models are actually table model wrappers. The same technique can be applied to ListModel and
TreeModel as well.
Corresponding to TableModelWrapper, there are ListModelWrapper and TreeModelWrapper.
Each of them has corresponding sortable and filterable implementations. See below.
SortableListModel and SortableTreeModel
Different from SortableTable, there is no SortableList or SortableTree. The reason is
SortableTable doesn’t really do the sorting. It’s the SortableTableModel who does the sorting.
SortableTable just provides a special table header which can accept mouse clicks. It still delegates to
SortableTableModel to sort the data. In the case of JList and JTree, there is no header. In fact, there
is no uniform way on the UI to make JList or JTree sortable. So there is no need for SortableList and
SortableTree. To make JList sortable,
SortableListModel sortableListModel = new SortableListModel(listModel);
JList sortableList = new JList(sortableListModel);
To sort the list, you just call
sortableListModel.sort(); // or sort(SortableListModel.SORT_DESCENDING) to sort descending.
Usually you can hook up this action with a button somewhere near the JList or on a local
toolbar.
It’s exactly the same way to make JTree sortable.
FilterableListModel and FilterableTreeModel
FilterableListModel is a list model wrapper which wraps another list model so that user can apply
filters on it. You can use addFilter(Filter) to a filter to the ListModel. By default, filters won't take
effect immediately. You need to call setFiltersApplied(true) to apply those filters. If filtersApplied

36
flag is true already, you just need to call refresh(). We don't refresh automatically because you might
have several filters to add. You can add all of them, then only call refresh once.
setFiltersApplied(boolean) controls all the filters. Each filter has its own enabled flag which will
control each individual filter.
By default, if you have more than one filters, all filters will be used in AND mode. You can see
javadoc of setAndMode(boolean) to find more information.
Again, FilterableTreeModel works exactly the same way.

37
HIERARCHICAL TABLE
HierarchicalTable is special type of table which can display any components hierarchically inside
the table itself. Talking about hierarchical, tree table can also display hierarchical information. But the
information in tree table is limited to be the same format. In HierarchicalTable, you can display any
components.
See below for three examples of hierarchical tables.

38
Figure 27 Examples of Hierarchical Tables
From the screenshot, you may be surprised by what HierarchicalTable can do.
Please note, the child component of each row is not limited to table. It could anything. The
second example shows another HierarchicalTable. The child component is a JPanel with many labels
and text fields. The first example fully leverages the feature that HierarchicalTable can use any
component as child component and easily implement master-detail table.
There are actual three tables in the second example. Each has different background colors. The
top level has four rows; each row is a JIDE product. You can further expand each row to display
components or features in that product. Further more, for each features, you can see further details.
Now three tables are organized in a hierarchical way, this is also why it is called HierarchicalTable.

39
The last one is the famous user interface of Windows Control Panel’s Add/Remove Program
dialog. People ask us how to do it but didn’t realize HierarchicalTable provides build-in support for.
The trick is the child component will cover the parent row if it returns false in isHierarchical(int row)
method of HierarchicalTableModel.
HierarchicalTableModel
There are only two major classes in HierarchicalTable component. One is very obvious, the
HierarchicalTable. The other one is called HierarchicalTableModel. HierarchicalTableModel is an interface
but it doesn’t extend TableModel. We named it XxxTableModel because we expect you always use it
with either TableModel, or AbstractTableModel or DefaultTableModel. There are three methods in this
interface. See below.
/**
* Checks if the row has child.
*
* @param row the row index
* @return true if the row has child. Otherwise false.
*/
boolean hasChild(int row);
/**
* Returns true if the child component will be shown in a new row. Returns false is the child
* component will replace the current row.
*
* @param row
* @return true if the child component will be shown in a new row. Otherwise false which means the child
* component will replace the current row when displaying.
*/
boolean isHierarchical(int row);
/**
* Gets the child object value associated with the row at row index.
*
* @param row
* @return the value. If child components are the same except the displaying is different, it's better to
* return a value using this method. Then the component factory can create the same component and only
* load a different value to that component. You can also return null in this method. If so,
* the component factory can look up in the table model on fly and find out how to create the child
component.
*/
Object getChildValueAt(int row);
Here are two typical usages of HierarchicalTableModel.
class ProductTableModel extends DefaultTableModel implements HierarchicalTableModel {

40
……
}
or
class ProductTableModel extends AbstractTableModel implements HierarchicalTableModel {
……
}
So in addition to implement methods defined in TableModel, you also need to implement the
three methods defined in HierarchicalTableModel.
HierarchicalTable
You probably noticed, HierarchicalTableModel only returns a value and doesn’t have code to create
a component to be display in HierarchicalTable. We added a new method to HierarchicalTable called
setComponentFactory. You can use this method to associate a HierarchicalTableComponentFactory object
with HierarchicalTable. It’s HierarchicalTableComponentFactory’s responsibility to create component and
destroy component.
HierarchicalTable extends SortableTable which indicated our HierarchicalTable can be sorted. In case
you don’t want it to be sortable, just call setSortable(false).
In addition to methods defined in JTable and SortableTable, HierarchicalTable defined several its
own methods.
HierarchicalTable has one special column called expandable column. If a column is an expandable
column, there will be an expand/collapse button on the left side of any cells in that column. Clicking
on that button will expand/collapse. By default, the first column is the expandable column. Usually if
you choose a column to be expandable column, the cells in that column should be read only. If you
want to control when to expand/collapse all by yourself, you can call setExpandableColumn(-1). For
example, at the screenshot below, the expandable column is 1 (the 2nd column since it’s 0-based).
Figure 28 HierarchicalTable when expandableColumn is 1
There is another attribute called singleExpansion. Typically when user expands a row, and then
expands another row, the first expanded row will remain expanded. However there are case user
wants only one row to be expanded at a time. Attribute singleExpansion can be used in this case.
singleExpansion is true means only one row can expanded at a time. Default is false.
Container for Child Component
Among the three methods of HierarchicalTableModel, the most important method is
getChildComponent(int row). Basically for each row, you can associate a component with it. However to

41
write this component is completely up to you. As usual, we created several classes you can leverage.
They are HierarchicalPanel and TreeLikeHierarchicalPanel..
HierarchicalPanel is a special JPanel which will always respect the preferred height of the
component it contains. So instead of return the child component directly in getChildComponent(),
wrapping it in HierarchicalPanel and return the HierarchicalPanel. If so, when the child component
height changed, HierarchicalPanel’s height will adjust to the new height automatically. It may be a little
hard to understand. But if you try to expand the child component, one with HierarchicalPanel and the
other with regular JPanel, you will notice the difference.
HierarchicalPanel also has a border BorderFactory.createEmptyBorder(0, 14, 1, 0) to match with
the margin of the expand/collapse button when expandable column is 0. However you can pass in
any border to HierarchicalPanel.
To make HierarchicalTable more like a tree, we also prepared
TreeLikeHierarchicalPanel. It’ll draw a hash line on the left margin
are, just like in JTree. See the red circle area in the left
screenshot. You can tell from the name of
TreeLikeHierarchicalPanel that it must extend HierarchicalPanel.
That’s correct. If you plan to create your own style of
HierarchicalPanel, we suggest you also make it extend HierarchicalPanel.
We are still working on other enhancements to HierarchicalPanel. One enhancement is to make
the panel resizable at the bottom. Instead of resizing the height automatically, user can have the
choice to resize the height. If your HierarchicalPanel extends HierarchicalPanel, you will get those
enhancements without any code change.
Maintaining single selection
When the child components in HierarchicalTable are also tables, sometimes you want to keep one
selection at a time. However since those are different table components and have their own
ListSelectionModels, you will end up with each table has its own row selected. To address this issue, we
create a class called ListSelectionModelGroup. The name comes from ButtonGroup which keeps exclusive
selection for a group of buttons. ListSelectionModelGroup will keep exclusive selection among a group
of ListSelectonModel. To add a ListSelectionModel to the group, you just call add() method. After the
ListSelectionModel is gone, call remove() method. This matches perfectly with HierarchicalTable’s
HierarchicalTableComponentFactory’s createChildComponent() and destroyChildComponent() methods. Basically
when child component is created and if it’s a table, call group.add(table.getSelectionModel()). When the
table is destroyed, call group.remove(table.getSelectionModel()). G8.1 HierarchicalTableDemo is such an
example to show you how to use this.
Migration from Hierarchical Table Beta version
If you first time use HierarchicalTable, you can skip this section. If you used HierarchicalTable beta
version, you should read this to find out how to migrate from your old code to the new one.
The main changes are in interface HierarchicalTableModel. Here are the details of interface changes.
Old method New method
boolean hasChildComponent(int row) boolean hasChild(int row)
boolean isHierarchical(int row) the same

42
Component getChildComponent(int row) Object getChildValueAt(int row)
The reason for this change is to separate the model from view. The old interface gave people the
impression that we are mixing model and view. So the new interface is only about data. To convert
the data to a component, you need to use HierarchicalTableComponentFactory defined on
HierarchicalTable.
HierarchicalTableComponentFactory has two methods
Component createChildComponent(HierarchicalTable table, Object value, int row);
void destroyChildComponent(HierarchicalTable table, Component component, int row);
In createChildComponent() method, the value is the value that returned from getChildValueAt
method in HierarchicalTableModel. The row is the same row as in getChildValueAt(int row). You have the
choices here. You can either always return null in getChildValueAt(int row) method and completely let
createChildComponent to figure out how to create the component. Or you can return a value in
getChildValueAt(int row) method and let createChildComponent to create the component, then associate
the component with the value. If you migrate from beta version, it’s easier to use the first way. You
can simply return null getChildValueAt(int row), and pretty much copy the old code in
getChildComponent(int row) method and put it in createChildComponent(). However if your child
components are using the same component with different data, you might think about changing to
the second way. For example, if your child component is always a table, you can return a table model
in getChildValueAt(int row) and in createChildComponent(), just set the table model to the table. You can
even use a table pool to contain all instances of table and reuse them.

43
TREETABLE
TreeTable is another kind of table component that can display hierarchical data as a table.
TreeTable is a combination of a tree and a table -- a component capable of both expanding and
contracting rows, as well as showing multiple columns of data. Tree and table work on different data
structure. The former is used to display hierarchical data. The latter is used to disable a flat tabular
data. So in order to make the data works in TreeTable, we need to hierarchize the flat tabular data. To
make the design simple, we make the following assumption
If the data can be used in TreeTable, it must be row-oriented.
Row orientated means the two dimension tabular table can be divided by into row first. Then
each row will provide data for the second dimension. Based on this assumption, we introduce several
concepts (they are all Interfaces) to make TreeTable possible.
Node: represent a node in tree data structure
Expandable: represent something can be expanded such as tree node with children.
Row: represent a row in table data structure.
ExpandableRow: represent a row which can have children rows.
It will be simple to understand this using an example. A typical TreeTable example is the file
system. In file system, there are files and folders. Using the concepts above, each file will be a Row;
each folder will be an ExpandableRow. Folder (the ExpandableRow) can have children which can be
either files (the Row) or other folders (the ExpandableRow). See screenshot of a TreeTable.
Figure 29 FileSystem TreeTable
The table model used by TreeTable is TreeTableModel. It extends AbstractTableModel. However it's
essentially a list of ExpandableRows or Rows. TreeTableModel is an abstract class. The only method
you has to implement is getColumnCount(). You might want to override getColumnName(int). Otherwise,
it will use "A", "B" etc as default names. You also need to make the columns match with the value
you returned in Row#getValueAt(int).
Once we create a java.util.List of the Rows, you call
TreeTableModel model = new MyTreeTableModel(list);

44
TreeTable table = new TreeTable(model);
Now you get a TreeTable instance.
TreeTable uses a special cell renderer on the first column to paint +/- icon as well as tree line. If
the row is expandable, you will see +/- icon. Clicking on it will expand the row. Clicking again will
collapse it. You can also use keyboard to expand/collapse a row. Right arrow key will expand the
selected row and left arrow key will collapse it. If the selected row doesn't have children or it is
collapsed already, it will change the selection to its parent. If you try it, you will find it is very
convenient to navigate in the tree table using arrow keys.
Since the first columns are used to paint +/- icon and tree lines, it'd better you make the first
column of the table not editable. There should be always workaround for this limitation, such as
using dialog to edit the first cell or rearranging the table columns to use a non-editable column as the
first one.
We used the same +/- icons used in JTree so it will change based on differen LookAndFeels. The
tree lines can be turn on or offusing setShowTreeLines(boolean). The line color can be set by
setTreeLineColor(Color). By default, it will use the JTree's tree line color which is
UIManager.getColor("Tree.hash").
Comparison between TreeTable and HierarchicalTable
Many people wonder when they should use TreeTable and when to use HierarchicalTable. The
following table will help you to understand and make you decision.
HierarchicalTable TreeTable
Data format of top level A regular tabular data just like
JTable
A list of rows with hierarchical
information built in the data
Data format of child levels Any data. Same data as the top level data
Nested components Any components There are no nested
components in tree table. They
are part of the TreeTable.
Scalability Bad in the sense that each
children component is a real
component. So if you have a
table with 100 rows all expanded
with a children table, you will
have 101 table instances.
Good. There is only one table
no matter how many nested
levels.
Level of hierarchies
(exclude the top level)
One. However you can archive
many levels by nested
HierarchicalTable inside another
HierarchicalTable.
As many as you want
From the table above, you can see which table to use is totally depending on what kind of data
you have. If the data on each child level can all be represent as table, it’s better to use TreeTable. If
not, you should use HierarchicalTable.

45
CELLSPANTABLE
To know what CellSpanTable is, we need to understand CellSpan first.
CellSpan defines how a cell spanning across several rows or/and columns. CellSpan has four
fields. They are row, column, rowSpan, columnSpan. All are int type. The (row, column) is actually
the anchor cell of the cell span. rowSpan tells how many rows the cell will span. columnSpan tells
how many columns the cell will span. You can view them as Rectangle’s y, x, height and width
respectively.
Let’s use the following table as an example. The cell marked as light green is a cell span. The cell
span is defined as row = 1, column = 1, rowSpan = 2, and columnSpan = 3.
(0, 0) (0, 1) (0, 2) (0, 3)
(1, 0)
(2, 0)
CellSpan (1, 1, 2, 3)
(3, 0) (3, 1) (3, 2) (3, 3)
Now you know how to define a cell span. But how to pass the cell span information to table so
that it knows how to paint the cells correctly? Instead of introduce a whole separate model, we
decided to use TableModel. First we defined SpanModel as an interface and then SpanTableModel
which combines SpanModel and SpanTableModel together. See below.
public interface SpanModel {
/**
* Gets the cell span at the specified row and column.
* @param rowIndex
* @param columnIndex
* @return CellSpan object.
*/
CellSpan getCellSpanAt(int rowIndex, int columnIndex);
/**
* Checks if the span is on. There are two meanings if it returns false.
* It could be getCellSpanAt() return a valid value but
* It could also be the span model is empty which means getCellSpanAt() always return null.
* @return true if span is on. Otherwise false.
*/
boolean isCellSpanOn();
}
/**
* <code>SpanTableModel</code> interface combines <code>TableModel</code> and
<code>SpanModel</code>.
*/
public interface SpanTableModel extends TableModel, SpanModel {
}
When you define your table model which you have to do it anyway, you can define what
SpanModel is. Let’s see some real examples.

46
This is a table with every third row spanning across the whole table width. The code to do it is
very simple at the getCellSpanAt(rowIndex, columnIndex) method. Every third row translated to if(
rowIndex % 3 == 0). So if rowIndex can be divided by 3, returns a cell span that anchor cell is at the
first cell in that row and columnSpan is column count.
Figure 30 CellSpanTable
class SpanTableTableModel extends AbstractSpanTableModel {
public int getRowCount() {
return 10000;
}
public int getColumnCount() {
return 9;
}
public boolean isCellEditable(int rowIndex, int columnIndex) {
return false;
}
public Object getValueAt(int rowIndex, int columnIndex) {
return "" + rowIndex + "," + columnIndex;
}
public CellSpan getCellSpanAt(int rowIndex, int columnIndex) {
if (rowIndex % 3 == 0 ) {
return new CellSpan(rowIndex, 0, 1, getColumnCount());
}
return null;
}
public boolean isCellSpanOn() {
return true;

47
}
}
Here is another more complex example. You can read the code to figure out how it works.
Figure 31 CellSpanTable
class SpanTableTableModel extends AbstractSpanTableModel {
return 10000;
}
return 9;
}
return false;
}
}
if ((rowIndex % 3) != 2 && (columnIndex % 3) != 2) {
return new CellSpan(rowIndex - rowIndex % 3, columnIndex - columnIndex % 3, 2, 2);
}
return super.getCellSpanAt(rowIndex, columnIndex);
}

48
return true;
}
}
You probably already noticed we used AbstractSpanTableModel in the examples above which we
haven’t introduced. AbstractSpanTableModel extends AbstractTableModel and implements SpanTableModel
and provides default implementation onto the two methods defined in SpanModel. Please note, it
returns false in isCellSpanOn() which means if you want to see cell span, you have to override it and
return true. The reason we did is because there are other table components that extends
CellSpanTable. We don’t want cell span is turned on by mistake.
AbstractSpanTableModel also provides support for SpanModelListener and SpanModelEvent.
abstract public class AbstractSpanTableModel extends AbstractTableModel implements
SpanTableModel {
return null;
}
return false;
}
.….
}
There is another table model called DefaultSpanTableModel. It extends DefaultTableModel and
implements SpanTableModel. In this model, you get additional methods such as addCellSpan,
removeCellSpan.
Once we understand the SpanTableModel and different subclasses, CellSpanTable is very simple to
use. There is no additional method on it except three methods starting with “orginal”. They are
originalRowAtPoint, originalColumnAtPoint and originalGetCellRect. They are handy when you
need to get the old cell rectangle, row and column without considering the cell spans but in most
cases you won’t need them.
In general, CellSpanTable is very fast. In the example above, we have 10000 rows in the table and
fairly complex cell spans, we couldn’t even notice any difference when scrolling up and down quickly.
However since it’s user’s responsibility to implement getCellSpanAt() method, how complex this
method is does affect the speed of CellSpanTable. So when you implement this method, please make
sure you optimize it as much as you can. We suggest you to use the same CellSpan instance over and
over again2 so that it will increase the memory usage in a short period of time (although it will be
garbage collected later). The other performance tuning technique you can use in this case is to cache
2 Please note, we didn’t use the same CellSpan instance in the two examples above as it will make the code a
little harder to read. However for you it’s very simple to change it to reuse the same instance. All you need is to
create a field of type CellSpan and set different row, column, rowSpan and columnSpan value on it and return
the same thing. If there is no cell span, still return null.

49
the cell span if the cell span is very difficult to calculate. Of course then you have to deal invalidating
the cache when table data changes.
Since Java doesn’t support multiple inherent, we have to put CellSpanTable at a lower level. Most
table components in JIDE Grids are actually CellSpanTable such as TreeTable, PropertyTable,
HierarchicalTable, SortableTable etc. There is one reason why we added isCellSpanOn() method to
SpanModel. If your table model is not an instance SpanModel or it is but isCellStyleOn() returns false,
there is no performance hit at all even if your table extends CellSpanTable.
CELLSTYLETABLE
What is cell style? Usually all the cells in the same table has the same color, same font, same
alignment (at least in the same column). However there are many cases we want to have different
styles on each cell to highlight certain cells or archive the strips effect. Usually we use cell renderers
to do it. CellStyleTable provides a better and easier way to archive this and more.
Cell styles include the foreground, the background, the font, the alignments (horizontal and
vertical), border etc. If you think there are other styles that should be added, just let us know. It’s
very simple to introduce new styles.
The design of CellStyleTable is almost the same as CellSpanTable. Instead of CellSpan, we got
CellStyle class. CellStyle is just a collection of the styles we mentioned above. Then we got StyleModel
and StyleTableModel.
public interface StyleModel {
/**
* Gets the cell style at the specified row and column.
* @param rowIndex
* @param columnIndex
* @return CellStyle object.
*/
CellStyle getCellStyleAt(int rowIndex, int columnIndex);
/**
* Checks if the style is on. There are two meanings if it returns false.
* It could be getCellStyleAt() return a valid value but
* It could also be the style model is empty which means getCellStyleAt() always return null.
* @return true if style is on. Otherwise false.
*/
boolean isCellStyleOn();
}
/**
* <code>StyleTableModel</code> interface combines <code>TableModel</code> and
<code>StyleModel</code>.
*/
public interface StyleTableModel extends TableModel, StyleModel {
}

50
If you just read CellSpanTable, you will see this is just a copy of it. When you implement
StyleModel, all you need to do is to return a desired CellStyle at getCellStyleAt() method. If the styles are
static (not change with table data change) such as stripe pattern or grid pattern, you can use the row
and column index that are passed in. See example below.
Figure 32 CellStyleTable
class StyleTableTableModel extends AbstractStyleTableModel {
protected final Color BACKGROUND1 = new Color(253, 253, 244);
return 10000;
}
return 9;
}
return false;
}
}
CellStyle _cellStyle = new CellStyle();
public CellStyle getCellStyleAt(int row, int column) {
_cellStyle.setHorizontalAlignment(SwingConstants.CENTER);
if (row % 3 == 0) {

51
_cellStyle.setBackground(BACKGROUND2);
}
else if (row % 3 == 1) {
}
else {
}
return _cellStyle;
}
public boolean isCellStyleOn() {
return true;
}
}
If the styles are dynamically changing with the table data, you call getValueAt(row, column) to get
the value and return different style based on the cell value. For example, if the value is negative,
returns red foreground cell style.

52
JIDETABLE
JideTable is an extended version of JTable. The additional features we added are
First, we added CellEditorListener support. You can add a JideCellEditorListener to JideTable.
JideCellEditorListener extends CellEditorListener which is a Swing class and adds several methods such as
editingStarting(ChangeEvent), editingStopping(ChangeEvent)} and editingStopped(ChangeEvent).
With these three methods, you can now do things like preventing cell from starting edit or preventing
cell from stopping edit.
The second feature is to support Validator3 . You can add a Validator to JideTable. The
validating() method in Validator will be called before cell stops editing. If the validation failed, the
cell editor won't be removed.
The third feature added to JideTable is the support of the listener for row height changes when
rows have various heights. You can add a listener by calling getRowHeights().
addRowHeightChangeListener(listener) A RowHeightChangeEvent will be fired whenever setRowHeight(int row,
int rowHeight) is called.
The fourth feature is rowAutoResizes. By default, JTable's row height is determined explicitly. It
wouldn't consider the cell content preferred height. There is a problem here if a cell renderer can
support multiple lines. So we added a new attribute called rowAutoResizes. By default, it's false
which is exactly the same behavior as JTable. If you set to true, the table row will resize automatically
when cell renderer's preferred height changes. Please note there is a performance hit if you turned it
on as it has to check all cells to find out the preferred row height. So only use it when it's really
necessary.
The fifth feature is what we called nested table column. See a picture below.
Figure 33 Nested table columns
Here is the code to create such a nested table column.
// create nested table columns
TableColumnModel cm = table.getColumnModel();
TableColumnGroup first = new TableColumnGroup("Sum 1 - 4");
first.add(cm.getColumn(0));
TableColumnGroup second = new TableColumnGroup("Sum 5 - 9");
second.add(cm.getColumn(4));
3 Validator and related classes are in package com.jidesoft.validation of jide-common.jar. Right now it is only
used in JideTable. However this is part of an infrastructure we will build that will cover all other components
which need validation.

53
TableColumnGroup all = new TableColumnGroup("Sum 1 - 9");
all.add(first);
all.add(second);
NestedTableHeader header = (NestedTableHeader) table.getTableHeader();
header.addColumnGroup(all);
The sixth feature is non-contiguous cell selection. This is probably one of the oldest bugs4 that
were reported to Sun Java back in 1998. In fact, it’s not that difficult to implement a selection model
that supports non-contiguous cell selection. We add the support to JideTable. To use it, you can just
table.setNonContiguousCellSelection(true).
The seventh feature is column auto-fit.
On Windows, if you double click on the gap between table header, the column will be
automatically resize to fit in the widest content in previous cell. JTable doesn’t have this feature. So
we added this to JideTable. You can call setColumnAutoResizable(true) to enable it. Similar to this
feature, we also added a function to TableUtils called autoResizeAllColumns(JTable table). This method
will automatically resize all columns to fit in the content in the cells. Good news about this method is
that it works for all JTable, not just JideTable.
From the screenshot below, you can see the Name column is too width and waste the space.
4 See bug report at http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4138111.

54
After double click on the table header gap, here is what you will see. Please note the width of
Name column is resized automatically to fit in the contents of all cells in that column.
The eighth feature are row resize and column resize. As you know, JTable supports column
resize only by dragging the table column header. And it doesn’t support row resize at all. It would be
nice if it can support resizing at the grid line. JideTable can support it. You just need to call
setColumnResizable(true) and setRowResizable(true) to enable column resizing and row resizing
respectively.
Here is how row resizing works.

55
Here is how column resizing works.
TABLESCROLLPANE
TableScrollPane is a component that supports table row header, row footer, and column footer.
In fact, you can implement row header even without this component. You basically create a separate
table and call setRowHeaderView() to set it to JScrollPane. Now you get a table with a row header.
Sounds simple? Unfortunately it’s more than that. What you can’t do with JScrollPane is that it
doesn’t row footer and column footer. You also needed to create two separate table models – one
for row header and the other for the table itself – which might be inconvenience. Of course, you also
need to deal with keystrokes. As they are two tables, keeping pressing left arrow or tab key won’t
navigate from row header to the table. Don’t forget the sorting. Sorting row header won’t change the
sort order of the table because, again, they are two tables. In fact, there are a lot of things you need to
do in order to support row header. TableScrollPane is such a component that takes care of all those
for you.
To simplify the usage, we also create an interface MultiTableModel to replace TableModel.
Instead of using AbstractTableModel or DefaultTableModel, you can use AbstractMultiTableModel
or DefaultMultiTableModel respectively. Interface MultiTableModel has a method called
getColumnType(int column)5 . By returning HEADER_COLUMN or FOOTER_COLUMN or
REGULAR_COLUMN, you can use one table model to define a table which has header columns
and footer columns.
Please see screenshot below for a typical use case of TableSplitPane.
5 The interface has another method called getTableIndex(). In case you noticed it, this method is for
TableSplitPane, the next component we will discuss. To use in TableScrollPane, you just need to return 0 inthat
method.

56
Figure 34 TableSplitPane - timesheet example
The whole timesheet table is based on one MultiTableModel. To determine which column is row
header or row footer, you just need to return different values in getColumnType. See below.
public int getColumnType(int column) {
if (column <= 4) {
return HEADER_COLUMN;
}
else if (column == HEADER.length - 1) {
return FOOTER_COLUMN;
}
else {
return REGULAR_COLUMN;
}
}
Even though header columns and footer columns are added as separate components, they will
work just like in one table. For example, row selection is synchonized. Tab key or left/right arrows
will navigate across all three tables. If you scroll vertically, all three tables will scroll together. If you
resize columns in any table, even the last column of the header column table and the first column of
footer column table. If you choose to have sortable table, sorting in one table will affect other tables.
Only one column will be sorted at a time.

57
TABLESPLITPANE
TableSplitPane is a special component that splits a large table into several smaller tables. There are
dividers between tables so each table can be resized independently. However, as just like in
TableScrollPane, all tables inside this component act just like one table. In short, this is an ideal
candidate if you have a large table model which has a lot of columns and those columns can be
divided into different categories.
TableSplitPane is built on top of MultiTableModel too. There is one more method on the
MultiTableModel interface called getTableIndex(int column). You can return any integer starting from 0. If
the value is 0, the column will in the first table. If 1, it will be in the second table, and so on.
TableSplitPane will look at the value returned from getTableIndex() and divider columns into several
tables. Then for each table, it will look at the value returned from getColumnType() and divide them
into header, regular or footer columns. As a result, you can use one table model to define multiple
tables; each can have its own header and footer. See below for an example.
Figure 35 TableSplitPane

58
INTERNATIONALIZATION AND LOCALIZATION
We have fully considered i18n and l10n. All strings used by JIDE Grids have been put into
properties files under each package. They are grid.properties under com.jidesoft.grid,
converter.properties under com.jidesoft.converter and combobox.properties under
com.jidesoft.combobox. If you need a localized version, you extract these properties from the jar,
translate them into the language you want, and put them back into jar with the right file name change
according to the locale.

Jide grids developer_guide

More Related Content

Similar to Jide grids developer_guide (20)

Recently uploaded (20)

Jide grids developer_guide