JavaFX's CustomNode class lets you create reusable node-based components for your user interfaces. Because these components aren't skinnable, you can't change a component's appearance and/or behavior without rewriting the component. Fortunately, Sun has addressed this limitation by providing the javafx.scene.control package with its two core classes:

• The Control class, which subclasses CustomNode, provides the component's model.
• The Skin class provides the component's look and feel.

Because JavaFX 1.1's documentation on Control and Skin is somewhat obtuse, I created this blog post to share some insight into using these classes to create components beyond javafx.scene.control's TextBox class. I'll specifically reveal a button component in terms of its Button model and ButtonSkin look and feel classes, and demonstrate using this component with the textbox.

Designing a skinnable button component

Control is the base class for user-interface components that support skins. You extend this class to define the component's model, supplying appropriate model-oriented attributes and an init block to initialize the component's default skin. For example, Listing 1 presents a Button class that subclasses Control to specify the model for a simple push button.

Listing 1: The Button model class

public class Button extends Control
{
    public var text: String;
    public var action: function (): Void;

    override protected var focused on replace
    {
        println ("focused = {focused}")
    }

    override protected var hover on replace
    {
        println ("hover = {hover}")
    }

    override protected var pressed on replace
    {
        println ("pressed = {pressed}")
    }

    init
    {
        skin = ButtonSkin {}
    }
}

This model requires two attributes: text to display, and a function to run whenever the button is activated (by a mouse click, or by pressing a special key while the button is focused). Additionally, the init block creates the button's skin as an instance of the ButtonSkin class, assigning this skin to Button's skin attribute, which this class inherits from Control.

You'll notice that I've overridden Node's focused, hover, and pressed attributes. Whenever the values of the skin's corresponding focused, hover, and pressed attributes change, the values of these attributes also change (thanks to behind-the-scenes binding). The replace triggers let you observe these changes.

Skin is the base class for defining a component's look and feel. Along with focused, hover, and pressed, Skin provides a control attribute for referencing the component's model's attributes, and a scene attribute for specifying the look and feel's scene graph. Listing 2's ButtonSkin class subclasses Skin to supply this look and feel.

Listing 2: The ButtonSkin look and feel class

class ButtonSkin extends Skin
{
    def buttonControl = bind control as Button;

    override protected def focused = bind scene.focused;

    override protected def hover = bind scene.hover;

    override protected def pressed = bind scene.pressed on replace
    {
        if (pressed)
            scene.requestFocus ()
    }

    init
    {
        scene = Group
        {
            var rectRef: Rectangle
            var textRef: Text

            content:
            [
                rectRef = Rectangle
                {
                    arcHeight: 12
                    arcWidth: 12

                    height: bind buttonControl.height
                    width: bind buttonControl.width

                    stroke: bind if (focused) Color.STEELBLUE else Color.GRAY
                    strokeWidth: bind if (focused) 2.0 else 1.5

                    opacity: 0.7

                    fill: LinearGradient
                    {
                        startX: 0.0
                        startY: 0.0

                        endX: 0.0
                        endY: 1.0

                        stops:
                        [
                            Stop
                            {
                                offset: 0.0
                                color: Color.web ("#dceaff")
                            }

                            Stop
                            {
                                offset: 0.49
                                color: Color.web ("#6885b2")
                            }

                            Stop
                            {
                                offset: 0.5
                                color: Color.web ("#2c599c")
                            }

                            Stop
                            {
                                offset: 1.0
                                color: Color.web ("#bed3f4")
                            }
                        ]
                    }
                }

                textRef = Text
                {
                    var w: Number
                    var h: Number

                    var _focused = false
                    def x = bind rectRef.boundsInLocal on replace
                    {
                        if (focused)
                            _focused = true
                        else if (not _focused)
                        {
                            w = x.width;
                            h = x.height;
                        }
                    }

                    translateX: bind (w-textRef.boundsInLocal.width)/2
                    translateY: bind h/2

                    x: bind if (pressed) 1 else 0
                    y: bind if (pressed) 1 else 0

                    content: bind buttonControl.text
                    font: Font
                    {
                        name: "Arial BOLD"
                        size: 12
                    }

                    fill: Color.WHITE
                }
            ]

            onMouseClicked: function (e: MouseEvent): Void
            {
                buttonControl.action ()
            }

            onKeyPressed: function (e: KeyEvent): Void
            {
                if (e.code != KeyCode.VK_SPACE)
                    return;

                def pause = PauseTransition
                {
                    duration: 0.15s

                    action: function (): Void
                    {
                        scene.pressed = false
                    }
                }

                scene.pressed = true;
                pause.play ();

                buttonControl.action ()
            }
        }
    }
}

ButtonSkin binds Skin's control attribute to buttonControl so that it can access the model's action and text attributes, not to mention inherited attributes such as height and width. (I probably should have specified buttonModel or model instead of buttonControl, to more accurately indicate this attribute's purpose.)

ButtonSkin next overrides focused, hover, and pressed (which are implicitly bound to Button's focused, hover, and pressed attributes), binding them to scene's versions of these attributes -- when scene's attributes change, binding causes ButtonSkin's same-named attributes to change, which implicitly causes Button's same-named attributes to change.

When ButtonSkin's pressed attribute changes its value (in response to the user pressing the mouse button while the mouse is over the component's scene graph, or releasing this button, whether or not the mouse is still over the scene graph), the replace trigger executes. If pressed is true, the trigger tells the JavaFX runtime to give focus to the scene graph (via requestFocus()).

When the scene graph receives focus (via requestFocus() or the Tab key), ButtonSkin's focused attribute is set to true. This attribute is used (via binding) to enlarge the button's outline and change its color (to indicate focus), and to solve a small problem (discussed later). (The scene graph receives focus when its root node is assigned a key handler, such as the function assigned to onKeyPressed.)

ButtonSkin's init block creates the scene graph, assigning its root node to the scene attribute. This node is of type Group because the scene graph consists of a Text node overlaying a Rectangle node. To ensure that the button receives focus, Group's onKeyPressed attribute is assigned a key handler. (Assigning a key handler to Rectangle's or Text's onKeyPressed attribute wouldn't work.)

A mouse handler is similarly assigned to Group's onMouseClicked attribute. Unlike the key handler, you could place the mouse handler in the Rectangle node and achieve the same effect. Alternatively, you could place this handler in the Text node. In this case, however, the handler would only activate (in response to a button click) whenever the mouse was exactly over the text -- not over the rectangle.

The Rectangle node's look is governed by its arcWidth and arcHeight attributes (which should probably be a percentage of this node's size rather than being specific values), its width and height attributes (which are bound to the model), its stroke and strokeWidth attributes (whose values depend on the scene graph's focused state), and its opacity and fill attributes (which specify its background).

The number of stops and their values for the LinearGradient assigned to the fill attribute originated in Amer Sohail's informative Creating Custom Button in JavaFX blog post -- I like the glassy appearance achieved by this gradient.

Moving on, we discover the Text node. Its object literal begins in a strange way, by specifying w, h, _focused, and x variables. Variable x is bound to the rectangle's boundsInLocal attribute, and provides a replace trigger to keep track of this attribute's width and height attribute values (in variables w and h) until the scene graph is first focused.

The w and h values are used with translateX and translateY to center the text horizontally over the rectangle background, and to give the text a nice vertical alignment according to its baseline. I bind to w and h instead of boundsInLocal.width and boundsInLocal.height because these dimensions change when the scene graph is focused/unfocused, which causes the text to move around disconcertingly.

In addition to binding x and y to expressions that use pressed to allow the text to shift slightly when the mouse is pressed, the Text literal also binds the content attribute to the model's text attribute. However, it supplies a specific font and a specific text color. (I elected to hardcode these values because they can be changed via stylesheet settings, but only in the desktop profile.)

Finally, Group's onMouseClicked and onKeyPressed handler functions invoke the model's action function. However, onKeyPressed's function has more work to do than onMouseClicked's function. Specifically, it detects an appropriate key to serve as the trigger for invoking the action function -- I've chosen the spacebar key. It also simulates a button click with the help of scene.pressed and a pause transition.

Using the skinnable button component

I've written a script that employs the button and textbox components in the user interface of a utility that converts between degrees and radians. Enter a numeric degrees/radians value into the textbox, and click a button to convert this value to radians or degrees. The result appears in the textbox, whose contents are erased by clicking a third button. Figure 1 shows this user interface from the desktop perspective.

Figure 1: The textbox displays the result of converting 180 degrees to radians via the Deg2Rad button, which currently has the focus. (Click to enlarge.)

Listing 3 excerpts the script's Stage literal, which is located in the Main.fx file of a NetBeans project named DRC. This literal specifies the user interface shown in Figure 1.

Listing 3: The DRC script's stage

Stage
{
    var model = Model {}

    title: "DRC"

    width: 390
    height: 190

    var sceneRef: Scene
    scene: sceneRef = Scene
    {
        fill: LinearGradient
        {
            startX: 0.0
            startY: 0.0
            endX: 0.0
            endY: 1.0
            stops:
            [
                Stop { offset: 0.0 color: Color.YELLOW },
                Stop { offset: 1.0 color: Color.CYAN }
            ]
        }

        var input: TextBox

        content: VBox
        {
            translateY: 20
            spacing: 20

            var titleRef: Text
            content:
            [
                titleRef = Text
                {
                    content: "Degrees/Radians Converter"
                    font: Font
                    {
                        name: "Arial BOLD",
                        size: 18
                    }
                    textOrigin: TextOrigin.TOP

                    translateX: bind (sceneRef.width-
                                      titleRef.boundsInLocal.width)/2
                }

                input = TextBox
                {
                    value: bind model.input with inverse
                    translateX: bind (sceneRef.width-
                                      input.boundsInLocal.width)/2
                }

                HBox
                {
                    def BTNWIDTH = 80
                    def SPACING = 10

                    spacing: SPACING

                    translateX: bind (sceneRef.width-3*(BTNWIDTH+SPACING))/2

                    content:
                    [
                        Button
                        {
                            text: "Deg2Rad"
                            width: BTNWIDTH
                            height: 28
                            action: function (): Void
                            {
                                model.deg2rad ()
                            }
                        }

                        Button
                        {
                            text: "Rad2Deg"
                            width: BTNWIDTH
                            height: 28
                            action: function (): Void
                            {
                                model.rad2deg ()
                            }
                        }

                        Button
                        {
                            text: "Clear"
                            width: BTNWIDTH
                            height: 28
                            action: function (): Void
                            {
                                input.value = ""
                            }
                        }
                    ]
                }
            ]
        }
    }
}

You might be wondering why I assign, to HBox's translateX attribute, the bind (sceneRef.width-3*(BTNWIDTH+SPACING))/2 expression rather than the equivalent bind (sceneRef.width-panel.boundsInLocal.width)/2 expression (where panel references the HBox literal), to horizontally center the three buttons.

If I assign bind (sceneRef.width-panel.boundsInLocal.width)/2 to translateX and, in the ButtonSkin class, increase the font size to a certain value such as 14 or 18, I've found that the leftmost button's text shifts horizontally as focus moves from one component to another. I'm not sure why this anomaly occurs, but I can overcome it via (sceneRef.width-3*(BTNWIDTH+SPACING))/2.

Listing 4 presents the script's Model class, which the stage instantiates and the button handlers use to perform the conversions. (The conversion code is unecessarily complicated, but interesting.)

Listing 4: The DRC script's Model class

class Model
{
    def base = "http://www.webservicex.net/ConvertAngle.asmx/ChangeAngleUnit?";

    var input: String;

    function deg2rad (): Void
    {
        def request = HttpRequest
        {
            location: "{base}AngleValue={input}&fromAngleUnit=degrees&"
                      "toAngleUnit=radians"

            onException: function (ex: Exception): Void
            {
                input = ex.getMessage ()
            }

            onInput: function (is: InputStream)
            {
                def parser = PullParser
                {
                    documentType: PullParser.XML
                    input: is

                    onEvent: function (event: Event)
                    {
                        if (event.type == PullParser.END_ELEMENT)
                            if (event.qname.name == "double")
                                input = event.text
                    }
                }
                parser.parse ();
                parser.input.close ()
            }
        }
        request.enqueue ()
    }

    function rad2deg (): Void
    {
        def request = HttpRequest
        {
            location: "{base}AngleValue={input}&fromAngleUnit=radians&"
                      "toAngleUnit=degrees"

            onException: function (ex: Exception): Void
            {
                input = ex.getMessage ()
            }

            onInput: function (is: InputStream)
            {
                def parser = PullParser
                {
                    documentType: PullParser.XML
                    input: is

                    onEvent: function (event: Event)
                    {
                        if (event.type == PullParser.END_ELEMENT)
                            if (event.qname.name == "double")
                                input = event.text
                    }
                }
                parser.parse ();
                parser.input.close ()
            }
        }
        request.enqueue ()
    }
}

The Model class specifies an input attribute that stores the value to be converted, and also stores the result of the conversion. Look closely at Listing 3 and you'll discover the bind model.input with inverse expression, which is assigned to the TextBox's value attribute. This binding allows the model to easily access the input value, and store the result in the textbox.

Model also specifies functions deg2rad() and rad2deg() for performing the degrees-to-radians and radians-to-degrees conversions. Although I could have easily hardcoded these calculations in these functions, I found a Web service that performs this task, and wanted to play with the HttpRequest and PullParser classes.

Whenever deg2rad() or rad2deg() is called, the function creates an HttpRequest object that specifies the location of the Web service, the angle value to pass to this service, and the conversion direction (degrees to radians or radians to degrees). The function then enqueues the request to run in the background, which keeps the user interface responsive.

If a non-numeric value (a letter or the empty string, for example) or otherwise illegal value (such as a mixture of digits and letters) is assigned to AngleValue and the Web service is invoked, the Web service returns an error value that results in the handler function assigned to onException being invoked. For simplicity, I assign this value to the model's input attribute, allowing it to appear in the textbox.

The onInput handler function is invoked whenever the Web service successfully returns the converted value, via a small XML document. This function creates a PullParser to parse out the converted value from the document's double tag, and stores this value in the model's input attribute, which subsequently appears in the user interface's textbox.

That's pretty much it for how the DRC script works. Because this script and the button component access only classes belonging to the common profile (unfortunately, I can't take advantage of the desktop-profile-oriented javafx.scene.effect classes), the script will run on the mobile emulator. Check out Figure 2 for the proof.

Figure 2: The user interface must be rotated 90 degrees to see it in its entirety. In a future blog post, I'll discuss creating user interfaces that automatically adapt to different screen dimensions. (Click to enlarge.)

While running the script on the mobile emulator, an interesting thing happens whenever you specify an invalid value (leave the textbox empty, for example), and then click a conversion button. Instead of the onException handler function being invoked, allowing the Web service's error message to appear in the textbox, the following NullPointerException is thrown:

java.lang.NullPointerException:   0
 - com.sun.javafx.data.pull.ukit.xml.ParserStAX.panic(), bci=25
 - com.sun.javafx.data.pull.ukit.xml.Parser.step(), bci=1048
 - com.sun.javafx.data.pull.ukit.xml.ParserStAX.next(), bci=204
 - javafx.data.pull.PullParser.next$impl(), bci=40
 - javafx.data.pull.PullParser.next(), bci=1
 - javafx.data.pull.PullParser.parse$impl(), bci=24
 - javafx.data.pull.PullParser.parse(), bci=1
 - drc.Main$Model$2.lambda(), bci=66
 - drc.Main$Model$2.invoke(), bci=2
 - drc.Main$Model$2.invoke(), bci=5
 - javafx.io.http.HttpRequest.setInput$impl(), bci=48
 - javafx.io.http.HttpRequest.setInput(), bci=2
 - com.sun.javafx.io.http.impl.BaseTask$ReadNotifier.run(), bci=15
 - com.sun.javafx.io.http.impl.msa.MsaProfile$1.invoke(), bci=4
 - javafx.lang.FX$1.run(), bci=4
 - com.sun.fxme.runtime.RunnableQueue$Worker.run(), bci=222

This exception appears to be thrown because of a bug in the JavaFX mobile runtime, and will be reported. Although somewhat annoying, the bug could be avoided by validating the textbox's input prior to invoking the Web service. Alternatively, I could avoid the Web service and just hardcode the calculations (but that wouldn't be as much fun).

Conclusion

Although it can be challenging to create skinnable components, I intend to present additional examples that complement the button component in future blog posts. Let me know if you have a favorite component that you'd like to see implemented next. In the meantime, perhaps Sun will provide additional skinnable components (and standardized support for themes, groups of logically related skins) in JavaFX 1.5.

Download a source file: cs j33109-src.zip

Like this blog? Subscribe to the CSJ Explorer RSS feed

Ian Darwin's Java Cookbook presents a collection of recipes for solving hundreds of problems that Java developers encounter. For example, in the first edition, one of Chapter 2's recipes discusses how to use the classpath effectively. To the best of my knowledge, O'Reilly hasn't published a similar cookbook that deals exclusively with Swing.

A Swing-only cookbook might make Swing more accessible to those inexperienced with this toolkit. Perhaps it would help for Chapter 1's recipes to target the Swing Application Framework, which is intended to make Swing applications easier to write, and which should debut in Java SE 7. Later chapters could each target one or more Swing components.

For example, one chapter might present recipes for both the JList and JComboBox components. (Because of their similarity, grouping JList and JComboBox recipes in the same chapter seems logical.) Although some recipes would be JList-specific, and other recipes would target only JComboBox, still other recipes would focus on both components. Custom cell rendering is one example.

JList and JComboBox each manage a list of items. They rely on a cell renderer component to render each item in a cell. Although the default cell renderer is adequate for most rendering tasks, scenarios exist where you'll want to install a custom cell renderer to handle a specific kind of rendering. For example, Figure 1 shows a custom cell renderer presenting a flag icon beside a country's name.

Figure 1: The flag icons are courtesy of British developer Mark James. (Click to enlarge.)

Prior to rendering an item in a cell, JList and JComboBox obtain an item-specific rendering component by invoking the ListCellRenderer interface's Component getListCellRendererComponent(JList list, Object value, int index, boolean isSelected, boolean cellHasFocus) method. The returned component performs the rendering, taking into account the method's arguments:

• list references the JList whose cell is to be rendered. (For a JComboBox, list references the JList part of this component.)
• value references the object that is to be rendered in the cell.
• index identifies value's location in the list. In some cases, such as when focus shifts away from the list, -1 is passed to index.
• isSelected indicates whether the cell being rendered is currently selected (true) or not (false).
• cellHasFocus indicates whether the cell being rendered has the input focus (true) or not (false). For JComboBox, this argument is always false because a combobox's text field, instead of the list, gets the focus.

JList and JComboBox default their cell renderers to instances of the DefaultListCellRenderer class, which implements ListCellRenderer. These defaults can be replaced by invoking JList's void setCellRenderer(ListCellRenderer cellRenderer) and JComboBox's void setRenderer(ListCellRenderer aRenderer) methods.

Before invoking setCellRenderer() or setRenderer(), you need to declare and instantiate a class that implements ListCellRenderer and provides the rendering logic. The easiest way to handle the rendering in a look-and-feel independent manner is to subclass an existing component such as a JLabel. This is precisely what the custom cell renderer illustrated in Figure 1 and specified in Listing 1 accomplishes.

Listing 1: Countries.java

// Countries.java

import java.awt.*;

import java.net.URL;

import java.util.*;

import javax.swing.*;
import javax.swing.border.Border;

public class Countries extends JFrame
{
   Countries (String title)
   {
      super (title);
      setDefaultCloseOperation (EXIT_ON_CLOSE);

      FlowLayout layout = new FlowLayout (FlowLayout.CENTER, 5, 5);
      layout.setAlignOnBaseline (true);
      getContentPane ().setLayout (layout);

      Country [] carray;
      JList list = new JList (carray = createCountriesArray ());
//      list.setEnabled (false);
      list.setCellRenderer (new CountryCellRenderer (null));
      list.setVisibleRowCount (8);
      list.setSelectedIndex (0);
      getContentPane ().add (new JScrollPane (list));

      JComboBox cb = new JComboBox (carray);
//      cb.setEnabled (false);
      cb.setRenderer (new CountryCellRenderer (cb));
      getContentPane ().add (cb);

      pack ();
      setVisible (true);
   }

   Country [] createCountriesArray ()
   {
      String [] citems =
      {
         "AD,Andorra",
         "AE,United Arab Emirates",
         "AF,Afghanistan",
         "AG,Antigua and Barbuda",
         "AI,Anguilla",
         "AL,Albania",
         "AM,Armenia",
         "AN,Netherlands Antilles",
         "AO,Angola",
         "AR,Argentina",
         "AS,American Samoa",
         "AT,Austria",
         "AU,Australia",
         "AW,Aruba",
         "AX,Åland Islands",
         "AZ,Azerbaijan",
         "BA,Bosnia and Herzegovina",
         "BB,Barbados",
         "BD,Bangladesh",
         "BE,Belgium",
         "BF,Burkina Faso",
         "BG,Bulgaria",
         "BH,Bahrain",
         "BI,Burundi",
         "BJ,Benin",
         "BM,Bermuda",
         "BN,Brunei Darussalam",
         "BO,Bolivia",
         "BR,Brazil",
         "BS,Bahamas",
         "BT,Bhutan",
         "BV,Bouvet Island",
         "BW,Botswana",
         "BY,Belarus",
         "BZ,Belize",
         "CA,Canada",
         "CC,Cocos (Keeling) Islands",
         "CD,Congo, the Democratic Republic of the",
         "CF,Central African Republic",
         "CG,Congo",
         "CH,Switzerland",
         "CI,Cote d'Ivoire Côte d'Ivoire",
         "CK,Cook Islands",
         "CL,Chile",
         "CM,Cameroon",
         "CN,China",
         "CO,Colombia",
         "CR,Costa Rica",
         "CU,Cuba",
         "CV,Cape Verde",
         "CX,Christmas Island",
         "CY,Cyprus",
         "CZ,Czech Republic",
         "DE,Germany",
         "DJ,Djibouti",
         "DK,Denmark",
         "DM,Dominica",
         "DO,Dominican Republic",
         "DZ,Algeria",
         "EC,Ecuador",
         "EE,Estonia",
         "EG,Egypt",
         "EH,Western Sahara",
         "ER,Eritrea",
         "ES,Spain",
         "ET,Ethiopia",
         "FI,Finland",
         "FJ,Fiji",
         "FK,Falkland Islands (Malvinas)",
         "FM,Micronesia, Federated States of",
         "FO,Faroe Islands",
         "FR,France",
         "GA,Gabon",
         "GB,United Kingdom",
         "GD,Grenada",
         "GE,Georgia",
         "GF,French Guiana",
         "GH,Ghana",
         "GI,Gibraltar",
         "GL,Greenland",
         "GM,Gambia",
         "GN,Guinea",
         "GP,Guadeloupe",
         "GQ,Equatorial Guinea",
         "GR,Greece",
         "GS,South Georgia and the South Sandwich Islands",
         "GT,Guatemala",
         "GU,Guam",
         "GW,Guinea-Bissau",
         "GY,Guyana",
         "HK,Hong Kong",
         "HM,Heard Island and McDonald Islands",
         "HN,Honduras",
         "HR,Croatia",
         "HT,Haiti",
         "HU,Hungary",
         "ID,Indonesia",
         "IE,Ireland",
         "IL,Israel",
         "IN,India",
         "IO,British Indian Ocean Territory",
         "IQ,Iraq",
         "IR,Iran, Islamic Republic of",
         "IS,Iceland",
         "IT,Italy",
         "JM,Jamaica",
         "JO,Jordan",
         "JP,Japan",
         "KE,Kenya",
         "KG,Kyrgyzstan",
         "KH,Cambodia",
         "KI,Kiribati",
         "KM,Comoros",
         "KN,Saint Kitts and Nevis",
         "KP,Korea, Democratic People's Republic of",
         "KR,Korea, Republic of",
         "KW,Kuwait",
         "KY,Cayman Islands",
         "KZ,Kazakhstan",
         "LA,Lao People's Democratic Republic",
         "LB,Lebanon",
         "LC,Saint Lucia",
         "LI,Liechtenstein",
         "LK,Sri Lanka",
         "LR,Liberia",
         "LS,Lesotho",
         "LT,Lithuania",
         "LU,Luxembourg",
         "LV,Latvia",
         "LY,Libyan Arab Jamahiriya",
         "MA,Morocco",
         "MC,Monaco",
         "MD,Moldova, Republic of",
         "ME,Montenegro",
         "MG,Madagascar",
         "MH,Marshall Islands",
         "MK,Macedonia, the former Yugoslav Republic of",
         "ML,Mali",
         "MM,Myanmar",
         "MN,Mongolia",
         "MO,Macao",
         "MP,Northern Mariana Islands",
         "MQ,Martinique",
         "MR,Mauritania",
         "MS,Montserrat",
         "MT,Malta",
         "MU,Mauritius",
         "MV,Maldives",
         "MW,Malawi",
         "MX,Mexico",
         "MY,Malaysia",
         "MZ,Mozambique",
         "NA,Namibia",
         "NC,New Caledonia",
         "NE,Niger",
         "NF,Norfolk Island",
         "NG,Nigeria",
         "NI,Nicaragua",
         "NL,Netherlands",
         "NO,Norway",
         "NP,Nepal",
         "NR,Nauru",
         "NU,Niue",
         "NZ,New Zealand",
         "OM,Oman",
         "PA,Panama",
         "PE,Peru",
         "PF,French Polynesia",
         "PG,Papua New Guinea",
         "PH,Philippines",
         "PK,Pakistan",
         "PL,Poland",
         "PM,Saint Pierre and Miquelon",
         "PN,Pitcairn",
         "PR,Puerto Rico",
         "PS,Palestinian Territory, Occupied",
         "PT,Portugal",
         "PW,Palau",
         "PY,Paraguay",
         "QA,Qatar",
         "RE,Reunion Réunion",
         "RO,Romania",
         "RS,Serbia",
         "RU,Russian Federation",
         "RW,Rwanda",
         "SA,Saudi Arabia",
         "SB,Solomon Islands",
         "SC,Seychelles",
         "SD,Sudan",
         "SE,Sweden",
         "SG,Singapore",
         "SH,Saint Helena",
         "SI,Slovenia",
         "SJ,Svalbard and Jan Mayen",
         "SK,Slovakia",
         "SL,Sierra Leone",
         "SM,San Marino",
         "SN,Senegal",
         "SO,Somalia",
         "SR,Suriname",
         "ST,Sao Tome and Principe",
         "SV,El Salvador",
         "SY,Syrian Arab Republic",
         "SZ,Swaziland",
         "TC,Turks and Caicos Islands",
         "TD,Chad",
         "TF,French Southern Territories",
         "TG,Togo",
         "TH,Thailand",
         "TJ,Tajikistan",
         "TK,Tokelau",
         "TL,Timor-Leste",
         "TM,Turkmenistan",
         "TN,Tunisia",
         "TO,Tonga",
         "TR,Turkey",
         "TT,Trinidad and Tobago",
         "TV,Tuvalu",
         "TW,Taiwan, Province of China",
         "TZ,Tanzania, United Republic of",
         "UA,Ukraine",
         "UG,Uganda",
         "UM,United States Minor Outlying Islands",
         "US,United States",
         "UY,Uruguay",
         "UZ,Uzbekistan",
         "VA,Holy See (Vatican City State)",
         "VC,Saint Vincent and the Grenadines",
         "VE,Venezuela",
         "VG,Virgin Islands, British",
         "VI,Virgin Islands, U.S.",
         "VN,Viet Nam",
         "VU,Vanuatu",
         "WF,Wallis and Futuna",
         "WS,Samoa",
         "YE,Yemen",
         "YT,Mayotte",
         "ZA,South Africa",
         "ZM,Zambia",
         "ZW,Zimbabwe"
      };

      ArrayList<Country> clist = new ArrayList<Country> ();
      for (String citem: citems)
      {
           String [] cdata = citem.split (",");
           clist.add (new Country (cdata [1],
                      getClass ().getResource ("icons/"+
                                               cdata [0].toLowerCase ()+
                                               ".png")));
      }

      Country [] carray = clist.toArray (new Country [0]);
      Arrays.sort (carray);
      return carray;
   }

   public static void main (String [] args)
   {
      Runnable r = new Runnable ()
                   {
                       public void run ()
                       {
                          // Always create Swing UIs on event-dispatching
                          // thread.

                          new Countries ("Countries");
                       }
                   };
      EventQueue.invokeLater (r);
   }
}

class Country implements Comparable<Country>
{
   private String name;
   private ImageIcon flagIcon;

   private URL path;

   Country (String name, URL path)
   {
      this.name = name;
      this.path = path;
   }

   String getName ()
   {
      return name;
   }

   ImageIcon getFlagIcon ()
   {
      // Lazily load flag icon. Make sure that each country's flag icon is 
      // loaded only once.

      if (flagIcon == null)
          flagIcon = new ImageIcon (path);

      return flagIcon;
   }

   public int compareTo (Country o)
   {
      return name.compareTo (o.name);
   }
}

class CountryCellRenderer extends JLabel implements ListCellRenderer
{
   private Border border;

   private JComboBox cb;

   CountryCellRenderer (JComboBox cb)
   {
      this.cb = cb;

      // Leave a 10-pixel separator between the flag icon and country name.

      setIconTextGap (10);

      // Swing labels default to being transparent; the container's color
      // shows through. To change a Swing label's background color, you must
      // first make the label opaque (by passing true to setOpaque()). Later,
      // you invoke setBackground(), passing the new color as the argument.

      setOpaque (true);

      // This border is placed around a cell that is selected and has focus.

      border = BorderFactory.createLineBorder (Color.RED, 1);
   }

   public Component getListCellRendererComponent (JList list,
                                                  Object value,
                                                  int index,
                                                  boolean isSelected,
                                                  boolean cellHasFocus)
   {
      Country c = (Country) value;
      setText (c.getName ());
      setIcon (c.getFlagIcon ());

      if (isSelected)

      {
          setBackground (list.getSelectionBackground ());
          setForeground (list.getSelectionForeground ());
      }
      else
      {
          setBackground (list.getBackground ());
          setForeground (list.getForeground ());
      }

      setFont (list.getFont ());

      // list.isEnabled() always returns true for a combobox's list, even if
      // the combobox is disabled.

      setEnabled (cb != null ? cb.isEnabled () : list.isEnabled ());

      if (isSelected && cellHasFocus) // cellHasFocus ignored for JComboBox
          setBorder (border);
      else
          setBorder (null);

      return this;
   }
}

Listing 1 is organized into Countries, Country, and CountryCellRenderer classes. The main Countries class creates the user interface and stores the URLs of various flag icons along with country names into an array of Country objects. Each of these objects is passed to CountryCellRenderer's getListCellRendererComponent() method to obtain a JLabel that can render the object.

These classes offer a variety of techniques that are worth remembering for your own Swing applications and custom cell renderers:

• JFrame's content pane defaults to a JPanel managed by a BorderLayout layout manager. Rather than wrap a component in a JPanel and add that panel to the content pane's panel, to display the component at its preferred size, simply set the content pane's panel's layout manager to a FlowLayout, which makes every effort to display components at their preferred sizes. Wrapping a component in a JPanel, which is then added to the content pane's panel, also works (but results in unnecessary JPanel creation) because JPanel's default layout manager is FlowLayout.
• Java SE 6 introduced the void setAlignOnBaseline(boolean alignOnBaseline) method to FlowLayout to allow components to be vertically aligned according to their baselines (when true is passed to alignOnBaseline). This method makes it possible to present the combobox near the top of its container instead of in the middle.
• An instance of a custom cell renderer class can be shared among multiple JLists and JComboBoxs provided that the class provides no instance-specific fields. For example, Listing 1's CountryCellRenderer class contains a cb field. This field is set to null if the custom cell renderer is assigned to a JList, or the JComboBox instance on which the custom cell renderer is being assigned. The JComboBox is needed to determine if this component is disabled, whereas the list reference passed to getListCellRendererComponent() is sufficient for determining whether a JList is disabled. Because the cb field has a dual role, Listing 1 requires two instances of CountryCellRenderer.
• The Country class's getFlagIcon() method uses ImageIcon to load the flag icon. It lazily loads this icon when actually required, and also to ensure that the flag icon is loaded only once -- the custom cell renderer invokes getFlagIcon() multiple times for each country.
• The Country class implements Comparable<T> to allow the array of Country objects (created in the Countries class's createCountriesArray() method) to be sorted (via Arrays.sort()) according to country name.
• DefaultListCellRenderer supports setting a border for a focused JList's selected item. CountryCellRenderer's getListCellRendererComponent() method also sets a red border for the selected item of a focused JList, to show that this component is focused. Rather than create a border object each time getListCellRendererComponent() is invoked, which is inefficient, I create the border exactly once, in CountryCellRenderer's constructor.
• Although it's convenient for CountryCellRenderer to offload the rendering task to JLabel, which handles icon and text rendering, there is a problem with JLabel that must be overcome before it can be used to show a selected item. Specifically, JLabel's opacity defaults to transparent, which allows the underlying container's background color to show through. As a result, a selection bar never appears. You can fix this problem by making JLabel opaque, which is accomplished in CountryCellRenderer's constructor.
• Finally, it's important to create as few objects as possible in getListCellRendererComponent() because this method is frequently called. Creating too many objects on the heap can lead to garbage collections pauses that can disrupt the smooth flow of program execution. Fortunately, getListCellRendererComponent() creates no objects (unless I'm mistaken). Furthermore, it reuses the same JLabel object.

After compiling Countries.java, it's easy to package this application into an executable JAR file by first creating a manifest file that contains Main-Class: Countries and (assuming the manifest file is named manifest.mf) executing jar cfm Countries.jar manifest.mf *.class icons. You then specify java -jar Countries.jar to execute this application.

With a bit of work, the previous cell-rendering material could be turned into a recipe in the hypothetical Swing cookbook's chapter on JList and JComboBox. (Recipes on rendering table and tree cells could appear in chapters that deal with JTable and JTree.) However, is creating a Swing cookbook a good idea, especially in light of JavaFX, which simplifies user interface development?

Download a source file: csj31009-src.zip

Like this blog? Subscribe to the CSJ Explorer RSS feed